### Setting Up and Running Pre-commit Hooks (Python/Bash)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Details the process of installing and enabling pre-commit hooks for code quality. It covers installing the pre-commit framework using pip and then installing the project's hooks, with an alternative using a provided script.

```bash
# Install pre-commit framework
pip install pre-commit

# Install hooks (includes formatting, linting, and basic checks)
pre-commit install

# Or use the project script
./scripts/install-pre-commit.sh
```

--------------------------------

### Cargo.toml Example Configuration

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Demonstrates how to configure an example in the `Cargo.toml` file for a Rust project, specifying the example's name and its source file path.

```toml
[[example]]
name = "my_example"
path = "examples/my_example.rs"
```

--------------------------------

### Rust Example Implementation

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

A basic Rust code snippet showing how to structure an example file within the `examples/` directory of a Rust project. It includes necessary imports.

```rust
// examples/my_example.rs
use prism_mcp_rs::prelude::*;

fn main() {
    // Example code here
}
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/AI_TOOL_INTEGRATION.md

Example JSON configuration for an MCP server, specifying the command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "windsurf-rust-server": {
      "command": "/path/to/target/release/your-server",
      "args": ["--windsurf-mode"],
      "env": {
        "WINDSURF_INTEGRATION": "true",
        "LOG_LEVEL": "debug"
      }
    }
  }
}
```

--------------------------------

### Install Prism MCP SDK and Development Tools (Bash)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Clones the Prism MCP SDK repository and installs necessary development tools using Cargo and Rustup. It also provides commands for installing Act, a tool for running GitHub Actions locally.

```bash
git clone https://github.com/prismworks-ai/prism-mcp-rs
cd prism-mcp-rs

# Install development tools
make install-tools

# Or manually:
cargo install cargo-audit cargo-llvm-cov cargo-deny cargo-nextest
rustup component add rustfmt clippy
```

--------------------------------

### Test Manual Server Startup

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/TROUBLESHOOTING.md

Manually starts the MCP server with different logging levels and tests basic client interaction via stdio.

```bash
# Run server directly to check for errors
/path/to/your/server --stdio
```

```bash
# With debug logging
RUST_LOG=debug /path/to/your/server --stdio
```

```bash
# Test with MCP client simulation
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}' | /path/to/your/server --stdio
```

--------------------------------

### Windsurf - Basic Configuration Example (JSON)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/examples/ai-tool-configs/README.md

A JSON configuration for Windsurf's basic MCP setup, detailing the server command, arguments for Windsurf integration, and specific environment variables.

```json
{
  "mcpServers": {
    "windsurf-server": {
      "command": "/usr/local/bin/windsurf-mcp",
      "args": ["--windsurf-integration"],
      "env": {
        "WINDSURF_MODE": "true",
        "CASCADE_SUPPORT": "enabled"
      }
    }
  }
}
```

--------------------------------

### Environment Variable Configuration Examples

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/AI_TOOL_INTEGRATION.md

Shows examples of setting environment variables for MCP servers in development and production environments.

```json
{
  "env": {
    "RUST_LOG": "debug",
    "DEVELOPMENT": "true",
    "CONFIG_PATH": "./config/dev.json"
  }
}
```

```json
{
  "env": {
    "RUST_LOG": "warn",
    "PRODUCTION": "true",
    "CONFIG_PATH": "/etc/myserver/config.json"
  }
}
```

--------------------------------

### Install DXT CLI and Pack Desktop Extension

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

Commands to install the Desktop Extension CLI globally using npm and then package the created extension into a distributable format (.dxt). Requires Node.js and npm.

```bash
npm install -g @anthropic-ai/dxt

```

```bash
dxt pack

```

--------------------------------

### Homebrew Formula for MCP Server

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

This Ruby script defines a Homebrew formula for installing the MCP server. It specifies the server's description, homepage, download URL, checksum, and license, and includes a method to install the binary.

```ruby
class YourServer < Formula
  desc "MCP server built with prism-mcp-rs"
  homepage "https://github.com/your-org/your-server"
  url "https://github.com/your-org/your-server/releases/download/v1.0.0/your-server-v1.0.0-darwin-universal.tar.gz"
  sha256 "sha256_hash_here"
  license "MIT"

  def install
    bin.install "your-server"
  end

  test do
    assert_match "your-server", shell_output("#{bin}/your-server --version")
  end
end
```

--------------------------------

### Universal Installer Script

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

A bash script designed to download and install the MCP server binary from GitHub releases. It automatically detects the host platform and architecture, fetches the latest release, downloads the appropriate binary, and installs it to a specified directory.

