Directives MCP Server

A tiny MCP (Model Context Protocol) server that serves your engineering directives (AGENT.md and any other markdown documents) to every Claude Code instance on your machine, from a single Docker container on an uncommon local port.

Register it once with user scope; after that, any Claude Code session in any project can call get_directives and work under your rules — no copying files between repositories.

How it fits together

┌─────────────────────────┐
│ 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
└─────────────────────────┘

Project layout

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)

Setup (one time)

# 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

Inside any Claude Code session you can also run /mcp to confirm the server and its tools are visible. Newly added servers are picked up when a session starts, so restart Claude Code (or start a new session) after registering.

Tools exposed

Tool	Purpose
get_directives()	Returns the full master AGENT.md
get_section(query, document?)	Returns section(s) whose heading matches, e.g. get_section("commit")
get_document(name)	Returns any document in docs/ by name
list_documents()	Inventory of available documents
health()	Liveness check

Verifying it works

# 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

End-to-end — connect over MCP and list/call the tools. Pick one of these; --network host (Linux) and host.docker.internal (Docker Desktop) are alternatives and must not be combined:

# 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

Directing Claude Code to use it

Put this one line in each project's CLAUDE.md (this is the entire per-project footprint):

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.

Or just say it in the prompt: "Load my directives from the directives MCP server, then execute Sprint 0."

Updating your directives

Edit files in ./docs/ — the directory is volume-mounted read-only into the container, so changes are live immediately. No rebuild, no restart. Add more documents (e.g. CHECKLIST.md, LARAVEL_MAPPING.md) by dropping them into docs/; they become available through get_document at once.

Operations

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

Notes

• Port 49721 is deliberately uncommon and bound to 127.0.0.1 only, so the server is unreachable from your network. If you ever want it reachable from other machines, change the bind and add an auth header — do not expose it unauthenticated.
• The container runs as an unprivileged user (uid 10001) and the docs volume is mounted read-only.
• The --scope user registration lives in ~/.claude.json, so it applies to every project without touching any repo. Use --scope project instead if you want a specific repo to carry the registration in a committable .mcp.json.