supost-mcp

supost-mcp

SUpost（スタンフォード向けのマーケットプレイス）のリモート MCP サーバーです。また、同じ supost-web コードベースから同じ公開 API を提供する Capmus（capmus.com）向けにも、BRAND=capmus で利用できます。1 つのリポジトリで 2 つの Vercel プロジェクトを運用します。

ブランド	Vercel プロジェクト	エンドポイント	環境変数
SUpost	supost-mcp	https://mcp.supost.com/mcp	（デフォルト）
Capmus	capmus-mcp	https://mcp.capmus.com/mcp	BRAND=capmus

BRAND は、サーバー名、ツールのタイトルと説明、デフォルトのベース URL を選択します。プレビューでは、SUPOST_BASE_URL でベース URL を引き続き上書きできます。

AI エージェントが、掲載中のリスティングを検索し、詳細を取得し、検証済みの市場統計を読み取り、投稿者にメッセージを送り、下書きのリスティングを作成できるようにします。

これはドキュメント 190 の作業ストリーム E3 です（supost-web/docs/dev/190-ai-agent-discovery-implementation-plan.md を参照）。SUpost の公開インターフェース（読み取り専用のリスティング API（E2）、公開リスティングページ、/stats.md）のみを利用する純粋なクライアントです。特権データベースアクセスはなく、シークレットも保持しません。設定項目は公開ベース URL のみです。

ツール

ツール	接続先	返される内容
search_listings	GET /api/public/listings	新しい順の掲載中リスティング（id、タイトル、価格、カテゴリ、created_at、正規 URL）を、不透明なカーソルによるページネーションで返します。パラメーター：q、cat、university、max_price、limit（≤50）、cursor。
get_listing	GET /post/index/<id> → 正規リスティングページ	ページの schema.org Product JSON-LD から解析した、説明全文を含む 1 件のリスティング。
get_market_stats	GET /stats.md	公開統計ページの Markdown 形式の内容（利用者層、リスティング件数、返信率・返信時間）。
list_categories	GET /api/public/categories	有効な create_post の値となる、掲載中のカテゴリ／サブカテゴリの分類。
create_post	POST /api/public/posts	下書きのリスティングを作成します。投稿者が写真を追加し、内容を確認して公開するための continue_url を返します（無料枠を利用していない場合は、先に支払いが必要です）。直接公開されることはありません。
send_message	POST /api/public/messages	リスティングの投稿者にメッセージを送信します。すぐには配信されません。reply_to_email に確認リンクがメールで送信され、人間がクリックした後にのみメッセージが送信されます。エージェントは送信済みではなく、確認待ちとして報告する必要があります。
check_message_status	PostgREST RPC get_guest_verification_status（公開可能なキー）	send_message の送信リクエストに対する確認メールが配信されたかどうかを返します：queued / sent / failed（＋理由） / unknown。リンクがクリックされたかどうかは返しません。

個人情報が返されることはありません。投稿者への連絡には、サポート対象の方法である send_message を使用してください。リスティングの url にも、サイト上のメッセージフォームがあります。API 利用規約： https://supost.com/api/public/openapi.json

バウンスしたアドレス

メッセージが配信されるのは、人間が確認リンクをクリックした後に限られるため、リンクが届かないアドレス宛てのメッセージは届きません（supost-web docs/dev/20260917-2040-guest-reply-bounce-feedback-handoff.md）。 そのため、send_message は無効なアドレスに対して、単に「保留中」とは決して応答しません。

• 確認メールが過去30日以内にハードバウンスしたアドレスは、何も保存される前に API によって 422 email_undeliverable で拒否されます。ツールは {status: "email_undeliverable", reason, email, message} を含むエラー結果を返し、再試行ではなく別のアドレスを尋ねるようエージェントに伝えます。
• それ以外の場合、API は status_key とともに 202 を返し、ツールは確認メールの配信状態を最大約8秒間ポーリングします（2秒間隔で4回確認します。抑制されたアドレスは1秒未満で失敗し、新たなハードバウンスは1～16秒で失敗します）。failed の判定は422と同じように報告されます。sent / queued は結果の confirmation_email として返され、後で check_message_status に使う status_key も含まれます。