```bash
#!/bin/bash
set -e

BINARY_NAME="your-server"
GITHUB_REPO="your-org/your-server"
INSTALL_DIR="/usr/local/bin"

# Detect platform
detect_platform() {
  local os=$(uname -s | tr '[:upper:]' '[:lower:]')
  local arch=$(uname -m)
  
  case $os in
    linux) 
      case $arch in
        x86_64) echo "x86_64-unknown-linux-musl" ;; 
        aarch64|arm64) echo "aarch64-unknown-linux-musl" ;; 
        *) echo "Unsupported architecture: $arch" >&2; exit 1 ;; 
      esac
      ;;
    darwin) 
      case $arch in
        x86_64|arm64) echo "universal-apple-darwin" ;; 
        *) echo "Unsupported architecture: $arch" >&2; exit 1 ;; 
      esac
      ;;
    mingw*|msys*|cygwin*) 
      echo "x86_64-pc-windows-msvc"
      ;;
    *) 
      echo "Unsupported OS: $os" >&2
      exit 1
      ;;
  esac
}

# Get latest release
get_latest_release() {
  curl -s "https://api.github.com/repos/$GITHUB_REPO/releases/latest" | \
    grep '"tag_name":' | \
    sed -E 's/.*"([^"]+)".*/\1/'
}

# Download and install
main() {
  local platform=$(detect_platform)
  local version=${1:-$(get_latest_release)}
  
  echo "Installing $BINARY_NAME $version for $platform..."
  
  local url="https://github.com/$GITHUB_REPO/releases/download/$version/${BINARY_NAME}-${version}-${platform}"
  if [[ $platform == *"windows"* ]]; then
    url="${url}.zip"
  else
    url="${url}.tar.gz"
  fi
  
  # Create temp directory
  local temp_dir=$(mktemp -d)
  cd "$temp_dir"
  
  # Download
  echo "Downloading from $url..."
  curl -L "$url" -o archive
  
  # Extract
  if [[ $platform == *"windows"* ]]; then
    unzip archive
  else
    tar -xzf archive
  fi
  
  # Install
  sudo mv "$BINARY_NAME" "$INSTALL_DIR/"
  sudo chmod +x "$INSTALL_DIR/$BINARY_NAME"
  
  # Cleanup
  cd /
  rm -rf "$temp_dir"
  
  echo "$BINARY_NAME installed successfully to $INSTALL_DIR"
  echo "Run '$BINARY_NAME --version' to verify installation"
}

main "$@"
```

--------------------------------

### Testing Utilities in prism-mcp-rs

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/guides/migration.md

Provides an example of how to use the testing utilities provided by the prism-mcp-rs project. It shows how to set up tests, mock tool calls, and assert responses using the `prism-test-utils` crate.

```rust
#[cfg(test)]
mod tests {
    // Test utilities are now in a separate crate
    // Add to your Cargo.toml:
    // [dev-dependencies]
    // prism-test-utils = { git = "https://github.com/prismworks-ai/prism-mcp-tools" }
    use prism_test_utils::*;
    
    #[test]
    fn test_my_handler() {
        let request = mock_tool_call("my-tool", json!({"arg": "value"}));
        // Test your handler
        
        let response = mock_success(json!({"result": "ok"}));
        assert_response_contains(&response, &["result"]);
    }
}
```

--------------------------------

### Setup Development Environment (Bash)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/CONTRIBUTING.md

Commands to clone the repository, install development dependencies using Make, or manually install required Rust tools like cargo-audit, cargo-llvm-cov, and configure rustup components for formatting and linting.

```bash
# Clone repository
git clone https://github.com/prismworks-ai/prism-mcp-rs
cd prism-mcp-rs

# Install development dependencies
make install-tools

# Alternatively, install manually
car go install cargo-audit cargo-llvm-cov cargo-deny cargo-nextest
rustup component add rustfmt clippy
```

--------------------------------

### Create and Build MCP Server with Rust

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/GETTING_STARTED.md

This snippet demonstrates how to create a new Rust project, add prism-mcp-rs and tokio dependencies, define a simple tool handler, and set up an MCP server with a 'hello' tool. It also includes commands for building the release version of the server.

```bash
# Create new project
cargo new my-mcp-server
cd my-mcp-server

# Add prism-mcp-rs dependency
cargo add prism-mcp-rs tokio --features full
```

```rust
use prism_mcp_rs::prelude::*;
use std::collections::HashMap;

#[derive(Clone)]
struct HelloToolHandler;

#[async_trait]
impl ToolHandler for HelloToolHandler {
    async fn call(&self, arguments: HashMap<String, Value>) -> McpResult<ToolResult> {
        let name = arguments.get("name")
            .and_then(|v| v.as_str())
            .unwrap_or("World");
            
        Ok(ToolResult {
            content: vec![ContentBlock::text(format!("Hello, {}!", name))],
            is_error: Some(false),
            meta: None,
            structured_content: None,
        })
    }
}

#[tokio::main]
async fn main() -> McpResult<()> {
    // Create server
    let mut server = McpServer::new(
        "my-first-server".to_string(), 
        "1.0.0".to_string()
    );
    
    // Add a simple hello tool
    let tool = Tool::new(
        "hello".to_string(),
        Some("Says hello to someone".to_string()),
        json!({
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Name to greet"
                }
            }
        }),
        HelloToolHandler,
    );
    
    server.add_tool(tool);
    
    // Start server
    server.start().await
}
```

