Typescript MCP

🚀 typescript-mcp

TypeScript-mcp 为 AI 编码代理提供 TypeScript 类型检查和代码导航功能，由 tsgo 提供支持。

🚀 快速开始

typescript-mcp 是一个 Go 语言编写的 MCP 服务器，它将 模型上下文协议 工具调用与 tsgo 内置的 LSP 服务器连接起来。它使编码代理能够进行真正的 TypeScript 类型检查和代码导航，而无需依赖正则表达式或启发式方法。

服务器会将 tsgo --lsp --stdio 作为子进程启动，通过 JSON-RPC 进行通信，并将 LSP 响应转换为简洁、适合代理的 JSON 格式。

✨ 主要特性

• 为 AI 编码代理提供 TypeScript 类型检查和代码导航功能。
• 借助 tsgo 内置的 LSP 服务器，实现真正的类型检查，不依赖正则或启发式方法。
• 支持多种工具调用，如获取诊断信息、查找定义、悬停提示等。

📦 安装指南

前提条件

• Go 1.24+
• tsgo -- 全局安装或使用 npx：

  npm install -g @typescript/native-preview
  # 或者不安装直接运行：
  npx @typescript/native-preview --version
  

安装方式

使用 go install

go install github.com/paulvanbrenk/typescript-mcp/cmd/typescript-mcp@latest

从源代码构建

git clone https://github.com/paulvanbrenk/typescript-mcp.git
cd typescript-mcp
go build -o typescript-mcp ./cmd/typescript-mcp

为 Claude Code 进行配置

将以下内容添加到你的 MCP 配置文件（.mcp.json 或 Claude Code 设置）中：

{
  "mcpServers": {
    "typescript": {
      "command": "typescript-mcp",
      "args": []
    }
  }
}

如果 typescript-mcp 不在你的 PATH 中，请使用二进制文件的完整路径。

💻 使用示例

工具参考

行号和列号都是 从 1 开始计数。

ts_diagnostics

获取文件的 TypeScript 错误和警告信息。

示例请求：

{
  "file": "/home/user/project/src/index.ts",
  "maxResults": 10
}

示例响应：

{
  "diagnostics": [
    {
      "file": "/home/user/project/src/index.ts",
      "line": 12,
      "column": 5,
      "severity": "error",
      "code": 2322,
      "message": "Type 'string' is not assignable to type 'number'."
    }
  ],
  "totalCount": 1,
  "truncated": false
}

ts_definition

跳转到符号的定义位置。返回符号定义的文件和位置，并提供源行的预览。

示例请求：

{
  "file": "/home/user/project/src/index.ts",
  "line": 10,
  "column": 15
}

示例响应：

[
  {
    "file": "/home/user/project/src/utils.ts",
    "line": 3,
    "column": 17,
    "preview": "export function formatDate(date: Date): string {"
  }
]

ts_hover

获取指定位置符号的类型信息和文档。返回解析后的类型签名。

示例请求：

{
  "file": "/home/user/project/src/index.ts",
  "line": 5,
  "column": 10
}

示例响应（纯文本）：

(property) AppConfig.port: number

响应是从悬停内容中提取的类型签名。会去除 Markdown 代码围栏，只返回类型信息。

ts_references

查找项目中某个符号的所有引用。返回符号使用的每个位置，包括声明位置。

示例请求：

{
  "file": "/home/user/project/src/utils.ts",
  "line": 3,
  "column": 17
}

示例响应：

{
  "references": [
    {
      "file": "/home/user/project/src/utils.ts",
      "line": 3,
      "column": 17,
      "preview": "export function formatDate(date: Date): string {"
    },
    {
      "file": "/home/user/project/src/index.ts",
      "line": 10,
      "column": 15,
      "preview": "const result = formatDate(new Date());"
    }
  ],
  "totalCount": 2,
  "truncated": false
}

ts_document_symbols

获取文件的符号大纲。返回包含所有函数、类、接口和变量及其类型的树结构。

