使用说明

MCP饼干切割机

一个强大的CLI工具和cookiecutter模板，用于创建模型上下文协议（MCP）服务器。只需一个命令即可在几秒钟内获得一个完整配置的MCP服务器，然后为您的API定制它。

特性

🎯 CLI工具：生成MCP服务器的一个命令- pip install mcp-cookie-cutter && mcp-cookie-cutter
🚀 快速开始：在几秒钟内生成一个可用的MCP服务器
🐍 Python与FastMCP：采用FastMCP框架的现代基于Python的MCP服务器
🔧 OpenAPI自动生成：根据OpenAPI/Swagger规范自动生成工具
🌐 本地和远程：支持STDIO（本地）和流式HTTP（远程）传输
🔐 认证：OAuth 2.1和API密钥身份验证的内置模板
📦 全功能：自动生成的工具、提示和Pydantic模型
📝 易于定制：添加API工具的清晰示例和指南
⚡ 现代工具：使用紫外线进行包装管理，使用紫外线进行生产
✅ 最佳实践：遵循MCP规范和安全指南

所得

完整的MCP服务器项目结构
智能OpenAPI解析 -请参阅生成期间可用的API操作
示例工具实现（GET和POST）
全面定制.md指南
身份验证模板
开发环境设置
Claude桌面集成说明

先决条件

Python 3.10+（必填）

安装与使用

🎯 选项1:CLI工具（推荐-最简单！）

最快的入门方法：

# Install the CLI tool
pip install mcp-cookie-cutter

# Generate your MCP server
mcp-cookie-cutter

# Or with specific options
mcp-cookie-cutter --no-input project_name="My API Server"

就是这样！ CLI捆绑了您需要的一切。

🔧 选项2：与Cookiecutter一起使用

如果您更喜欢直接使用cookiecutter：

# Install cookiecutter first
pip install cookiecutter

# Use the template from GitHub
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter

依赖关系详细信息

所有依赖项都会使用CLI工具自动安装。如果直接使用炊具：

饼干模具 （必填）-模板生成引擎
格式（可选）-用于解析YAML OpenAPI规范
请求： （可选）-用于从URL获取OpenAPI规范
openapi媒染剂 （可选）-用于验证和解析具有类型安全性的OpenAPI模式
数据模型代码生成器 （可选）-用于生成Pydantic模型

如果没有可选的依赖关系，您仍然可以生成MCP服务器，但OpenAPI规范解析和工具建议将不可用。

快速开始

步骤1：安装并运行

使用CLI（推荐）：

pip install mcp-cookie-cutter
mcp-cookie-cutter

或者使用炊具：

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或专有软件中选择

步骤3：自定义您的工具

生成的服务器包括示例工具。按照CUSTOMIZATION.md指南添加您的API端点。

步骤4：运行服务器

按照生成后显示的设置说明进行操作，或查看生成的README.md。

生成什么

项目结构

my-mcp-server/
├── src/
│   └── my_mcp_server/
│       ├── server.py          # FastMCP server with auto-discovery
│       ├── tools/             # Individual tool files (auto-generated)
│       │   ├── __init__.py
│       │   ├── addPet.py      # Example: POST /pet
│       │   ├── getPetById.py  # Example: GET /pet/{petId}
│       │   └── ...
│       ├── prompts/           # Auto-generated prompts from OpenAPI
│       │   ├── __init__.py
│       │   └── pet_operations.py
│       └── models/            # Pydantic models from OpenAPI
│           ├── __init__.py
│           └── schemas.py
├── test_server.py         # Development testing with auto-reload
├── pyproject.toml         # Python project configuration
├── .env.example           # Environment variables template
├── Dockerfile             # Docker container configuration
├── docker-compose.yml     # Docker compose for easy deployment
├── README.md              # Generated documentation
├── CUSTOMIZATION.md       # Guide for adding custom tools
└── .gitignore

特性

OpenAPI集成：根据OpenAPI规范自动生成工具、提示和Pydantic模型
FastMCP框架：具有基于装饰器的工具定义的现代Python MCP框架
运输支持:
- 本地（STDIO）：适用于Claude Desktop和本地客户
- 远程（流式HTTP）：带uvicorn的生产级HTTP服务器
认证:
- 无：开放获取（仅限本地开发）
- API密钥：承载令牌身份验证
- OAuth 2.1：符合标准的OAuth，支持PKCE
MCP功能:
- 工具：从OpenAPI操作自动生成（每个工具的单个文件）
- 提示词：API操作中自动生成的有用提示
- 模型：OpenAPI模式中的Pydantic模型
- 日志记录：正确的stderr日志记录（STDIO安全）

OpenAPI/Swagger集成

该模板包括智能OpenAPI解析：

