Update README.md
This commit is contained in:
249
CLAUDE_API_INTEGRATION.md
Normal file
249
CLAUDE_API_INTEGRATION.md
Normal file
@ -0,0 +1,249 @@
|
||||
# Claude Integration with Nomad MCP
|
||||
|
||||
This document explains how to configure Claude to connect to the Nomad MCP service and manage jobs.
|
||||
|
||||
## Overview
|
||||
|
||||
The Nomad MCP service provides a simplified REST API specifically designed for Claude to interact with Nomad jobs. This API allows Claude to:
|
||||
|
||||
1. List all jobs in a namespace
|
||||
2. Get the status of a specific job
|
||||
3. Start, stop, and restart jobs
|
||||
4. Create new jobs with a simplified specification
|
||||
5. Retrieve logs from jobs
|
||||
|
||||
## API Endpoints
|
||||
|
||||
The Claude-specific API is available at the `/api/claude` prefix. The following endpoints are available:
|
||||
|
||||
### List Jobs
|
||||
|
||||
```
|
||||
GET /api/claude/list-jobs?namespace=development
|
||||
```
|
||||
|
||||
Returns a list of all jobs in the specified namespace with their IDs, names, statuses, and types.
|
||||
|
||||
### Manage Jobs
|
||||
|
||||
```
|
||||
POST /api/claude/jobs
|
||||
```
|
||||
|
||||
Manages existing jobs with operations like status check, stop, and restart.
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"job_id": "example-job",
|
||||
"action": "status|stop|restart",
|
||||
"namespace": "development",
|
||||
"purge": false
|
||||
}
|
||||
```
|
||||
|
||||
### Create Jobs
|
||||
|
||||
```
|
||||
POST /api/claude/create-job
|
||||
```
|
||||
|
||||
Creates a new job with a simplified specification.
|
||||
|
||||
Request body:
|
||||
```json
|
||||
{
|
||||
"job_id": "example-job",
|
||||
"name": "Example Job",
|
||||
"type": "service",
|
||||
"datacenters": ["jm"],
|
||||
"namespace": "development",
|
||||
"docker_image": "nginx:latest",
|
||||
"count": 1,
|
||||
"cpu": 100,
|
||||
"memory": 128,
|
||||
"ports": [
|
||||
{
|
||||
"Label": "http",
|
||||
"Value": 0,
|
||||
"To": 80
|
||||
}
|
||||
],
|
||||
"env_vars": {
|
||||
"ENV_VAR1": "value1",
|
||||
"ENV_VAR2": "value2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Job Logs
|
||||
|
||||
```
|
||||
GET /api/claude/job-logs/{job_id}?namespace=development
|
||||
```
|
||||
|
||||
Retrieves logs from the latest allocation of the specified job.
|
||||
|
||||
## Configuring Claude Desktop Application
|
||||
|
||||
To configure Claude to connect to the Nomad MCP service, follow these steps:
|
||||
|
||||
### 1. Set Up API Access
|
||||
|
||||
Claude needs to be configured with the base URL of your Nomad MCP service. This is typically:
|
||||
|
||||
```
|
||||
http://your-server-address:8000
|
||||
```
|
||||
|
||||
### 2. Create a Claude Tool Configuration
|
||||
|
||||
In the Claude desktop application, you can create a custom tool configuration that allows Claude to interact with the Nomad MCP API. Here's a sample configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{
|
||||
"name": "nomad_mcp",
|
||||
"description": "Manage Nomad jobs through the MCP service",
|
||||
"api_endpoints": [
|
||||
{
|
||||
"name": "list_jobs",
|
||||
"description": "List all jobs in a namespace",
|
||||
"method": "GET",
|
||||
"url": "http://your-server-address:8000/api/claude/list-jobs",
|
||||
"params": [
|
||||
{
|
||||
"name": "namespace",
|
||||
"type": "string",
|
||||
"description": "Nomad namespace",
|
||||
"required": false,
|
||||
"default": "development"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"name": "manage_job",
|
||||
"description": "Manage a job (status, stop, restart)",
|
||||
"method": "POST",
|
||||
"url": "http://your-server-address:8000/api/claude/jobs",
|
||||
"body": {
|
||||
"job_id": "string",
|
||||
"action": "string",
|
||||
"namespace": "string",
|
||||
"purge": "boolean"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "create_job",
|
||||
"description": "Create a new job",
|
||||
"method": "POST",
|
||||
"url": "http://your-server-address:8000/api/claude/create-job",
|
||||
"body": {
|
||||
"job_id": "string",
|
||||
"name": "string",
|
||||
"type": "string",
|
||||
"datacenters": "array",
|
||||
"namespace": "string",
|
||||
"docker_image": "string",
|
||||
"count": "integer",
|
||||
"cpu": "integer",
|
||||
"memory": "integer",
|
||||
"ports": "array",
|
||||
"env_vars": "object"
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "get_job_logs",
|
||||
"description": "Get logs for a job",
|
||||
"method": "GET",
|
||||
"url": "http://your-server-address:8000/api/claude/job-logs/{job_id}",
|
||||
"params": [
|
||||
{
|
||||
"name": "namespace",
|
||||
"type": "string",
|
||||
"description": "Nomad namespace",
|
||||
"required": false,
|
||||
"default": "development"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Import the Tool Configuration
|
||||
|
||||
1. Open the Claude desktop application
|
||||
2. Go to Settings > Tools
|
||||
3. Click "Import Tool Configuration"
|
||||
4. Select the JSON file with the above configuration
|
||||
5. Click "Save"
|
||||
|
||||
### 4. Test the Connection
|
||||
|
||||
You can test the connection by asking Claude to list all jobs:
|
||||
|
||||
```
|
||||
Please list all jobs in the development namespace using the Nomad MCP service.
|
||||
```
|
||||
|
||||
Claude should use the configured tool to make an API request to the Nomad MCP service and return the list of jobs.
|
||||
|
||||
## Example Prompts for Claude
|
||||
|
||||
Here are some example prompts you can use with Claude to interact with the Nomad MCP service:
|
||||
|
||||
### List Jobs
|
||||
|
||||
```
|
||||
Please list all jobs in the development namespace.
|
||||
```
|
||||
|
||||
### Check Job Status
|
||||
|
||||
```
|
||||
What is the status of the job "example-job"?
|
||||
```
|
||||
|
||||
### Start a New Job
|
||||
|
||||
```
|
||||
Please create a new job with the following specifications:
|
||||
- Job ID: test-nginx
|
||||
- Docker image: nginx:latest
|
||||
- Memory: 256MB
|
||||
- CPU: 200MHz
|
||||
- Port mapping: HTTP port 80
|
||||
```
|
||||
|
||||
### Stop a Job
|
||||
|
||||
```
|
||||
Please stop the job "test-nginx" and purge it from Nomad.
|
||||
```
|
||||
|
||||
### Get Job Logs
|
||||
|
||||
```
|
||||
Show me the logs for the job "example-job".
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If Claude is unable to connect to the Nomad MCP service, check the following:
|
||||
|
||||
1. Ensure the Nomad MCP service is running and accessible from Claude's network
|
||||
2. Verify the base URL in the tool configuration is correct
|
||||
3. Check that the Nomad MCP service has proper connectivity to the Nomad server
|
||||
4. Review the logs of the Nomad MCP service for any errors
|
||||
|
||||
## Security Considerations
|
||||
|
||||
The Claude API integration does not include authentication by default. If you need to secure the API:
|
||||
|
||||
1. Add an API key requirement to the FastAPI application
|
||||
2. Include the API key in the Claude tool configuration
|
||||
3. Consider using HTTPS for all communications between Claude and the Nomad MCP service
|
||||
Reference in New Issue
Block a user