mcp-tool-catalog

Generate human-readable docs for any MCP server's tools.

An MCP server exposes its tools programmatically through tools/list, but there is rarely a clean, human-friendly document describing what those tools do and what arguments they take. mcp-tool-catalog launches a server, performs the MCP handshake, reads its tool surface, and renders a tidy Markdown or HTML catalog: one section per tool, with a parameter table and descriptions.

Great for READMEs, onboarding, PR reviews, and keeping a living record of what an agent can actually do.

Part of the AAIF (Agentic AI Innovation Foundation) open-source toolset for the agentic AI ecosystem.

Highlights

• Works with any stdio MCP server, not a specific implementation.
• Markdown output with a table of contents and per-tool parameter tables.
• Self-contained HTML output for sharing.
• Standard library only. No pip dependencies, no markdown engine.

Install

pip install -e .

Requires Python 3.9 or newer.

Usage

Pass the command that launches your server after --:

mcp-tool-catalog -- mcp-mock-server --config examples/weather.json

Write HTML to a file:

mcp-tool-catalog --format html -o catalog.html -- mcp-mock-server

Write Markdown to a file:

mcp-tool-catalog -o TOOLS.md -- python my_server.py

Example output

For a server exposing a get_forecast tool, the Markdown looks like:

# weather-mock — tool catalog

**Server version:** 1.0.0
**Protocol:** 2025-06-18
**Tools:** 1

## `get_forecast`

Return a canned weather forecast for a city.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `city` | string | yes |  |

How it works

mcp-tool-catalog includes a minimal stdio JSON-RPC client. It sends initialize, the notifications/initialized acknowledgement, then tools/list, and renders the returned tool definitions. It never calls tools, so it is safe to run against servers with side effects.

Development

pip install -e .
pytest

Tip: mcp-mock-server (a companion project) is a convenient target for trying this out without a real backend.

License

MIT. See LICENSE.