Implement FastAPI MCP zero-config integration

- Add fastapi_mcp to provide automatic MCP tooling from API endpoints
- Create MCP request/response schema models
- Update main.py to initialize FastAPI MCP with zero config
- Add comprehensive MCP integration documentation
- Update README with zero-config MCP integration information

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2025-04-15 11:50:55 +07:00
parent 403fa50b4f
commit ba9201dfa6
5 changed files with 250 additions and 87 deletions

135
MCP_INTEGRATION.md Normal file
View File

@ -0,0 +1,135 @@
# MCP Integration Guide
Nomad MCP provides seamless integration with AI assistants through the Model Context Protocol (MCP), enabling AI agents to interact with your Nomad cluster directly.
## What is the Model Context Protocol (MCP)?
The Model Context Protocol (MCP) is a standardized way for AI agents to interact with external tools and services. It allows AI models to call specific functions and receive structured responses, which they can then incorporate into their reasoning and responses.
## Zero-Config MCP Integration
Nomad MCP uses FastAPI MCP to automatically expose all API endpoints as MCP tools with zero configuration. This means that all endpoints in the REST API are immediately available as MCP tools without any manual definition or configuration.
### Connection Endpoint
AI assistants can connect to the MCP endpoint at:
```
http://your-server:8000/mcp/sse
```
The SSE (Server-Sent Events) transport is used for communication between the AI agent and the MCP server.
### Available Tools
All the endpoints in the following routers are automatically exposed as MCP tools:
- **Jobs**: Managing Nomad jobs (start, stop, restart, etc.)
- **Logs**: Retrieving job and allocation logs
- **Configs**: Managing job configurations
- **Repositories**: Working with code repositories
Each endpoint is converted to an MCP tool with:
- Proper parameter validation
- Detailed descriptions
- Type information
- Example values
### Example MCP Interactions
Here are some examples of how an AI agent might use the MCP tools:
#### Listing Jobs
```json
{
"type": "tool_call",
"content": {
"name": "list_jobs",
"parameters": {
"namespace": "development"
}
}
}
```
#### Getting Job Status
```json
{
"type": "tool_call",
"content": {
"name": "get_job_status",
"parameters": {
"job_id": "my-service"
}
}
}
```
#### Starting a Job
```json
{
"type": "tool_call",
"content": {
"name": "start_job",
"parameters": {
"job_id": "my-service",
"namespace": "development"
}
}
}
```
## Setting Up Claude with MCP
### 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:
```bash
claude-code --mcp-url http://your-server:8000/mcp/sse
```
### Claude API Integration
For integration with the Claude API, you can use the MCP toolchain configuration provided in the `claude_nomad_tool.json` file.
See the [Claude API Integration Documentation](CLAUDE_API_INTEGRATION.md) for more detailed instructions.
## Debugging MCP Connections
If you're having issues with MCP connections:
1. Check the server logs for connection attempts and errors
2. Verify that the `BASE_URL` environment variable is correctly set
3. Ensure the AI agent has network access to the MCP endpoint
4. Check that the correct MCP endpoint URL is being used
5. Verify the AI agent supports the SSE transport for MCP
## Custom Tool Configurations
While the zero-config approach automatically exposes all endpoints, you can customize the MCP tools by modifying the FastAPI MCP initialization in `app/main.py`:
```python
mcp = FastApiMCP(
app,
base_url=base_url,
name="Nomad MCP Tools",
description="Tools for managing Nomad jobs via MCP protocol",
include_tags=["jobs", "logs", "configs", "repositories"],
# Add custom configurations here
)
```
## Security Considerations
The MCP endpoint provides powerful capabilities for managing your Nomad cluster. Consider implementing:
1. Authentication for the MCP endpoint
2. Proper network isolation
3. Role-based access control
4. Audit logging for MCP interactions
By default, the MCP endpoint is accessible without authentication. In production environments, you should implement appropriate security measures.