```bash
# Build release version
cargo build --release

# Your binary is now at:
# ./target/release/my-mcp-server
```

--------------------------------

### Load and Log Configuration in Rust

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/TROUBLESHOOTING.md

A Rust example demonstrating how to load configuration values (database URL and API key) from environment variables using the `serde` crate. It includes error handling and logs the loaded configuration.

```rust
use serde::Deserialize;

#[derive(Deserialize, Debug)]
struct Config {
    database_url: String,
    api_key: String,
}

fn load_config() -> Result<Config, Box<dyn std::error::Error>> {
    let config = Config {
        database_url: std::env::var("DATABASE_URL")?,
        api_key: std::env::var("API_KEY")?,
    };
    
    tracing::info!("Loaded config: {:?}", config);
    Ok(config)
}
```

--------------------------------

### Rust Doc Test Example

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Demonstrates how to write testable documentation comments in Rust using ///. It includes an example of asserting server properties within a doc test.

```rust
/// Example of a testable documentation comment
///
/// ```rust
/// use prism_mcp_rs::prelude::*;
/// 
/// let server = McpServer::new("test".to_string(), "1.0.0".to_string());
/// assert_eq!(server.name(), "test");
/// ```
pub fn example_function() {}
```

--------------------------------

### Build all examples using Cargo

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/examples/README.md

Builds all example applications within the project using the Cargo build command. This is a prerequisite for running individual examples.

```bash
cargo build --examples
```

--------------------------------

### Example Secure MCP Server Configuration

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/AI_TOOL_INTEGRATION.md

A secure configuration example for an MCP server, demonstrating restricted access, read-only mode, and sensitive environment variables.

```json
{
  "mcpServers": {
    "secure-server": {
      "command": "/usr/local/bin/my-server",
      "args": [
        "--allowed-dirs", "/home/user/safe-directory",
        "--read-only",
        "--log-level", "warn"
      ],
      "env": {
        "API_KEY": "${SECRET_API_KEY}",
        "TLS_CERT_PATH": "/etc/ssl/certs/server.pem"
      }
    }
  }
}
```

--------------------------------

### Binary Path Configuration Examples

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/AI_TOOL_INTEGRATION.md

Illustrates different ways to specify the binary path for an MCP server, including absolute, relative, and PATH-based references.

```json
{
  "command": "/usr/local/bin/my-server",
  "args": []
}
```

```json
{
  "command": "./target/release/my-server",
  "args": []
}
```

```json
{
  "command": "my-server",
  "args": []
}
```

--------------------------------

### Install prism-mcp-rs as a Windows Service using winsw

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

This snippet demonstrates how to configure prism-mcp-rs to run as a Windows service using winsw. It requires a service configuration XML file and command-line arguments for installation and starting.

```xml
<service>
  <id>YourMCPServer</id>
  <n>Your MCP Server</n>
  <description>MCP server built with prism-mcp-rs</description>
  <executable>C:\\Program Files\\YourServer\\your-server.exe</executable>
  <arguments>--config "C:\\Program Files\\YourServer\\config.json"</arguments>
  <log mode="roll"/>
</service>
```

```cmd
winsw install your-server-service.xml
winsw start YourMCPServer
```

--------------------------------

### Manage Prism MCP Server systemd Service

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

Commands to enable the Prism MCP Server to start automatically on boot and to start the service immediately. These commands require root privileges.

```bash
sudo systemctl enable your-server

```

```bash
sudo systemctl start your-server

```

--------------------------------

### Install Prism MCP Server on Windows using PowerShell

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

A PowerShell script to download, install, and configure the Prism MCP Server on Windows. It fetches the latest release from GitHub, extracts it, and adds the server's directory to the user's PATH environment variable. Requires PowerShell.

```powershell
param(
    [string]$Version = "latest",
    [string]$InstallPath = "$env:LOCALAPPDATA\Programs\YourServer"
)

$ErrorActionPreference = "Stop"

$repoOwner = "your-org"
$repoName = "your-server"
$binaryName = "your-server.exe"

function Get-LatestVersion {
    $response = Invoke-RestMethod -Uri "https://api.github.com/repos/$repoOwner/$repoName/releases/latest"
    return $response.tag_name
}

function Install-YourServer {
    if ($Version -eq "latest") {
        $Version = Get-LatestVersion
    }
    
    Write-Host "Installing $binaryName $Version..."
    
    $downloadUrl = "https://github.com/$repoOwner/$repoName/releases/download/$Version/$binaryName-$Version-x86_64-pc-windows-msvc.zip"
    $tempPath = Join-Path $env:TEMP "your-server-install.zip"
    
    # Download
    Write-Host "Downloading from $downloadUrl..."
    Invoke-WebRequest -Uri $downloadUrl -OutFile $tempPath
    
    # Create install directory
    if (!(Test-Path $InstallPath)) {
        New-Item -ItemType Directory -Path $InstallPath -Force | Out-Null
    }
    
    # Extract
    Expand-Archive -Path $tempPath -DestinationPath $InstallPath -Force
    
    # Add to PATH
    $userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
    if ($userPath -notlike "*$InstallPath*") {
        [Environment]::SetEnvironmentVariable("PATH", "$userPath;$InstallPath", "User")
        Write-Host "Added $InstallPath to PATH"
    }
    
    # Cleanup
    Remove-Item $tempPath
    
    Write-Host "$binaryName installed successfully to $InstallPath"
    Write-Host "Restart your terminal and run '$binaryName --version' to verify installation"
}

