MCP-饼干切割器
项目介绍
MCP Cookie Cutter
一个强大的命令行工具和cookiecutter模板，用于创建模型上下文协议（MCP）服务器。只需一条命令即可在几秒钟内生成一个完全配置好的MCP服务器，然后根据您的API进行自定义。
功能
- 🎯 命令行工具：一条命令生成您的MCP服务器 -
pip install mcp-cookie-cutter && mcp-cookie-cutter - 🚀 快速开始：几秒钟内生成一个可工作的MCP服务器
- 🐍 基于Python的FastMCP：现代基于Python的MCP服务器，使用FastMCP框架
- 🔧 自动生成OpenAPI工具：从OpenAPI/Swagger规范中自动生成工具
- 🌐 本地与远程支持：支持STDIO（本地）和流式HTTP（远程）传输
- 🔐 认证：内置OAuth 2.1和API密钥认证模板
- 📦 全功能：自动生成工具、提示和Pydantic模型
- 📝 易于定制：清晰的例子和指南，帮助添加您的API工具
- ⚡ 现代工具：使用uv进行包管理和生产环境中的uvicorn
- ✅ 最佳实践：遵循MCP规范和安全指南
您将获得
- 完整的MCP服务器项目结构
- 智能OpenAPI解析 - 在生成过程中查看可用的API操作
- 工具实现示例（GET和POST）
- 综合的CUSTOMIZATION.md指南
- 认证模板
- 开发环境设置
- Claude Desktop集成说明
先决条件
- Python 3.10+（必需）
安装与使用
🎯 方案1：命令行工具（推荐 - 最简单！）
最快的方式开始：
# 安装命令行工具
pip install mcp-cookie-cutter
# 生成您的MCP服务器
mcp-cookie-cutter
# 或者使用特定选项
mcp-cookie-cutter --no-input project_name="我的API服务器"
就这样！ 命令行工具捆绑了您所需的一切。
🔧 方案2：使用cookiecutter
如果您更喜欢直接使用cookiecutter：
# 首先安装cookiecutter
pip install cookiecutter
# 使用GitHub上的模板
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter
依赖项详情
所有依赖项都会通过命令行工具自动安装。如果直接使用cookiecutter：
- cookiecutter（必需） - 模板生成引擎
- pyyaml（可选） - 解析YAML OpenAPI规范
- requests（可选） - 从URL获取OpenAPI规范
- openapi-pydantic（可选） - 使用类型安全验证和解析OpenAPI模式
- datamodel-code-generator（可选） - 生成Pydantic模型
没有这些可选依赖项，您仍然可以生成MCP服务器，但OpenAPI规范解析和工具建议将不可用。
快速开始
第一步：安装并运行
使用命令行（推荐）：
pip install mcp-cookie-cutter
mcp-cookie-cutter
或者使用cookiecutter：
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter
第二步：回答提示
您将被要求配置：
- 项目名称：您的MCP服务器名称
- 项目描述：简短描述
- 作者信息：您的姓名和电子邮件
- OpenAPI规范路径：(可选) 您的OpenAPI/Swagger规范的路径或URL
- 部署类型：本地（STDIO）或远程（流式HTTP）
- 服务器端口：远程部署的端口（默认：8000）
- 认证：无、API密钥或OAuth 2.1
- 许可证：从MIT、Apache-2.0、BSD-3-Clause、GPL-3.0或专有中选择
第三步：自定义您的工具
生成的服务器包括示例工具。请参阅CUSTOMIZATION.md指南以添加您的API端点。
第四步：运行您的服务器
按照生成后显示的设置说明操作，或查看生成的README.md。
生成的内容
项目结构
my-mcp-server/
├── src/
│ └── my_mcp_server/
│ ├── server.py # 自动发现的FastMCP服务器
│ ├── tools/ # 单个工具文件（自动生成）
│ │ ├── __init__.py
│ │ ├── addPet.py # 示例：POST /pet
│ │ ├── getPetById.py # 示例：GET /pet/{petId}
│ │ └── ...
│ ├── prompts/ # 从OpenAPI自动生成的提示
│ │ ├── __init__.py
│ │ └── pet_operations.py
│ └── models/ # 从OpenAPI生成的Pydantic模型
│ ├── __init__.py
│ └── schemas.py
├── test_server.py # 开发测试，带自动重载
├── pyproject.toml # Python项目配置
├── .env.example # 环境变量模板
├── Dockerfile # Docker容器配置
├── docker-compose.yml # Docker Compose，便于部署
├── README.md # 生成的文档
├── CUSTOMIZATION.md # 添加自定义工具的指南
└── .gitignore
特性
- OpenAPI集成：从OpenAPI规范中自动生成工具、提示和Pydantic模型
- FastMCP框架：现代基于Python的MCP框架，带有基于装饰器的工具定义
- 传输支持：
- 本地（STDIO）：适用于Claude Desktop和本地客户端
- 远程（流式HTTP）：生产级HTTP服务器，使用uvicorn
- 认证：
- 无：开放访问（仅限本地开发）
- API密钥：Bearer令牌认证
- OAuth 2.1：符合标准的OAuth，支持PKCE
- MCP特性：
- 工具：从OpenAPI操作自动生成（每个工具单独文件）
- 提示：从API操作自动生成的帮助提示
- 模型：从OpenAPI模式生成的Pydantic模型
- 日志：适当的stderr日志记录（STDIO安全）
OpenAPI/Swagger集成
模板包括智能OpenAPI解析，它：
- 加载您的OpenAPI/Swagger规范（从文件或URL）
- 验证规范（如果已安装openapi-pydantic）
- 提取所有可用端点（GET、POST、PUT、DELETE、PATCH）
- 在生成过程中显示操作细节
支持的OpenAPI格式
- OpenAPI 3.0/3.1（JSON或YAML）
- Swagger 2.0（JSON或YAML）
OpenAPI示例流程
# 提供您的OpenAPI规范路径
openapi_spec_path: https://petstore.swagger.io/v2/swagger.json
# 钩子将扫描并显示：
✨ 找到20个可用的API操作：
----------------------------------------------------------------------
1. POST /pet - addPet
添加一个新的宠物到商店
2. GET /pet/{petId} - getPetById
根据ID查找宠物
...
----------------------------------------------------------------------
💡 您可以在生成的服务器中实现这些作为MCP工具。
配置示例
无认证的本地服务器
deployment_type: local
auth_mechanism: none
openapi_spec_path: https://petstore3.swagger.io/api/v3/openapi.json
结果：基于STDIO的服务器，适用于Claude Desktop，并自动生成工具
带API密钥的远程服务器
deployment_type: remote
server_port: 9090
auth_mechanism: api_key
openapi_spec_path: https://petstore3.swagger.io/api/v3/openapi.json
结果：带API密钥认证的流式HTTP服务器，并自动生成工具
带OAuth的远程服务器
deployment_type: remote
server_port: 8000
auth_mechanism: oauth2
openapi_spec_path: https://api.github.com/openapi.json
结果：带OAuth 2.1认证的流式HTTP服务器
最佳实践
生成的服务器遵循MCP最佳实践：
-
安全性：
- 推荐公共客户端使用OAuth 2.1
- 内部服务使用API密钥
- 正确的用户同意流程
- 基于环境的凭据管理
-
传输：
- 本地部署使用STDIO（无网络暴露）
- 远程部署使用SSE（状态连接）
- 正确的日志记录到stderr（绝不会到stdout）
-
错误处理：
- 全面的错误消息
- 输入验证
- 平滑降级
-
代码质量：
- 类型提示（Python）/ TypeScript类型
- 包含linting和格式化配置
- 包含测试设置
开发
自定义模板
模板使用Jinja2模板。关键文件：
cookiecutter.json：配置选项hooks/pre_gen_project.py：预生成验证和OpenAPI扫描hooks/post_gen_project.py：生成后的设置和清理{{cookiecutter.project_slug}}/：带有Jinja2语法的模板文件
测试您的模板
# 生成一个测试项目
cookiecutter . --no-input
# 或者使用特定值
cookiecutter . --no-input deployment_type=local auth_mechanism=none
# 使用OpenAPI规范测试
cookiecutter . --no-input \
openapi_spec_path="https://petstore3.swagger.io/api/v3/openapi.json" \
deployment_type="remote" \
server_port="9090"
测试资源
使用这些经过验证的API测试您的MCP Cookie Cutter模板，它们具有OpenAPI 3.0规范：
1. Swagger Petstore ⭐ 推荐用于测试
- OpenAPI规范：https://petstore3.swagger.io/api/v3/openapi.json
- 基础URL：https://petstore3.swagger.io/api/v3
- 认证：无需认证
- 资源：宠物、商店、用户
- 为什么：API测试的黄金标准，功能齐全，无需认证
2. JSONPlaceholder - 简单且免费
- OpenAPI规范：https://gist.githubusercontent.com/oshevtsov/7d17f88f74730ce9c95b6d7bb3e03c3d/raw/jsonplaceholder-openapi-3.0.yaml
- 基础URL：https://jsonplaceholder.typicode.com
- 认证：无需认证
- 资源：帖子、评论、专辑、照片、待办事项、用户
- 为什么：免费的假REST API，适合快速测试
3. GitHub REST API - 现实世界示例
- OpenAPI规范：https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json
- 基础URL：https://api.github.com
- 认证：可选（使用令牌可提高速率限制）
- 资源：仓库、问题、用户、拉取请求
- 为什么：真实的生产API，全面的操作
- 注意：非常大的规范（约15MB） - Pydantic模型生成可能会失败，但工具仍会生成
4. Stripe API - 支付处理
- OpenAPI规范：https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
- 基础URL：https://api.stripe.com
- 认证：API密钥（提供免费测试模式）
- 资源：支付、客户、产品、订阅
- 为什么：文档详尽，生产级API
5. APIs-guru集合 - 超过300个公开API
- 仓库：https://github.com/APIs-guru/openapi-directory
- 流行API：
- OpenWeatherMap：https://raw.githubusercontent.com/APIs-guru/openapi-directory/main/APIs/openweathermap.org/2.5/openapi.yaml
- Spotify：https://raw.githubusercontent.com/APIs-guru/openapi-directory/main/APIs/spotify.com/openapi.yaml
- Twilio：https://raw.githubusercontent.com/APIs-guru/openapi-directory/main/APIs/twilio.com/openapi.yaml
快速测试命令
使用命令行工具（推荐）：
# 如果尚未安装，请安装
pip install mcp-cookie-cutter
# 使用Petstore测试（只需运行并输入OpenAPI URL）
mcp-cookie-cutter
# 或使用--no-input进行自动化测试
mcp-cookie-cutter --no-input \
project_name="petstore_server" \
openapi_spec_path="https://petstore3.swagger.io/api/v3/openapi.json" \
deployment_type="remote" \
server_port="9090" \
auth_mechanism="none"
或者直接使用cookiecutter：
# 使用Petstore测试
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter \
project_name="petstore_server" \
openapi_spec_path="https://petstore3.swagger.io/api/v3/openapi.json" \
deployment_type="remote" \
server_port="9090" \
auth_mechanism="none"
# 使用JSONPlaceholder测试
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter \
project_name="jsonplaceholder_server" \
openapi_spec_path="https://gist.githubusercontent.com/oshevtsov/7d17f88f74730ce9c95b6d7bb3e03c3d/raw/jsonplaceholder-openapi-3.0.yaml" \
deployment_type="remote" \
server_port="9090" \
auth_mechanism="none"
# 使用GitHub API测试（注意：非常大的规范，可能需要一分钟）
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter \
project_name="github_server" \
openapi_spec_path="https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json" \
deployment_type="remote" \
server_port="9090" \
auth_mechanism="api_key"
自托管测试选项
快速Docker部署 - Petstore：
docker run -d -p 8080:8080 swaggerapi/petstore3:unstable
# OpenAPI规范可在：http://localhost:8080/api/v3/openapi.json
Prism Mock Server（模拟任何OpenAPI规范）：
npm install -g @stoplight/prism-cli
prism mock https://petstore3.swagger.io/api/v3/openapi.json
# 创建一个模拟API服务器在http://localhost:4010
资源
分发
对最终用户
最简单的使用方式是通过PyPI：
# 安装命令行工具
pip install mcp-cookie-cutter
# 在任何地方使用
mcp-cookie-cutter
对团队
通过PyPI分享（推荐）：
# 团队成员只需安装并使用
pip install mcp-cookie-cutter
mcp-cookie-cutter
或者通过GitHub分享：
# 团队成员直接从GitHub使用
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter
对开发者
如果您想本地修改模板：
# 克隆仓库
git clone https://github.com/maheshmahadevan/mcp-cookie-cutter.git
cd mcp-cookie-cutter
# 以编辑模式安装
pip install -e .
# 现在命令行使用的是您的本地版本
mcp-cookie-cutter
贡献
欢迎贡献！请：
- 分叉仓库
- 创建功能分支
- 测试您的更改
- 提交拉取请求
许可
MIT许可 - 查看LICENSE文件了解详情
支持
对于问题和疑问：
- 在GitHub上打开一个问题
- 查看现有问题和讨论
- 查看MCP文档
几秒钟内生成生产就绪的MCP服务器！