灵魂食品MCP工作坊
模型上下文协议（MCP）的文化相关介绍
通过构建一个灵魂食物食谱规划助手来学习MCP，该助手在展示现代人工智能架构的同时，尊重非裔美国人和南方人的烹饪传统。
🎯 你将学到什么
这个实践工作坊教授 模型上下文协议（MCP） 通过一个有意义的例子：
MCP概念
- 资源：只读上下文（食谱、茶水间、膳食计划、烹饪历史）
- 提示：可重复使用的、具有文化意识的膳食计划模板
- 工具：修改状态的操作（创建计划、更新库存）
- 进度流：生成膳食计划期间的实时更新
- 通知：异步厨房提醒和用餐准备提醒
- 取样和根：自然语言对话和解释
- 引出：互动式饮食偏好协商
- 运输：多种传输实现（HTTP、SSE、stdio）
文化学习
- 尊重南方黑人的烹饪传统
- 了解地区差异（低地、密西西比三角洲、路易斯安那克里奥尔）
- 尊重饮食偏好，同时保持真实性
- 厨房智慧和膳食准备实践
🏗️ 建筑
┌─────────────────────┐ ┌─────────────────────┐
│ MCP Client │ ◄─────► │ MCP Server │
│ │ │ │
│ - Connection │ │ - Resources │
│ - UI/Progress │ │ - Prompts │
│ - Notifications │ │ - Tools │
│ - Sampling/Roots │ │ - Progress Events │
│ - Elicitation │ │ - Notifications │
└─────────────────────┘ └─────────────────────┘
│
▼
┌─────────────────────┐
│ DataStore │
│ (In-Memory) │
│ │
│ - Recipes │
│ - Pantries │
│ - Meal Plans │
│ - Cook Logs │
│ - Shopping Lists │
└─────────────────────┘🚀 快速开始
先决条件
- Python 3.13或更高版本
- 基本熟悉Python和终端命令
- 虚拟环境工具（venv、uv或poetry）
安装
# Clone the repository
git clone
cd cac
# Create and activate virtual environment
python3.13 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install -e ".[dev]"
# Verify installation
python -m mcp_server.server
python -m mcp_client.client📚 厂房结构
研讨会分为15个阶段，每个阶段都在前一阶段的基础上进行：
基础（第1-3阶段）
- 第一阶段：项目脚手架和工具✅
- 第2阶段：使用Pydantic的域模型✅
- 第三期：带有种子数据的内存数据存储✅
MCP服务器（第4-9阶段）
- 阶段4：资源（只读视图）✅
- 阶段5：提示库✅
- 第6阶段：工具定义✅
- 第7阶段：进度流✅
- 第8阶段：通知系统✅
- 第9阶段：服务器程序集✅
MCP客户端（第10-13阶段）
- 第10阶段：连接与内省✅
- 第11阶段：带有进度UI的工具调用✅
- 第12阶段：取样、生根和诱导✅
- 第13阶段：通知显示✅
波兰语（第14-15阶段）
- 第14阶段：教学抛光和文件✅
- 第15阶段：试运行和验证✅
🎨 项目结构
cac/
├── mcp_server/ # MCP server implementation
│ ├── __init__.py
│ ├── models.py # Pydantic domain models
│ ├── data_store.py # In-memory persistence
│ ├── resources.py # MCP resource definitions
│ ├── prompts.py # Named prompt templates
│ ├── tools.py # MCP tool implementations
│ ├── sampling.py # Sampling and elicitation support
│ └── server.py # Server entry point
├── mcp_client/ # MCP client demo application
│ ├── __init__.py
│ ├── connection.py # Server connection logic
│ ├── ui.py # Console UI and rendering
│ └── client.py # Client entry point
├── tests/ # Comprehensive test suite (197 tests)
│ ├── test_models.py
│ ├── test_data_store.py
│ ├── test_resources.py
│ ├── test_prompts.py
│ ├── test_tools.py
│ ├── test_sampling.py
│ └── test_integration.py
├── scripts/ # Helper scripts
│ └── seed_recipes.py # Recipe data generation
├── docs/ # Comprehensive documentation
│ ├── schema.ts # MCP TypeScript schema reference
│ ├── transports.md # Transport layer documentation
│ ├── transports/ # Transport implementation examples
│ │ ├── README.md
│ │ ├── index.html # HTTP/SSE transport demo
│ │ ├── main.py # Python server example
│ │ ├── pyproject.toml
│ │ ├── uv.lock
│ │ └── transport-http.zip
│ ├── SOUL_FOOD_MCP_WORKSHOP_IMPLEMENTATION_PLAN.md # Master plan
│ ├── PHASE1_SUMMARY.md through PHASE15_SUMMARY.md # Phase documentation
│ ├── WORKSHOP_PRESENTATION_OUTLINE.md # Complete workshop script
│ ├── WORKSHOP_QUICK_REFERENCE.md # Quick reference guide
│ ├── WORKSHOP_SNIPPETS.md # Code snippets for live coding
│ ├── WORKSHOP_QA.md # Q&A preparation
│ ├── WORKSHOP_MATERIALS_README.md # Teaching materials guide
│ ├── SPEAKER_NOTES.md # Detailed speaker notes
│ ├── EXECUTION_GUIDE.md # Day-of workshop checklist
│ ├── CULTURAL_CONTEXT.md # Cultural design rationale
│ ├── TROUBLESHOOTING.md # Common issues and fixes
│ ├── LIVE_DEMO_TROUBLESHOOTING.md # Demo-specific troubleshooting
│ ├── FINAL_VALIDATION_CHECKLIST.md # Pre-delivery validation
│ └── LIVE-CODE-PRE-BAKE-DEMO-ONLY.md # Live coding vs pre-baked guide
├── pyproject.toml # Project configuration
├── README.md # This file
└── .gitignore🧪 发展
代码质量
# Format code
ruff format .
# Lint code
ruff check .
ruff check --fix .
# Type check
mypy mcp_server mcp_client
# Run all quality checks
ruff check . && ruff format . && mypy .测试
# Run all tests (197 tests - 100% passing!)
pytest
# Run with coverage
pytest --cov=mcp_server --cov=mcp_client
# Run only unit tests (skip integration)
pytest -m "not integration"
# Verbose output
pytest -v运行应用程序
# Terminal 1: Start the MCP server
python -m mcp_server.server
# Terminal 2: Run the client demo
python -m mcp_client.client🍽️ 演示流程
客户端演示了以下工作流程：
- 内省：发现服务器功能
- 浏览食谱：查看具有文化背景的灵魂美食食谱
- 生成膳食计划：创建带有进度跟踪的7天计划
- 自然总结：用热情的“阿姨”的声音解释用餐计划
- 饮食偏好：交互式处理无猪肉、低钠等
- 购物清单：根据计划生成列表，减去食品储藏室物品
- 厨房提醒：接收具有文化意识的通知
🌍 文化语境
该项目以南方黑人烹饪传统为中心：
- 使技术学习具有吸引力和意义
- 展示尊重文化习俗的人工智能系统
- 展示如何真实地处理饮食需求
- 尊重地区美食的多样性
传统类型示例
- 周日晚餐：传统的教堂后家庭聚餐
- 露天烧烤餐：夏季采集食物
- 假期：感恩节、圣诞节、六月大餐
饮食适应示例
- 无色情：用烟熏火鸡代替火腿
- 低钠：在保持风味的同时调整调味料
- 无乳制品：椰子奶等传统替代品
区域差异
- 低地：南卡罗来纳州/佐治亚州沿海美食
- 密西西比三角洲：丰富、丰盛的安慰食物
- 路易斯安那克里奥尔语：受法国和非洲影响
📖 文档
研讨会演讲者
这 docs/ 文件夹包含综合教材：
- 从这里开始:
WORKSHOP_MATERIALS_README.md-所有材料指南 - 规划:
SOUL_FOOD_MCP_WORKSHOP_IMPLEMENTATION_PLAN.md-总体实施计划 - 交付:
EXECUTION_GUIDE.md-检查表和流程日期 - 内容:
SPEAKER_NOTES.md-详细的谈话要点和时间安排 - 代码:
WORKSHOP_SNIPPETS.md-实时编码参考 - 上下文:
CULTURAL_CONTEXT.md-文化设计原理 - 帮助:
TROUBLESHOOTING.md-常见问题和解决方案
研讨会参与者
WORKSHOP_QUICK_REFERENCE.md-MCP概念快速参考WORKSHOP_QA.md-常见问题和答案- 阶段总结（阶段1-15）-详细的实施说明
技术参考
schema.ts-完整的MCP协议TypeScript模式transports.md-传输层文件transports/-工作运输实施示例
📚 学习资源
MCP文件
灵魂美食烹饪资源
- *杰迈玛密码* 托尼·蒂普顿·马丁
- *禧年* 托尼·蒂普顿·马丁
- *烹饪基因* 作者：迈克尔·W·特维蒂
🛠️ 故障排除
Python版本问题
# Verify Python version
python --version # Should be 3.13+
which python # Should point to .venv/bin/python导入错误
# Reinstall in development mode
pip install -e ".[dev]"清洁启动
# Remove virtual environment and reinstall
rm -rf .venv
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"服务器连接问题
看 docs/TROUBLESHOOTING.md 获取全面的故障排除指南。
🎓 车间交付
快速设置（日期）
- 环境验证:
# Check all systems
pytest -v # Should show 197 passing
ruff check . # Should show "All checks passed!"
python -m mcp_server.server # Should start without errors- 窗口布局:
- 编辑器（左）：用于实时编码 - WORKSHOP_SNIPPETS.md （右）：代码参考 - 终端1（左下）：服务器正在运行 - 终端2（右下）：客户端演示
- 印刷材料:
- EXECUTION_GUIDE.md -放在笔记本电脑旁边 - 紧急联系信息
时间估计
- 90分钟版本：第0-2、4-6、10-11阶段（核心概念）
- 2小时版本：添加第7-8、12-13阶段（进度和通知）
- 3-4小时版本：包含问答环节的完整15阶段研讨会
看 EXECUTION_GUIDE.md 了解详细的时间和节奏策略。
🤝 贡献
这是一个以教学为重点的研讨会项目。促进以下方面的贡献：
- 文化真实性和准确性
- 教学清晰度
- 代码示例和文档
- 其他运输实施
特别受欢迎。
📝 许可证
\[许可证待定\]
🙏 致谢
本次工作坊向非裔美国人和南方厨师的丰富烹饪传统致敬， 他们塑造了美国美食，但往往得不到多少认可。
特别感谢MCP社区提供的协议规范和Python SDK。
______________________________________________________________________
📊 当前状态
实施：第15阶段完成✅ （全部15个阶段完成！）
测试：197/197次测试通过（100%成功率）
代码质量:
- ✅ Linting：所有检查均已通过
- ✅ 格式：始终一致
- ✅ 类型提示：所有关键问题均已解决
文档:
- ✅ 15阶段总结
- ✅ 13车间教学文件
- ✅ 技术参考资料
- ✅ 交通示例和演示
车间状态: 🎉 100%准备交付！ 🍽️
什么起作用
✅ 具有所有功能的完整MCP服务器 ✅ 具有完整UI的交互式MCP客户端 ✅ 12种文化上正宗的灵魂美食食谱 ✅ 长时间操作的进度流 ✅ 厨房提醒通知系统 ✅ 采样和启发支持 ✅ 全面的测试覆盖率 ✅ 生产就绪代码质量 ✅ 完整的教材 ✅ 运输实施示例
后续步骤
- 对于演示者：评论
WORKSHOP_MATERIALS_README.md - 对于参与者：按照上述安装步骤进行操作
- 面向开发者：参见
PHASE1_SUMMARY.md通过PHASE15_SUMMARY.md - 对于学习者：从以下内容开始
WORKSHOP_QUICK_REFERENCE.md
______________________________________________________________________
准备好通过灵魂食物烹饪的视角学习MCP了吗？ 让我们开始吧！ 🥘