CodeRoot-Authoring-MCP

An MCP server that captures an agentic asset's foundational record while the asset is being built. It writes and maintains a single file, asset-record.json, at the root of the repository being built — creation facts (language, framework, runtime, direct dependencies, repository identity) plus three facts only the author can assert (created_by, maintained_by, model_access.mode). The file is committed alongside the code and read downstream (by CodeRoot) as declared provenance. It never affects how the asset is classified.

This server has no configuration, no network access, and no secrets. It reads and writes one JSON file in a directory the caller names.

The record contract

{
  "record_version": 1,
  "created_by": "settletop-niles",
  "created_at": "2026-08-09T00:00:00Z",
  "source_repo": {"host": "github.com", "owner": "SettleTop-Inc", "name": "example"},
  "maintained_by": "SettleTop-Inc",
  "technologies": {
    "language": "python",
    "framework": "mcp",
    "runtime": "python>=3.11",
    "dependencies": ["mcp", "httpx"]
  },
  "model_access": {"mode": "byo", "provider": null, "model": null},
  "confirmation": {
    "mode": "elicitation",
    "confirmed": ["created_by", "maintained_by", "model_access.mode"],
    "complete": true
  }
}

• record_version is required and always 1.
• model_access.mode is "pinned" or "byo"; pinned requires a non-null provider and model, byo forces both null.
• technologies.dependencies is DIRECT dependencies only (not the resolved tree) — at most 50 entries, 100 chars each.
• Every string field must be non-blank and at most 200 chars.
• Unknown top-level keys are ignored (forward compatible).

This is a summary. The machine-readable contract — the one the server itself validates against — is served live via the record://schema resource (and identically by the get_record_schema tool), so a client can always fetch the current shape instead of trusting a copy in this file.

Tools

Tool	Arguments	Returns
get_record_schema	—	RECORD_SCHEMA (the JSON-Schema-shaped contract) directly
record_facts	patch: dict, directory: str = "."	{"record": ..., "missing": [...]} on success, {"error": "<code>", ...} on rejection
read_record	directory: str = "."	{"record": ..., "missing": [...]} on success (an empty record if no file exists yet), {"error": "<code>", ...} on rejection
finalize_record	confirmations: dict, directory: str = ".", mode: str = "conversation"	{"record": ..., "missing": []} on success, {"error": "<code>", ...} on rejection — rejection writes nothing

record_facts deep-merges its patch into the existing record and is meant to be called repeatedly, as each fact is decided during the build. finalize_record is the only tool that marks a record complete: it requires the author's own confirmation of created_by, maintained_by, and model_access.mode, and refuses to write anything if the resulting record would be invalid or a confirmation is missing.

There is also a record://schema resource (identical to get_record_schema) and a create_asset_record prompt that walks the capture → review → confirm workflow end to end.

Install

claude mcp add coderoot-authoring -- uv run --directory <path-to-this-repo> python -m authoring.server

Replace <path-to-this-repo> with wherever you've cloned CodeRoot-Authoring-MCP. The server talks stdio and needs no environment variables, tokens, or network access. Installing the package also exposes a coderoot-authoring-mcp console script (authoring.server:main), an equivalent entry point to python -m authoring.server for clients that prefer to invoke it directly.

Skill

skills/creating-agentic-assets/SKILL.md teaches an agent to use this server proactively while building a new asset — capture facts as they're decided, finalize before the first push, and never assert the author-only fields on the author's behalf. Install it by copying or symlinking the skill directory into ~/.claude/skills/:

ln -s "$(pwd)/skills/creating-agentic-assets" ~/.claude/skills/creating-agentic-assets

(On Windows, copy the directory instead of symlinking, or use mklink /D from an elevated shell.)

Confirmation modes

finalize_record supports two ways to get the author's confirmation of the three author-only fields:

• mode="conversation" (the default, and the floor) — the calling agent asks the author in the conversation, in its own words, and passes their answers in confirmations. This works with any MCP client, since it needs no special capability, and is what the skill instructs agents to use unless the client is known to support interactive prompting (see "Client support" below).
• mode="elicitation" — the server asks the client to prompt the author directly, via a typed elicitation request (AuthorConfirmation). Prefer it only for a client you know supports interactive prompting: over MCP, a client that hasn't declared form-elicitation capability gets a protocol-level error (JSON-RPC -32021) before the tool body even runs, and as of this writing the interactive accept path has not been observed live for any client (see "Client support" below — only the cancel path has, over Claude Code headless). The {"error": "confirmation_unavailable", ...} shape only occurs for in-process/direct invocation, not over MCP.

Either way, the confirmation is checked against what was actually passed to finalize_record in that call — a value written earlier via record_facts is never treated as a confirmation of itself.

Client support

Live findings, Claude Code headless (claude -p --mcp-config, 2026-08-09):

• Instructions: injected. A fresh instance quoted the server's instructions first sentence verbatim, unprompted, and listed all four tools — the ambient contract reaches the agent on this client.
• Elicitation: capability declared. finalize_record(mode="elicitation") did not hit the JSON-RPC -32021 capability error; the elicit request went through, the non-interactive harness cancelled it, and the server returned {"error": "confirmation_cancelled"} with nothing written — the cancel path verified over the real wire.
• Interactive accept path: not yet observed live. The SDK-level accept flow is covered end-to-end by this repo's tests (a real in-memory client answering the elicitation); whether interactive Claude Code renders the form to a human author remains to be confirmed the first time this server is used in a live interactive session. Until then, mode="conversation" stays the default and the floor — see "Confirmation modes" above.

Development

Requires Python >= 3.11.

uv sync --extra dev
uv run pytest -q

152 tests, all green.

License

GPL-3.0-or-later. See LICENSE.

Security

This server handles no secrets: no tokens, no credentials, no network calls. Its filesystem authority is broader than a single fixed file, though: the directory argument every tool takes is unrestricted — absolute paths and .. segments are honored as given, a missing directory is created rather than rejected, and an existing asset-record.json at the target is merged into rather than refused. The server runs with exactly the privileges of the client that launched it — the MCP client is the trust boundary, not this server — and what bounds what can be written is that the filename is never caller-controlled: every write lands at <directory>/asset-record.json, always that exact basename.