MCP Typescribe

1> [!CAUTION]
2>   Public development is currently suspended as no active community formed. We are working on a follow-up project, specifically for the [yFiles](https://yfiles.com) API. You can read more, here: [yFiles MCP Server](https://www.yfiles.com/the-yfiles-sdk/web/yfiles-for-html/yfiles-mcp-server). yFiles developers can use the MCP to query API, development guides, source code snippets and recipes using those tools, instead. They work far better than the implementation in this repository.
3 
4 
5[![npm version](https://img.shields.io/npm/v/mcp-typescribe.svg)](https://www.npmjs.com/package/mcp-typescribe)
6 
7# MCP-Typescribe - an MCP Server providing LLMs API information
8 
9## The Problem
10 
11Large Language Models (LLMs) have made incredible strides in code generation and developer productivity. However, they face a key limitation: they can only reliably use APIs and libraries they’ve seen during training. This creates a bottleneck for adopting new tools, SDKs, or internal APIs — LLMs simply don’t know how to use them effectively.
12 
13While tools can be given source code access (when interacting with APIs for which the sources are available) or access to documentation files (e.g. typescript type definition files), this doesn't scale well for large APIs. LLMs need a more efficient way to learn more about an API. Putting all the documentation into context for every request is inefficient, unfeasible, and leads to poor results.
14 
15## As a result:
16 
17Larger new or internal APIs remain "invisible" to LLMs.
18 
19Developers must manually guide LLMs or provide example usage.
20 
21Innovation is slowed by the lag between an API’s release and its widespread understanding by AI tools.
22 
23## The Idea
24 
25This project is an open-source implementation of the Model Context Protocol (MCP)—a protocol designed to provide LLMs with contextual, real-time access to information. In this case it's the API documentation, and particularly for now in this project TypeScript definitions.
26 
27## Our goal is to:
28 
29Parse TypeScript (and other) definitions into a machine-readable format.
30 
31Serve this context dynamically to LLMs through tools like Claude, Cline, Cursor, or Windsurf and other custom interfaces.
32 
33Enable agentic behavior by letting LLMs query, plan, and adapt to unfamiliar APIs without retraining.
34 
35## What This Enables
36 
37Plug-and-play API support for LLM-based coding assistants.
38 
39Faster onboarding for new or proprietary SDKs.
40 
41A step toward more autonomous, context-aware coding agents.
42 
43## Project Overview
44 
45![Image](docs/screenshot.png)
46 
47This project provides a way for AI agents to efficiently explore and understand unknown TypeScript APIs. It loads TypeDoc-generated JSON documentation and exposes it through a set of query endpoints that allow agents to search for symbols, get detailed information about specific parts of the API, and understand relationships between different components.
48 
49## Current Features
50 
51- **TypeDoc Integration**: Loads and indexes TypeDoc JSON documentation for efficient querying
52- **Comprehensive Query Capabilities**: Provides a wide range of tools for exploring TypeScript APIs
53- **MCP Protocol**: Follows the Model Context Protocol for seamless integration with AI agents
54 
55## Query Capabilities
56 
57The server provides the following tools for querying the API:
58 
59- `search_symbols`: Find symbols by name with optional filtering by kind
60- `get_symbol_details`: Get detailed information about a specific symbol
61- `list_members`: List methods and properties of a class or interface
62- `get_parameter_info`: Get information about function parameters
63- `find_implementations`: Find implementations of interfaces or subclasses
64- `search_by_return_type`: Find functions returning a specific type
65- `search_by_description`: Search in JSDoc comments
66- `get_type_hierarchy`: Show inheritance relationships
67- `find_usages`: Find where a type/function is used
68 
69## Getting Started
70 
71### Prerequisites
72 
73- Node.js
74- npm
75 
76### Installation
77 
781. Clone the repository
792. Install dependencies:
80   ```bash
81   npm install
82   ```
83 
84### Usage
85 
861. Generate TypeDoc JSON for your TypeScript API:
87 
88   ```bash
89   npx typedoc --json docs/api.json --entryPointStrategy expand path/to/your/typescript/files
90   ```
91 
92   If you (only) have an existing`.d.ts` file, you can create an api json file like so:
93 
94   Create a separate `tsconfig.docs.json`:
95 
96   ```json
97   {
98     "extends": "./tsconfig.json",
99     "files": ["existing.d.ts"],
100     "typedocOptions": {
101       "entryPoints": ["existing.d.ts"],
102       "json": "docs/api.json",
103       "pretty": false
104     }
105   }
106   ```
107 
108   Then do
109 
110   ```bash
111   npx typedoc --tsconfig tsconfig.docs.json
112   ```
113 
1142. Build the project:
115 
116   ```bash
117   npm run build
118   ```
119 
1203. Explore the MCP server:
121 
122   ```bash
123   npx @modelcontextprotocol/inspector node ./dist/mcp-server/cli.js run-server docs/api.json
124   ```
125 
1264. Connect an AI agent to the server to query the API
127 
128   E.g. with cline in VSCode, specify the following MCP server in `cline_mcp_settings.json`:
129 
130   ```json
131   {
132     "mcpServers": {
133       "typescribe": {
134         "command": "npx",
135         "args": [
136           "-y",
137           "mcp-typescribe@latest",
138           "run-server",
139           "<PATH_TO_API_DOT_JSON>"
140         ],
141         "env": {}
142       }
143     }
144   }
145   ```
146 
1475. Enable the server and likely auto-approve the various tools. Tell the agent to use the "typescribe" tool to learn about your API.
148 
149## Project Structure
150 
151- `src/sample-api/`: A sample TypeScript API for testing - it uses a weird German-like dialect for the API names to test that the LLM does not hallucinate the API
152- `src/mcp-server/`: The MCP server implementation
153  - `utils/`: Utility functions
154  - `schemas/`: JSON schemas for the MCP tools
155  - `core/`: Core functionality
156  - `server.ts`: The MCP server implementation
157  - `index.ts`: Entry point for the library exports
158  - `cli.ts`: the entry point for the CLI/binary
159- `tests/`: Tests for the API functionality
160 
161## Development
162 
163### Running Tests
164 
165```bash
166npm test
167```
168 
169### Building
170 
171```bash
172npm run build
173```
174 
175## License
176 
177MIT
178 
179Copyright 2025 yWorks GmbH - https://www.yworks.com
180