create-mcp-servers

MCP 服务通过提供工具、资源和提示词来扩展 Claude 的能力。本技能将指导你创建可用于生产环境的 MCP 服务，包括 API 集成、OAuth 身份验证、响应优化，以及在 Claude Code 和 Claude Desktop 中正确安装。

<essential_principles>

<the_5_rules> 每个 MCP 服务都必须遵循以下规则：

1. 绝不硬编码密钥 - 在配置中使用 ${VAR} 展开，在代码中使用环境变量
2. 使用 cwd 属性 - 隔离依赖项（不要在 args 中使用 --cwd）
3. 始终使用绝对路径 - 使用 which uv 查找路径，绝不使用相对路径
4. 每个目录只放一个服务 - ~/Developer/mcp/{server-name}/
5. 使用 uv 编写 Python - 优于 pip，并可自动处理虚拟环境 </the_5_rules>

<security_checklist>

• 绝不要求用户将密钥粘贴到聊天中
• 始终使用环境变量保存凭据
• 在配置中使用 ${VAR} 展开
• 提供供用户在终端中运行的确切命令
• 验证环境变量是否存在，但不显示其值
• 绝不在代码或配置中硬编码 API 密钥 </security_checklist>

<architecture_decision> 操作数量决定架构：

• 1-2 个操作 → 传统模式（扁平工具）
• 3 个或更多操作 → 按需发现模式（元工具）

传统模式：每个操作对应一个独立工具 按需模式：4 个元工具（discover、get_schema、execute、continue）+ operations.json </architecture_decision>

MCP 服务提供： - **工具**：Claude 可以调用的函数（API 请求、文件操作、计算） - **资源**：Claude 可以读取的数据（文件、数据库记录、API 响应） - **提示词**：带参数的可重复使用的提示词模板

标准位置：~/Developer/mcp/{server-name}/

</essential_principles>

根据用户意图，转到相应的工作流：

未提供上下文（调用技能时未附带描述）： 使用 AskUserQuestion：

• header：”模式”
• question：”你想做什么？”
• options：
  • ”创建新的 MCP 服务” → workflows/create-new-server.md
  • ”更新现有 MCP 服务” → workflows/update-existing-server.md
  • ”排查服务问题” → workflows/troubleshoot-server.md

已提供上下文（用户已描述需求）： 直接转到 workflows/create-new-server.md

<workflows_index>

工作流	用途
create-new-server.md	从需求收集到验证的完整 8 步工作流
update-existing-server.md	修改或扩展现有服务
troubleshoot-server.md	诊断并修复连接或运行时问题
</workflows_index>

<templates_index>

模板	用途
python-server.py	Python 传统模式入门模板
typescript-server.ts	TypeScript 传统模式入门模板
operations.json	按需发现操作定义
</templates_index>

<scripts_index>

脚本	用途
setup-python-project.sh	使用 uv 初始化 Python MCP 项目
setup-typescript-project.sh	使用 npm 初始化 TypeScript MCP 项目
</scripts_index>

<references_index> 核心工作流：

• creation-workflow.md - 完整的分步指南，包含确切命令

架构模式：

• traditional-pattern.md - 适用于 1-2 个操作（扁平工具）
• large-api-pattern.md - 适用于 3 个或更多操作（按需发现）

语言专属：

• python-implementation.md - 异步模式、类型提示
• typescript-implementation.md - 类型安全、SDK 功能

进阶主题：

• oauth-implementation.md - 通过 stdio 隔离实现 OAuth
• response-optimization.md - 字段截断、分页
• tools-and-resources.md - 资源 API、提示词、流式传输
• testing-and-deployment.md - 单元测试、打包、发布
• validation-checkpoints.md - 所有验证检查
• adaptive-questioning-guide.md - 需求收集问题模板
• api-research-template.md - API 研究文档格式 </references_index> <quick_reference>

# List servers
claude mcp list

# Add server (Python)
claude mcp add --transport stdio <name> \
  --env API_KEY='${API_KEY}' \
  -- uv --directory ~/Developer/mcp/<name> run python -m src.server

# Add server (TypeScript)
claude mcp add --transport stdio <name> \
  --env API_KEY='${API_KEY}' \
  -- node ~/Developer/mcp/<name>/build/index.js

# Remove server
claude mcp remove <name>

# Check logs
tail -f ~/Library/Logs/Claude/mcp-server-<name>.log

# Find paths
which uv && which node && which python

</quick_reference>

<troubleshooting_quick> **服务未显示：**检查 claude mcp list，并验证 ~/.claude/settings.json 中的配置

**“找不到命令”：**使用 which uv / which node 获取的绝对路径

未找到环境变量：

echo $MY_API_KEY  # Check if set
echo 'export MY_API_KEY="value"' >> ~/.zshrc && source ~/.zshrc

**对话中出现密钥：**立即停止。删除对话。轮换凭据。切勿在聊天中粘贴密钥。

完整故障排查指南：workflows/troubleshoot-server.md </troubleshooting_quick>

<success_criteria> 可用于生产环境的 MCP 服务应具备：

• 在 Claude Code 中配置有效（claude mcp list 显示 ✓ Connected）
• 在 Claude Desktop 配置中配置有效
• 在 ~/.zshrc 中安全设置环境变量
• 架构与操作数量相匹配
• 如适用，隔离 OAuth stdio
• 优化列表／搜索操作的响应
• 通过所有验证检查点
• 日志中无错误 </success_criteria>