ポーリングには、ウェブフォームと同じ匿名で呼び出せる PostgREST RPC get_guest_verification_status(status_key) を使用し、マーケットプレイスの公開可能キー（すべてのブラウザーがすでに取得している値）でアクセスします。返されるのは queued | sent | failed と失敗の分類（mailbox_unknown | no_mx | suppressed | other）のみで、引き換えトークン、メッセージ、アドレスは返されません。環境変数 SUPOST_STATUS_URL / SUPOST_STATUS_KEY でデフォルト値（本番プロジェクト）を上書きできます。SUPOST_STATUS_KEY="" にするとポーリングが無効になり（ツールは unknown を報告します）、SUPOST_STATUS_POLL_ATTEMPTS / SUPOST_STATUS_POLL_INTERVAL_MS で呼び出し中の待機時間を調整できます。

ホスティング

Vercel 上で、ステートレスなストリーミング可能 HTTP MCP エンドポイント（mcp-handler + @modelcontextprotocol/sdk）としてデプロイされています。

https://mcp.supost.com/mcp        (rewritten to /api/mcp)
https://mcp.supost.com/health     (rewritten to /api/health)

セッション、Redis、認証はありません。各リクエストは個別に処理され、上流データはすべて公開されており、CDN にキャッシュされます。

現在稼働中のコミット

Vercel では、initialize レスポンスの serverInfo.version は <package version>+<short git sha> です（例：VERCEL_GIT_COMMIT_SHA 由来の 0.3.0+835efb3。ローカルでは 0.3.0。詳しくは src/version.ts を参照してください）。そのため、どの MCP クライアントからでも、または GET /health で、デプロイ済みコミットを確認できます。問題が古い状態に見える場合は、git rev-parse --short origin/master と比較してください。

ヘルスチェックと稼働時間の監視

GET /health は、上流への呼び出しなしで {"ok": true, "brand": "supost", "version": "…"} を返します（api/health.ts）。これは関数が応答していることを示すもので、supost.com が稼働していることを示すものではありません。各ブランドにUptimeRobot HTTP モニターを設定してください（手動での設定が必要です。両方とも設定してください）。

• https://mcp.supost.com/health
• https://mcp.capmus.com/health

200 以外の応答（キーワード "ok":true は任意）でアラートを設定すると、デプロイの不具合やドメインの切断を検知できます。レスポンス本文の version から、どのコミットが応答したかを確認できます。

デプロイ

vercel deploy          # preview
vercel deploy --prod   # production

任意の環境変数：SUPOST_BASE_URL（デフォルトは https://supost.com。プレビュー環境で開発用スタックを参照するには https://preview.supost.com を設定してください）。

本番環境へのデプロイは、GitHub インテグレーションを通じて master から行います。ローカルのチェックアウトが origin/master と一致していない場合は、vercel deploy --prod の実行を避けてください。古い状態の CLI デプロイによって、本番エイリアスが Git ビルドより優先されます（これは2026-09-17に発生し、vercel promote で修正しました）。

利用状況の分析

すべてのツール呼び出しで、PostHog の mcp_tool_called イベントが 1 件出力されます（引数はサニタイズされ、個人を特定できる情報は含まれません。src/analytics.ts を参照）。また、TOOL_LOG_URL ／TOOL_LOG_KEY が設定されている場合は、マーケットプレイスの非公開 ops.mcp_tool_call テーブルにすべての引数を含む行が記録されます（src/toollog.ts を参照）。

失敗した呼び出しには error_code が含まれます。これは、公開 API のエラーコード （rate_limited、not_found、email_undeliverable、invalid_request、…） または、それ以外の場合（ネットワーク障害、予期しないレスポンス形式など）の unknown です。成功時は null です。エラー メッセージ は送信されません。ユーザーのコンテンツが引用される可能性があるためです。error_code ごとに分類することで、レート制限の急増と上流の障害を見分けられます。

