scaffold-mcp-tool

A checklist for adding a tool without forgetting any of the six places it needs to land. The substrate tool discipline is set by ADR 0001 (docs/decisions/0001-chronometric-tool-design.md); newer servers follow the same pattern.

Servers in scope:

• packages/mcp-chronometric/
• packages/mcp-cognitive-graph/
• packages/mcp-guardrail/
• packages/mcp-task-fractionator/
• packages/mcp-translation/

(Native-host and CLI tools are out of scope here — different bindings.)

When to use

• Adding a new MCP tool to an existing server.
• Reviewing a PR that claims to add a new tool, to make sure nothing was

skipped.

What it does

Walks through the six required edits, in order. The skill does not perform the edits — it surfaces the checklist and the canonical examples to follow.

1. Author the schema

Add packages/mcp-<server>/schemas/<tool_name>.schema.json. Use one of these as a template:

• packages/mcp-cognitive-graph/schemas/record_fact.schema.json (input

with $ref defs, output, errors, examples, compatibility)

• packages/mcp-task-fractionator/schemas/decompose.schema.json (array

output, dependency model, error vocabulary)

• packages/mcp-translation/schemas/translate_incoming.schema.json (LLM

provenance, eval-corpus slice reference)

Required top-level keys: $schema, $id, title, description, version, properties.input, properties.output, errors, examples, compatibility.

2. Implement the handler

Add packages/mcp-<server>/src/<package>/tools/<tool_name>.py. Look at packages/mcp-cognitive-graph/src/neurodock_mcp_cognitive_graph/tools/record_fact.py for the shape: typed Pydantic models, a single async def handle(input, ctx), explicit error raising mapped to the schema's errors block.

3. Register the tool

Add the handler to packages/mcp-<server>/src/<package>/server.py in the tool registration block. The MCP server enumerates handlers; an unregistered handler is dead code.

4. Add tests

Add at least packages/mcp-<server>/tests/test_<tool_name>.py with:

• One happy-path test per examples[] in the schema.
• One negative-path test per errors.* key.
• One side-effect test if the tool mutates state (e.g. record_fact's

auto-create entities).

5. ADR delta (if signature changes)

If the tool's existence or signature affects the substrate design, update the relevant ADR under docs/decisions/. Per ADR 0001, "new tools are added by extending the schema set; renames or required-param additions require a new ADR." For purely additive tools, a one-line note in the existing ADR's "Tool inventory" section is enough.

6. CHANGELOG entry

Append to packages/mcp-<server>/CHANGELOG.md under a new ## Unreleased section. Use the version-impact skill before opening the PR to confirm the bump kind matches the change.

How to invoke

This skill is a checklist, not a script. Read it before starting the work and again at the end as a self-review pass.

If a generator script is later added (e.g. scripts/scaffold-mcp-tool.sh), the steps above remain authoritative — the script is convenience, not the contract.

Limitations

• No generator exists yet; all six steps are manual.
• The skill does not check that the schema's $id URL is unique across

servers — duplicate $ids will cause confusing validator errors elsewhere.

• The skill assumes Python servers. The convention for any future TypeScript

MCP server (none today) would differ.

Voice

This is a procedure, not a creative brief. List the steps, name the canonical examples, then stop. The contributor reading this is already mid-task and does not want philosophy about why MCP tools exist.