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.

Related MCP server: tatastu-proof

Tools

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

Two ways to run it: a prebuilt container from GHCR, or straight from a local checkout with uv. Both speak MCP over stdio and both write asset-record.json into a directory you name. Nothing else — no environment variables, no tokens, no network.

Run with Docker (GHCR)

The image is published to GitHub Container Registry as ghcr.io/settletop-inc/coderoot-authoring-mcp, but the package is private, so authenticate once on this machine before pulling — otherwise docker pull / docker run returns 403:

# One-time. Use a GitHub Personal Access Token (classic) with the
# read:packages scope as the password.
docker login ghcr.io -u <github-username>
# Or, with the gh CLI:
#   gh auth refresh -s read:packages && gh auth token | docker login ghcr.io -u <github-username> --password-stdin

Then run the server against the repo you are authoring. Because it writes into a directory, bind-mount that repo and attach stdin:

docker run --rm -i -w /work -v "$PWD:/work" ghcr.io/settletop-inc/coderoot-authoring-mcp

• -i attaches stdin — required for a stdio MCP server; without it the server has no channel to speak on and exits immediately.

• -v "$PWD:/work" mounts the repo being authored into the container, so the asset-record.json the server writes lands on your host and survives the container exiting.

• -w /work makes /work the container's working directory, so the tools' default directory="." resolves to your mounted repo. The image's own working directory is /app, which is not mounted; without -w /work a tool called with the default . writes inside the container and the file is lost on exit. So either pass -w /work as shown, or call the tools with an explicit directory="/work". (Every tool also accepts an arbitrary directory argument, so the agent can target any repo path directly.)

On Windows, use ${PWD} in PowerShell or %CD% in cmd.exe in place of $PWD.

Tags: :latest and :sha-<short> track main; a release is tagged :vX.Y.Z. No -e flags are needed — this server reads no environment.

Run locally (uv)

Straight from a checkout, no container:

uv run --directory <path-to-this-repo> python -m authoring.server

Replace <path-to-this-repo> with wherever you've cloned CodeRoot-Authoring-MCP. 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. The server talks stdio and needs no environment variables, tokens, or network access.

Use with Claude Code

Register the server with claude mcp add. Claude Code launches it as a subprocess and speaks MCP over its stdin/stdout, so the whole launch command goes after the --.

Docker (private GHCR image — run docker login ghcr.io first, see above):

claude mcp add coderoot-authoring -- docker run --rm -i -w /work -v "$PWD:/work" ghcr.io/settletop-inc/coderoot-authoring-mcp

Local checkout (uv):

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

Then confirm it connected:

claude mcp list

coderoot-authoring should show as connected, and inside a Claude Code session its four tools — record_facts, read_record, finalize_record, get_record_schema — plus the create_asset_record prompt become available.

Configuration

There is nothing to configure: authoring/server.py constructs the server at import with no settings to read, no config file, and no secrets. The only things that decide where the record is written are the bind mount and the directory argument the tools already take:

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.