示例请求：

{
  "file": "/home/user/project/src/utils.ts"
}

示例响应：

[
  {
    "name": "formatDate",
    "kind": "function",
    "line": 3,
    "detail": "(date: Date) => string"
  },
  {
    "name": "AppConfig",
    "kind": "interface",
    "line": 8,
    "children": [
      {
        "name": "port",
        "kind": "property",
        "line": 9,
        "detail": "number"
      },
      {
        "name": "host",
        "kind": "property",
        "line": 10,
        "detail": "string"
      }
    ]
  }
]

ts_rename

在整个项目中重命名一个符号。此工具 会写入磁盘 — 包含该符号的所有文件会原子性地更新（失败时会回滚）。应用编辑后，LSP 会重新同步。

示例请求：

{
  "file": "/home/user/project/src/store.ts",
  "line": 42,
  "column": 14,
  "newName": "repository"
}

示例响应：

{
  "newName": "repository",
  "totalEdits": 9,
  "changes": [
    {
      "file": "/home/user/project/src/actions.ts",
      "edits": 8,
      "preview": "import { repository } from '@/lib/store';"
    },
    {
      "file": "/home/user/project/src/store.ts",
      "edits": 1,
      "preview": "export const repository = new Store();"
    }
  ]
}

ts_project_info

获取 TypeScript 项目的配置信息。返回 tsconfig 路径和项目根目录。

示例请求：

{
  "cwd": "/home/user/project"
}

示例响应：

{
  "tsconfigPath": "/home/user/project/tsconfig.json",
  "projectRoot": "/home/user/project"
}

工作流示例

编辑 - 检查 - 修复循环

编辑 TypeScript 文件后，使用 ts_diagnostics 检查类型错误，修复错误，然后再次验证：

1. 编辑文件（例如，更改函数签名）
2. 使用文件路径调用 ts_diagnostics 获取错误信息
3. 修复报告的错误
4. 再次调用 ts_diagnostics 确认没有错误

代码探索

使用符号、悬停提示和跳转到定义功能来浏览不熟悉的代码：

1. 调用 ts_document_symbols 获取文件结构的概述
2. 对感兴趣的符号调用 ts_hover 查看其类型签名
3. 调用 ts_definition 跳转到符号的源定义位置

安全重构

一步完成整个项目中符号的重命名：

1. 使用符号的位置和新名称调用 ts_rename
2. 对受影响的文件调用 ts_diagnostics 验证正确性

或者手动重构时，先查找所有使用位置：

1. 对要更改的符号调用 ts_references
2. 编辑所有返回的位置
3. 对受影响的文件调用 ts_diagnostics 验证正确性

🔧 技术细节

环境变量

开发

构建

go build ./cmd/typescript-mcp

测试

go test ./...

本地运行

# 确保 tsgo 可用
tsgo --version

# 运行 MCP 服务器（通过 stdio 通信）
./typescript-mcp

项目结构

cmd/typescript-mcp/     入口点和 MCP 服务器设置
internal/
  lsp/                  LSP 客户端和 tsgo 进程管理
    client.go           JSON-RPC 连接，LSP 方法包装器
    process.go          tsgo 进程生命周期（启动、停止、解析）
  docsync/              与 LSP 服务器的文档同步
    sync.go             打开/更改/关闭通知
    uri.go              文件路径 <-> URI 转换
  tools/                MCP 工具处理程序
    tools.go            工具注册（模式和描述）
    diagnostics.go      ts_diagnostics 处理程序
    definition.go       ts_definition 处理程序
    hover.go            ts_hover 处理程序
    references.go       ts_references 处理程序
    rename.go           ts_rename 处理程序（写入工具）
    symbols.go          ts_document_symbols 处理程序
    project.go          ts_project_info 处理程序
    util.go             共享实用程序（readLine）
cmd/test-client/        用于针对实际项目进行手动测试的 CLI

📄 许可证

详情请参阅 LICENSE。