使用说明
配方MCP服务器
A. 生产就绪模型上下文协议（MCP）服务器 提供LLM驱动的客户端 具有全面的食谱管理、营养分析和膳食计划能力。
作为两个a 学习展示 展示MCP的所有能力
2025-11-25规范（23个不同特征）和 生产服务 集成的
进入 recipe-web-app 微服务生态系统。
技术栈
| 组件 | 技术 | 目的 |
|---|---|---|
| 框架 | FastMCP 3.1.1+ | MCP服务器，带原生OTel+模式生成器 |
| 语言 | Python 3.13+ | 最新稳定版本，异步/等待 |
| 运行时管理器 | mise | Python版本+任务运行器 |
| 包管理器 | uv | 快速确定性依赖解析 |
| 数据库 | SQLite（aiosqlite） | 零基础设施，WAL模式 |
| 缓存 | Redis 7+ | API响应缓存，会话状态 |
| ORM | SQLAlchemy 2.0+ | 异步支持，存储库模式 |
| 验证 | Pydantic 2.10+ | 工具参数的自动JSON模式 |
| 追踪 | OpenTetry+Jaeger | 分布式追踪 |
| 测试 | pytest+pytest-asyncio | 异步测试支持，覆盖率高 |
快速启动
# Prerequisites: mise (https://mise.jdx.dev)
git clone <repo> && cd recipe-mcp-server
# Install Python 3.13, uv, and all tools
mise install
# Install dependencies
uv sync
# Copy and configure environment
cp .env.example .env
# Run the server (stdio mode for Claude Desktop)
mise run dev
码头工人
# Start the full stack (server + Redis + Jaeger)
mise run docker-up
# View Jaeger tracing UI
open http://localhost:16686
# Stop all services
mise run docker-down
建筑
Client (Claude Desktop / AI Agent)
│
▼
┌─────────────────────────────────────┐
│ FastMCP Server (tools/resources/ │
│ prompts/sampling/elicitation) │
├─────────────────────────────────────┤
│ Middleware (auth, rate limit, │
│ error handling, validators) │
├─────────────────────────────────────┤
│ Services (recipe, nutrition, │
│ meal plan, shopping, conversion) │
├──────────────┬──────────────────────┤
│ API Clients │ DB Repositories │
│ (MealDB, │ (SQLAlchemy 2.0 │
│ USDA, │ + aiosqlite) │
│ Spoon...) │ │
├──────────────┴──────────────────────┤
│ Observability (OTel + structlog) │
│ Cache (Redis) │
└─────────────────────────────────────┘
项目结构
recipe-mcp-server/
├── .mise.toml # mise: Python version + uv + task runner
├── pyproject.toml # uv: dependencies + build + tool config
├── lefthook.yml # Git hooks: lint, format, test, secrets
│
├── src/recipe_mcp_server/
│ ├── __init__.py
│ ├── __main__.py # Entry point: python -m recipe_mcp_server
│ ├── server.py # FastMCP app factory
│ ├── config.py # pydantic-settings configuration
│ ├── models/ # Pydantic domain models
│ ├── db/ # SQLite persistence (engine, tables, repos)
│ ├── cache/ # Redis caching
│ ├── clients/ # Downstream API clients
│ ├── services/ # Business logic orchestration
│ ├── tools/ # MCP Tool definitions
│ ├── resources/ # MCP Resource definitions
│ ├── prompts/ # MCP Prompt definitions
│ ├── sampling/ # Server-initiated LLM sampling
│ └── elicitation/ # User input collection
│
├── tests/
│ ├── conftest.py # Shared fixtures
│ ├── factories/ # Test data factories
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests (Redis)
│ └── e2e/ # End-to-end protocol tests
│
├── migrations/ # Alembic database migrations
└── docs/ # Requirements and design docs
可用任务
所有任务都通过运行 mise run <task>:
| 任务 | 描述 |
|---|---|
dev |
在本地运行服务器（stdio模式） |
dev-http |
在本地运行服务器（HTTP模式） |
test |
运行所有测试 |
test-unit |
仅运行单元测试 |
test-integration |
运行集成测试（需要Redis） |
test-e2e |
运行端到端MCP协议测试 |
test-coverage |
使用覆盖率报告运行测试（最低85%） |
lint |
运行所有门楣（ruff+mypy） |
fmt |
自动格式化代码 |
security |
运行安全检查（osv扫描仪+土匪） |
docker-build |
构建Docker镜像 |
docker-up |
启动所有服务（服务器+Redis+Jaeger） |
docker-down |
停止所有服务 |
db-migrate |
运行Alembic迁移 |
db-seed |
包含样本数据的种子数据库 |
inspect |
启动MCP检查器 |
check |
运行所有检查（lint+test+security） |
clean |
删除构建工件和缓存 |