Install-YourServer

```

--------------------------------

### Run specific example using Cargo

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/examples/README.md

Executes a specific example application from the project using the Cargo run command. Replace `your_example` with the desired example name.

```bash
cargo run --example bidirectional_basic
cargo run --example closure_handlers
cargo run --example custom_transport
```

--------------------------------

### Install Act for Local GitHub Actions Testing (Shell)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Provides commands to install Act, a tool for running GitHub Actions workflows locally, for different operating systems. Includes installation for macOS via Homebrew, Linux via curl script, and Windows via Chocolatey, Scoop, or winget.

```bash
# macOS
brew install act
```

```bash
# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
```

```powershell
# Windows
choco install act-cli
# or
scoop install act
# or
winget install nektos.act
```

```bash
# Verify Installation
act --version
act -l  # List available workflows
```

--------------------------------

### Rust License Header Example

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/guides/plugins.md

An example of a license header comment in Rust, specifying the SPDX license identifier and copyright information. This is a best practice for open-source projects.

```rust
// SPDX-License-Identifier: MIT
// Copyright (c) 2025 Your Name
```

--------------------------------

### Project Configuration for MCP Server

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/AI_TOOL_INTEGRATION.md

Example JSON configuration for an MCP server within a project's `.mcp.json` file.

```json
{
  "mcpServers": {
    "local-rust-server": {
      "command": "./target/release/server",
      "args": ["--project-mode"],
      "env": {
        "PROJECT_PATH": "."
      }
    }
  }
}
```

--------------------------------

### Generate and open documentation with Cargo

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/examples/README.md

Generates the project's documentation, including any embedded code examples, and opens it in the default web browser. This is useful for reviewing the documentation output.

```bash
cargo doc --open
```

--------------------------------

### Configure Claude Desktop for MCP Server

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/GETTING_STARTED.md

This JSON configuration snippet is used to register a local MCP server with Claude Desktop. It requires the full path to the compiled server binary. After adding this configuration, Claude Desktop needs to be restarted for the changes to take effect.

```json
{
  "mcpServers": {
    "my-first-server": {
      "command": "/full/path/to/your/project/target/release/my-mcp-server",
      "args": [],
      "env": {}
    }
  }
}
```

--------------------------------

### Install Rust Formatting Tool (Bash)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Command to install the rustfmt tool, which is used for formatting Rust code according to community standards. This is a component managed by rustup.

```bash
rustup component add rustfmt
```

--------------------------------

### Argument Patterns for MCP Servers

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/AI_TOOL_INTEGRATION.md

Provides examples of common argument patterns for configuring MCP servers, such as for file system, database, and HTTP servers.

```json
{
  "args": [
    "--allowed-dirs", "/home/user/projects",
    "--read-only", "false"
  ]
}
```

```json
{
  "args": [
    "--database-url", "postgresql://localhost/mydb",
    "--max-connections", "10"
  ]
}
```

```json
{
  "args": [
    "--port", "8080",
    "--host", "127.0.0.1",
    "--tls-cert", "/path/to/cert.pem"
  ]
}
```

--------------------------------

### Test documentation examples with Cargo

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/examples/README.md

Runs documentation tests for the project using Cargo. This command verifies that code examples embedded within the documentation are valid and runnable.

```bash
cargo test --doc
```

--------------------------------

### Rust MCP Server Setup with System Info Tool

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/README.md

This Rust code demonstrates how to set up an MCP server using prism-mcp-rs. It defines a `SystemToolHandler` to provide system information and registers it with the server, which then starts using the STDIO transport.

```rust
use prism_mcp_rs::prelude::*;
use std::collections::HashMap;

#[derive(Clone)]
struct SystemToolHandler;

#[async_trait]
impl ToolHandler for SystemToolHandler {
    async fn call(&self, arguments: HashMap<String, Value>) -> McpResult<ToolResult> {
        match arguments.get("tool_name").and_then(|v| v.as_str()) {
            Some("system_info") => {
                let info = format!(
                    "Host: {}, OS: " , 
                    hostname::get().unwrap_or_default().to_string_lossy(),
                    std::env::consts::OS
                );
                Ok(ToolResult {
                    content: vec![ContentBlock::text(&info)],
                    is_error: Some(false),
                    meta: None,
                    structured_content: None,
                })
            },
            _ => Err(McpError::invalid_request("Unknown tool"))
        }
    }
}

