alchm-kitchen

Alchm.kitchen MCP サーバー

バージョン 1.4.0 は、stdio 経由でライブトランジット、厳選された成分分析、レシピ検索、ネイタルオーバーレイ、トリプリケート価格設定、エビデンススナップショット、レシピのリフレクションの8つのツールを公開します。メンテナンスされている 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、サイドカーは mcp-server/bin/alchm-mcp です。バイナリビルドでは、作業ディレクトリからの dotenv/bunfig の自動読み込みを無効にし、macOS 上でアドホック署名を修復・検証します。ビルドではローカルアーティファクトを準備します。npm の公開、レジストリメタデータ、サイドカーのリリースは、それぞれ個別のリリース手順です。

ツール

ツール	認証済みのコスト	動作
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	無料	1人のエージェントについて、空とネイタルのアスペクト、および元素ごとの連続的なブーストを返します。
compute_triplicate_synastry	無料	共鳴の見積もり、リベートの可能性、クールダウンウィンドウキーを返します。取引の実行やリベートの支払いは行いません。
create_evidence_snapshot	各ESMSを2.5（合計10）	トランジット、任意の成分、レシピ候補を1回の呼び出しでまとめます。完全なスナップショットの場合にのみ課金されます。
submit_recipe_reflection	各ESMSを0.1（合計0.4）	proposed リフレクションとその引き落としを1つのトランザクションで保存し、その後フィードへの公開を試みます。認証済みの非合成呼び出し元が必要です。

匿名の呼び出し元は、デモモードで読み取りツールを使用できます。レシピ検索とエビデンススナップショットでは認証済みの呼び出し元に課金され、リフレクションの公開には認証が必要です。入力された認証情報が無効な場合は拒否されます。APIキーの検証と課金処理を行うには、オペレーターが DATABASE_URL を設定する必要があります。APIキーだけでは、このstdioプロセスをホスト型認証サービスに接続できません。

ツールのアノテーションでは、有料呼び出しとリフレクションの公開をミューテーションとして示します。カタログでは入力範囲を定めており、検証は認証、課金、ハンドラー処理の前に実行されます。座標は緯度・経度の範囲内である必要があります。成分リストには1～100件の文字列を含める必要があり、リフレクションは1～4000文字（保存先カラムの上限）である必要があります。また、ネイタルチャート／量／タイムスタンプは、公開済みのスキーマに一致している必要があります。

課金と安全な再試行

有料の読み取りは結果の配信時に課金されます。まずツールが実行され、成功した結果だけが精算されます。検索の失敗や部分的なスナップショット（エラー）には課金されません。精算前にキャンセルした呼び出し元にも課金されず、精算が拒否された場合は結果が返されません（QUOTA、または課金に接続できない場合はUNAVAILABLE）。リフレクションの引き落としとそのrecipe_reflections行は1つのトランザクションでコミットされるため、保存されなかったリフレクションに対して課金されることはありません。フィードの公開はセーブポイントの背後で同じトランザクション内で実行されます。失敗した場合、リフレクションとその課金は確定し、レシートにはpublished: falseと報告されます。

冪等性キーがない場合、呼び出しのたびに課金され、リフレクションの呼び出しのたびに別のリフレクションが保存されます。有料の呼び出しを安全に再試行するには、_meta.idempotencyKey（A-Z a-z 0-9 . _ : ~ -からなる1～200文字）を渡します。

• 24時間以内に同じ引数で再試行した場合、再度課金されません（billing.status: "replayed"）。レシピ検索またはスナップショットは再計算されるため、再生されたスナップショットには新しい snapshotIdと観測時刻が含まれます。リフレクションの再試行では保存済みのリフレクションが返され（replayed: true）、その後リフレクションがモデレーションされていない（非表示、削除、または却下されていない）場合、以前失敗したフィード公開が再試行されます。
• 異なる引数でキーを再利用した場合、または24時間経過後に再利用した場合は、CONFLICTが返されます。_meta内の認証情報と相関フィールドは比較対象になりません。
• キーは課金アカウントとツールごとにスコープされ、同じキーを使った並行再試行は最初の試行が完了するまで待機した後、それを再生します。ESMS台帳にはキーのハッシュのみが保存されます。呼び出しテレメトリーには、呼び出しの他の引数とともに生のキーが7日間保持されます。

有料の呼び出しが精算に到達すると、その結果はbillingフィールドに処理内容を報告します（無効な引数、認証失敗、BUSYなど、それ以前に発生したエラーにはこのフィールドは含まれません）。status（charged、replayed、またはnot_charged。reasonにはanonymous-caller、synthetic-probe-exempt、not-deliveredなどが入ります）、この呼び出しで引き落とされたamounts、およびエコーバックされたidempotencyKeyが含まれます。

結果

結果にはstructuredContentと、テキストコンテンツブロック内に同じJSONをシリアル化したものが含まれ、correlationIdも付与されます。各ツールは、成功時のペイロードまたは共通のエラーエンベロープを受け入れるoutputSchemaを公開するため、構造化結果を検証するクライアント（TypeScriptおよびPython SDKのクライアントなど）はどちらも受け入れます。エラーになったエビデンススナップショットは、利用可能なデータとコンポーネントの来歴をエラーペイロードのdataフィールドに保持します。ツールの失敗時には、安定したerrorCodeとmessageを伴ってisError: trueが設定されます。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を設定する必要があります。

APIキーは/profile/api-keysで発行および取り消しができます。キーは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 を送信し、8 つすべてのツールを検査して、ローカルツールを呼び出し、検証とエラーをテストします。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 ステータス画面、エージェントのテレメトリ、合成 MCP プローブにデータを送ります。テレメトリはベストエフォートであり、ログを利用できない場合も呼び出しは機能します。データの保持期間は、可観測性のプルーニングジョブによって 7 日間に設定されています。キーごとのレート制限とプロセス全体での同時実行数の上限（4 回）により、負荷を制限します。呼び出しには 20 秒後にキャンセルシグナルが送られ、MCP のキャンセルシグナルも送信されます。タイムアウトしても、すでに開始された下流の副作用がロールバックされるとは限りません。

所有権とデータフローについては、ARCHITECTURE.md を参照してください。