# 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

```bash
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:

```python
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
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).