TypeScript Definition Finder MCP Server

TypeScript 定义查找器 MCP 服务

一个模型上下文协议（MCP）服务，可帮助 AI 代码编辑器在代码库中查找 TypeScript 符号定义。当你需要在 TypeScript 项目中定位导入符号、类、接口或函数的原始定义时，这个工具特别有用。

功能

• 查找 TypeScript 符号的原始定义
• 支持查找来自外部包的导入符号
• 返回定义位置和代码片段
• 支持 stdio 接口，可与 AI 代码编辑器无缝集成

先决条件

• 已安装 typescript 依赖的 TypeScript 项目
• 用于运行服务的 Node.js

安装和使用

这是一个 Model Context Protocol（MCP）stdio 服务，需要访问本地文件系统以查找 TypeScript 定义。

运行 MCP 服务

使用 MCP 服务：

1. 确保项目已将 TypeScript 安装为依赖
2. 在项目目录中运行以下命令：

npx -y ts-def-mcp@latest

你可以将此命令集成到支持 MCP 的各种 AI 代码编辑器中：

• Claude Desktop
• Claude Code
• Codex
• Cursor
• Windsurf
• Roo Cline Editor

重要说明：由于需要访问本地文件系统，Docker + WebSocket 方案无法使用。

在 Claude Code 中安装

使用 Claude Code CLI 添加服务：

claude mcp add ts-def -- npx -y ts-def-mcp@latest

或者，将其添加到所有项目中（用户范围）：

claude mcp add --scope user ts-def -- npx -y ts-def-mcp@latest

在 Codex 中安装

将服务添加到 Codex MCP 配置（~/.codex/config.toml）：

[mcp_servers.ts-def]
command = "npx"
args = ["-y", "ts-def-mcp@latest"]

工具说明

该服务提供了一个 find_typescript_definition 工具，具有以下功能：

• 工具名称：find_typescript_definition
• 触发命令：/ts-def（如果你想强制让 AI 编辑器查找引用符号的定义，这在 ‘Cursor’ 中很有用）
• 用途：在代码库中定位 TypeScript 符号的原始定义

输入参数

该工具需要三个参数：

1. file_path（字符串）：

   • 当前 TypeScript 文件的绝对路径
   • 示例：/path/to/your/project/src/index.ts

2. symbol（字符串）：

   • 你想查找定义的 TypeScript 符号（变量、类名、接口、类型等）
   • 必须出现在 line_content 中
   • 示例：StdioServerTransport、MyClass、interface1

3. line_content（字符串）：

   • 包含要查找定义的符号的整行内容
   • 用于定位该行在文件中的行号以及符号的准确位置
   • 必须包含与指定内容完全一致的符号

示例

1. 查找导入符号的定义

给定以下导入语句：

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

要查找 StdioServerTransport 的定义，可使用：

{
  "file_path": "~/my-mcp-project/src/index.ts",
  "symbol": "StdioServerTransport",
  "line_content": "import { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";"
}

2. 查找本地符号的定义

对于本地类的用法：

class MyService {
  private transport: StdioServerTransport;
}

要查找 StdioServerTransport 的定义，请使用：

{
  "file_path": "/path/to/project/src/service.ts",
  "symbol": "StdioServerTransport",
  "line_content": "  private transport: StdioServerTransport;"
}

响应格式

该工具返回一个 JSON 响应，其中包含：

• 找到定义的文件路径
• 定义所在的行号
• 定义的实际代码片段

Cursor 调用示例

MCP 输入：

{
  "file_path": "/Users/rossz/workspace/ai-tools/mcp/ts-def-mcp/src/index.ts",
  "symbol": "SSEServerTransport",
  "line_content": "import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';"
}

MCP 输出：

[
  {
    "file": "/Users/rossz/workspace/ai-tools/mcp/ts-def-mcp/node_modules/@modelcontextprotocol/sdk/dist/esm/server/sse.d.ts",
    "type": "Definition",
    "location": "Line 9, Column 22",
    "codeSnippet": "   8    */\n   9 > export declare class SSEServerTransport implements Transport {\n  10 +     private _endpoint;\n  11 +     private res;\n  12 +     private _sseResponse?;\n  13 +     private _sessionId;\n  14 +     onclose?: () => void;\n  15 +     onerror?: (error: Error) => void;\n  16 +     onmessage?: (message: JSONRPCMessage) => void;\n  17 +     /**\n  18 +      * Creates a new SSE server transport, which will direct the client to POST messages to the relative or absolute URL identified by `_endpoint`.\n  19 +      */\n  20 +     constructor(_endpoint: string, res: ServerResponse);\n  21 +     /**\n  22 +      * Handles the initial SSE connection request.\n  23 +      *\n  24 +      * This should be called when a GET request is made to establish the SSE stream.\n  25 +      */\n  26 +     start(): Promise<void>;\n  27 +     /**\n  28 +      * Handles incoming POST messages.\n  29 +      *\n  30 +      * This should be called when a POST request is made to send a message to the server.\n  31 +      */\n  32 +     handlePostMessage(req: IncomingMessage, res: ServerResponse, parsedBody?: unknown): Promise<void>;\n  33 +     /**\n  34 +      * Handle a client message, regardless of how it arrived. This can be used to inform the server of messages that arrive via a means different than HTTP POST.\n  35 +      */\n  36 +     handleMessage(message: unknown): Promise<void>;\n  37 +     close(): Promise<void>;\n  38 +     send(message: JSONRPCMessage): Promise<void>;\n  39 +     /**\n  40 +      * Returns the session ID for this transport.\n  41 +      *\n  42 +      * This can be used to route incoming POST requests.\n  43 +      */\n  44 +     get sessionId(): string;\n  45   }\n"
  }
]

开发

此项目使用 bun v1.2.2 中的 bun init 创建。Bun 是一个快速的一体化 JavaScript 运行时。

在开发模式下运行

开发时，你可以使用 Bun 直接运行服务：

bun run src/index.ts

许可证

[在此处添加许可证信息]

贡献

[在此处添加贡献指南]