MCP Diagnostics Trae

🚀 MCP Diagnostics - Trae IDE 診斷信息讀取工具

一個專門為 Trae IDE 開發的 MCP (Model Context Protocol) 服務器，讓 Trae 的 AI Agent 能夠即時獲取項目中的錯誤、警告和提示信息，從而提供更智能的代碼分析和建議。

英文文檔: README_EN.md

🚀 快速開始

步驟 1: 安裝 VS Code 擴展

為了讓此工具能夠訪問 VS Code 的診斷信息，您需要先安裝配套的 VS Code 擴展。

1. 打開 VS Code。
2. 打開命令面板 (Ctrl+Shift+P 或 Cmd+Shift+P)。
3. 選擇 “擴展: 從 VSIX 安裝...”。
4. 找到本項目 diagnostics-extension 目錄下的 trae-diagnostics-server-0.0.1.vsix 文件並安裝。
5. 安裝後，重新加載 VS Code 窗口。

安裝成功後，擴展會自動在後臺運行一個本地服務器，用於提供診斷數據。

步驟 2: 克隆並構建項目

# 克隆項目
git clone https://github.com/lin037/mcp-diagnostics-trae.git
cd mcp-diagnostics

# 安裝依賴
npm install

# 構建項目
npm run build

步驟 3: 在 Trae 中配置

1. 打開 Trae 的 MCP 設置。
2. 選擇 手動添加。
3. 粘貼以下配置：

{
  "mcpServers": {
    "diagnostics": {
      "command": "npx",
      "args": ["-y", "/path/to/mcp-diagnostics"],
      "description": "Trae IDE 診斷信息讀取工具"
    }
  }
}

⚠️ 重要提示

要將 args 中的 /path/to/mcp-diagnostics 替換為你 clone 下來項目的實際路徑。

例如：git clone 後，項目在 E:/MCPWork/trae-diagnostics/mcp 目錄下：

{
  "mcpServers": {
    "diagnostics": {
      "command": "npx",
      "args": [
        "-y",
        "E:/MCPWork/trae-diagnostics/mcp"
      ]
    }
  }
}

✨ 主要特性

• 🔍 即時診斷：讀取 Trae IDE 當前工作區的所有診斷信息（錯誤/警告/提示）。
• 📁 文件級診斷：獲取指定文件的診斷信息，支持多種路徑格式。
• 📊 統計摘要：快速查看診斷統計（文件數、錯誤數、警告數）。
• 🤖 AI 增強：讓 Trae 的 AI Agent 能夠理解代碼問題，提供更精準的修復建議。
• 🔌 擴展協同：通過配套的 VS Code 擴展，穩定、高效地獲取診斷信息。
• 🎯 智能匹配：支持相對路徑、文件名、絕對 URI 等多種文件路徑格式。

🎯 項目目標

本項目專門為 Trae IDE 設計，目的是讓 Trae 的 AI Agent 能夠：

• 即時瞭解代碼中的錯誤和警告。
• 提供基於實際問題的修復建議。
• 智能分析項目代碼質量。
• 協助開發者快速定位和解決問題。

💻 使用示例

基礎用法

獲取項目診斷摘要

用戶: "請幫我查看當前項目的診斷摘要"

AI 會自動調用 getDiagnosticsSummary 工具。

獲取所有診斷詳情

用戶: "請列出當前項目的所有錯誤和警告"

AI 會調用 getDiagnostics 工具。

獲取特定文件的診斷

用戶: "請檢查 src/index.ts 文件的問題"

AI 會調用 getDiagnosticsForPath 工具，參數為 {"filePath": "src/index.ts"}。

高級用法

支持的對話示例

• "當前項目有多少個錯誤？"
• "幫我找出所有 TypeScript 類型錯誤"
• "列出所有警告信息"
• "檢查 TestJava.java 文件有什麼問題"
• "項目代碼質量如何？"
• "有哪些文件需要修復？"

📚 詳細文檔

🛠️ MCP 工具清單

1. getDiagnostics()

獲取當前工作區所有文件的診斷信息。

輸入：無參數

{}

輸出：診斷信息數組

