使用MCP服务器的Claude代码

项目概述

本项目使Claude能够使用模型上下文协议（MCP）服务器来增强其功能，包括网络搜索、GitHub集成、文件操作、数据库访问以及通信工具。

关键概念

• MCP（模型上下文协议）：一种标准化的方式，用于大型语言模型与外部工具和服务进行交互。
• 参考MCP服务器：位于$HOME/dev/mcp-servers-repo（github.com/modelcontextprotocol/servers的一个克隆）
• 本地MCP服务器：我们自己的实现位于$HOME/dev/claude-code/mcp-servers/

参考服务器应被视为只读。我们的本地服务器将是我们的实现，其中一些基于参考服务器但进行了扩展和改进。

目录结构

• docs/ - 参考文档
• mcp-servers/ - 我们的本地MCP服务器实现
• archive/ - 存储已弃用的代码组件
• data/ - 存储服务器数据（如SQLite数据库、内存文件等）
• scripts/ - 设置和测试的实用脚本
• src/ - Python模块和实用工具

MCP服务器配置

配置由项目根目录下的claude-mcp脚本处理。此脚本：

1. 设置服务器路径的环境变量
2. 使用claude mcp add命令将服务器注册到Claude
3. 使用来自npm/pypi的包式服务器和本地实现

# 脚本路径
/Users/williambrown/dev/claude-code/claude-mcp

# 列出所有已注册的服务器
claude mcp list

可用的MCP服务器

服务器	目的	来源
brave-search	网络搜索能力	npm 包
github	GitHub仓库操作	npm 包
filesystem	本地文件系统操作	npm 包
fetch	网页抓取	PyPI 包
memory	持久记忆的知识图谱	npm 包
sqlite	数据库操作	本地实现
slack	Slack通信	npm 包
linear	Linear问题跟踪	npm 包
e2b	代码执行沙箱	npm 包

必要的环境变量

• BRAVE_API_KEY - 用于brave-search服务器
• GITHUB_TOKEN - 用于GitHub操作
• LINEAR_API_KEY - 用于Linear问题跟踪
• SLACK_BOT_TOKEN 和 SLACK_TEAM_ID - 用于Slack通信
• E2B_API_KEY - 用于代码执行沙箱
• ALLOWED_PATHS - 用于文件系统访问控制（默认为主项目根目录）

开发方法

我们采用双管齐下的方式来开发MCP服务器：

1. 利用现有服务器：通过npm/PyPI包使用已建立的MCP服务器以实现标准功能
2. 构建自定义服务器：开发我们自己的实现以实现扩展功能和实验

所有遗留或不再维护的代码都会移动到archive/目录中，以保持主代码库的整洁和专注。

开发指南

包管理

• 使用uv进行Python包管理（永远不要使用pip）
• 安装：uv add package
• 运行工具：uv run tool
• TypeScript：使用npm进行包管理

代码质量

• 所有Python和TypeScript代码都需要类型提示
• 公共API必须有文档字符串
• 函数必须集中且小巧
• 行长度：最大88个字符
• 遵循Python的PEP标准
• 遵循TypeScript的现有模式

测试

• 框架：uv run pytest
• 异步测试：使用anyio，而不是asyncio
• 覆盖率：测试边缘情况和错误
• 新功能需要测试
• 修复bug需要回归测试

编码原则

• 使用干净、模块化的抽象
• 避免代码重复
• 确保向后兼容性
• 文档所有扩展和与参考实现的不同之处
• 努力编写易于维护的最小化干净代码

Git工作流

• 在单独的分支上开发，快速合并到主分支
• 对于用户报告的修复：git commit --trailer "Reported-by:<user>"
• 对于GitHub问题：git commit --trailer "Github-Issue:#<number>"
• 绝不提及共同作者或创建提交/PR的工具

MCP服务器开发指南

在开发我们自己的本地MCP服务器时：

1. 首先参考实现：

   • 研究MCP_REPO_PATH中的原始服务器
   • 了解其API、行为和实现细节
   • 记录关键函数和特性

2. 实现策略：

   • 首先完全模仿参考服务器
   • 基础功能运行后，添加扩展
   • 确保向后兼容性

3. 代码质量：

   • 使用适当的类型（TypeScript/Python类型提示）
   • 添加全面的文档

• 实现正确的错误处理
• 遵循一致的命名约定
• 为所有功能编写测试

有关项目标准、代码风格和特定服务器实现的详细信息，请参阅CLAUDE.md。