Recipe MCP Server

个人配方管理器MCP服务器

一种模型上下文协议（MCP）服务器，允许ChatGPT持久存储、检索和组织配方文件。食谱存储为带有YAML frontmatter的Markdown文件，使其对人工智能友好且易于人类阅读。

特性

• 永久存储：使用YAML frontmatter将食谱存储为Markdown文件
• 三个核心工具:

- save_recipe：使用元数据创建或更新食谱 - read_recipe：检索配方内容 - list_recipes：列出所有具有可选类别过滤的食谱

• 安全：通过模糊UUID路径进行基于URL的身份验证
• 部署：基于Docker的Render部署，具有持久磁盘存储

建筑

服务器使用：

• 协议：HTTP上的模型上下文协议（MCP）+服务器发送事件（SSE）
• 存储：包含YAML frontmatter的Markdown文件 /app/recipes
• 认证：模糊安全-URL路径中嵌入UUID
• 框架：支持SSE的FastAPI

项目结构

recipe-mcp-server/
├── server.py              # Main MCP server implementation
├── Dockerfile             # Docker configuration
├── requirements.txt       # Python dependencies
├── .dockerignore          # Docker ignore patterns
├── .gitignore            # Git ignore patterns
├── README.md             # This file
└── recipes/              # Local testing directory (not in Docker)
    └── .gitkeep

安装说明

地方发展

1. 克隆存储库 （或导航到项目目录）

1. 创建虚拟环境:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

1. 安装依赖项:

   pip install -r requirements.txt

1. 设置环境变量 （可选）：

   export MCP_AUTH_UUID="your-uuid-here"  # Optional: set custom UUID
   export PORT=8000  # Optional: set custom port

1. 运行服务器:

   python server.py

服务器将于启动 http://localhost:8000

Docker本地测试

1. 构建Docker镜像:

   docker build -t recipe-mcp-server .

1. 运行容器:

   docker run -p 8000:8000 -v $(pwd)/recipes:/app/recipes recipe-mcp-server

注意：对于本地测试，您可能需要挂载一个本地配方目录。

要渲染的部署

先决条件

• 渲染帐户
• GitHub存储库（可选，用于自动部署）

部署步骤

1. 将代码推送到GitHub （如果使用GitHub集成）

1. 在渲染时创建Web服务:

- 转到渲染仪表板 - 点击“新建+”→ “Web服务” - 连接您的GitHub存储库（或使用公共Git存储库）

1. 配置服务:

- 名字: recipe-mcp-server （或您喜欢的名字） - 运行时: Docker - 实例类型: Starter （或支持磁盘的任何层） - 生成命令：（留空，Docker处理此问题） - 启动命令：（留空，Dockerfile CMD处理此问题）

1. 添加永久磁盘 （关键）：

- 在服务设置中，转到“磁盘” - 点击“添加磁盘” - 安装路径: /app/recipes - 尺寸: 1GB （根据需要进行调整） - 名字: recipe-storage

1. 设置环境变量 （可选）：

- MCP_AUTH_UUID：身份验证路径的自定义UUID（如果未设置，将生成一个） - PORT：端口号（默认值：8000，Render会自动设置）

1. 部署:

- 点击“创建Web服务” - 等待部署完成

1. 获取您的MCP端点URL:

- 部署后，访问服务URL - 根端点(/)将显示MCP端点路径 - 您的完整MCP URL将是： https://your-service.onrender.com/mcp-{uuid}/sse

连接到ChatGPT

1. 获取您的MCP端点URL 从渲染服务（见上文）

1. 打开ChatGPT开发者设置:

- 转到ChatGPT设置 - 导航到开发人员模式或MCP设置 - 添加新的MCP服务器

1. 配置MCP服务器:

- 名字：配方管理器（或您的首选名称） - 统一资源定位符: https://your-service.onrender.com/mcp-{uuid}/sse - 类型：HTTP+SSE

1. 保存并测试:

- 服务器现在应该可以用于ChatGPT - 尝试让ChatGPT保存一个配方来测试连接

API 文档

工具： save_recipe

使用YAML frontmatter创建或更新配方文件。

端点: POST /mcp-{uuid}/sse/tools/save_recipe

请求体:

{
  "filename": "spicy_tacos.md",
  "content": "# Spicy Tacos\n\n**Ingredients:**\n- ...",
  "category": "Dinner",
  "tags": ["mexican", "spicy", "easy"],
  "prep_time": "15m",
  "cook_time": "20m",
  "servings": 4
}

可选字段:

• prep_time：准备时间（例如“15m”、“30分钟”）
• cook_time：烹饪时间（例如“45米”、“1小时”）
• servings：份数（整数）

响应:

{
  "success": true,
  "message": "Recipe 'spicy_tacos.md' saved successfully",
  "filename": "spicy_tacos.md"
}

工具： read_recipe

检索配方文件的完整内容（包括frontmatter）。

端点: POST /mcp-{uuid}/sse/tools/read_recipe

请求体:

{
  "filename": "spicy_tacos.md"
}

响应:

{
  "success": true,
  "filename": "spicy_tacos.md",
  "content": "---\ncategory: Dinner\ntags: [mexican, spicy, easy]\n---\n# Spicy Tacos\n\n..."
}

工具： list_recipes

列出所有配方文件，可选择按类别筛选。

端点: POST /mcp-{uuid}/sse/tools/list_recipes

请求体:

{
  "category": "Dinner"  // Optional
}

响应:

{
  "success": true,
  "recipes": ["spicy_tacos.md", "lasagna.md"],
  "count": 2
}

配方文件格式

食谱存储为带有YAML frontmatter的Markdown文件：

---
category: "Dinner"
tags: ["italian", "pasta", "comfort-food"]
prep_time: "30m"
---
# Classic Lasagna

**Ingredients:**
- ...

**Instructions:**
1. ...

安全注意事项

基于URL的身份验证

服务器使用“模糊安全”-身份验证嵌入在URL路径本身中：

• 生成（或通过以下方式设置）随机UUID MCP_AUTH_UUID 环境变量）
• MCP端点仅在以下位置可访问 /mcp-{uuid}/sse
• 如果有人不知道UUID，他们就无法访问服务器

重要:

• 不要公开共享您的MCP URL
• 如果URL被泄露，任何有URL的人都可以读/写你的食谱
• 如果URL暴露，请考虑重新生成UUID

路径横向保护

服务器实现了严格的文件名验证：

• 拒绝包含以下内容的文件名 ../ 或路径分隔符
• 拒绝绝对路径
• 只允许 .md 文件
• 所有文件操作都限制为 /app/recipes

错误处理

• 无效的文件名：返回400个带错误消息的错误请求
• 缺少文件：返回404未找到
• 正面无效：优雅地处理解析错误（如果需要，跳过列表中的文件）
• 磁盘已满：返回500内部服务器错误

故障排除

服务器无法启动

• 检查端口8000是否可用（或已设置 PORT 环境变量）
• 验证是否安装了所有依赖项： pip install -r requirements.txt
• 如果在Docker中运行，请检查Docker日志

食谱不持久

• 在渲染时：验证持久磁盘是否已装载在 /app/recipes
• 在Render仪表板中检查磁盘大小和使用情况
• 验证磁盘是否正确连接到服务

MCP连接失败

• 验证包含UUID路径的完整URL
• 检查服务器是否正在运行且可访问
• 测试根端点(/)获取正确的MCP路径
• 检查渲染服务日志是否有错误

类别筛选不起作用

• 验证配方是否具有有效的YAML frontmatter
• 检查一下 category 字段设置在前台
• 类别匹配不区分大小写

发展

在本地运行测试

测试服务器终结点：

# Start the server
python server.py

# In another terminal, test save_recipe
curl -X POST http://localhost:8000/mcp-{uuid}/sse/tools/save_recipe \
  -H "Content-Type: application/json" \
  -d '{"filename": "test.md", "content": "# Test Recipe", "category": "Test"}'

# Test read_recipe
curl -X POST http://localhost:8000/mcp-{uuid}/sse/tools/read_recipe \
  -H "Content-Type: application/json" \
  -d '{"filename": "test.md"}'

# Test list_recipes
curl -X POST http://localhost:8000/mcp-{uuid}/sse/tools/list_recipes \
  -H "Content-Type: application/json" \
  -d '{}'

许可证

本项目按原样提供供个人使用。

支持

对于问题或疑问：

1. 检查上面的故障排除部分
2. 查看渲染服务日志
3. 验证MCP端点URL是否正确