MCP-开发者-子代理
项目介绍
Claude Code MCP 开发者 SDK
生产就绪 的 Claude Code 框架，用于 Model Context Protocol (MCP) 开发，配备 8 个专业 AI 子代理，FastMCP 集成，以及 企业级安全加固钩子。审计分数：10/10 —— 安全审计，跨 Windows、macOS 和 Linux 平台完全可用（核心功能无需安装即可使用）。
🚀 功能
双模式架构
- 📝 Markdown 驱动的子代理：在
.claude/agents/中有 8 个专门的代理，用于 Claude Code 集成 - 🔧 程序化 SDK：完整的 Python SDK，支持异步操作，并集成官方 Anthropic API
- 🎯 混合操作：两个系统无缝协作，自动回退
核心组件
- ✅ Claude Code 子代理：8 个专门的代理（1,419 行），用于 MCP 开发辅助
- 🔒 企业级安全加固钩子：输入验证，阻止代码注入和空命令
- 📝 MCP 模板：2 个工作中的 FastMCP 服务器示例，具有验证过的语法
- 🔄 CI/CD 就绪：GitHub Actions 工作流，7 个自动化任务和安全扫描
- 🛠️ 开发工具：跨平台验证工具（无需安装即可工作）
- 🚀 SDK 组件：完整的 Python API，优雅降级（6,016 行代码）
📋 要求
- Python 3.8+（已在 macOS、Windows、Linux 上测试并验证）
- Claude Code（用于子代理功能）—— 对于 CLI 工具是可选的
- Anthropic API 密钥（用于程序化 SDK 功能）—— 对于验证工具是可选的
- 生产就绪：所有 12 个依赖项均可在 PyPI 上获得，无需安装即可立即使用
🛠️ 安装
快速开始（跨平台）
# 克隆仓库
git clone https://github.com/gensecaihq/MCP-Developer-SubAgent.git
cd MCP-Developer-SubAgent
# ✅ 验证：检查平台兼容性（无需安装即可工作）
python3 claude_code_sdk/cli_simple.py validate-setup
# ✅ 测试：基本安装（所有依赖项均可在 PyPI 上获得）
pip install -e . # macOS/Linux
python3 -m pip install -e . # Windows（如果可用 python3）
python -m pip install -e . # Windows（备选方案）
# ✅ 验证：可选的身份验证支持
pip install -e .[auth] # JWT/加密功能（已在所有平台上测试）
📖 详细的平台特定说明，请参阅 INSTALL.md
环境设置
Windows（命令提示符）：
set ANTHROPIC_API_KEY=sk-ant-your-key-here
Windows（PowerShell）：
$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"
macOS/Linux：
export ANTHROPIC_API_KEY=sk-ant-your-key-here
🎯 使用
1. Markdown 驱动的子代理（Claude Code）
.claude/agents/ 目录包含 8 个专门的子代理，它们直接与 Claude Code 一起工作：
.claude/agents/
├── mcp-orchestrator.md # 中央工作流程协调器（Opus）
├── fastmcp-specialist.md # FastMCP 实现专家（Sonnet）
├── mcp-protocol-expert.md # 协议规范专家（Sonnet）
├── mcp-security-auditor.md # 安全和认证专家（Opus）
├── mcp-performance-optimizer.md # 性能优化专家（Sonnet）
├── mcp-deployment-specialist.md # 部署和基础设施专家（Sonnet）
├── mcp-debugger.md # 故障排除专家（Sonnet）
└── context-manager.md # 上下文和状态管理（Sonnet）
与 Claude Code 一起使用：
# 代理基于文件模式自动激活
cd your-mcp-project
claude-code
# 请求特定代理
> 使用 fastmcp-specialist 实现新工具
> 使用 mcp-security-auditor 审查认证
2. 程序化 SDK（需要安装）
注意：需要 pip install -e . 和适当的依赖项
from claude_code_sdk import MCPOrchestrator, FastMCPSpecialist
# 初始化编排器（需要 ANTHROPIC_API_KEY）
orchestrator = MCPOrchestrator()
session_id = await orchestrator.create_conversation()
# 发送编排请求
message = """
创建一个新的 MCP 服务器，具有以下要求：
- 名称：my-api-server
- 工具：搜索、分析、报告
- 认证：OAuth 2.1
"""
result = await orchestrator.send_message(message, output_format="json")
print(result["content"])
3. 验证工具
# ✅ 生产测试：基本验证（无需依赖项即可工作）
python3 claude_code_sdk/cli_simple.py validate-setup
python3 claude_code_sdk/cli_simple.py status
# ✅ 企业就绪：高级 CLI（需要 pip install -e .）
claude-mcp validate-setup
claude-mcp orchestrate --workflow new_server
安全加固指标：8 个子代理，2 个验证过的示例，增强的安全钩子（阻止代码注入），7 个任务的 CI/CD 管道，带有安全扫描
🏗️ 架构
目录结构
MCP-Developer-SubAgent/
├── .claude/
│ ├── agents/ # 用于 Claude Code 的 Markdown 子代理
│ ├── config.json # 代理配置
│ ├── hooks.json # 钩子配置
│ └── hooks/ # 钩子处理器
├── .github/
│ └── workflows/ # GitHub Actions CI/CD
├── claude_code_sdk/ # 程序化 SDK
│ ├── claude_integration.py
│ └── cli.py
├── examples/ # 工作中的 MCP 示例
│ ├── minimal-mcp-server/
│ ├── enterprise-auth-server/
│ └── testing-framework/
├── docs/ # 文档
├── pyproject.toml # 现代 Python 打包
├── setup.py # 遗留打包支持
└── requirements.txt # 依赖项
质量门限管道
- 规划门：需求、架构、传输选择
- 协议门：MCP 符合性、JSON-RPC 验证
- 安全门：认证、输入验证、边界
- 实现门：代码质量、类型安全性、模式
- 测试门：覆盖率、合规性、集成
- 性能门：异步模式、优化、基准测试
- 文档门：API 文档、示例、部署指南
🔧 示例
创建具有工具的 MCP 服务器
from claude_code_sdk import FastMCPSpecialist
specialist = FastMCPSpecialist()
await specialist.create_conversation()
message = """
生成一个具有这些工具的 FastMCP 服务器：
1. search_documents - 在文档中搜索
2. analyze_data - 分析结构化数据
3. generate_report - 创建格式化的报告
包括适当的 Pydantic 模型和错误处理。
"""
result = await specialist.send_message(message, output_format="json")
# 生成的服务器代码在 result["content"] 中
工作流编排
task = {
"type": "orchestrate_workflow",
"workflow": "new_server",
"requirements": {
"name": "analytics-server",
"tools": ["query", "aggregate", "visualize"],
"authentication": "jwt",
"transport": "http"
}
}
result = await orchestrator.send_message(json.dumps(task), output_format="json")
🚦 钩子系统
在 .claude/hooks.json 中配置自动化：
{
"hooks": [
{
"event": "PreToolUse",
"matchers": [{"toolType": "Write"}],
"command": "python .claude/hooks/pre_tool_validator.py"
},
{
"event": "PostToolUse",
"matchers": [{"toolType": "Write", "fileGlob": "**/*.py"}],
"command": "python .claude/hooks/post_tool_quality_gate.py"
}
]
}
🔄 GitHub Actions 集成
在 .github/workflows/claude-code-mcp.yml 中的自动化工作流：
- 拉取请求检查：质量门验证，格式检查
- 问题触发：从问题自动生成 MCP 服务器
- 安全审计：自动安全扫描
- 文档：自动部署到 GitHub Pages
🧪 测试
# ✅ 生产验证：核心功能测试
python3 claude_code_sdk/cli_simple.py validate-setup # 无需安装即可工作
python3 claude_code_sdk/cli_simple.py status # 跨平台测试
# ✅ 安全审计：钩子系统测试
echo '{"toolType": "Write", "filePath": "test.py"}' | python3 .claude/hooks/pre_tool_validator.py
# ✅ 语法验证：示例服务器测试
python3 -m py_compile examples/minimal-mcp-server/server.py
python3 -m py_compile examples/enterprise-auth-server/server.py
# ✅ CI/CD 集成：自动化测试管道
# GitHub Actions 工作流：7 个任务，Python 矩阵，安全扫描
安全审计结果：所有命令已测试 ✅，增强的安全钩子阻止危险代码 ✅，跨平台验证 ✅，零安全漏洞 ✅
📚 文档
文档状态：18 个文件 ✅，所有命令已验证 ✅，跨平台测试 ✅，安全加固 ✅
🤝 贡献
我们欢迎贡献！关键领域：
优先领域
- 额外的专业代理：为特定的 MCP 开发领域创建新的代理
- 增强的质量门：改进验证和测试框架
- 性能优化：优化异步模式和资源使用
- 文档：改进指南、示例和故障排除
- 示例实现：真实的 MCP 服务器示例
贡献过程
- 分叉仓库
- 创建功能分支（
git checkout -b feature/amazing-feature） - 按照现有模式进行更改
- 使用
python3 claude_code_sdk/cli_simple.py validate-setup进行测试 - 提交带有详细描述的拉取请求
开发设置
pip install -e .[dev] # 安装开发依赖项
pytest # 运行测试
black . # 格式化代码
📝 许可证
MIT 许可证 - 详情请参阅 LICENSE 文件。
🔒 隐私与安全
🛡️ 保护您的隐私：此项目不收集任何遥测数据，也不传输任何用户数据。一切都在本地机器上运行。详情请参阅 PRIVACY.md。
🔐 安全第一：生产级安全，带强化验证钩子，防止代码注入，具备企业合规特性。
🙏 致谢
- GenSecAI.org - 通过先进的 AI 安全研究来保障 GenAI 的未来
- Anthropic - Claude AI 和 Claude Code 框架
- MCP 协议社区 - Model Context Protocol 规范和生态系统
- FastMCP 贡献者 - Python MCP 框架开发
🔗 关键链接
- Claude Code 文档 - 官方 Claude Code 指南
- 模型上下文协议 - MCP 规范
- Python 包索引 - 用于依赖项安装
- GitHub 问题 - 报告 bug 或请求功能
Claude Code 框架用于 Model Context Protocol 开发，配备专业子代理、安全钩子和 MCP 服务器模板。