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.

The creation workflow

The new_asset prompt is a twelve-step workflow for building a new MCP server or agent: decide what it does, whether it is really an agent, what it must never do, how you will know it worked, what it can use and when it stops — then make the repo, build, test on real work, containerise, prove the same tests pass inside the image, and ship a tag. The first six get worse if asked after a scaffold exists, which is why the order is enforced rather than suggested.

Two tools hold your place, so you are not tracking twelve steps by hand:

Tool	Arguments	Returns
next_step	directory: str = "."	{"step": <int>, "title": ..., "asks": ..., "done": [...], "remaining": [...]}, or {"complete": true}
complete_step	step: int, answer: str, directory: str = "."	{"recorded": <int>, "next": {...}}, or {"error": "<code>", ...}

They read and write WORKFLOW.md at the repo root — the checklist is the state, so the place you are up to survives a session ending or someone picking the work up a week later. complete_step refuses a step whose predecessors are unanswered (E_OUT_OF_ORDER), refuses a blank answer, and does not count a ticked box with nothing under it.

WORKFLOW.md is committed with the code and is the account of why the asset is the way it is. asset-record.json remains the facts of record — the file anything downstream reads. The workflow calls record_facts at steps 7 and 8 and finalize_record at step 12, so following it produces both.

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), the new_asset prompt above, and a create_asset_record prompt that walks the capture → review → confirm sequence on its own for an asset built without the full workflow.

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

On Windows PowerShell, brace the variable — bare $PWD: is a PowerShell parser error (it reads : as a drive/scope qualifier) — so use ${PWD}:

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

${PWD} is captured when you run claude mcp add, so run it from the repo you want to author (or replace it with an explicit path, e.g. "C:\path\to\repo:/work").

Local checkout (uv):

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

Make it global, and reload. claude mcp add defaults to local scope — the server is available only in the directory you ran it in, so it won't appear in a session for a different project. Add --scope user to register it for every project. MCP servers connect when a session starts, so restart Claude Code (or open a new chat) after adding — a mid-session add won't show until then.

Confirm it connected. Run the /mcp command inside Claude Code (there is no MCP menu or button — /mcp lists each server, its connection status, and its tools), or claude mcp list in a terminal:

claude mcp list

coderoot-authoring should show as connected, and inside a Claude Code session its six tools — next_step, complete_step, 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:

Name	Required?	Meaning
(environment variables)	—	None. The server reads no environment variables, tokens, or credentials, and makes no network calls.
-v "<host-repo>:/work" (docker)	Docker only	Bind-mounts the repo being authored into the container so writes survive the container exiting.
-w /work (docker)	Recommended	Makes the mount the container's working directory, so the tools' default directory="." lands in your repo. Otherwise pass directory="/work".
directory (tool argument)	No (default .)	Every tool takes it; the record is always written to <directory>/asset-record.json. Local (uv) runs resolve . against the server process's working directory.

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.