[
  {
    "uri": "file:///workspace/src/index.ts",
    "diagnostics": [
      {
        "range": {
          "start": { "line": 12, "character": 5 },
          "end": { "line": 12, "character": 10 }
        },
        "severity": 1,
        "source": "typescript",
        "message": "類型 'string' 不能賦值給類型 'number'。"
      }
    ]
  }
]

2. getDiagnosticsForPath(filePath) ⭐ 推薦使用

根據文件路徑獲取診斷信息，支持靈活的路徑匹配。

輸入：

{
  "filePath": "src/index.ts"
}

支持的路徑格式：

• 相對路徑：src/index.ts
• 文件名：index.ts
• 帶目錄的文件名：test/TestJava.java

輸出：匹配文件的診斷信息數組

使用示例：

• 查看 TypeScript 文件："filePath": "src/index.ts"
• 查看 Java 文件："filePath": "TestJava.java"
• 查看測試文件："filePath": "test/test-errors.ts"

3. getDiagnosticsForFile(fileUri)

獲取指定文件的診斷信息（需要完整 URI）。

輸入：

{
  "fileUri": "file:///workspace/src/index.ts"
}

⚠️ 重要提示

必須使用 file:///workspace/ 開頭的完整 URI 格式。

4. getDiagnosticsSummary()

獲取診斷統計信息。

輸入：無參數

{}

輸出：統計摘要

{
  "totalFiles": 4,
  "errors": 4,
  "warnings": 4
}

📊 診斷嚴重級別

• 1 - 錯誤 (Error) ❌
• 2 - 警告 (Warning) ⚠️
• 3 - 信息 (Info) ℹ️
• 4 - 提示 (Hint) 💡

🔧 技術細節

🔧 技術架構

Trae IDE (MCP客戶端) ←→ MCP服務器 ←→ Trae IDE (DAP接口)

1. MCP 層：使用 @modelcontextprotocol/sdk 實現標準 MCP 協議。
2. 通信層：通過 stdin/stdout 與 Trae 通信。
3. 診斷層：通過 Debug Adapter Protocol 連接 Trae IDE。
4. 數據層：解析和格式化診斷信息。

🛠️ 開發

開發模式運行

npm run dev

構建

npm run build

測試連接

# 啟動服務器
npm start

# 在另一個終端測試
node test-file-diagnostics.js

❓ 故障排除

無法連接到 Trae IDE

解決方案：

1. 確保 Trae IDE 正在運行。
2. 檢查項目已在 Trae 中打開。
3. 等待語言服務器完成初始化。

返回空診斷

可能原因：

1. 項目沒有錯誤或警告。
2. 語言服務器還在分析中。
3. 文件類型不支持診斷。

解決方案：

• 等待幾秒鐘後重試。
• 確保文件已保存。
• 檢查 Trae 是否顯示診斷信息。

getDiagnosticsForFile 返回空數組

解決方案：

• 使用 getDiagnosticsForPath 工具（推薦）。
• 確保使用正確的 URI 格式：file:///workspace/文件路徑。
• 先調用 getDiagnostics 查看可用的文件 URI。

工具調用失敗

檢查項目：

1. MCP 服務器是否正常啟動。
2. 網絡連接是否正常。
3. 查看 Trae 的錯誤日誌。

🔮 未來展望

• 官方版本：相信 Trae 官方未來可能會開發官方版本的 MCP 診斷工具。
• 社區維護：本項目完全由作者通過 AI 開發，技術有限，未來維護主要依靠社區 fork。
• 當前狀態：目前版本功能完整，足夠日常使用。

🤝 貢獻與維護

本項目由作者通過 AI 助手開發完成，由於作者技術有限且時間有限，未來的維護主要依靠社區：

• Fork 歡迎：歡迎其他開發者 fork 本項目進行改進。
• Issue 反饋：可以提交 Issue，但響應可能不及時。
• Pull Request：歡迎提交 PR，會盡量審核。
• 社區驅動：鼓勵社區自發維護和改進。

📄 許可證

本項目採用 MIT 許可證。

🎉 現在您可以讓 Trae 的 AI Agent 即時瞭解項目中的代碼問題了！