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。