#[tokio::main] async fn main() -> McpResult<()> {
    let mut server = McpServer::new(
        "system-server".to_string(), 
        "1.0.0".to_string()
    );
    
    // Add the system_info tool using the async add_tool method
    server.add_tool(
        "system_info",
        Some("Get system information"),
        json!({"type": "object", "properties": {}}),
        SystemToolHandler,
    ).await?;
    // Start server with STDIO transport
    let transport = StdioServerTransport::new();
    server.start(transport).await
}
```

--------------------------------

### Minimal Server Configuration Template

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/TROUBLESHOOTING.md

A basic JSON configuration for the MCP server, setting up a minimal instance that executes an echo command. This serves as a starting point for creating custom configurations.

```json
{
  "mcpServers": {
    "test": {
      "command": "/bin/echo",
      "args": ["test"],
      "env": {}
    }
  }
}
```

--------------------------------

### Using Cross for Cross-Platform Rust Builds

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

Installs and utilizes the 'cross' tool to simplify building Rust projects for various target architectures and operating systems directly from your development machine. Demonstrates building for Linux and Windows targets.

```bash
cargo install cross

# Build for multiple targets
cross build --release --target x86_64-unknown-linux-musl
cross build --release --target aarch64-unknown-linux-musl
cross build --release --target x86_64-pc-windows-gnu
```

--------------------------------

### Load Prism MCP Server launchd Service (macOS)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

Command to load the created launchd plist file, registering the Prism MCP Server as a managed service that will start automatically on user login.

```bash
launchctl load ~/Library/LaunchAgents/com.yourorg.your-server.plist

```

--------------------------------

### Rust Convenience Methods for JSON-RPC Errors

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/guides/migration.md

Provides examples of using built-in helper methods in prism-mcp-rs for quickly creating standard and MCP-specific JSON-RPC errors.

```rust
use prism_mcp_rs::protocol::JsonRpcError;

// Standard JSON-RPC errors
let err1 = JsonRpcError::parse_error();
let err2 = JsonRpcError::method_not_found(request_id);
let err3 = JsonRpcError::invalid_params(request_id);

// MCP-specific errors
let err4 = JsonRpcError::tool_not_found(request_id, "unknown-tool");
let err5 = JsonRpcError::resource_not_found(request_id, "missing.txt");
```

--------------------------------

### Environment-Specific Configuration Files (YAML)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

Example YAML files for providing environment-specific configurations. These files can be used to override default settings for different deployment environments like production and development.

```yaml
# config/production.yaml
database_url: "${DATABASE_URL}"
api_endpoint: "https://api.production.com"
log_level: "warn"
max_connections: 100

# config/development.yaml  
database_url: "sqlite:dev.db"
api_endpoint: "http://localhost:3000"
log_level: "debug"
max_connections: 10
```

--------------------------------

### Run Cargo Examples with Features

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/examples/generated/README.md

Demonstrates how to execute a specific example from the Cargo project, including how to pass required features.

```bash
# Run a specific example
cargo run --example <example_name>

# Run with required features
cargo run --example <example_name> --features "feature1 feature2"
```

--------------------------------

### Cursor - Global Configuration Example (JSON)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/examples/ai-tool-configs/README.md

A JSON configuration file for Cursor's global MCP settings, defining a utility server with specific arguments and environment variables for integration.

```json
{
  "mcpServers": {
    "global-utilities": {
      "command": "/usr/local/bin/cursor-utils",
      "args": ["--global-mode"],
      "env": {
        "CURSOR_INTEGRATION": "true",
        "RUST_LOG": "info"
      }
    }
  }
}
```

--------------------------------

### Unit Test Tool Execution in Rust

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/guides/plugins.md

Provides an example of a Rust unit test for a tool's execution. It instantiates a tool, prepares arguments using `HashMap` and `json!`, calls the tool, and asserts that the operation was successful.

```rust
#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_tool_execution() {
        let tool = MyTool::new();
        let mut args = HashMap::new();
        args.insert("param".to_string(), json!("value"));
        
        let result = tool.call(args).await;
        assert!(result.is_ok());
    }
}
```

--------------------------------

### Rust Module and Function Documentation

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Illustrates Rust documentation practices for modules and functions, including the use of `//!` for module-level documentation and standard doc comments for functions with sections for arguments and return values. The `no_run` attribute is shown for examples that should not be executed.

```rust
//! Module-level documentation goes here.
//!
//! # Examples
//!
//! ```rust,no_run
//! use prism_mcp_rs::module::*;
//! // Example code
//! ```

/// Function documentation.
///
/// # Arguments
///
/// * `param` - Parameter description
///
/// # Returns
///
/// Return value description
pub fn function(param: Type) -> ReturnType {
    // Implementation
}
```

--------------------------------

### Create APT Repository Package (.deb)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEPLOYMENT_GUIDE.md

A set of bash commands to create a Debian package (.deb) for the MCP server. This involves installing packaging tools, setting up the package structure, copying the binary, creating a control file, and building the package.

```bash
# Install packaging tools
sudo apt-get install dpkg-dev devscripts

