nomad_mcp/README.md

# Nomad MCP

A service that enables AI agents (like Claude) to manage HashiCorp Nomad jobs via MCP (Machine Control Protocol).

## Features

- Associate code repositories with Nomad job definitions
- Start, stop, and update Nomad jobs
- Retrieve allocation logs and build errors
- Simple configuration system for mapping repositories to jobs
- RESTful API for AI agent interaction
- Gitea integration for repository validation and discovery
- **Web UI for job management and monitoring**
- **Claude AI integration for natural language job control**

## Getting Started

### Prerequisites

- Python 3.8+
- HashiCorp Nomad cluster
- Nomad ACL token with appropriate permissions
- (Optional) Gitea instance for repository integration

### Installation

1. Clone this repository
2. Install dependencies:
   ```
   pip install -r requirements.txt
   ```
3. Copy `.env.example` to `.env` and configure the environment variables
4. Run the service:
   ```
   uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
   ```

### Docker Deployment

You can also run the service using Docker:

```bash
# Build and run with docker-compose
docker-compose up -d

# Or build and run manually
docker build -t nomad-mcp .
docker run -p 8000:8000 --env-file .env -v ./configs:/app/configs nomad-mcp
```

## Configuration

### Environment Variables

Key environment variables to configure:

#### Nomad Configuration
- `NOMAD_ADDR` - URL of your Nomad server (e.g., `http://nomad.internal:4646`)
- `NOMAD_TOKEN` - ACL token for Nomad API authentication
- `NOMAD_NAMESPACE` - Default namespace for Nomad operations (e.g., `development`)
- `NOMAD_SKIP_VERIFY` - Set to `true` to skip SSL verification (for self-signed certs)

#### Gitea Configuration
- `GITEA_API_URL` - URL of your Gitea API (e.g., `http://gitea.internal/api/v1`)
- `GITEA_API_TOKEN` - Personal access token for Gitea API
- `GITEA_VERIFY_SSL` - Set to `false` to skip SSL verification for internal Gitea

### Repository-Job Mappings

Job configurations are stored in YAML files in the `configs` directory. Each configuration maps a repository to a Nomad job.

Example configuration file (`configs/my-service.yaml`):

```yaml
repository: http://gitea.internal.example.com/username/repo-name
repository_alias: my-service
job_id: my-service
description: Example service managed by MCP
meta:
  owner: ai-team
  environment: development
```

## Web UI

The service includes a web-based user interface for managing Nomad jobs. The UI provides the following features:

- View all jobs across different namespaces
- Check job status and details
- View job logs (stdout and stderr)
- Restart and stop jobs
- Filter jobs by namespace

To access the UI, navigate to the root URL of the service (e.g., `http://localhost:8000`).

![Nomad Job Manager UI](docs/ui_screenshot.png)

## Claude AI Integration

The service includes a specialized API for Claude AI to interact with Nomad jobs using natural language. This allows Claude to:

1. List all jobs in a namespace
2. Get the status of specific jobs
3. Start, stop, and restart jobs
4. Create new jobs with simplified specifications
5. Retrieve job logs

### Claude Tool Configuration

To configure Claude to use the Nomad MCP service, use the provided `claude_nomad_tool.json` configuration file. This file defines the API endpoints and parameters that Claude can use to interact with the service.

For detailed instructions on setting up Claude with the Nomad MCP service, see the [Claude API Integration Documentation](CLAUDE_API_INTEGRATION.md).

## API Documentation

Once running, API documentation is available at:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## API Usage Examples

### Manage Jobs

```bash
# List all jobs
curl http://localhost:8000/api/jobs

# Get a specific job
curl http://localhost:8000/api/jobs/my-service

# Start a job
curl -X POST http://localhost:8000/api/jobs/my-service/restart

# Stop a job
curl -X DELETE http://localhost:8000/api/jobs/my-service
```

### Manage Configurations

```bash
# List all configurations
curl http://localhost:8000/api/configs

# Create a configuration
curl -X POST http://localhost:8000/api/configs/link \
  -H "Content-Type: application/json" \
  -d '{"repository": "http://gitea.internal.example.com/username/repo-name", "job_id": "service", "repository_alias": "service"}'
```

### Repository Management

```bash
# List available repositories
curl http://localhost:8000/api/repositories

# Get repository information
curl http://localhost:8000/api/repositories/my-service

# Get repository branches
curl http://localhost:8000/api/repositories/my-service/branches
```

### Get Logs

```bash
# Get logs for a job
curl http://localhost:8000/api/logs/job/my-service?plain_text=true

# Get build logs for a job
curl http://localhost:8000/api/logs/build/my-service?plain_text=true
```

### Claude API Endpoints

```bash
# List all jobs in a namespace
curl http://localhost:8000/api/claude/list-jobs?namespace=development

# Get job status
curl -X POST http://localhost:8000/api/claude/jobs \
  -H "Content-Type: application/json" \
  -d '{"job_id": "my-service", "action": "status", "namespace": "development"}'

# Create a new job
curl -X POST http://localhost:8000/api/claude/create-job \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "test-nginx",
    "docker_image": "nginx:latest",
    "memory": 256,
    "cpu": 200,
    "ports": [{"Label": "http", "Value": 0, "To": 80}]
  }'

# Get job logs
curl http://localhost:8000/api/claude/job-logs/my-service?namespace=development
```

## Troubleshooting

### Common Issues

1. **Connection to Nomad fails**:
   - Verify that the `NOMAD_ADDR` environment variable is correct
   - Check that the Nomad server is accessible from the service
   - Ensure that the `NOMAD_TOKEN` has appropriate permissions

2. **Jobs fail to start**:
   - Check the job specification format
   - Verify that the namespace exists and is accessible
   - Look for resource constraints or policy violations

3. **UI doesn't load**:
   - Ensure that the service is running with the correct host and port
   - Check browser console for JavaScript errors
   - Verify that the static files are being served correctly

### Logs

The service logs provide detailed information about operations and errors. By default, logs are output to the console. You can adjust the log level using the `LOG_LEVEL` environment variable.

## For AI Agents

If you're an AI agent (like Claude) using this API, here are the main endpoints you'll likely use:

1. **Repository Management**:
   - `GET /api/repositories` - List available repositories
   - `GET /api/repositories/{repository}` - Get repository details

2. **Job Management**:
   - `GET /api/jobs/by-repository/{repository}` - Get job info by repository
   - `POST /api/jobs/by-repository/{repository}/start` - Start a job
   - `POST /api/jobs/by-repository/{repository}/stop` - Stop a job
   - `POST /api/jobs/by-repository/{repository}/restart` - Restart a job

3. **Logs**:
   - `GET /api/logs/repository/{repository}` - Get logs for a repository's job
   - `GET /api/logs/build/{job_id}` - Get build logs for a job

4. **Configuration**:
   - `POST /api/configs/link` - Link a repository to a job

5. **Claude-Specific API**:
   - `GET /api/claude/list-jobs` - List all jobs in a namespace
   - `POST /api/claude/jobs` - Manage existing jobs
   - `POST /api/claude/create-job` - Create a new job
   - `GET /api/claude/job-logs/{job_id}` - Get logs for a job

The repository parameter can be either the full repository URL or the repository alias configured in the mapping.

## License

This project is licensed under the MIT License - see the LICENSE file for details.