项目介绍
🏭 MCP 工厂
完整的 MCP 开发基础 - 生产就绪的服务器、模板和工具，用于模型上下文协议开发
🎯 什么是 MCP 工厂？
MCP 工厂 是最全面的 MCP 开发基础，包括生产就绪的服务器、双向通信、真实的大型语言模型采样以及构建高级AI集成所需的一切。
graph LR
A[🎯 基础 MCP] --> B[🚀 快速MCP 2.0]
B --> C[🔄 双向通信]
C --> D[🌟 知识助手]
D --> E[🏭 生产就绪]
style E fill:#e8f5e8,stroke:#4caf50,stroke-width:2px
🌟 高亮：我们的 知识助手 服务器展示了 45个 MCP 功能，包括真实的大规模语言模型采样、双向通信和外部API集成。
🚀 快速开始
⚡ 尝试知识助手（推荐）
# 1. 克隆并设置
git clone https://github.com/your-username/mcpFactory.git
cd mcpFactory
# 2. 安装UV（现代Python包管理器）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 3. 运行知识助手服务器
cd src/servers/knowledge_assistant
uv sync
uv run python server.py
# 4. 启动检查器（新终端）
cd ../../..
./scripts/start-inspector.sh
🎉 结果：Chrome 自动打开，带有连接到具有 45个功能 的服务器的 MCP 检查器！
🧪 测试力量
- 连接：检查器自动连接到
http://127.0.0.1:8080/mcp/ - 探索：运行
get_server_info()查看所有45个功能 - 双向尝试：执行
ask_question()- 服务器会问你问题！ - 真实大规模语言模型：测试
generate_summary()- 使用实际的大规模语言模型通过ctx.sample()
📊 内容概览？
🌟 知识助手 - 皇冠上的明珠
🧠 知识助手（45个 MCP 功能）
├── 🛠️ 17个工具 → CRUD，管理，分析
├── 📁 7个资源 → 基于URI的数据访问
├── 💬 6个提示 → 大规模语言模型模板
├── 🎲 6个采样 → 通过 ctx.sample() 实现的真实大规模语言模型
├── 🔄 3个交互式 → 双向通信
└── 🌐 5个外部 → 维基百科，ArXiv，新闻API
🏗️ 完整的服务器集合
| 服务器 | 目的 | 复杂度 | 特性 |
|---|---|---|---|
hello_world | 基础MCP示例 | ⭐ 简单 | 工具，资源 |
ping_pong | 通信模式 | ⭐⭐ 中等 | 纯MCP vs 快速MCP |
two_way | 双向聊天 | ⭐⭐⭐ 高级 | 交互式调查 |
knowledge_assistant | 完整展示 | ⭐⭐⭐⭐⭐ 专家 | 所有MCP特性 |
debug | 开发工具 | ⭐⭐ 中等 | 调试工具 |
🏗️ 项目结构
📁 mcpFactory/
├── 📚 docs/ # 综合文档
│ ├── en-us/ # 英文指南
│ │ ├── 01-concepts.md # MCP基础
│ │ ├── 02-architecture.md # 技术深入
│ │ ├── 03-guide.md # 实施指南
│ │ ├── fastmcp/ # 快速MCP框架指南
│ │ │ ├── 01-introduction.md
│ │ │ ├── 02-quickstart.md
│ │ │ ├── 03-development-tools.md
│ │ │ └── 04-advanced-concepts.md
│ │ └── two-way/ # 双向通信指南
│ │ ├── 01-fundamental-concepts.md
│ │ ├── 02-quick-start.md
│ │ ├── 03-understanding-existing-server.md
│ │ ├── 04-developing-new-mcp.md
│ │ ├── 05-multiple-clients.md
│ │ └── 06-practical-use-cases.md
│ └── pt-br/ # 葡萄牙语文档（完整）
│ ├── 01-conceitos.md # 基本概念
│ ├── 02-arquitetura.md # 技术架构
│ ├── 03-guia.md # 实施指南
│ ├── 05-exemplos.md # 实用示例
│ ├── fastmcp/ # 快速MCP框架指南
│ │ ├── 01-introducao.md
│ │ ├── 02-guia-rapido.md
│ │ ├── 03-ferramentas-de-desenvolvimento.md
│ │ └── 04-conceitos-avancados.md
│ └── two-way/ # 双向通信指南
│ ├── 01-conceitos-fundamentais.md
│ ├── 02-quick-start.md
│ ├── 03-entendendo-servidor-existente.md
│ ├── 04-desenvolvendo-novo-mcp.md
│ ├── 05-multiplos-clientes.md
│ └── 06-casos-de-uso-praticos.md
│
├── 🚀 src/servers/ # 生产就绪的MCP服务器
│ ├── knowledge_assistant/ # 🌟 45个功能展示
│ │ ├── server.py # 快速MCP 2.0 + 真实采样
│ │ ├── core/ # 知识库及模型
│ │ ├── modules/ # MCP特性模块
│ │ └── data/ # 真实样本数据
│ ├── two_way/ # ⭐ 双向通信
│ ├── hello_world/ # 基础MCP示例
│ ├── ping_pong/ # 通信模式
│ └── debug/ # 开发工具
│
├── 🛠️ templates/ # 即用模板
│ ├── starter.py # 基础MCP服务器模板
│ ├── interactive.py # 双向通信模板
│ └── production.py # 企业级模板
│
├── 🔧 scripts/ # 开发工具
│ └── start-inspector.sh # 一键启动检查器
│
└── 📋 项目文件
├── pyproject.toml # UV/Python配置
├── uv.lock # 依赖锁定文件
├── CHANGELOG.md # 版本历史
├── CONTRIBUTING.md # 贡献指南
└── ROADMAP.md # 未来计划
✨ 关键特性
🔄 双向通信
传统的MCP是单向的。我们实现了真正的双向通信：
graph LR
subgraph "❌ 传统MCP"
A1[客户端] -->|问题| B1[服务器]
B1 -->|响应| A1
end
subgraph "✅ 双向MCP"
A2[客户端] -->|"分析代码"| B2[服务器]
B2 -->|"什么类型的分析？"| A2
A2 -->|"安全"| B2
B2 -->|"发现3个漏洞"| A2
end
style B2 fill:#e8f5e8
🧠 真实大规模语言模型采样（快速MCP 2.0）
@server.tool()
async def generate_summary(topic: str, ctx: Context = None) -> dict:
"""使用客户端的大规模语言模型通过 ctx.sample() 生成真实摘要"""
result = await ctx.sample(
prompt=f"总结：{topic}",
max_tokens=400,
model_preferences={
"intelligence_priority": 0.8,
"speed_priority": 0.5,
"cost_priority": 0.2
}
)
return {"摘要": result.text, "模型": result.model}
🏭 生产架构
- ✅ 快速MCP 2.0 支持真实采样
- ✅ Pydantic v2 数据验证
- ✅ 会话管理 适用于多用户场景
- ✅ 外部API集成（维基百科，ArXiv，新闻）
- ✅ 错误处理 具有优雅降级
- ✅ 全面测试 - 所有功能均已验证
🛠️ 开发工具
- 🎯 一键检查器 - 自动启动Chrome并进行配置
- 📊 高级日志 - 详细的调试信息
- 🔧 热重载 - 开发模式自动重启
- 📚 可视化文档 - Mermaid图表和指南
🎮 使用案例与示例
🔍 你可以构建什么
mindmap
root((MCP 工厂))
生产系统
知识管理
文档处理
代码分析
数据集成
互动工具
智能调查
上下文助手
教育平台
客户支持
企业解决方案
多用户系统
会话管理
API编排
工作流自动化
📈 现实世界应用
- 📚 知识管理：智能文档检索，带上下文
- 💻 代码助手：互动代码分析和建议
- 🎓 教育工具：适应性学习，双向反馈
- 🏢 企业集成：多系统通过MCP编排
- 🤖 AI工作流程：复杂的多步骤AI交互
🌟 为什么选择 MCP 工厂？
🚀 加速开发
- 完整基础：所有MCP模式都在一个地方
- 生产模板：企业就绪的起点
- 经过验证的架构：经实战考验的设计
- 丰富的示例：从基础到高级实现
📚 教育卓越
- 渐进学习：从hello_world到知识助手
- 可视化文档：Mermaid图表和流程图
- 最佳实践：行业标准模式
- 故障排除指南：解决常见问题
🔧 开发者体验
- 现代工具：UV包管理器，快速MCP 2.0
- 一键设置：自动配置检查器
- 热重载：开发模式快速迭代
- 全面测试：对你的实现充满信心
🚀 高级用法
🔄 双向通信服务器
# 运行双向服务器
cd src/servers/two_way
uv run python server.py
# 测试互动功能
# → start_survey: 开始互动对话
# → 服务器会问你问题！
🧠 具有真实大规模语言模型的知识助手
# 具有45个功能的全功能服务器
cd src/servers/knowledge_assistant
uv run python server.py
# 尝试这些惊人的功能：
# → generate_summary: 真实大规模语言模型摘要
# → search_knowledge: 类似RAG的知识检索
# → fetch_wikipedia: 外部API集成
# → ask_question: 互动问答会话
🏭 生产部署
# 使用企业模板
cp templates/production.py my_server.py
# 根据需要定制
# → 包含会话管理
# → 内置错误处理
# → 外部API模式准备就绪
# → 启用多用户支持
📖 文档
🎯 快速参考
🎯 专业指南
📚 完整文档地图
| 部分 | 英文 | 葡萄牙语 | 重点 |
|---|---|---|---|
| 核心概念 | en-us/01-concepts.md | pt-br/01-conceitos.md | MCP基础 |
| 架构 | en-us/02-architecture.md | pt-br/02-arquitetura.md | 技术设计 |
| 实施 | en-us/03-guide.md | pt-br/03-guia.md | 分步指南 |
| 快速MCP框架 | en-us/fastmcp/ | pt-br/fastmcp/ | 现代开发 |
| 双向通信 | en-us/two-way/ | pt-br/two-way/ | 双向模式 |
| 实用示例 | - | pt-br/05-exemplos.md | 真实用例 |
🎯 文档亮点
- 📖 完全覆盖：24+综合指南
- 🌍 双语：英文和葡萄牙语版本
- 📊 可视化学习：Mermaid图表和流程图
- 🚀 渐进复杂度：从hello_world到生产系统
- 💡 最佳实践：行业标准实现模式
🤝 贡献
我们欢迎贡献！MCP工厂旨在成为MCP开发的权威基础。
🎯 贡献领域
- 🌟 新的服务器示例，针对不同的使用案例
- 📚 文档改进和翻译
- 🔧 开发工具增强
- 🧪 测试和验证改进
- 🏭 生产模板，针对各种场景
📝 开始
- 分叉仓库
- 查看我们的贡献指南
- 在问题和PR中参与讨论
- 帮助我们建立最好的MCP基础！
📞 支持与社区
🐛 常见问题及解决方案
| 问题 | 解决方案 |
|---|---|
| CORS错误 | 使用Chrome/Firefox（而不是Safari） |
| 端口已被占用 | 更改服务器配置中的端口 |
| 检查器无法连接 | 运行 ./scripts/start-inspector.sh |
| 缺少依赖项 | 在项目目录中运行 uv sync |
💬 获取帮助
- 📖 查看文档：90%的问题在我们的指南中都有答案
- 🔍 搜索问题：许多问题之前已经被解决过
- 📋 跟随示例：逐步实现可用
- 🎯 从小处开始：从hello_world开始，逐渐进展到复杂示例
🏆 项目影响
MCP工厂 将完整的MCP生态系统整合成一个结构化的基础，使生产就绪的AI集成的快速开发成为可能。
graph TD
A[🏗️ 完整基础] --> E[🚀 快速开发]
B[🔧 生产模板] --> E
C[💡 经验模式] --> E
D[📚 丰富文档] --> E
E --> F[🌟 你的成功]
style F fill:#e8f5e8,stroke:#4caf50,stroke-width:3px
🎯 基础优势
- ⚡ 开发速度提高10倍：跳过样板代码，从工作代码