# Create package structure
mkdir -p your-server-1.0.0/DEBIAN
mkdir -p your-server-1.0.0/usr/local/bin

# Copy binary
cp target/release/your-server your-server-1.0.0/usr/local/bin/

# Create control file
cat > your-server-1.0.0/DEBIAN/control << EOF
Package: your-server
Version: 1.0.0
Section: utils
Priority: optional
Architecture: amd64
Maintainer: Your Name <your.email@example.com>
Description: MCP server built with prism-mcp-rs
 A high-performance MCP server implementation.
EOF

# Build package
dpkg-deb --build your-server-1.0.0
```

--------------------------------

### Server Dependency Management: Health Checks and Shutdown (Rust)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/AI_TOOL_INTEGRATION.md

Provides examples of implementing health checks and graceful shutdown procedures in Rust for managing server dependencies. The 'wait_for_dependency' function illustrates checking service availability, and the 'tokio::signal::ctrl_c' example shows how to handle termination signals.

```rust
// In your server
async fn wait_for_dependency() {
    // Check if required service is available
}
```

```rust
// Handle graceful shutdown
tokio::signal::ctrl_c().await?;
```

--------------------------------

### Generate Documentation Examples Coverage Locally

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/reports/README.md

This command generates a report for documentation examples coverage. The report is saved as examples/validation_report.md. This is typically executed via a make command.

```bash
# Documentation examples
make examples-validate
# Report will be in examples/validation_report.md
```

--------------------------------

### Rust File System Server with Read File and List Directory Tools

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/GETTING_STARTED.md

This Rust code implements a file system server using Prism MCP. It includes handlers for reading file content and listing directory entries. The `ReadFileHandler` reads a file's content, while `ListDirHandler` lists files in a directory. The `main` function sets up the server and adds these tools, demonstrating both direct handler implementation and the use of closure helpers for tool creation.

```rust
use prism_mcp_rs::prelude::*;
use std::collections::HashMap;

#[derive(Clone)]
struct ReadFileHandler;

#[async_trait]
impl ToolHandler for ReadFileHandler {
    async fn call(&self, arguments: HashMap<String, Value>) -> McpResult<ToolResult> {
        let path = arguments.get("path")
            .and_then(|v| v.as_str())
            .ok_or_else(|| McpError::invalid_request("Missing 'path' parameter"))?;
        
        match std::fs::read_to_string(path) {
            Ok(content) => Ok(ToolResult {
                content: vec![ContentBlock::text(content)],
                is_error: Some(false),
                meta: None,
                structured_content: None,
            }),
            Err(e) => Err(McpError::internal_error(format!("Failed to read file: {}", e)))
        }
    }
}

#[derive(Clone)]
struct ListDirHandler;

#[async_trait]
impl ToolHandler for ListDirHandler {
    async fn call(&self, arguments: HashMap<String, Value>) -> McpResult<ToolResult> {
        let path = arguments.get("path")
            .and_then(|v| v.as_str())
            .ok_or_else(|| McpError::invalid_request("Missing 'path' parameter"))?;
        
        match std::fs::read_dir(path) {
            Ok(entries) => {
                let files: Result<Vec<_>, _> = entries
                    .map(|entry| entry.map(|e| e.file_name().to_string_lossy().to_string()))
                    .collect();
                
                match files {
                    Ok(file_list) => Ok(ToolResult {
                        content: vec![ContentBlock::text(file_list.join(", "))],
                        is_error: Some(false),
                        meta: None,
                        structured_content: None,
                    }),
                    Err(e) => Err(McpError::internal_error(format!("Failed to read directory: {}", e)))
                }
            },
            Err(e) => Err(McpError::internal_error(format!("Failed to read directory: {}", e)))
        }
    }
}

#[tokio::main]
async fn main() -> McpResult<()> {
    let mut server = McpServer::new(
        "filesystem-server".to_string(), 
        "1.0.0".to_string()
    );
    
    // Read file tool using closure helper
    let read_file_tool = closure_tool(
        "read_file".to_string(),
        Some("Read contents of a file".to_string()),
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "File path to read"}
            },
            "required": ["path"]
        }),
        |args| {
            let path = args.get("path")
                .and_then(|v| v.as_str())
                .ok_or_else(|| McpError::invalid_request("Missing 'path' parameter"))?;
            
            match std::fs::read_to_string(path) {
                Ok(content) => Ok(vec![ContentBlock::text(content)]),
                Err(e) => Err(McpError::internal_error(format!("Failed to read file: {}", e)))
            }
        }
    );
    
    // List directory tool
    let list_dir_tool = closure_tool(
        "list_directory".to_string(),
        Some("List contents of a directory".to_string()),
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Directory path to list"}
            },
            "required": ["path"]
        }),
        |args| {
            let path = args.get("path")
                .and_then(|v| v.as_str())
                .ok_or_else(|| McpError::invalid_request("Missing 'path' parameter"))?;
            
            match std::fs::read_dir(path) {
                Ok(entries) => {
                    let files: Result<Vec<_>, _> = entries
                        .map(|entry| entry.map(|e| e.file_name().to_string_lossy().to_string()))
                        .collect();
                    
                    match files {
                        Ok(file_list) => Ok(vec![ContentBlock::text(file_list.join(", "))]),
                        Err(e) => Err(McpError::internal_error(format!("Failed to read directory: {}", e)))
                    }
                },
                Err(e) => Err(McpError::internal_error(format!("Failed to read directory: {}", e)))
            }
        }
    );
    
    server.add_tool(
        "read_file",
        Some("Read contents of a file"),
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "File path to read"}
            },
            "required": ["path"]
        }),
        ReadFileHandler,
    ).await?;
    
    server.add_tool(
        "list_directory", 
        Some("List contents of a directory"),
        json!({
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Directory path to list"}
            },
            "required": ["path"]
        }),
        ListDirHandler,

