agentsclimarketplace

Scaffold mcp tool

Skill tlennon-ie/neurodock/.claude/skills/scaffold-mcp-tool

Walk through adding a new tool to one of the six MCP servers under packages/mcp-*. Touches schema, handler, registration, tests, ADR delta, CHANGELOG.From its SKILL.md

Install
npx -y skills add tlennon-ie/neurodock --skill scaffold-mcp-tool

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 20 stars20 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.8 KB, as published. Nobody here has run it

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.

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.