alchm-kitchen

Alchm.kitchen MCP 服务

版本 1.4.0 通过 stdio 提供八种工具：实时行运、精选食材分析、食谱搜索、本命盘叠加、三重报价、证据快照和食谱感想。它使用持续维护的 MCP TypeScript SDK v1 系列，并支持现有的 MCP 初始化握手。它不提供 HTTP/SSE 服务。

安装或运行

bunx @alchm/mcp-server
# Node.js alternative (Node 18+)
npx -y @alchm/mcp-server

# From this repository
bun install --cwd mcp-server
bun run mcp-server/src/index.ts

# Distributable Node bundle and standalone Bun sidecar
bun run --cwd mcp-server build
bun run --cwd mcp-server build:binary

程序包位于 mcp-server/dist/index.js；sidecar 位于 mcp-server/bin/alchm-mcp。二进制构建会禁用工作目录 dotenv/bunfig 自动加载，并在 macOS 上修复／验证临时签名。构建会准备本地构件；发布 npm、Registry 元数据和 sidecar 版本是彼此独立的发布步骤。

工具

工具	已认证费用	功能
get_live_sky_transits	免费	观测者的当前行星位置和元素平衡。
alchemize_ingredients	免费	最多 100 种食材的精选元素／ESMS 数据和热力学指数。缺失的 ESMS 数量将保留为 null。
generate_cosmic_recipe	每种 ESMS 2.5（共 10）	按关键词、元素、菜系和饮食类型搜索食谱目录。仅在搜索成功时收费。
compute_synastry_overlay	免费	跨星盘相位、评分和立场。cacheStrategy: "write" 会更新可选数据库缓存，并要求匹配的内部探测密钥。
get_transit_natal_overlay	免费	单个 Agent 的天象至本命盘相位，以及各元素的连续增益。
compute_triplicate_synastry	免费	报价共振、潜在返利和冷却窗口键；不会执行交易或支付返利。
create_evidence_snapshot	每种 ESMS 2.5（共 10）	一次调用即可打包行运、可选食材和候选食谱。仅在快照完整时收费。
submit_recipe_reflection	每种 ESMS 0.1（共 0.4）	在一个事务中保存 proposed 感想及其扣款，然后尝试发布到动态；要求调用方已通过身份验证，且非合成调用方。

匿名调用方可在演示模式下使用读取工具。食谱搜索和证据快照会向已认证调用方扣费；发布感想则要求身份验证。提供的凭据无效时将被拒绝。运营方必须配置 DATABASE_URL，才能验证 API 密钥并执行计费。仅凭 API 密钥无法将此 stdio 进程连接到托管身份验证服务。

工具注释会将付费调用和感想发布标记为变更操作。目录声明了有界输入；验证会在身份验证、计费和处理器工作之前运行。坐标必须在纬度／经度范围内，食材列表必须包含 1–100 个字符串，感想长度为 1–4000 个字符（与存储列的限制一致），本命盘和数量／时间戳必须符合其已发布的架构。

计费与安全重试

付费读取按交付结果计费：工具先运行，只有成功结果才会结算。搜索失败或快照不完整（发生错误）绝不会收费；调用方若在结算前取消，则不会收费；若结算被拒绝，则不会返回结果（QUOTA；无法连接计费系统时为 UNAVAILABLE）。一次反思的扣款与其 recipe_reflections 行在同一事务中提交，因此调用方绝不会为未存储的反思付费。Feed 发布在同一事务的保存点后运行：若发布失败，反思仍会保存且费用仍会扣除，回执会报告 published: false。

没有幂等键时，每次调用都会再次收费，每次反思调用都会再存储一条反思。传入 _meta.idempotencyKey（1–200 个字符，仅限 A-Z a-z 0-9 . _ : ~ -），即可安全重试付费调用：

• 24 小时内使用相同参数重试，不会再次收费（billing.status: "replayed"）。菜谱搜索或快照会重新计算，因此重放的快照会带有新的 snapshotId 和观测时间；重试反思会返回已存储的反思（replayed: true），并重新尝试此前失败的 Feed 发布，除非该反思之后已被审核处理（隐藏、删除或拒绝）。
• 使用不同参数重用密钥，或在 24 小时后重用密钥，会返回 CONFLICT。_meta 中的凭据和关联字段不参与比较。
• 密钥按付费账户和工具进行作用域隔离，同一密钥的并发重试会等待首次尝试完成，然后重放结果。ESMS 账本仅以哈希形式存储密钥；调用遥测会将原始密钥与该调用的其他参数一同保留 7 天。

付费调用一旦进入结算阶段，其结果就会在 billing 字段中报告处理情况（此阶段之前的错误，例如参数无效、身份验证失败或 BUSY，不包含此字段）：status（charged、replayed 或 not_charged，并带有 anonymous-caller、synthetic-probe-exempt 或 not-delivered 等 reason）、本次调用扣除的 amounts，以及回显的 idempotencyKey。

结果