```

--------------------------------

### Claude Desktop - Basic Server Configuration (JSON)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/examples/ai-tool-configs/README.md

Example JSON configuration for setting up a basic MCP server for Claude Desktop. It specifies the server command and environment logging level.

```json
{
  "mcpServers": {
    "my-rust-server": {
      "command": "/usr/local/bin/my-server",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}
```

--------------------------------

### Development Environment Configuration (JSON)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/examples/ai-tool-configs/README.md

Example JSON configuration for a development environment, specifying a debug build command, hot-reloading arguments, and development-specific environment variables including a database URL.

```json
{
  "mcpServers": {
    "dev-server": {
      "command": "./target/debug/server",
      "args": ["--dev", "--hot-reload"],
      "env": {
        "RUST_LOG": "debug",
        "DATABASE_URL": "sqlite:dev.db",
        "DEVELOPMENT": "true"
      }
    }
  }
}
```

--------------------------------

### Configure MCP Server Environment Variables

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/TROUBLESHOOTING.md

A JSON configuration example specifying environment variables for an MCP server instance. This includes database connection strings, API keys, logging levels, and server ports, essential for proper server operation.

```json
{
  "mcpServers": {
    "configured-server": {
      "command": "/path/to/server",
      "args": ["--config", "/path/to/config.json"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb",
        "API_KEY": "your-secret-key",
        "RUST_LOG": "info",
        "MCP_SERVER_PORT": "8080"
      }
    }
  }
}
```

--------------------------------

### Regenerate Examples with Cargo or Make

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/examples/generated/README.md

Provides commands to regenerate the example files from the project's documentation using either Cargo tests or a Makefile.

```bash
cargo test --test doc_examples
```

```bash
make examples-generate
```

--------------------------------

### CLI Commands for Managing MCP Servers

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/AI_TOOL_INTEGRATION.md

Commands to list configured MCP servers and test their connections.

```bash
# List configured servers
claude mcp list

# Test server connection
claude mcp test my-rust-server
```

--------------------------------

### Install Cargo Audit (Bash)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Command to install the cargo-audit tool, which performs security audits on Rust dependencies by checking against known vulnerabilities. This is installed using cargo.

```bash
cargo install cargo-audit
```

--------------------------------

### Install Cargo Deny (Bash)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Command to install cargo-deny, a tool for enforcing license policies and preventing the inclusion of disallowed dependencies in Rust projects. This is installed using cargo.

```bash
cargo install cargo-deny
```

--------------------------------

### VS Code - Workspace Configuration Example (JSON)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/examples/ai-tool-configs/README.md

Illustrates a JSON configuration for VS Code to integrate an MCP server at the workspace level. It uses the 'stdio' type and includes workspace-specific arguments and environment variables.

```json
{
  "servers": {
    "RustMCPServer": {
      "type": "stdio",
      "command": "/path/to/rust-server",
      "args": ["--workspace", "${workspaceFolder}"],
      "env": {
        "VSCODE_WORKSPACE": "${workspaceFolder}",
        "RUST_LOG": "info"
      }
    }
  }
}
```

--------------------------------

### Rust Commit Convention Example (Text)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/CONTRIBUTING.md

Illustrates the conventional commit message format, including type, scope, subject, body, and footer, with a concrete example for adding HTTP/3 support.

```text
<type>(<scope>): <subject>

<body>

<footer>

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation
- `style`: Formatting
- `refactor`: Code restructuring
- `perf`: Performance improvement
- `test`: Testing
- `chore`: Maintenance

**Example:**
```
feat(transport): Add HTTP/3 support

Implements QUIC-based HTTP/3 transport with connection migration
and 0-RTT support.

Closes #789
```
```

--------------------------------

### Install Cargo LLVM Coverage (Bash)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Command to install the cargo-llvm-cov tool, which is used for generating code coverage reports for Rust projects using LLVM. This is installed using cargo.

```bash
cargo install cargo-llvm-cov
```

--------------------------------

### Correct Configuration Format for Claude Desktop

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/TROUBLESHOOTING.md

Provides the correct JSON structure for configuring an MCP server in Claude Desktop, highlighting common mistakes.

```json
{
  "mcpServers": {
    "server-name": {
      "command": "/absolute/path/to/binary",
      "args": [],
      "env": {}
    }
  }
}
```

```json
// ❌ Wrong - missing mcpServers wrapper
{
  "server-name": {
    "command": "/path/to/binary"
  }
}
```

```json
// ❌ Wrong - incorrect field names
{
  "mcpServers": {
    "server-name": {
      "executable": "/path/to/binary",  // Should be "command"
      "arguments": []                   // Should be "args"
    }
  }
}
```

--------------------------------

### Install Cargo Nextest (Bash)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Command to install cargo-nextest, an enhanced test runner for Rust projects that provides features like parallel test execution and better output control. This is installed using cargo.

```bash
cargo install cargo-nextest
```

--------------------------------

### Rust API Documentation Structure (Rust)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/CONTRIBUTING.md

Provides a comprehensive example of Rust documentation comments for a public async function, covering brief and detailed explanations, arguments, return values, errors, examples, panics, and safety considerations.

```rust
/// Brief description.
///
/// Detailed explanation of functionality, behavior, and usage patterns.
///
/// # Arguments
///
/// * `param_name` - Parameter description with constraints
///
/// # Returns
///
/// Description of return value and possible states
///
/// # Errors
///
/// Returns [`McpError`] when:
/// - Specific error condition
/// - Another error condition
///
/// # Examples
///
/// ```rust
/// use prism_mcp_rs::prelude::*;
///
/// let result = function_name(param).await?;
/// assert_eq!(result, expected);
/// ```
///
/// # Panics
///
/// Panics if:
/// - Panic condition (if applicable)
///
/// # Safety
///
/// Safety requirements (for unsafe functions)
pub async fn function_name(param: Type) -> McpResult<ReturnType> {
    // Implementation
}
```

--------------------------------

### Install Rust Linter (Bash)

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/DEVELOPMENT.md

Command to install the clippy linter, which helps catch common mistakes and improve Rust code quality. This is a component managed by rustup.

```bash
rustup component add clippy
```

--------------------------------

### Basic Server Testing Commands

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/TROUBLESHOOTING.md

Essential commands for interacting with the server binary, including displaying help information and version details. These are fundamental for initial verification and understanding the server's capabilities.

```bash
/path/to/server --help
/path/to/server --version
```

--------------------------------

### Rust API Client Server with Async Operations

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/GETTING_STARTED.md

Implements an HTTP client as a tool for an MCP server. It uses the `ToolHandler` trait to perform asynchronous GET requests. Dependencies include `prism-mcp-rs`, `reqwest`, `async-trait`, `tokio`, and `serde_json`.

```rust
use prism_mcp_rs::prelude::*;
use reqwest::Client;
use async_trait::async_trait;
use std::collections::HashMap;

#[derive(Clone)]
struct HttpTool {
    client: Client,
}

#[async_trait]
impl ToolHandler for HttpTool {
    async fn call(&self, arguments: HashMap<String, Value>) -> McpResult<ToolResult> {
        let url = arguments.get("url")
            .and_then(|v| v.as_str())
            .ok_or_else(|| McpError::invalid_request("Missing URL parameter"))?;
        
        match self.client.get(url).send().await {
            Ok(response) => {
                let text = response.text().await
                    .map_err(|e| McpError::internal_error(format!("HTTP response error: {}", e)))?;
                
                Ok(ToolResult {
                    content: vec![ContentBlock::text(text)],
                    is_error: Some(false),
                    meta: None,
                    structured_content: None,
                })
            }
            Err(e) => Err(McpError::internal_error(format!("HTTP request failed: {}", e)))
        }
    }
}

#[tokio::main]
async fn main() -> McpResult<()> {
    let mut server = McpServer::new(
        "api-client".to_string(), 
        "1.0.0".to_string()
    );
    
    // For async operations, create Tool with ToolHandler
    let schema = json!({
        "type": "object",
        "properties": {
            "url": {"type": "string", "description": "URL to fetch"}
        },
        "required": ["url"]
    });
    
    let http_tool = Tool::new(
        "http_get".to_string(),
        Some("Make HTTP GET request".to_string()),
        schema,
        HttpTool { client: Client::new() }
    );
    
    server.add_tool(http_tool);
    server.start().await
}

```

--------------------------------

### Rust Server Initialization

Source: https://github.com/prismworks-ai/prism-mcp-rs/blob/main/docs/README.md

Example of initializing an McpServer in Rust using the Prism MCP SDK. It demonstrates setting a name, version, and configuring authentication, rate limiting, and health checks.

```rust
use prism_mcp_rs::server::McpServer;

let server = McpServer::builder()
    .name("production-server")
    .version("2.0.0")
    .with_auth(auth_config)
    .with_rate_limiting(rate_limit_config)
    .with_health_check(health_config)
    .build()?;
```