MCP-Typescribe - 一个提供 LLMs API 信息的 MCP 服务器

问题

大型语言模型（LLMs）在代码生成和开发人员生产力方面取得了惊人的进展。然而，它们面临一个关键限制：它们只能可靠地使用在训练过程中见过的 API 和库。这为采用新工具、SDK 或内部 API 创造了一个瓶颈——LLMs 简单地不知道如何有效地使用它们。

虽然可以给工具提供源代码访问（当与有源代码可用的 API 交互时）或文档文件访问（例如 TypeScript 类型定义文件），但这对于大型 API 来说并不容易扩展。LLMs 需要一种更有效的方式来了解 API。将所有文档放入每个请求的上下文中是低效的、不可行的，并且会导致糟糕的结果。

结果：

较大的新 API 或内部 API 对 LLMs 来说是“不可见”的。

开发人员必须手动指导 LLMs 或提供示例用法。

由于 API 发布与其被 AI 工具广泛理解之间存在滞后，创新被放缓。

想法

这个项目是一个开源实现，实现了 Model Context Protocol (MCP)——一种旨在为 LLMs 提供上下文、实时信息访问的协议。在这个项目中，它主要是 API 文档，特别是 TypeScript 定义。

我们的目标是：

将 TypeScript（及其他）定义解析为机器可读格式。

通过诸如 Claude、Cline、Cursor 或 Windsurf 以及其他自定义接口等工具动态地将这些上下文提供给 LLMs。

通过让 LLMs 查询、计划和适应不熟悉的 API 而无需重新训练来实现代理行为。

这使得

即插即用的 API 支持，适用于基于 LLM 的编码助手。

新 SDK 或专有 SDK 的更快上手。

向更自主、上下文感知的编码代理迈出一步。

项目概述

这个项目提供了一种方法，使 AI 代理能够高效地探索和理解未知的 TypeScript API。它加载 TypeDoc 生成的 JSON 文档并通过一组查询端点暴露出来，允许代理搜索符号、获取关于 API 特定部分的详细信息，并理解不同组件之间的关系。

当前功能

• TypeDoc 集成：加载并索引 TypeDoc JSON 文档以进行高效查询
• 全面的查询能力：提供了广泛的工具来探索 TypeScript API
• MCP 协议：遵循 Model Context Protocol 以无缝集成 AI 代理

查询能力

服务器提供了以下工具来查询 API：

- **符号搜索**：允许代理搜索特定符号。
- **详细信息获取**：提供关于 API 特定部分的详细信息。
- **关系理解**：帮助代理理解不同组件之间的关系。

请注意，上述翻译保留了原始 Markdown 格式，并且没有更改任何代码块或链接内容。

• search_symbols: 按名称查找符号，并可选按种类过滤
• get_symbol_details: 获取特定符号的详细信息
• list_members: 列出类或接口的方法和属性
• get_parameter_info: 获取函数参数的信息
• find_implementations: 查找接口或子类的实现
• search_by_return_type: 查找返回特定类型的函数
• search_by_description: 在 JSDoc 注释中搜索
• get_type_hierarchy: 显示继承关系
• find_usages: 查找类型/函数的使用位置

开始使用

前提条件

• Node.js
• npm

安装

1. 克隆仓库
2. 安装依赖项：

   npm install
   

使用

1. 为您的 TypeScript API 生成 TypeDoc JSON：

   npx typedoc --json docs/api.json --entryPointStrategy expand path/to/your/typescript/files
   

   如果您（仅）有一个现有的.d.ts文件，您可以这样创建一个 api json 文件：

   创建一个单独的 tsconfig.docs.json：

   {
     "extends": "./tsconfig.json",
     "files": ["existing.d.ts"],
     "typedocOptions": {
       "entryPoints": ["existing.d.ts"],
       "json": "docs/api.json",
       "pretty": false
     }
   }
   

   然后执行

   npx typedoc --tsconfig tsconfig.docs.json
   

2. 构建项目：

   npm run build
   

3. 探索 MCP 服务器：

   npx @modelcontextprotocol/inspector node ./dist/mcp-server/index.js run-server docs/api.json
   

4. 将 AI 代理连接到服务器以查询 API

   例如，在 VSCode 中使用 cline，在 cline_mcp_settings.json 中指定以下 MCP 服务器：

   {
     "mcpServers": {
       "typescribe": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-typescribe@latest",
           "run-server",
           "<PATH_TO_API_DOT_JSON>"
         ],
         "env": {}
       }
     }
   }
   

5. 启用服务器并可能自动批准各种工具。告诉代理使用“typescribe”工具来了解您的 API。

项目结构

• src/sample-api/：用于测试的示例 TypeScript API - 它使用一种类似德语的方言来命名 API，以测试 LLM 是否不会对 API 产生幻觉
• src/mcp-server/：MCP 服务器实现
  • utils/：实用函数
  • schemas/：MCP 工具的 JSON 模式
  • core/：核心功能
  • server.ts：MCP 服务器实现
  • index.ts：入口点
• tests/：API 功能的测试

开发

运行测试

npm test

构建

npm run build

许可证

MIT

版权所有 2025 yWorks GmbH - https://www.yworks.com