Agent Registry MCP
# Agent Registry MCP
Shared engineering context and dynamic project memory for AI coding agents.
This project follows the attached Agent Registry architecture:
- Git owns governed artifacts: skills, canonical context, policies, hooks, profiles, teams, and registry configuration.
- PostgreSQL owns dynamic knowledge: feature memory, decision memory, observations, known issues, recent changes, provenance, lifecycle, and stale markers.
- MCP is the runtime interface used by Claude, Copilot, Codex, and other agents.
- Memory is not automatically canonical; it moves through `OBSERVED -> CANDIDATE -> VERIFIED -> CANONICAL -> DEPRECATED`.
- No vector database is used in the MVP.
## Run With Docker Compose
```bash
docker compose up --build
```
You can copy `.env.example` to `.env` when you want to override local defaults.
Services:
- PostgreSQL: `localhost:5432`
- MCP server container: `agent-registry-mcp`
The server reads governed context from `.claude/` and dynamic memory from PostgreSQL.
## Local Development
```bash
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
python -m unittest discover -s tests/agent_registry_mcp
ruff check .
```
## MCP Tools
Implemented MVP tools:
- `project_detect`
- `project_register`
- `project_get`
- `context_get`
- `context_search`
- `skill_search`
- `skill_get`
- `skill_resolve`
- `memory_register`
- `memory_search`
- `memory_get`
- `memory_recent`
- `registry_status`
- `agent_status`
Tools that modify shared memory require a server-side API key with the required role.
Each client project should register its stable slug and locally computed ProjectModel
with `project_register(api_key=..., ...)` at the start of an agent session. The server stores that
identity in PostgreSQL; subsequent memory reads and writes must use the same
`project_slug`. The server does not need the client repository mounted to share
dynamic memory between sessions.
## Server-Side Roles
Configure API keys with `REGISTRY_API_KEYS`:
```text
REGISTRY_API_KEYS=member-token:MEMBER,lead-token:LEAD
```
`MEMBER` can read, search, resolve, capture, and register candidate memory.
`LEAD` can additionally promote, deprecate, and publish governed state in future commands.
Never commit real API keys. `.env.example` contains only placeholders.
## Connect Claude Code
See [docs/claude-connect.md](docs/claude-connect.md).
## AI Project Index
Agents should start with [PROJECT_INDEX.md](PROJECT_INDEX.md) to understand the repository
layout, MCP connection contract, project-scoped memory sharing pattern, and CLI bootstrap
template.
TDQS
Scored across 15 tools
Most tools clearly target a distinct resource+action pair (context/skill/project/memory/agent), and parallel search/get operations across resources are reasonably distinguishable. However, skill_resolve versus skill_get is ambiguous without descriptions, and memory_get versus memory_recent plus context_search versus context_get have overlapping retrieval semantics that an agent could easily misselect.
All 15 tools use consistent snake_case with a resource-first, action-second pattern (e.g. context_search, skill_get, memory_register, project_detect). The two *_status tools (registry_status, agent_status) fit the same resource_action convention rather than deviating from it.
15 tools is at the upper end but well-scoped for a registry spanning six resource domains (context, skill, project, memory, registry, agent), with roughly 2-3 tools per domain and no obvious redundancy.
The surface covers registration, lookup, and search for some resources, and memory has a full lifecycle including memory_transition. But there is no skill_register, no context_register, no update/delete operations for projects or contexts, and agent support is limited to a single status tool, leaving notable lifecycle gaps.