MCP Base

MCP Base

MCP 项目的坚实基础起点。MCP Base 是一个可用于生产环境、可扩展的模板，用于构建 Python 版模型上下文协议（MCP）服务。快速创建、扩展和部署 MCP 服务，向大模型和 Agent 客户端提供工具、提示词和资源。

---

🚀 这是什么？

这是一个 Python 入门基础模板，而不是特定的服务实现。它提供了一个模块化、文档完善的基础，用于构建自己的 Python MCP 服务，支持多种传输层（STDIO、SSE、HTTP 等），并展示安全性、可扩展性和可维护性方面的最佳实践。

---

🏗️ 架构概览

.
├── src/
│   ├── base/                # Base classes for tools, prompts, resources
│   ├── tools/               # Example tools (filesystem, API, prompt, etc.)
│   ├── resources/           # Example resources (static/dynamic)
│   ├── prompts/             # Example prompts (text generation, summarization)
│   ├── transports/          # Transport layer implementations & docs
│   │   ├── stdio/
│   │   │   └── README.md
│   │   ├── sse/
│   │   │   └── README.md
│   │   └── ...
│   ├── config.py            # Configuration and environment management
│   ├── server.py            # Server instantiation and registration
│   └── main.py              # Entrypoint: selects transport, starts server
├── tests/                   # Example tests for tools/resources
├── Dockerfile               # Containerized deployment
├── requirements.txt / pyproject.toml
├── README.md                # This file
├── CONTRIBUTING.md
└── ...

---

✨ 功能

• 多传输方式支持： STDIO、SSE、HTTP 等（参见 /src/transports/）
• 模块化工具/提示词/资源： 创建类并注册即可添加新功能
• 类型安全的输入验证： 使用 Pydantic 定义架构
• 安全最佳实践： 目录沙箱、输入验证、错误处理
• 可扩展且易于维护： 清晰划分职责、基类和注册表
• 可用于生产环境： 日志记录、环境管理、Docker 支持
• 完善的文档： 面向用户和贡献者

---

🛠️ 开始使用

1. 安装依赖项

pip install -r requirements.txt

2. 配置环境

将 .env.example 复制为 .env，并填写必需的值。

3. 运行服务

STDIO 传输：

python main.py --transport=stdio

SSE/HTTP 传输： 详情请参阅 /src/transports/sse/README.md 和 /src/transports/http/README.md。

---

🧩 添加工具、提示词和资源

工具

• 在 /src/tools/ 中创建一个继承自 BaseTool 的新类
• 实现必需的方法和输入架构
• 在工具注册表中注册该工具

提示词

• 在 /src/prompts/ 中创建一个继承自 BasePrompt 的新类
• 实现必需的方法和输入架构
• 在提示词注册表中注册该提示词

资源

• 在 /src/resources/ 中添加静态或动态资源
• 在资源注册表中注册这些资源

---

🔌 支持的传输方式

• STDIO： 用于 CLI 和 Agent 集成（参见 /src/transports/stdio/README.md）
• SSE： 用于服务器发送事件和 Web 客户端（参见 /src/transports/sse/README.md）
• HTTP： 用于 RESTful 或 Web 集成（参见 /src/transports/http/README.md）

每种传输方式都是模块化的，可以扩展或替换。

---

🛡️ 安全与最佳实践

• 所有文件和目录操作都限制在允许的路径内
• 对所有工具/资源输入执行输入验证
• 错误处理保持一致且便于用户理解
• 通过环境变量管理敏感配置

---

🧪 测试

• /tests/ 中提供了示例测试
• 使用 Pytest 作为测试运行器
• 测试指南请参阅 CONTRIBUTING.md

---

🤝 参与贡献

欢迎贡献！有关指南、代码风格和 PR 流程，请参阅 CONTRIBUTING.md。

---

📚 延伸阅读

• 模型上下文协议文档
• 官方 MCP Python SDK
• MCP 服务参考图库
• 传输层文档

---

📝 许可证

MIT 许可证。详情请参阅 LICENSE。

---

💬 社区与支持

• Discord
• Reddit
• GitHub 讨论区

---

MCP Base 是所有新建 Python MCP 服务项目的推荐起点。复刻、扩展并贡献改进！