anchorage-ecode-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Development Commands

# Install dependencies (uv preferred, pip fallback)
uv sync                              # or: pip install -r requirements.txt

# Run local MCP server (no Lambda needed)
python3 scripts/local_server.py      # Serves on http://localhost:8000/mcp
# Single entry point. It routes through UniversalHTTPHandler, so local dev
# enforces the same Origin allowlist, MCP-Protocol-Version check and
# path/method validation as prod.

# Validate config
python3 -c "from core.validators import load_and_validate_config; load_and_validate_config('config.yaml')"

# Tests
uv run pytest tests/ -n auto                                    # All tests, parallel
uv run pytest tests/test_ckan_plugin.py -v                      # Single file
uv run pytest tests/test_ckan_plugin.py::TestClass::test_name -v  # Single test
uv run pytest tests/ --cov=core --cov=plugins --cov-report=term-missing  # With coverage (80% minimum)

# Linting (ruff)
uv run ruff check core/ plugins/ server/ tests/      # Check
uv run ruff check core/ plugins/ server/ tests/ --fix # Auto-fix
uv run ruff format core/ plugins/ server/ tests/      # Format

# Pre-commit hooks
pre-commit run --all-files

# Go client (requires Go 1.21+)
cd client && make build

# Deploy to AWS
./scripts/deploy.sh --environment staging

Architecture

Core rule: One Fork = One MCP Server. Each deployment runs exactly ONE plugin. This is enforced at config validation time (core/validators.py) and at runtime (PluginManager.load_plugins()). To deploy multiple MCP servers, fork the repo per plugin.

Request flow:

Claude (stdio) → Go client (client/) or stdio_bridge.py → HTTP POST /mcp
  → Lambda (server/adapters/aws_lambda.py) or scripts/local_server.py
  → server/http_handler.py → core/mcp_server.py (JSON-RPC 2.0)
  → core/plugin_manager.py → Plugin → External API

Key modules:

• core/interfaces.py — Abstract bases: MCPPlugin, DataPlugin, plus ToolDefinition, ToolResult, PluginType enum
• core/plugin_manager.py — Discovers plugins by scanning plugins/ and custom_plugins/ for plugin.py files. Registers tools with pluginname__toolname prefix. Routes tools/call to the correct plugin.
• core/mcp_server.py — Handles MCP JSON-RPC methods. Dual-era: legacy revisions (≤2025-11-25) get initialize, tools/list, tools/call, ping on a session; the modern revision (2026-07-28) is stateless — every request carries _meta (protocol version, client info/capabilities), server/discover replaces initialize, results carry resultType and cache hints, and the Streamable HTTP headers (Mcp-Method, Mcp-Name, MCP-Protocol-Version) must mirror the body or the request is a 400/-32020
• core/validators.py — Loads config from config.yaml (local) or OPENCONTEXT_CONFIG env var (Lambda). Enforces single-plugin rule.
• server/adapters/aws_lambda.py — the ONLY AWS Lambda entry point (handler: server.adapters.aws_lambda.lambda_handler), and the only thing Terraform points at.
• server/http_handler.py — Cloud-agnostic HTTP handler shared by Lambda and local server
• stdio_bridge.py — Python stdio-to-HTTP bridge for connecting Claude Desktop/Code to the local server (alternative to Go client)