JinDaGe - vscode_mcp_python MCP Details

article

README

🚀 MCP 服务器 - 模型上下文协议服务器

MCP（模型上下文协议）服务器可用于集成 VSCode 和 Claude，具备全面的工具支持、性能监控和诊断功能，适用于生产环境。

🚀 快速开始

MCP 服务器是一个为 VSCode 和 Claude 集成设计的生产级服务器。以下是快速上手的步骤：

确保满足安装的前提条件，如 Python 3.8 或更高版本。
按照安装步骤克隆或下载仓库，并配置好相关文件。
参考配置部分，将服务器配置添加到 Claude Desktop 的配置文件中。
运行快速启动命令，启动服务器。

✨ 主要特性

⚡ 技术优化

减少令牌开销：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

安装步骤

克隆或下载此仓库。
确保所有文件位于同一目录下：
- mcp_server.py - 主服务器
- tools.py - 工具实现
- vscode_detector.py - VSCode 集成
- diagnostics.py - 健康检查
- performance_monitor.py - 性能跟踪
- languages.json - 语言配置
配置您的人工智能桌面（适用于 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 进程检测
最小的内存占用

性能指标

| 指标 | 值 | |------|------| | 启动时间 | < 1 秒 | | 工具执行时间 | 10 - 100 毫秒（缓存：< 1 毫秒） | | 内存使用量 | ~50MB | | 缓存命中率 | 70 - 90% |

诊断

健康检查

运行全面诊断：

# 完整诊断套件
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）
验证工作区目录是否可访问

权限错误

以管理员身份运行（如有需要）
检查文件/目录权限
验证配置中的路径

代码贡献指南

遵循 PEP 8 风格指南。
为所有函数添加类型提示。
编写全面的文档字符串。
包含错误处理。
为新功能添加测试。
为新工具更新 README。

添加新工具

在 tools.py 中实现工具函数。
在 mcp_server.py 的 TOOL_DEFINITIONS 中添加工具定义。
在 main() 函数中注册工具。
更新 README 文档。
如有需要，添加诊断检查。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

支持

文档

代码文档字符串中提供完整的 API 参考。
本 README 中包含使用示例。
提供诊断工具用于故障排除。

获取帮助

运行诊断：python diagnostics.py
检查标准错误输出中的日志。
仔细查看错误消息。
验证配置文件。

鸣谢

作者：Kommandant
版本：1.0.0
许可证：MIT
状态：开发中