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