内容
# Paprika 代理
连接 Claude Desktop 到 Paprika 食谱管理应用程序的 MCP 服务器，通过其非官方 API 实现。
## 功能
- `list_recipes` — 从您的 Paprika 账户中获取并缓存所有食谱
- `get_recipe` — 按名称（不区分大小写）检索完整的食谱详情
- `search_recipes` — 在食谱标题中进行关键词搜索（顺序无关）
- `sync_recipes` — 将内存缓存与 Paprika API 同步；增量模式使用哈希比较来检测添加、编辑和删除；完整刷新模式则会清除并重新填充缓存
## 演示
<video src="https://github.com/user-attachments/assets/214a9f09-ef78-420a-b58e-2ce75bc01412"
controls autoplay loop muted
style="max-width: 100%;">
</video>
Claude Desktop 调用所有四个 Paprika 代理工具 — list、get、search 和 sync。
## 快速开始
### 先决条件
- Python 3.13+
- [uv](https://docs.astral.sh/uv/) — Python 包管理器
- [Claude Desktop](https://claude.ai/download)
- 具有启用云同步的 [Paprika 3](https://www.paprikaapp.com/) 账户
### 安装
```bash
git clone https://github.com/apelullo/paprika-agent.git
cd paprika-agent
uv sync
```
### 配置凭证
复制模板并填写您的 Paprika 凭证：
```bash
cp .env.example .env
```
```
PAPRIKA_EMAIL=your@email.com
PAPRIKA_PASSWORD=yourpassword
```
`.env.example` 中记录的可选 `MCP_*` 变量配置网络传输（第 2 阶段，正在进行中）— 忽略它们以进行本地使用。
### 连接 Claude Desktop
打开 Claude Desktop → **设置 → 开发者 → 编辑配置**。在 `claude_desktop_config.json` 中添加以下内容，替换路径为您自己的（运行 `which uv` 以找到您的 `uv` 二进制文件）：
```json
{
"mcpServers": {
"paprika": {
"command": "/path/to/uv",
"args": [
"run",
"--directory",
"/absolute/path/to/paprika-agent",
"python",
"server.py"
]
}
}
}
```
重启 Claude Desktop。Paprika 工具将在任何新聊天中可用。
## 架构
Paprika 代理围绕一个指导原则构建：**每个设计决策都应该自然扩展，而不是随着项目的增长而需要替换。**
服务器分为三个模块，具有强制边界：
- **`server.py`** — MCP 层，仅此而已：四个工具定义和入口点。它不导入任何 HTTP 库，也不拥有任何状态。
- **`config.py`** — 环境驱动的服务器配置。`ServerConfig` 通过 `ServerConfig.from_env` 解析；将 `MCP_TRANSPORT` 留空以进行本地标准输入/输出，或设置为 `http` 以进行网络模式（第 2 阶段，正在进行中）。选择是值授权的 — 未知值会大声失败 — 网络默认值会关闭（`127.0.0.1`，而非 `0.0.0.0`）。`.env.example` 中有完整的契约。
- **`paprika_client.py`** — Paprika API 客户端：身份验证、食谱获取、输入验证、同步和它独有的内存缓存。
在第一次工具调用时，服务器会急切地从 Paprika API 获取所有食谱，并填充 `paprika_client` 中的两个模块级结构： `_recipe_cache`（uid → 完整的食谱数据）和 `_name_index`（规范化名称 → uid）。后续调用纯粹是内存查找 — 零额外的 API 调用。此缓存是所有当前工具共享的基础，也是持久本地数据库的自然前身。 `_cache_populated` 标志跟踪缓存是否至少已填充一次，以确保对于零食谱的账户，no-op 保护正确。
工具设计上很薄。每个工具都调用 `_populate_cache()`，从共享缓存中读取并返回结果。 `search_recipes` 今天在标题上执行子字符串匹配；明天它在嵌入式上执行语义搜索 — 相同的工具接口，更智能的实现在下面。架构不会改变；复杂性在其中增长。
## 技术栈
Python · FastMCP · uv · pytest · ruff · GitHub Actions · Paprika API
## 路线图
- [x] MCP 工具套件（v0.1.0）
- [ ] 本地网络部署 — *进行中*
- [ ] 本地食谱数据库（SQLite）
- [ ] 自定义客户端
- [ ] 语义搜索和嵌入式
- [ ] 贝叶斯食谱推荐器
- [ ] 云部署和 MLOps（v1.0.0）