PostHog の distinct_id は、呼び出し元の IP と User-Agent をソルト付き SHA-256 でハッシュした値です（src/client.ts を参照）。そのため、uniq(distinct_id) で IP を保存せずに個別のエージェント数を集計できます。イベントには client_ua（MCP クライアントの User-Agent。ハーネスを特定します）と client_country（Vercel の地理情報ヘッダー）も含まれます。ハッシュを推測できないようにするには、Vercel プロジェクトの環境変数に CLIENT_ID_SALT を設定してください。リポジトリ内のデフォルト値でもローカル開発は引き続き動作します。 IP または User-Agent なしで届いた呼び出しには、ブランドごとの ID mcp.<brand>.com が使用されます。

クライアントを接続する

claude mcp add --transport http supost https://mcp.supost.com/mcp

または、リモートサーバーに対応する任意の MCP クライアントで、上記の URL をストリーミング可能な HTTP サーバーとして追加します。

レート制限

公開 API は IP あたり約 60 リクエスト／分を制限し、5 分間の CDN キャッシュを提供します。src/http.ts のクライアントはこれに従います。429 が返された場合は Retry-After を尊重して（上限 5 秒）、1 回だけ再試行します。それ以外の場合は、エージェントにバックオフを指示する構造化された rate_limited エラーを返します。ループで再試行することはありません。すべてのリクエストには supost-mcp/… User-Agent が付与されます。

すべてのマーケットプレイス呼び出し（ステータス RPC は対象外）には、信頼されたエージェント用のヘッダーも付与されます。x-supost-api-key（デプロイ環境の SUPOST_API_KEY。Git には含めません）と、呼び出し元エージェントの IP が判明している場合は x-supost-agent-client-ip（MCP の受信した x-forwarded-for の最初のホップ）が含まれます。API はキーが有効な場合にのみこの IP を信頼するため（supost-web の docs/dev/469-mcp-agent-api-hardening-handoff.md を参照）、すべてのエージェントで共有される単一の Vercel エグレス IP ではなく、エージェントごとに IP 制限を適用できます。通常の X-Forwarded-For では機能しません。supost.com は Vercel 上で稼働しており、Vercel がエッジでこのヘッダーを上書きするためです。

開発

npm install
npm run check    # typecheck + tests
SUPOST_BASE_URL=https://preview.supost.com npx tsx scripts/smoke.ts   # live end-to-end

テスト（vitest）では、各ツールのリクエスト／レスポンスのマッピング、エラーのマッピング、JSON-LD の抽出、レート制限の契約（Retry-After の尊重、上限、1 回のみの再試行、構造化された失敗）を検証します。

今後の作業（手動の手順）

• MCP レジストリに公開する — server.json の準備は完了しています。 まずリポジトリを公開してから（gh repo edit Capmus-Team/supost-mcp --visibility public）、次のコマンドを実行します。 sh brew install mcp-publisher mcp-publisher login github # デバイスフロー。ブラウザーが必要です mcp-publisher publish # リポジトリのルートから実行 Capmus のエントリーについては、同じ方法で server.capmus.json を公開します（一時チェックアウトで cp server.capmus.json server.json を実行するか、 対応している場合は mcp-publisher publish --file server.capmus.json を実行します）。
• supost-web の /help/mcp ドキュメントページ — PR #1242（ガイド のレジストリエントリーと llms.txt の MCP 行）。dev から master にマージされると公開されます。
• PR／引用の告知 — docs/announcement-draft.md に草案とストーリーの要点があります。レジストリへの掲載と /help/mcp の公開後に投稿します（ドキュメント 190 の作業ストリーム F）。
• E2 は本番環境（supost.com、2026-07-09）で稼働中です。スモークスクリプトで本番環境に対する検証が完了し、サーバーは https://mcp.supost.com/mcp にデプロイされています。