Mcp Server Tools

When to Use

• Adding, removing or renaming an inbound MCP tool, or changing its description, arguments, annotations or scopes.
• Changing a token scope, its label or blurb, the expiry presets or the token prefix.

For a tool RedAmon's OWN agent calls (outbound, mcp/servers/), use agentic-tool-integration. For making a recon setting writable over MCP, use project-settings-cascade. The tools that exist are listed by the server itself and by the generated reference page, never by this skill.

Critical Rules

• ALWAYS run npm run docs:mcp in webapp/ after any change this skill's trigger names, and commit MCP-API-Reference.md inside the redamon.wiki repo. A main-repo commit moves only the submodule pointer. The page is rendered by apiReference.ts; a hand edit is overwritten by the next run.
• NEVER set destructiveHint: false on a tool that overwrites or aborts existing state. In the MCP spec false means only additive updates, and clients use it to decide when to ask the user first. No test checks this.
• ALWAYS add an EXAMPLE_EXTRA_ARGS entry in apiReference.ts when a tool's body requires an argument its JSON Schema marks optional. The generated example sends only schema-required arguments, and the test calls every example.
• ALWAYS give a new tool an ONBOARDING_PLAYBOOK entry and a capability area in playbook.ts. The Agent Onboarding pack is generated from the live tools/list, and a coverage test in onboarding.test.ts fails the moment a tool ships without whenToUse + gotchas, or sits in zero or two capability areas. Also decide whether any profile in profiles.ts should leansOn it; that half is editorial and is not enforced.
• A tool that reads NO backend must be added to BACKEND_FREE_TOOLS in apiReference.test.ts. That file proves a tool's declared scopes are enough by calling it and expecting the generic database failure, because every Prisma model is mocked away. A tool derived purely from constants (describe_recon_settings, list_recon_presets) SUCCEEDS instead, and would otherwise read as a failure. Do not relax the assertion; name the tool.

Pattern: registering a tool

Copy the shape of an existing registerTool call in server.ts: annotations, _meta: scopesMeta({ required, conditional }) naming exactly the scopes the tool body enforces with requireScope, and inputSchema. A scope that applies only to a particular argument goes under conditional, and the arguments that trigger it need a CONDITIONAL_TRIGGERS entry in apiReference.test.ts.

Commands

bashCopy code
cd webapp
npm run docs:mcp                 # rewrites ../redamon.wiki/MCP-API-Reference.md
npx vitest run src/lib/mcp/      # scope, example-call, onboarding-coverage and stale-page checks

cd ../redamon.wiki
git add MCP-API-Reference.md
git commit -m "docs: regenerate MCP API reference"

Resources

• MCP-Server.md, section "Regenerating the API reference" - what the page is built from, and the stale-page test
• README.MCP.SERVER.md - security model, settings allowlist, deploy wiring; §3.1-3.2 cover Agent Profiles (never an authorization input) and how the onboarding pack is generated
• Related skills: agentic-tool-integration, project-settings-cascade, redamon-testing