Skip to main content
Glama

pokelances-mcp

An MCP server and a Claude agent that turn a seller's description of their Pokémon TCG cards into listing drafts for PokeLances, a Pokémon TCG marketplace in Peru, plus a small RAG that answers buyers' and sellers' questions from the help docs, with citations.

"Tengo un Charizard ex de 151, el 199, casi nuevo, y 2 Pikachu reverse" → finds each card in the catalog, checks whether it is already listed, suggests a price in soles and creates a draft for the seller to review.

Why

Sellers list cards one by one: look up the exact printing, check the market price, convert it to soles, adjust for condition and make sure it isn't already listed. This project exposes those steps as tools that any MCP client (Claude Code, Claude Desktop, GitHub Copilot…) can use, plus a small agent that chains them.

The agent never publishes. It only creates drafts; the seller reviews them and publishes from the store's admin panel.

Related MCP server: @pokemontcgapi/mcp

How it works

flowchart LR
    U[Seller] -->|plain text| A[Agent<br/>Claude tool runner]
    C[Claude Code / any MCP client] --> S
    A -->|MCP over stdio| S[pokelances-mcp server]
    S --> CAT[(Catalog<br/>TCGplayer data via tcgcsv.com)]
    S -->|read-only| API[PokeLances public API]
    S --> D[(drafts.json)]
    S --> K[(Help docs<br/>knowledge/*.md)]

Tool

What it does

Writes?

search_cards

Search the catalog by name, set (name or code) and collector number. Returns USD market price per sub-type.

No

suggest_price

USD market × exchange rate × condition factor (NM 1, LP 0.85, MP 0.7, HP 0.5, DMG 0.35), rounded to S/ 0.50.

No

search_store

Search what is already listed on pokelances.com.

No

create_draft

Create a draft with the seller's price or the suggested one. Warns about duplicates and prices far from the suggestion.

Drafts only

search_help

RAG over the help docs: returns the passages that answer a question, with their source, for the model to answer and cite.

No

list_drafts

List the drafts created so far.

No

Guardrails

  • Drafts only, human approval: nothing reaches the live store without the seller.

  • Idempotency: create_draft takes an idempotencyKey; a retried call returns the existing draft instead of creating a second one.

  • Read-only access to the store, through its public API.

  • Validated inputs: every tool has a Zod schema; bad arguments come back as tool errors, not crashes.

  • Step limit: the agent stops after 8 tool-calling iterations and says so.

  • Logged tool calls: the agent appends every call (tool, arguments, duration, success) to data/agent-log.jsonl.

  • stdout belongs to the protocol: the server logs to stderr only.

RAG over the help docs

search_help answers questions like "¿cobran más si pago con tarjeta?" from knowledge/*.md (payments, shipping, ways to buy, products, stores).

  1. Chunking: one chunk per ## section, with the document title as context and a stable id (pagos.md#pagar-con-tarjeta).

  2. Two retrievers: BM25 for exact terms (Izipay, Shalom, NM) and local multilingual embeddings (multilingual-e5-base via Transformers.js: no API key, no cost).

  3. Hybrid score: a weighted sum of min-max normalized scores (0.8 vectors, 0.2 BM25).

  4. Grounded answer: the tool returns passages with their source; the model answers only from them, cites them and says so when they don't answer the question.

Evaluation

knowledge/eval.json has 20 paraphrased questions, each with the section that answers it. npm run eval measures retrieval, and CI fails if hybrid recall@3 drops below 90%.

Retriever

recall@1

recall@3

MRR

BM25

65%

65%

0.66

Vectors (e5-base)

85%

95%

0.91

Hybrid (0.8 / 0.2)

85%

95%

0.91

What the numbers taught me:

  • Reciprocal Rank Fusion made things worse here: 75% recall@3 versus 85% for vectors alone (both with e5-small). Any weak one-word BM25 match outranked the best semantic match. A weighted sum of normalized scores fixed it.

  • The embedding model mattered most: e5-small reached 85% recall@3, e5-base 95%.

  • On paraphrased questions BM25 adds nothing measurable; it stays for exact names and codes, which these 20 questions barely use.

  • No similarity threshold: e5 cosine similarities are compressed (about 0.8 both for answerable and unanswerable questions), so deciding "not in the docs" is left to the answering model, and the tool description tells it to.

The help docs only state what PokeLances does today; anything else (returns, shipping costs) is meant to come back as "I don't have that information".

Quick start

Requires Node.js 20+.

npm install
npm run build
npm run sync-catalog            # downloads the Pokémon catalog from tcgcsv.com into data/catalog.json

sync-catalog options: --groups 23237,23651 for specific sets, or --from-cardpulse <raw snapshot dir> to reuse a raw snapshot from CardPulse, my TCG price pipeline, offline.

Use it from Claude Code

claude mcp add pokelances -- node /absolute/path/to/pokelances-mcp/dist/server.js

Then ask Claude Code something like "busca el Charizard ex 199 de 151 y crea un borrador en NM".

Try the tools in a browser

npm run inspect                 # MCP Inspector

Run the agent

export ANTHROPIC_API_KEY=...
npm run agent -- "Tengo un Charizard ex de 151, el 199, casi nuevo, y 2 Pikachu reverse"

The agent starts the MCP server as a child process, loads its tools with the Anthropic SDK's MCP helpers and runs them with the SDK's tool runner (claude-opus-5-5).

Configuration

Variable

Default

CATALOG_PATH

data/catalog.json

DRAFTS_PATH

data/drafts.json

STORE_URL

https://www.pokelances.com

USD_TO_PEN

3.75

KNOWLEDGE_DIR

knowledge/

MODEL_CACHE_DIR

Transformers.js default cache

Tests

npm test
npm run eval      # RAG retrieval eval (downloads the embedding model the first time)

Unit tests cover catalog search, pricing, idempotent drafts, store pagination, chunking and BM25. The end-to-end test starts the real server over stdio, talks to it with the MCP client SDK and uses a fake store API, so it never touches the live site.

Project layout

src/
  server.ts        MCP server (stdio)
  agent.ts         Claude agent: MCP client + tool runner
  tools.ts         tool definitions shared by the server
  catalog.ts       in-memory catalog search
  pricing.ts       price suggestion
  store.ts         read-only client for the PokeLances API
  drafts.ts        local draft store with idempotency
  rag/help.ts      chunking, BM25, embeddings and hybrid search
  cli/eval.ts      retrieval evaluation
  cli/sync-catalog.ts
knowledge/                     help docs + eval.json
tests/
fixtures/catalog-sample.json   one set (Scarlet & Violet 151) for tests

Notes

  • Prices are a starting point, not an appraisal. The condition factors are configurable rules of thumb.

  • Card data comes from TCGplayer through tcgcsv.com. This project is not affiliated with The Pokémon Company, Nintendo or TCGplayer.

License

MIT

Available Tools

6 tools
create_draftCreate a listing draftA
Idempotent

Create a listing DRAFT for the seller to review. It never publishes anything. If pricePen is omitted, the suggested price is used. Reusing an idempotencyKey returns the existing draft instead of creating another. The result includes warnings, e.g. when the same card is already listed.

Inputs: condition (required), productId (required), idempotencyKey (required), subType, +3 more.

list_draftsList draftsA
Read-onlyIdempotent

List the listing drafts created so far, newest last.

Inputs: no named parameters.

search_cardsSearch the card catalogA
Read-onlyIdempotent

Search the Pokémon TCG catalog (TCGplayer data) by card name, optionally narrowed by set name or code and collector number. Returns productId, set, number, rarity and USD market price per sub-type (Normal, Holofoil, Reverse Holofoil). If several products match, ask the seller for the set or number instead of guessing.

Inputs: name (required), set, kind, limit, +1 more.

search_helpSearch the PokeLances help docsA
Read-onlyIdempotent

Search PokeLances' help docs (payments, shipping, ways to buy, products, stores) for passages that answer a buyer's or seller's question. Answer ONLY with what the passages say and cite each one by its source. Each passage has its cosine similarity to the question; passages are always returned, so check that they actually answer it. If they don't, say you don't have that information instead of guessing.

Inputs: question (required), k.

search_storeSearch live PokeLances listingsA
Read-onlyIdempotent

Search what is already listed on pokelances.com (public, read-only). Use it to spot duplicates and compare prices before drafting.

Inputs: name (required), set.

suggest_priceSuggest a price in solesA
Read-onlyIdempotent

Suggest a listing price in Peruvian soles for a catalog product: USD market price x exchange rate x a condition discount, rounded to S/ 0.50. It is a starting point; the seller has the final word.

Inputs: productId (required), subType, condition.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: catalog search, price suggestion, store listing search, draft creation, help-doc search, and draft listing. The three search tools could look similar at a glance, but their targets are explicit and non-overlapping.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun convention, such as search_cards, suggest_price, create_draft, and list_drafts. There are no mixed casing styles or inconsistent verb patterns.

    Tool Count5/5

    Six tools is well-scoped for a Pokémon TCG seller-assistant workflow. Each tool supports a distinct step from catalog lookup and pricing to draft creation and help lookup without excessive surface area.

    Completeness3/5

    The surface covers search, pricing, duplicate checking, draft creation, draft listing, and help lookup. However, draft lifecycle operations such as updating, deleting, or retrieving a specific draft are missing, leaving notable gaps for managing drafts after creation.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables LLM clients to query live TCG inventory, pricing, alerts, profit and loss, and eBay listings directly through natural language tool calls.
      11
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables read-only Magic: The Gathering pricing lookups across Cardmarket, TCGplayer, and Scryfall using your own API keys, with a free no-key Scryfall tier. It lets an assistant search cards and products, pull price guides and seller offers, and generate suggested repricing for a listing.
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to price trading cards and sealed products across 14 games with sourced, dated quotes, graded medians, PSA populations, eBay sold data and 365 days of history. Also supports card identification from free text or photo, batch lookups, and side-by-side price comparisons through 16 read-only tools.
      1
      MIT