结果包含 structuredContent，以及文本内容块中序列化为 JSON 的相同内容，并带有 correlationId。每个工具都会发布一个 outputSchema，接受其成功负载或通用错误封装，因此验证结构化结果的客户端（TypeScript 和 Python SDK 客户端会进行验证）都能接受两者。失败的证据快照会在错误负载的 data 字段中保留可用数据和组件溯源信息。工具失败会设置 isError: true，并附带稳定的 errorCode 和 message；RATE_LIMIT 和 BUSY 会包含 retryAfterSec。诊断输出写入 stderr；stdout 仅包含 JSON-RPC 消息。收到 SIGINT、SIGTERM 或 stdin 关闭时，会在退出前执行最长 1 秒的遥测排空。

配置

ALCHM_MCP_BACKEND_URL=https://alchm.kitchen
MCP_USER_API_KEY=sk_alchm_...
# ALCHM_MCP_USER_API_KEY is also accepted for sanitized Planetary Agents environments.
DATABASE_URL=postgresql://...  # operator-only: key validation, billing, cache and telemetry

星盘／交通请求会向 <base>/api/astrologize 发送 POST 请求。显式设置的 ALCHM_MCP_BACKEND_URL、NEXT_PUBLIC_SITE_URL、SITE_URL 或 Vercel URL 优先使用。打包／编译产物默认使用 https://alchm.kitchen；源码运行默认使用 http://localhost:3000。因此，开发源码时需要启动本地应用，或显式指定可访问的后端 URL。

在 /profile/api-keys 创建和撤销 API 密钥。密钥以 SHA-256 哈希形式存储；创建时明文仅显示一次。

每个工具都接受其参数中的 _meta：

{
  "name": "generate_cosmic_recipe",
  "arguments": {
    "prompt": "spicy",
    "cuisine": "thai",
    "_meta": {
      "apiKey": "sk_alchm_live_REPLACE_ME",
      "caller": "claude-desktop",
      "correlationId": "dinner-plan-123",
      "idempotencyKey": "dinner-plan-123-search"
    }
  }
}

环境密钥为单用户安装提供默认值。仍支持旧版 _meta.authKey、_authKey 和 _apiKey 参数别名。合成探测会提供与服务端 INTERNAL_API_SECRET 匹配的 _meta.internalSecret；SYNTHETIC_PROBE_USER_ID 可选，用于标注来源。仅设置服务端密钥绝不会将外部调用认证为探测调用。合成调用无法发布反思。

连接 Claude Desktop 或 Cursor

在 Claude Desktop 的 claude_desktop_config.json 或 Cursor 的 .cursor/mcp.json 中使用相同的 mcpServers 配置格式：

{
  "mcpServers": {
    "alchm-kitchen": {
      "command": "npx",
      "args": ["-y", "@alchm/mcp-server"],
      "env": {
        "MCP_USER_API_KEY": "sk_alchm_live_REPLACE_ME"
      }
    }
  }
}

对于本地源代码检出，请使用 "command": "bun" 和 "args": ["run", "/absolute/path/to/WhatToEatNext-master/mcp-server/src/index.ts"]。数据库配置由运行服务的运营者负责。请参阅 claude-desktop.config.example.json 和 cursor.mcp.example.json 中的源代码运行模板。

验证与运维

bun run --cwd mcp-server typecheck
bun run jest src/lib/mcp/__tests__/ --runInBand
bun run --cwd mcp-server test:stdio
MCP_E2E=1 MCP_E2E_ENTRY=mcp-server/dist/index.js bun test mcp-server/src/__tests__/
MCP_E2E=1 MCP_E2E_ENTRY=mcp-server/bin/alchm-mcp bun test mcp-server/src/__tests__/

stdio 测试会启动真实的源代码／打包文件／二进制进程，初始化会话，发送 notifications/initialized，检查全部八个工具，调用本地工具，并测试验证逻辑与错误处理。测试会拒绝任何非 JSON-RPC 的 stdout 行，且不需要连接运行中的数据库或生产后端。sdkClient.test.ts 会通过官方 SDK 客户端重复这些调用，并依据公布的 outputSchema 验证每个结果，包括错误。

结算功能通过真实 PostgreSQL 进行验证：src/lib/mcp/__tests__/settlement.postgres.test.ts 会针对包含所有迁移的临时数据库运行账本、幂等重放、并发重试和反思事务（包括从动态插入失败中恢复）。测试文件头部列出了设置说明；只有当 MCP_TEST_DATABASE_URL 指向环回地址上的 mcp_test* 数据库时才会运行。

由数据库驱动的调用会写入 mcp_invocations，并显示在管理端 MCP 状态界面、Agent 遥测和合成 MCP 探测中。遥测采用尽力而为策略；即使日志记录不可用，调用仍可正常运行。可观测性清理作业会保留数据七天。每个密钥的速率限制和四次调用的进程并发上限用于限制工作负载；调用会在 20 秒后收到取消信号，并会收到 MCP 取消信号。超时并不能保证已启动的下游副作用已回滚。

有关所有权和数据流，请参阅 ARCHITECTURE.md。