KH Merch Graph

KH Merch Graph

An MCP (Model Context Protocol) server that turns a Japanese secondhand-listing title for Kingdom Hearts merchandise (Mercari, Yahoo! Auctions, Suruga-ya, Mandarake, …) into: the likely official SKU, what the condition wording actually means, bootleg-caution flags, a price-to-MSRP ratio, and a landed-cost estimate to your country. Point any MCP-capable AI agent at it and hand it listing text — it does the rest.

Try it in your browser (no AI agent needed): https://merchgraph.app

Why this is different

1. Verified catalog, not scraped or guessed. Every SKU in the catalog was checked by a human against a primary source (an official product page, a maker's press release, etc.) — the source URL is attached to every entry and returned with every match, so you can check it yourself. Nothing is inferred by an LLM inside the server.
2. No confident guess, no candidate. When the match confidence is low, this server does not present a guess as an answer. Low-confidence matches are returned separately as weak_matches, never mixed into candidates — an empty candidates array means "probably not in the catalog," not "best effort."
3. Bring Your Own Listing. This server never crawls or scrapes marketplaces itself, and never stores the listing text or URL you send it. You already have the listing open; you paste the text, it interprets it.

Supported IP

Kingdom Hearts only, for now. The catalog is hand-verified one SKU at a time, so it grows slowly on purpose. If you ask about another franchise, the server won't fabricate an answer — it notes the request (see Data sourcing & privacy) to help decide what to add next. Use report_correction or open a GitHub issue if you want to nominate a franchise or a specific missing SKU.

Usage examples

These are things you'd say to your AI agent once it's connected to this server (see Connect).

1. "Is this listing worth it?"

"I found this on Mercari for ¥8,000: 一番くじ KINGDOM HEARTS -25th Anniversary- A賞 ソラ スタチュー 開封済み. What is it, and is that a fair price?"

The agent calls resolve_listing and gets back the matched SKU, the MSRP, the price ratio, the meaning of 「開封済み」("opened"), and a link to the primary source for that SKU.

2. "What Sora merch exists under ¥5,000?"

"Show me Kingdom Hearts Sora items under ¥5,000 that I could display."

The agent calls discover({ ip: "kingdom-hearts", character: "Sora", budget_jpy: 5000, purpose: "display" }) and gets a list of catalog SKUs matching those filters (this does not mean any of them are currently for sale anywhere — it's a catalog browse, not a marketplace search).

3. "What would it cost me, landed, in the US?"

"That listing is ¥8,000 plus it weighs about 400g. What's the total cost shipped to the US?"

The agent calls estimate_landed_cost({ price_jpy: 8000, weight_g: 400, dest_country: "US" }) and gets per-route estimates (proxy fee + shipping) with the cheapest option highlighted, plus when the rate table was last checked.

Connect

• MCP endpoint (Streamable HTTP, JSON-RPC 2.0, no auth): https://mcp.merchgraph.app/mcp (the older https://kh-merch-graph.fandex.workers.dev/mcp keeps working)
• Health check: .../health
• For AI agents that discover servers by URL: .../llms.txt (plain-language entry point) and .../openapi.json (schema reference — the real transport is MCP's own tools/list/tools/call, this is a documentation aid for OpenAPI-only tooling)

Claude Desktop / Claude.ai

Add it as a custom connector using the MCP endpoint URL above. No API key or auth is required.

Any other MCP client

Point it at the /mcp endpoint with the Streamable HTTP transport. tools/list returns the live, authoritative schema for all five tools below.

ツール

ツール	機能
resolve_listing	出品タイトル／説明 → SKU 候補、状態を示す用語、海賊版への注意フラグ、価格比
resolve_listings_batch	1 回の呼び出しで複数の出品について resolve_listing と同じ処理を行います（デフォルトで 1 回につき最大 5 件。wrangler.toml の MAX_BATCH_LISTINGS で設定）。結果は入力順に並びます
explain_product	sku_id または自由形式のクエリ → 1 つの SKU の詳細（シリーズ、キャラクター、寸法、再販履歴、出典）
discover	IP／キャラクター／予算／目的でカタログを検索します
estimate_landed_cost	出品価格 + 重量／SKU + 仕向国 → 輸送ルート別の着地価格の見積もり
report_correction	カタログの誤りを報告するか、一次情報源を添えて新しい SKU を提案します

入力／出力の完全な形式については、docs/SPEC.md をご覧ください。

データソースとプライバシー

• カタログの各行には、一次情報源を示す source_url が必要です。未検証の行には、暗黙に信頼するのではなく、verified=false と記されています。
• このサーバーはマーケットプレイスのスクレイピング、閲覧、ログインを行いません。エージェントから送信されたテキストを、1 回のリクエストの処理中に限り読み取ります。
• 公開デプロイ環境の使用ログに含まれるのは、ツール名、一致した SKU ID、価格、仕向国、タイムスタンプのみです。出品タイトル、説明、および渡された URL は記録も保存もされません。
• resolve_listing で候補が見つからなかった場合、またはまだカタログにない IP について discover で検索された場合、サーバーは識別につながらない簡単なシグナル（認識した少数のキーワード、またはリクエストされた IP 名のみ。出品テキストそのものは記録しません）をログに記録し、メンテナーが次に追加する項目を把握できるようにします。

免責事項

• 真贋は注意を促すフラグであり、判定ではありません。 flags は、販売者に確認する価値のある点（希望小売価格を大きく下回る価格、偽造品に関連する素材や刻印など）を示します。このサーバーが商品を本物または偽物と断定することはありません。
• 価格は計画用の見積もりであり、査定額や見積価格ではありません。 希望小売価格との比率や着地価格の合計は、さらに調べるかどうかを判断するための参考情報であり、購入の判断や価格評価にそのまま用いることを想定していません。

修正または新しい SKU の報告

変更したいフィールドと、変更後の値を指定して report_correction を呼び出してください（新しい商品を提案する場合は sku_id を空欄にします）。根拠となる source_url も必ず添えてください。GitHub issue を作成することもできます。

コントリビュート／自分でビルドする

このリポジトリは、このような MCP サーバーを一から構築する手順を学ぶための教材でもあります。完全な設計については、docs/GETTING_STARTED_JA.md（日本語）と docs/SPEC.md をご覧ください。ライセンスは MIT です（LICENSE を参照）。サードパーティの名称、ロゴ、画像は対象外です。NOTICE をご覧ください。

パイプライン：稼働中