加载OpenAPI/Swagger规范 （来自文件或URL）
验证规格 使用openapi pydantic（如果已安装）
提取所有可用端点 （获取、发布、放置、删除、修补）
显示操作详细信息 在生成过程中

支持的OpenAPI格式

OpenAPI 3.0/3.1（JSON或YAML）
Swagger 2.0（JSON或YAML）

OpenAPI流示例

# Provide your OpenAPI spec path when prompted
openapi_spec_path: https://petstore.swagger.io/v2/swagger.json

# The hook will scan and display:
✨ Found 20 available API operations:
----------------------------------------------------------------------
 1. POST   /pet                           - addPet
     Add a new pet to the store
 2. GET    /pet/{petId}                   - getPetById
     Find pet by ID
...
----------------------------------------------------------------------

💡 You can implement these as MCP tools in your generated server.

配置示例

无身份验证的本地服务器

deployment_type: local
auth_mechanism: none
openapi_spec_path: https://petstore3.swagger.io/api/v3/openapi.json

结果：Claude Desktop基于STDIO的服务器，带有自动生成的工具

具有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类型
- 装订和格式化配置
- 包括测试设置

发展

自定义模板

模板使用Jinja2模板。关键文件：

cookiecutter.json：配置选项
hooks/pre_gen_project.py：预生成验证和OpenAPI扫描
hooks/post_gen_project.py：生成后设置和清理
{{cookiecutter.project_slug}}/：具有Jinja2语法的模板文件

测试您的模板

# Generate a test project
cookiecutter . --no-input

# Or with specific values
cookiecutter . --no-input deployment_type=local auth_mechanism=none

# Test with OpenAPI spec
cookiecutter . --no-input \
  openapi_spec_path="https://petstore3.swagger.io/api/v3/openapi.json" \
  deployment_type="remote" \
  server_port="9090"

测试资源

使用这些经过验证的具有OpenAPI 3.0规范的API测试您的MCP Cookie Cutter模板：

1. Swagger宠物店 ⭐ 推荐用于测试

OpenAPI规范: https://petstore3.swagger.io/api/v3/openapi.json
基础URL: https://petstore3.swagger.io/api/v3
认证：无需
资源：宠物、商店、用户
为什么：API测试金标准，功能齐全，无需授权

2. JSON占位符 -简单&免费

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. 条纹API -付款处理

OpenAPI规范: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
基础URL: https://api.stripe.com
认证：API密钥（可用的免费测试模式）
资源：付款、客户、产品、订阅
为什么：文件齐全，生产级API

5. API大师合集 -300+公共API

仓库: https://github.com/APIs-guru/openapi-directory
热门API:
- 开放天气地图: https://raw.githubusercontent.com/APIs-guru/openapi-directory/main/APIs/openweathermap.org/2.5/openapi.yaml
- 声破天: https://raw.githubusercontent.com/APIs-guru/openapi-directory/main/APIs/spotify.com/openapi.yaml
- 提里奥: https://raw.githubusercontent.com/APIs-guru/openapi-directory/main/APIs/twilio.com/openapi.yaml

快速测试命令

使用CLI工具（推荐）：

# Install if you haven't already
pip install mcp-cookie-cutter

# Test with Petstore (just run and enter the OpenAPI URL when prompted)
mcp-cookie-cutter

# Or use with --no-input for automated testing
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"

或者直接使用炊具：

# Test with 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"

# Test with 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"

# Test with GitHub API (note: very large spec, may take a minute)
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 spec available at: http://localhost:8080/api/v3/openapi.json

Prism模拟服务器（模拟任何OpenAPI规范）：

npm install -g @stoplight/prism-cli
prism mock https://petstore3.swagger.io/api/v3/openapi.json
# Creates a mock API server on http://localhost:4010

资源

分布

面向最终用户

使用此工具最简单的方法是通过PyPI：

# Install the CLI tool
pip install mcp-cookie-cutter

# Use it anywhere
mcp-cookie-cutter

对于团队

通过PyPI分享（推荐）：

# Team members simply install and use
pip install mcp-cookie-cutter
mcp-cookie-cutter

或者通过GitHub分享：

# Team members use directly from GitHub
cookiecutter gh:maheshmahadevan/mcp-cookie-cutter

面向开发者

如果要在本地修改模板：

# Clone the repository
git clone https://github.com/maheshmahadevan/mcp-cookie-cutter.git
cd mcp-cookie-cutter

# Install in editable mode
pip install -e .

# Now the CLI uses your local version
mcp-cookie-cutter

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
测试您的更改
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

在GitHub上打开一个问题
检查现有问题和讨论
查阅MCP文档

在几秒钟内生成生产就绪的MCP服务器！