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.

Tools

Tool	What it does
resolve_listing	Listing title/description → SKU candidates, condition terms, bootleg-caution flags, price ratio
resolve_listings_batch	Same as resolve_listing for several listings in one call (up to 5 per call by default, set by MAX_BATCH_LISTINGS in wrangler.toml); results in input order
explain_product	sku_id or free-text query → full detail on one SKU (line, character, dimensions, rerelease history, source)
discover	Browse the catalog by IP/character/budget/purpose
estimate_landed_cost	Listing price + weight/SKU + destination country → landed-cost estimate by route
report_correction	Report a catalog error, or propose a new SKU, with a primary source

Full input/output shapes: docs/SPEC.md.

Data sourcing & privacy

• Every catalog row requires a source_url to a primary source; unverified rows are marked verified=false rather than silently trusted.
• This server does not scrape, browse, or log in to any marketplace. It only reads the text an agent sends it, for the duration of a single request.
• Usage logs on the public deployment contain only: tool name, matched SKU IDs, price, destination country, and timestamp. The listing title, description, and any URL you pass are never logged or stored.
• When resolve_listing finds no candidate, or discover is asked about an IP not yet in the catalog, the server logs a small, non-identifying signal (a handful of recognized keywords, or the requested IP name only — never the raw listing text) so maintainers know what to add next.

Disclaimers

• Authenticity is a caution flag, not a verdict. flags point out things worth asking the seller about (price far below MSRP, materials/marks associated with counterfeits, etc.). This server never states that an item is genuine or fake.
• Prices are estimates for planning, not appraisals or quotes. MSRP ratios and landed-cost totals are meant to help you decide whether to look closer, not to be relied on for a purchase decision or a valuation.

Reporting a correction or a new SKU

Call report_correction with the field you want changed (or leave sku_id empty to propose a new item), your proposed value, and — importantly — a source_url backing it up. You can also open a GitHub issue.

Contributing / building this yourself

This repo is also a step-by-step teaching kit for building an MCP server like this one from scratch. See docs/GETTING_STARTED_JA.md (Japanese) and docs/SPEC.md for the full design. License: MIT (see LICENSE). Third-party names, logos and images are not covered; see NOTICE.

Pipeline: active