┌─────────────────────────┐
│ Docker: directives-mcp  │  serves ./docs/*.md via MCP
│ 127.0.0.1:49721/mcp     │  (streamable HTTP transport)
└───────────▲─────────────┘
            │ registered once: claude mcp add --scope user
┌───────────┴─────────────┐
│ Any Claude Code session │  tools: get_directives, get_section,
│ in any project          │         get_document, list_documents, health
└─────────────────────────┘

directives-mcp-server/
├── server.py            # the MCP server (FastMCP, streamable-HTTP)
├── requirements.txt     # exact runtime pin used by the Docker build (mcp==1.28.1)
├── pyproject.toml       # project metadata + ruff config
├── Dockerfile           # slim, non-root image
├── docker-compose.yml   # one-command build + run, localhost-only
├── .dockerignore        # keeps the build context minimal
├── .gitignore
├── .gitattributes       # pins line endings (LF for Docker/shell, CRLF for .ps1)
├── docs/
│   └── AGENT.md         # THE served directives — single source of truth
├── test_server.py       # offline smoke tests of the tool logic
├── verify_client.py     # end-to-end MCP reachability check
├── register.ps1         # register with Claude Code (Windows)
└── register.sh          # register with Claude Code (macOS/Linux/Git Bash)

# 1. Build and start the container
docker compose up -d --build

# 2. Register with Claude Code — user scope = available in ALL projects
#    (or run ./register.sh  /  ./register.ps1)
claude mcp add --transport http --scope user directives http://127.0.0.1:49721/mcp

# 3. Verify Claude Code can reach it
claude mcp list          # directives should show ✓ Connected

# Offline unit tests of the tool logic (runs in the built image, no network):
docker run --rm -v "$PWD:/work" -w /work --entrypoint python \
  directives-mcp:latest test_server.py

# Simplest (any OS): run the checker directly on the host.
pip install -r requirements.txt      # once, e.g. into a venv
python verify_client.py

# From a container — Linux hosts only (host networking reaches the published port):
docker run --rm --network host -v "$PWD:/work" -w /work --entrypoint python \
  directives-mcp:latest verify_client.py

# From a container — Windows/macOS (Docker Desktop): use the default bridge and
# reach the host via host.docker.internal. Do NOT add --network host here.
docker run --rm -e MCP_URL=http://host.docker.internal:49721/mcp \
  -v "$PWD:/work" -w /work --entrypoint python \
  directives-mcp:latest verify_client.py

Before any work in this repository, call the `directives` MCP server's
`get_directives` tool and follow the returned document as the authoritative
source for code standards, sprint structure, modularization, commit
discipline, and clarification protocol. Re-read relevant sections with
`get_section` when starting a sprint task.

docker compose logs -f directives    # watch requests
docker compose restart directives    # restart
docker compose down                  # stop
claude mcp remove directives         # unregister from Claude Code