Percolate

Percolate MCP 服务

从 Claude 或任何兼容 MCP 的 AI 客户端查询 Percolate 精品咖啡数据库。只读访问 1,100 多款精选咖啡，包含风味档案、冲煮配方、搭配建议和购买链接。

Percolate 是一款适用于 iOS 的精品咖啡日志应用——在 App Store 上获取。

工具

工具	功能
search_coffees	按类别、烘焙程度、冲煮方式和价格筛选目录
get_coffee	获取单款咖啡的完整记录：烘焙程度、醇厚度／酸度／甜度、风味、搭配建议和零售商
find_similar	根据风味重合度以及烘焙程度／醇厚度／酸度的接近程度查找相似咖啡
get_recommendations	根据风味偏好、预算、烘焙程度和你的冲煮设备推荐咖啡
compare_coffees	并排比较：档案、共有／不同风味、价格差
trending_coffees	查看 Percolate 用户目前正在添加到收藏中的咖啡
dial_in_suggestion	针对特定咖啡提供冲煮指导——目录中的精选配方（粉水比、温度、研磨度），或基于烘焙程度的起始建议
what_to_brew	推荐一款适合当下的咖啡——晚间推荐倾向于低因咖啡，早晨则倾向于明亮风味

每个响应都包含来源说明、可用于引用的摘要、链接和数据新鲜度日期。所有评分均由确定性规则计算——服务内部不会调用 AI。所有工具均标注为只读／幂等。

安装（Claude Desktop）

需要 Node.js 18+。

将以下内容添加到 claude_desktop_config.json（Claude Desktop → Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "percolate": {
      "command": "npx",
      "args": ["-y", "percolate-mcp"]
    }
  }
}

重启 Claude Desktop。无需 API 密钥或其他配置——此服务提供公开的只读访问。

配置（可选）

环境变量可覆盖默认值（仅使用显式设置的环境变量——此软件包不会读取 .env 文件）：

变量	用途
SUPABASE_URL	覆盖数据库 URL
SUPABASE_SERVICE_ROLE_KEY	仅供内部使用——可启用实时统计近 30 天的收藏添加趋势。切勿分发此密钥。

未提供服务密钥时，trending_coffees 会回退到目录人气数据，并在响应中标明所用方法。

远程端点（无需安装）

为通过 URL 连接的 Web Agent 和 MCP 客户端提供 Streamable HTTP：

https://wmpiabzlcaqyrzxvfihi.supabase.co/functions/v1/mcp

也已列入 Smithery 和官方 MCP 注册表，名称为 io.github.bguillow-rgb/percolate。

Agent 请求示例

Agent 可使用这些工具回答的问题：

• “推荐一款带有巧克力和坚果风味的中度烘焙咖啡。” → 使用 get_recommendations，参数为 preferences: ["chocolate","nutty"], roast_level: "medium"
• “这款 Onyx Monarch 用 V60 应该怎么冲？” → dial_in_suggestion（精选配方：粉水比、温度、研磨度）
• “有什么适合意式浓缩、价格低于 $20 的咖啡？” → 使用 search_coffees，参数为 brew_method: "espresso", price_max: 20
• “今晚冲什么咖啡好？” → what_to_brew（晚间推荐会自动倾向于低因咖啡）
• “帮我找一款类似这款埃塞俄比亚日晒咖啡的。” → find_similar
• “比较这两包咖啡。” → compare_coffees

响应示例结构（已截断）：

{
  "method": "curated_pairing",
  "recipes": [
    { "recipe": "Pour-over (V60), 1:16, 205°F",
      "why": "clarity that lets the delicate, high-acid notes open up" }
  ],
  "attribution": {
    "source": "Percolate — Specialty Coffee Journal",
    "links": { "website": "https://percolateapp.com/" }
  }
}

开发

npm install
npm run dev     # run from TypeScript via tsx
npm run build   # compile to dist/
npm start       # run compiled server

此服务通过 stdio 使用 MCP。目录访问在设计上为只读：每条查询路径都会对行级安全策略下可公开读取的表执行 SELECT，并限制为每分钟 60 次调用。

使用遥测：每次工具调用都会将工具名称、参数、客户端名称／版本、耗时和成功／失败状态记录到只写日志表（在 RLS 下仅允许插入；内容不可公开读取；90 天后清除）。不会收集用户身份、账户数据或对话内容。日志记录采用即发即弃方式，绝不会影响响应。

数据与署名

咖啡数据、风味档案、冲煮配方和搭配均由 Percolate 精选整理。零售商链接可能包含联盟链接。引用时请注明出处：

来源：Percolate — Specialty Coffee Journal (percolateapp.com)

每款咖啡标注的更新日期反映了其数据的最近更新时间。