mcp-typescribe

MCP-Typescribe is an MCP server that loads TypeScript API documentation (via TypeDoc JSON) and exposes rich querying capabilities to AI agents. It provides tools to search for symbols, inspect details, navigate type hierarchies, and discover usages and parameter information, enabling LLMs to understand and reason about a TypeScript API in real time. Typical workflows involve running the server, feeding it a TypeDoc JSON file for your API, and then querying it through the MCP interface to learn about symbols, members, and relationships within the API.

To use the server, start it with the provided run-server entry, point it at your API JSON export, and connect your agent (e.g., via a tool like cline or another MCP client) to issue commands such as search_symbols, get_symbol_details, list_members, find_usages, and get_type_hierarchy. This setup lets AI agents reason about API surface areas, functions, types, and their interconnections without requiring hard-coded knowledge of the API.

Prerequisites:

• Node.js and npm installed on your system
• Git (optional, for cloning the repo)

Installation steps:

1. Install dependencies from the project root: npm install

2. Build the project (if you need a built server for distribution): npm run build

3. Run the MCP server locally (example using the README’s approach): npx @modelcontextprotocol/inspector node ./dist/mcp-server/cli.js run-server docs/api.json

4. Generate or obtain your API JSON (TypeDoc output) and point the server at it when starting or via your MCP client configuration.

5. Connect an AI agent or tool (e.g., cline) to the server using the provided mcpServers configuration and start querying the API.

Tips and notes:

• The server expects a TypeDoc JSON file (docs/api.json in examples) describing your TypeScript API. If you only have a .d.ts, you can generate a TypeDoc JSON with a small docs.json configuration as shown in the README.
• Use the example MCP client settings to integrate with tools like cline: the typescribe server entry is named 'typescribe' in the mcp_servers config.
• Ensure you have compatible Node.js/npm versions and that the mcp-typescribe package version is suitable for your setup (latest is referenced in the command).
• If you encounter permission or path issues, verify that the PATH_TO_API_DOT_JSON points to a valid JSON file and that the server process has read access.
• You can customize environment variables in the mcp_config if you need to adjust logging, authentication, or other runtime options.