MCP Server Cookie Cutter Template

MCP 服务 Cookie Cutter 模板

用于创建新的 MCP（Model Context Protocol）服务的 Cookie Cutter 模板。此模板可生成一个功能完备的 MCP 服务，支持多种传输方式（stdio 和 streamable HTTP），并提供高级日志记录、自动装饰器和基于 Web 的管理界面。

功能

• 官方 MCP SDK 1.28+：基于官方 mcp Python SDK 构建（版本固定为 <2.0）
• 多传输方式支持：在单个实现中支持 stdio 和 streamable HTTP，并可选无状态／JSON 响应模式，以用于无服务器部署
• 全部三种 MCP 原语：工具、资源（静态资源 + 模板）和提示词
• 结构化输出：类型化的 Pydantic 工具返回值，并自动生成输出架构
• 工具元数据：便于理解的标题和行为注解（只读、破坏性、幂等、开放世界提示）
• 自动装饰器：异常处理、日志记录、类型转换和并行化
• 统一日志系统：基于 SQLite 的日志记录，支持关联 ID 和可扩展的存储目标
• Web 管理界面：基于 Streamlit 的配置、日志和文档管理界面
• 示例工具：可直接使用并遵循最佳实践的示例工具（包括征询、进度和通知演示）
• 全面兼容 MCP Inspector：便于测试和调试
• 规范的绝对导入：始终保持整洁的软件包结构
• DevFlow 集成：内置 JIRA 工作流命令（plan-work、implement、security-review、complete）
• 全面的文档：包含 README、开发指南和设置提示词的模板

前置条件

1. Python 3.11 或更高版本

   python --version  # Should be 3.11 or higher
   

2. uv（快速 Python 软件包安装工具）

   # Install uv if you don't have it
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Cookie Cutter

   uv pip install cookiecutter
   

创建新的 MCP 服务

你可以直接从 GitHub 创建新的 MCP 服务，也可以使用此模板的本地副本。

选项 1：直接从 GitHub 创建

cookiecutter gh:codingthefuturewithai/mcp-cookie-cutter

选项 2：使用本地副本创建

1. 克隆此模板：

   git clone https://github.com/codingthefuturewithai/mcp-cookie-cutter
   

2. 使用本地模板创建项目：

   cookiecutter path/to/mcp-cookie-cutter
   

模板配置

系统会提示你填写以下信息：

• project_name：便于理解的名称（例如，“My MCP Server”）
• __project_slug：Python 软件包名称（根据 project_name 自动生成，例如，“my_mcp_server”）
• description：项目简短描述
• author_name：你的姓名
• email：你的电子邮箱地址
• server_port：Streamable HTTP 传输端口（默认值：3001）

生成的项目结构

my_mcp_server/              # Your project directory
├── .claude/                # Claude Code integration
│   ├── agents/            # Security scanner agent
│   └── commands/          # DevFlow workflow commands
│       └── devflow/       # JIRA-integrated development workflow
├── my_mcp_server/          # Python package directory
│   ├── __init__.py
│   ├── __main__.py
│   ├── client/             # Client implementations
│   │   ├── __init__.py
│   │   └── app.py         # Test client for development
│   ├── server/            # Server implementation
│   │   ├── __init__.py
│   │   └── app.py        # Multi-transport MCP server (stdio, streamable HTTP)
│   ├── tools/             # Tool implementations
│   │   ├── __init__.py
│   │   └── example_tools.py  # Example tools with decorators
│   ├── decorators/        # Automatic tool decorators
│   │   ├── exception_handler.py
│   │   ├── tool_logger.py
│   │   ├── type_converter.py
│   │   └── parallelize.py
│   ├── log_system/        # Unified logging system
│   │   ├── correlation.py     # Correlation ID tracking
│   │   ├── unified_logger.py  # Main logging interface
│   │   └── destinations/      # Log destinations (SQLite, etc.)
│   ├── ui/                # Streamlit management UI
│   │   ├── app.py
│   │   ├── lib/          # UI components and utilities
│   │   └── pages/        # UI pages (Home, Config, Logs, Docs)
│   ├── config.py          # Server configuration
│   └── logging_config.py  # Logging setup
├── tests/                 # Test suite
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── pyproject.toml         # Project configuration and dependencies
├── README.md             # Project documentation template
├── DEVELOPMENT.md        # Development guide
├── DEVELOPER_GUIDE.md    # Developer reference
└── SETUP_PROMPT.md       # AI-assisted setup guide

后续步骤

项目生成后：

1. 查看文档模板

   • 根据项目自定义 README.md
   • 查看 DEVELOPMENT.md，了解开发工作流
   • 查看 DEVELOPER_GUIDE.md，了解架构详情
   • 使用 SETUP_PROMPT.md 获取 AI 辅助设置

2. 设置开发环境

   • 安装依赖：uv pip install -e .
   • 运行测试：pytest
   • 启动服务：python -m your_project_name --transport stdio

3. 探索传输方式

   • STDIO：python -m your_project_name --transport stdio
   • Streamable HTTP：python -m your_project_name --transport streamable-http --port 3001

4. 使用 MCP Inspector 测试

   • 安装：npm install -g @modelcontextprotocol/inspector
   • 运行：mcp dev your_project_name/server/app.py

5. 访问管理界面

   • 启动界面：streamlit run your_project_name/ui/app.py
   • 查看日志、配置服务、浏览文档

6. 添加自己的工具

   • 在 tools/example_tools.py 中添加函数
   • 装饰器会自动应用
   • 在 example_tools 或 parallel_example_tools 列表中注册

7. 使用 DevFlow 工作流（可选）

   • 连接到 JIRA
   • 使用 /devflow:plan-work ISSUE-KEY 进行规划
   • 使用 /devflow:implement ISSUE-KEY 进行实现
   • 使用 /devflow:security-review ISSUE-KEY 进行扫描
   • 使用 /devflow:complete ISSUE-KEY 创建 PR

许可证

此模板采用 MIT 许可证授权，详情请参阅 LICENSE 文件。