mcp-tool-card-generator

Generate spec-conformant MCP Tool Cards from an MCP server's tools/list. It bootstraps a per-tool safety/disclosure profile — side-effect class, reversibility, PII and secret exposure — so you start from a reviewed draft instead of a blank file.

Implements the mcp-tool-card-spec (tool_card_version 0.1). Pairs with mcp-registry-risk-scanner (scan a manifest for risk → generate the per-tool disclosures) in the Kinetic Gain MCP governance lane.

Why

A Tool Card is the per-tool disclosure a reviewer reads before trusting an MCP tool: what it touches, whether it's reversible, whether it can expose PII or secrets, whether it needs human approval. Authoring those by hand for a 30-tool server is tedious and error-prone. This generator reads the server's tools/list, infers a conservative safety profile from each tool's name and description, and emits a valid card skeleton per tool — you review and tighten, rather than write from scratch.

The inference is deliberately cautious: unknown verbs default to mutating, anything matching delete/drop/purge is destructive (and the spec then forces human_approval_required: true), and PII/secret keywords raise exposure. It is a starting point for human review, not an authority.

Install

npm install -g mcp-tool-card-generator   # CLI
npm install mcp-tool-card-generator      # library

Requires Node ≥ 20.

CLI

# print a JSON array of cards
mcp-toolcard-gen tools.json \
  --server-id io.github.acme/billing \
  --server-uri https://mcp.acme.example/billing

# write one <tool>.json per tool, ready for /.well-known/mcp-tools/
mcp-toolcard-gen tools.json \
  --server-id io.github.acme/billing \
  --server-uri https://mcp.acme.example/billing \
  --out ./well-known/mcp-tools

tools.json is an MCP tools/list result: { "tools": [{ "name", "description", "inputSchema" }, ...] }.

Library

import { generateCards } from "mcp-tool-card-generator";

const cards = generateCards(toolsListResult, {
  serverId: "io.github.acme/billing",
  serverUri: "https://mcp.acme.example/billing"
});
for (const { filename, card } of cards) {
  // card.safety.side_effect_class, card.safety.human_approval_required, ...
}

What gets inferred

Field	How it's inferred
safety.side_effect_class	keyword match → destructive / mutating / external / read; unknown → mutating
safety.reversible	true only for read tools
safety.human_approval_required	true for destructive (spec invariant), else false
safety.pii_exposure	medium when name/description mention PII terms, else none
safety.secrets_exposure	reads_secret_material when secret/token/key terms appear, else none
schema.input_schema_inline	copied from the tool's inputSchema

Everything else (tested_with, performance, cost, audit details) is left for you to fill in.

License

AGPL-3.0-or-later — see LICENSE.