add-tool

Context

Tools use the tool() builder from @cyanheads/mcp-ts-core. Each tool lives in src/mcp-server/tools/definitions/ with a .tool.ts suffix. The standard registration pattern uses a definitions/index.ts barrel that collects all tools into an allToolDefinitions array for createApp(). Fresh scaffolds from init start with direct imports in src/index.ts — the barrel is introduced as definitions grow. Match the pattern already used by the project you're editing.

Steps

1. Gather the tool's name, purpose, and input/output shape from the user's request — ask only if genuinely absent
2. Determine if it needs input the caller may not supply — a confirmation, a choice, the client's roots — which makes it a multi-round-trip handler (ctx.requestInput / ctx.inputs, see api-context)
3. Create the file at src/mcp-server/tools/definitions/{{tool-name}}.tool.ts
4. Register the tool in the project's existing createApp() tool list (directly in src/index.ts for fresh scaffolds, or via a barrel if the repo already has one)
5. Run bun run devcheck to verify — it applies Biome's formatting fixes as it runs
6. Smoke-test with bun run rebuild && bun run start:stdio < /dev/null (or start:http) — the Core services constructed log record must list the new tool in its tools field (the message text shows only counts); if it doesn't, the tool never reached createApp()

Naming

Tools use lowercase snake_case with a canonical server/domain prefix, {server}_{verb}_{noun} by default. Drop the noun only when the verb is a complete action on its own (git_pull, git_status): if {server}_{verb} leaves "…what?" unanswered — search what? connect to what? — the noun is missing. The full rule is the Name row of the design-mcp-server Design table.

Examples: pubmed_search_articles, pubmed_fetch_fulltext, clinicaltrials_find_eligible.

The server prefix is judged on clarity, not length: the brand name or the plain well-known word for the domain both pass (pubmed_, patents_); an abbreviation fails only when it reads as something else out of context (loc_, ct_). A fourth segment is fine when the noun is inherently two words (openfda_search_device_clearances). When a name resists the schema — can't pick a verb, noun feels generic, the verb wants a second word — that's usually a signal the scope is fuzzy; split the tool, rename, or reconsider.