📚 Update documentation with complete MCP integration guide
- 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 <noreply@anthropic.com>
This commit is contained in:
@ -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 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
|
```bash
|
||||||
claude-code --mcp-url http://your-server:8000/mcp/sse
|
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.
|
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
|
## Debugging MCP Connections
|
||||||
|
|
||||||
If you're having issues with MCP connections:
|
If you're having issues with MCP connections:
|
||||||
|
Reference in New Issue
Block a user