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.

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.