From a0bd71e438130ea43e33148fe04f91191de8e322 Mon Sep 17 00:00:00 2001 From: Nicolas Koehl Date: Sat, 31 May 2025 11:17:23 +0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Update=20documentation=20with=20?= =?UTF-8?q?complete=20MCP=20integration=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Enhanced README with new MCP features and setup instructions - Updated MCP_INTEGRATION.md with Claude Desktop configuration - Added network deployment options and security considerations - Fixed README encoding from UTF-16 to UTF-8 - Comprehensive guide for both local and network MCP deployments - Example usage patterns for Claude Desktop integration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- MCP_INTEGRATION.md | 184 ++++++++++++++++++++++++++++++++++++++++++++- README.md | Bin 17458 -> 10720 bytes 2 files changed, 182 insertions(+), 2 deletions(-) diff --git a/MCP_INTEGRATION.md b/MCP_INTEGRATION.md index f407c98..0ea0a80 100644 --- a/MCP_INTEGRATION.md +++ b/MCP_INTEGRATION.md @@ -82,11 +82,96 @@ Here are some examples of how an AI agent might use the MCP tools: } ``` -## Setting Up Claude with MCP +## MCP Integration Options + +Nomad MCP provides two integration approaches: + +### 1. FastAPI MCP Integration (Zero-Config) + +Automatically exposes all REST API endpoints as MCP tools via SSE: + +``` +http://your-server:8000/mcp/sse +``` + +### 2. Standalone MCP Server (Claude Desktop) + +A dedicated MCP server optimized for Claude Desktop with enhanced capabilities. + +## Setting Up Claude Desktop with Standalone MCP Server + +### Prerequisites + +1. **Install Dependencies**: + ```bash + uv venv + uv pip install -r requirements.txt + ``` + +2. **Set Environment Variables**: + ```bash + export NOMAD_ADDR="http://your-nomad-server:4646" + export NOMAD_NAMESPACE="development" # optional + ``` + +### Local Setup + +1. **Configure Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`): + ```json + { + "mcpServers": { + "nomad-mcp": { + "command": "/path/to/nomad_mcp/run_mcp_server.sh", + "env": { + "NOMAD_ADDR": "http://your-nomad-server:4646" + } + } + } + } + ``` + +2. **Restart Claude Desktop** to load the configuration + +### Available MCP Tools + +The standalone MCP server provides these tools: + +- **`list_nomad_jobs`** - List all jobs in a namespace +- **`get_job_status`** - Get detailed job status and health +- **`stop_job`** - Stop jobs with optional purge +- **`restart_job`** - Restart jobs +- **`create_job`** - Create jobs from specifications +- **`submit_job_file`** ⭐ - Submit Nomad job files (JSON/HCL) +- **`get_job_logs`** - Retrieve stdout/stderr logs +- **`get_allocation_status`** ⭐ - Detailed allocation monitoring +- **`get_job_evaluations`** ⭐ - Placement failure analysis +- **`force_evaluate_job`** ⭐ - Retry failed placements + +### Example Workflow + +1. **Submit a job file**: + ``` + Please submit this job file: [paste JSON job spec] + ``` + +2. **Monitor deployment**: + ``` + Check the status and allocations for my-service + ``` + +3. **Debug issues**: + ``` + Get evaluations for my-service to see why it failed + ``` + +4. **Force retry**: + ``` + Force evaluate my-service to retry placement + ``` ### Claude Code Integration -Claude Code can directly connect to the MCP endpoint at `http://your-server:8000/mcp/sse`. Use the `--mcp-url` flag when starting Claude Code: +Claude Code can directly connect to the FastAPI MCP endpoint: ```bash claude-code --mcp-url http://your-server:8000/mcp/sse @@ -98,6 +183,101 @@ For integration with the Claude API, you can use the MCP toolchain configuration See the [Claude API Integration Documentation](CLAUDE_API_INTEGRATION.md) for more detailed instructions. +## Network Deployment + +### Running MCP Server on Nomad Cluster + +You can deploy the MCP server itself on your Nomad cluster for centralized access. + +#### Option 1: FastAPI MCP Server (HTTP/SSE) + +Deploy the full FastAPI application with MCP endpoint: + +```bash +# Start the FastAPI server with MCP endpoint +uvicorn app.main:app --host 0.0.0.0 --port 8000 +``` + +**Access via**: `http://your-nomad-server:8000/mcp/sse` + +#### Option 2: Standalone MCP Server (TCP/Network) + +For network access to the standalone MCP server, you'll need to modify it to use TCP transport instead of stdio. + +**Current limitation**: The standalone MCP server (`mcp_server.py`) uses stdio transport, which is designed for local process communication. + +**Network solution**: Create a TCP-based version or use the FastAPI MCP endpoint instead. + +### Claude Desktop Network Configuration + +To connect Claude Desktop to a network MCP server: + +#### For FastAPI MCP (Recommended) + +Create a wrapper script that uses the HTTP/SSE endpoint: + +```json +{ + "mcpServers": { + "nomad-mcp-network": { + "command": "npx", + "args": [ + "@modelcontextprotocol/server-everything", + "--url", "http://your-nomad-server:8000/mcp/sse" + ] + } + } +} +``` + +#### For Custom Network MCP Server + +If you need a network-accessible standalone MCP server, you would need to: + +1. **Modify the transport** in `mcp_server.py` from stdio to TCP +2. **Add network security** (authentication, TLS) +3. **Configure Claude Desktop** to connect via TCP + +**Example network MCP server** (requires modification): +```python +# In mcp_server.py - replace stdio with TCP transport +import mcp.server.tcp + +async def main(): + async with mcp.server.tcp.tcp_server("0.0.0.0", 8001) as server: + await server.run(...) +``` + +**Claude Desktop config for network TCP**: +```json +{ + "mcpServers": { + "nomad-mcp-tcp": { + "command": "mcp-client", + "args": ["tcp://your-nomad-server:8001"] + } + } +} +``` + +### Security Considerations for Network Deployment + +When deploying MCP servers on the network: + +1. **Use HTTPS/TLS** for HTTP-based MCP servers +2. **Implement authentication** (API keys, OAuth, etc.) +3. **Network isolation** (VPN, private networks) +4. **Firewall rules** to restrict access +5. **Rate limiting** to prevent abuse +6. **Audit logging** for all MCP operations + +### Recommended Network Architecture + +``` +Claude Desktop → HTTPS/WSS → Load Balancer → FastAPI MCP Server → Nomad API + (secure) (optional) (on cluster) (internal) +``` + ## Debugging MCP Connections If you're having issues with MCP connections: diff --git a/README.md b/README.md index 3f61bd0c41316d8911a0539f74c7b57993f2746a..df4d5bc7219a5fdf85c049b516794d11827538cd 100644 GIT binary patch literal 10720 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