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:

# 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:

   # 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:

   # 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:

   # .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:

   # 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.