Vscode MCP Python

🚀 MCP 服務器 - 模型上下文協議服務器

MCP（模型上下文協議）服務器可用於集成 VSCode 和 Claude，具備全面的工具支持、性能監控和診斷功能，適用於生產環境。

🚀 快速開始

MCP 服務器是一個為 VSCode 和 Claude 集成設計的生產級服務器。以下是快速上手的步驟：

1. 確保滿足安裝的前提條件，如 Python 3.8 或更高版本。
2. 按照安裝步驟克隆或下載倉庫，並配置好相關文件。
3. 參考配置部分，將服務器配置添加到 Claude Desktop 的配置文件中。
4. 運行快速啟動命令，啟動服務器。

✨ 主要特性

⚡ 技術優化

• 減少令牌開銷：MCP 服務器允許 Claude 僅查詢所需的特定數據，而不是將大型數據集粘貼到聊天中。這使得響應速度更快，且每個令牌的使用成本更低。
• 異步執行：藉助 Python 的異步功能，服務器可以同時處理多個數據請求，而不會凍結交互。
• 自定義工具映射：可以將複雜的 Python 庫（如 pandas、beautifulsoup 或 os）封裝成簡單的工具，供 Claude 立即調用。

🌟 為項目增值

• 彌合差距：它將 Claude 從“聊天機器人”轉變為“開發人員代理”，使其能夠查看和修改本地代碼或數據庫。
• 工作流自動化：只需與 Claude 對話，就可以自動化執行重複性任務，如日誌分析、本地文件重組或數據庫查詢。
• 私有數據上下文：由於服務器在本地運行，您可以為 Claude 提供來自私有文檔或公司內部數據的上下文，而無需將這些文件上傳到雲端。

核心能力

• 10 種專業流程：完成文件操作、代碼分析和 VSCode 集成。
• LRU 緩存：智能請求緩存，性能提升 2 - 3 倍。
• 類型安全：100% 類型提示（符合 PEP 484）。
• 企業架構：遵循 SOLID 原則、設計模式，具備專業的結構。
• 全面日誌記錄：將結構化日誌記錄到標準錯誤輸出，便於調試。
• 錯誤處理：具備生產級的錯誤處理和特定異常處理。

📦 安裝指南

前提條件

• Python 3.8 或更高版本
• VSCode（可選，用於 VSCode 集成功能）
• Windows、Linux 或 macOS

安裝步驟

1. 克隆或下載此倉庫。
2. 確保所有文件位於同一目錄下：
   • mcp_server.py - 主服務器
   • tools.py - 工具實現
   • vscode_detector.py - VSCode 集成
   • diagnostics.py - 健康檢查
   • performance_monitor.py - 性能跟蹤
   • languages.json - 語言配置
3. 配置您的人工智能桌面（適用於 Claude）以使用此服務器（請參閱配置部分）。

快速啟動

# 測試服務器編譯
python -m py_compile mcp_server.py

# 運行診斷
python diagnostics.py

# 啟動服務器（通常由 Claude 調用）
python mcp_server.py

📚 詳細文檔

配置

將以下內容添加到您的 Claude Desktop 配置文件中：

Windows

%APPDATA%\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

配置示例

{
  "mcpServers": {
    "vscode-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\mcp_server.py"]
    }
  }
}

💻 使用示例

基礎用法

讀取文件

用戶：“讀取 mcp_server.py 的內容”
Claude：使用 read_file 工具
結果：顯示文件內容

代碼分析

用戶：“分析 tools.py 中的代碼”
Claude：使用 analyze_code 工具
結果：列出函數、類和導入，並顯示行號

編寫代碼

用戶：“編寫一個 Python 計算器”
Claude：使用 write_code_to_project 工具
系統：出現權限提示
用戶：批准
結果：創建 calculator.py 並提供詳細反饋

修改代碼

用戶：“在 calculator.py 中，為 divide 函數添加錯誤處理”
Claude：使用 change_code 工具
系統：出現權限提示
用戶：批准
結果：更新函數，並提供前後預覽

項目概述

用戶：“顯示項目結構”
Claude：使用 get_project_structure 工具
結果：按編程語言組織文件

🔧 技術細節

主要組件

MCPServer 類

• 實現 MCP 2024 - 11 - 05 協議處理
• JSON - RPC 2.0 通信
• 異步/等待模式
• 請求/響應管理

ToolRegistry 類

• 工具註冊和管理
• 輸入模式驗證
• 工具調用

RequestCache 類

• LRU 緩存機制
• 可配置的緩存大小
• 自動淘汰

LanguageConfig 類

• 語言配置管理
• 代碼分析的模式匹配
• 文件擴展名處理

設計模式

• 註冊表模式 - 工具管理
• 緩存模式 - 請求緩存
• 數據類模式 - 類型安全的元數據
• 依賴注入 - 配置管理
• 策略模式 - 工具執行

性能優化

優化特性

• 安全工具請求的 LRU 緩存
• 非阻塞操作的異步/等待
• 高效的文件系統掃描
• 智能 VSCode 進程檢測
• 最小的內存佔用

性能指標

診斷

健康檢查

運行全面診斷：

# 完整診斷套件
python diagnostics.py

# 快速檢查
python diagnostics.py --mode quick

# 健康狀態（JSON）
python diagnostics.py --mode health

診斷測試

• Python 版本兼容性
• 所需文件是否存在
• 文件權限
• 配置有效性
• 模塊導入
• 語法檢查
• 磁盤空間
• 內存使用量
• VSCode 狀態
• 網絡連接

開發

代碼質量標準

• PEP 8 - 遵循風格指南
• PEP 257 - 遵循文檔字符串約定
• PEP 484 - 使用類型註解
• Google 風格 - 採用文檔字符串格式

測試

# 檢查所有文件的語法
python -m py_compile *.py

# 運行診斷
python diagnostics.py

# 測試工具導入
python -c "import tools; import mcp_server"

故障排除

常見問題

服務器無法啟動

• 檢查 Python 版本：python --version（必須為 3.8 或更高版本）
• 運行診斷：python diagnostics.py
• 檢查語法：python -m py_compile mcp_server.py

工具無法工作

• 驗證文件權限
• 檢查 languages.json 是否為有效的 JSON 文件
• 運行導入測試：python -c "import tools"

VSCode 檢測失敗

• 確保 VSCode 正在運行
• 檢查進程權限（Windows）
• 驗證工作區目錄是否可訪問

權限錯誤

• 以管理員身份運行（如有需要）
• 檢查文件/目錄權限
• 驗證配置中的路徑

代碼貢獻指南

1. 遵循 PEP 8 風格指南。
2. 為所有函數添加類型提示。
3. 編寫全面的文檔字符串。
4. 包含錯誤處理。
5. 為新功能添加測試。
6. 為新工具更新 README。

添加新工具

1. 在 tools.py 中實現工具函數。
2. 在 mcp_server.py 的 TOOL_DEFINITIONS 中添加工具定義。
3. 在 main() 函數中註冊工具。
4. 更新 README 文檔。
5. 如有需要，添加診斷檢查。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

支持

文檔

• 代碼文檔字符串中提供完整的 API 參考。
• 本 README 中包含使用示例。
• 提供診斷工具用於故障排除。

獲取幫助

1. 運行診斷：python diagnostics.py
2. 檢查標準錯誤輸出中的日誌。
3. 仔細查看錯誤消息。
4. 驗證配置文件。

鳴謝

作者：Kommandant
版本：1.0.0
許可證：MIT
狀態：開發中