acdl/mcp/atelier/README.md

Nova Atelier MCP Server

exposes Atelier engineering principles to the citizen developer's AI agent. Plugin-registry architecture; stdio transport; vendored Atelier for audit reproducibility.

What This Is

The server exposes 4 tools that let a citizen developer's AI coding agent look up production-grade engineering principles and validate code against them — agentic validation that goes beyond deterministic scanners (Wiz, Checkmarx, Mend) by catching correctness, clarity, simplicity, and observability gaps.

Tools

Tool	Description
atelier.lookup_principle(domain, principle_id)	Look up a principle by domain + P-rule ID (e.g., security, P4). Returns the principle text + the core C-rule it derives from.
atelier.list_domains()	List the 19 Atelier domains with P-rule counts + Nova-relevance.
atelier.matrix_lookup(domain)	Look up the domain→core principle mapping for a given domain.
atelier.validate_against_principles(snippet, domains?)	Validate a code/diff snippet against the Atelier agent-checklist. Returns pass/fail per check item with the principle citation.

Architecture — Plugin Registry

mcp/atelier/
├── server.py              # entrypoint: loads plugins, starts server
├── plugins/
│   ├── __init__.py
│   ├── principles.py       # lookup_principle, list_domains, matrix_lookup
│   └── validation.py       # validate_against_principles
├── vendor/                 # pinned Atelier snapshot
│   ├── VERSION.md           # pinned tag + upgrade instructions
│   ├── core/first-principles.md
│   ├── domains/security/first-principles.md
│   ├── review/agent-checklist.md
│   └── matrix/principles-matrix.md
└── README.md               # this file

Each plugin module exposes register(mcp) -> None and calls @mcp.tool() for its tools. server.py scans plugins/ and calls register on each. Future capabilities drop in as a new plugin file — no server.py edits.

Running

With the MCP Python SDK installed

pip install "mcp[cli]"
python3 -m mcp.atelier.server

The server runs over stdio. An MCP client (e.g., the citizen developer's AI coding agent) spawns it as a subprocess and calls tools via JSON-RPC.

Without the SDK (fallback / test mode)

The server degrades to a plain-Python tool registry. Tools are callable directly — this is how tests run without the SDK installed:

from mcp.atelier.server import NovaAtelierServer
s = NovaAtelierServer()
s.load_plugins()
result = s.call_tool("atelier_lookup_principle", {"domain": "security", "principle_id": "P4"})

Vendoring

Atelier is vendored under vendor/ at a pinned tag (v0.3.6, see vendor/VERSION.md). An agentic validation result is only reproducible if the principles that produced it are pinned. Live-fetch breaks replayability (Atelier main drifts). To upgrade:

bash scripts/update_atelier_vendor.sh <new-tag>

Extensibility

To add a new tool (e.g., a cost-estimation tool, a policy-as-code evaluator): create plugins/<name>.py, expose register(mcp), and call @mcp.tool() on your function. The server picks it up automatically. No server.py edit. This is the extensibility insurance for future capabilities.

Transport

• Now: stdio (local agent consumption — the citizen developer's AI agent spawns the server as a subprocess).
• Future: Streamable HTTP (the MCP SDK supports it on the same MCPServer object; adding it is a transport-only change in server.py, not a rewrite).