nomad_mcp/CLAUDE.md

# CLAUDE.md - Guide for AI Coding Agents

## Project Overview
Nomad MCP is a service that enables management of HashiCorp Nomad jobs via REST API, with Claude AI integration.

## Commands
- **Run server**: `uvicorn app.main:app --reload --host 0.0.0.0 --port 8000`
- **Tests**: `pytest` (all) or `pytest tests/test_nomad_service.py::test_job_lifecycle` (single)
- **Build docker**: `docker build -t nomad-mcp .`
- **Run docker**: `docker-compose up -d`

## Code Style
- **Imports**: Standard library → Third-party → Local modules (alphabetically)
- **Type annotations**: Required for all function parameters and returns
- **Error handling**: Use try/except with proper logging and HTTP exceptions
- **Logging**: Use Python's logging module with appropriate levels
- **API responses**: Return consistent JSON structures with Pydantic models
- **Docstrings**: Required for all functions and classes
- **Variables**: snake_case for variables, CamelCase for classes

## Structure
- `/app`: Main code (/routers, /schemas, /services)
- `/configs`: Configuration files
- `/static`: Frontend assets
- `/tests`: Test files

Always maintain backward compatibility with existing API endpoints. Follow REST principles.

## Enhanced Log Analysis Features

The logs API has been enhanced with advanced filtering and analysis capabilities:

### REST API Endpoints:
- `/api/logs/job/{job_id}` - Enhanced with time, level, and search filtering
- `/api/logs/errors/{job_id}` - Get only error/warning logs  
- `/api/logs/search/{job_id}` - Search logs for specific terms
- `/api/logs/repository/{repository}` - Get logs by repository name

### New Query Parameters:
- `start_time` & `end_time` - Filter by time range (HH:MM format)
- `log_level` - Filter by levels (ERROR, WARNING, INFO, etc.)
- `search` - Search for specific terms
- `lines` - Limit number of lines returned
- `formatted` - Proper line breaks (default: true)

### MCP Tools Available:
- `get_job_logs` - Enhanced with all filtering options
- `get_error_logs` - Convenience tool for troubleshooting
- `search_job_logs` - Search logs for patterns

### Example Usage:
```bash
# Get errors between 8pm-6am for plant-manager in production
curl "https://nomad_mcp.dev.meisheng.group/api/logs/errors/plant-manager?namespace=production&start_time=20:00&end_time=06:00"

# Search for pump issues
curl "https://nomad_mcp.dev.meisheng.group/api/logs/search/plant-manager?q=pump&namespace=production"

# Get last 50 lines with proper formatting  
curl "https://nomad_mcp.dev.meisheng.group/api/logs/job/plant-manager?namespace=production&lines=50&formatted=true"
```

Always maintain backward compatibility with existing API endpoints. Follow REST principles.

## SSL Certificate Management for Internal Services

When working with internal/corporate services that use custom Certificate Authorities (CAs):

### Problem
- Internal services use SSL certificates signed by custom/corporate CAs
- System trust stores don't recognize these CAs
- Results in `SSL: CERTIFICATE_VERIFY_FAILED` errors

### Solution: Extract and Configure CA Bundle

1. **Extract CA Certificate Chain**:
   ```bash
   # Find the CA issuer from certificate details
   openssl s_client -connect your-service.internal:443 -showcerts
   
   # Download CA certificate (adjust URL for your PKI)
   curl -k "https://vault.internal:8200/v1/pki/ca" -o certs/ca_bundle.pem
   ```

2. **Test CA Bundle**:
   ```bash
   # Test with curl
   curl --cacert certs/ca_bundle.pem https://your-service.internal
   
   # Test with Python
   python -c "import requests; print(requests.get('https://your-service.internal', verify='certs/ca_bundle.pem').status_code)"
   ```

3. **Create Environment Configuration**:
   ```bash
   # .env.ssl
   export SSL_CERT_FILE="$(pwd)/certs/ca_bundle.pem"
   export REQUESTS_CA_BUNDLE="$(pwd)/certs/ca_bundle.pem"
   export CURL_CA_BUNDLE="$(pwd)/certs/ca_bundle.pem"
   export GIT_SSL_CAINFO="$(pwd)/certs/ca_bundle.pem"
   ```

4. **Usage**:
   ```bash
   # Load SSL configuration
   source .env.ssl
   
   # Now all tools use the CA bundle automatically
   curl https://your-service.internal
   git clone https://git.internal/repo.git
   pip install -i https://pypi.internal/simple/ package
   ```

### For Different Tools

- **Curl**: `curl --cacert path/to/ca_bundle.pem`
- **Python requests**: `requests.get(url, verify='path/to/ca_bundle.pem')`
- **Git**: `git config http.sslCAInfo path/to/ca_bundle.pem`
- **Node.js**: `NODE_EXTRA_CA_CERTS=path/to/ca_bundle.pem`
- **Docker**: Mount certs and set `SSL_CERT_FILE` environment variable

### Environment Variables Priority
1. `SSL_CERT_FILE` - Used by most SSL libraries
2. `REQUESTS_CA_BUNDLE` - Python requests library
3. `CURL_CA_BUNDLE` - curl command
4. Tool-specific variables (e.g., `GIT_SSL_CAINFO`)

### Best Practices
- **Keep CA bundle in version control** (it's public key material)
- **Test SSL connections** with a script to verify setup
- **Document certificate renewal process** in project README
- **Use environment variables** for consistent configuration across tools
- **Never disable SSL verification** in production code

This approach provides proper SSL security while working with internal services.