pokelances-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pokelances-mcp Busca el Charizard ex 199 de 151 y crea un borrador en NM"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 the catalog by name, set (name or code) and collector number. Returns USD market price per sub-type. | No |
| 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 what is already listed on pokelances.com. | No |
| Create a draft with the seller's price or the suggested one. Warns about duplicates and prices far from the suggestion. | Drafts only |
| RAG over the help docs: returns the passages that answer a question, with their source, for the model to answer and cite. | No |
| List the drafts created so far. | No |
Guardrails
Drafts only, human approval: nothing reaches the live store without the seller.
Idempotency:
create_drafttakes anidempotencyKey; 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).
Chunking: one chunk per
##section, with the document title as context and a stable id (pagos.md#pagar-con-tarjeta).Two retrievers: BM25 for exact terms (Izipay, Shalom, NM) and local multilingual embeddings (
multilingual-e5-basevia Transformers.js: no API key, no cost).Hybrid score: a weighted sum of min-max normalized scores (0.8 vectors, 0.2 BM25).
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-smallreached 85% recall@3,e5-base95%.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.jsonsync-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.jsThen 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 InspectorRun 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 |
|
|
|
|
|
|
|
|
|
|
| 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 testsNotes
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 toolscreate_draftCreate a listing draftAIdempotent
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 draftsARead-onlyIdempotent
List the listing drafts created so far, newest last.
Inputs: no named parameters.
search_cardsSearch the card catalogARead-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 docsARead-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 listingsARead-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 solesARead-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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Hosted MCP server for 3Dsellers, the multichannel selling platform. Connect Claude, ChatGPT, Cursor, VS Code or any MCP client and manage your eBay, Amazon, Walmart, Etsy, Shopify, WooCommerce and TikTok Shop stores in plain language: search and update products, publish listings, sync inventory, tag and track orders, run bulk actions and CSV imports, and reply to customer messages. 120+ tools. Sign in with OAuth or a personal token. No eBay developer account and nothing to install. Setup guides and config examples for every client: https://github.com/3dsellers/ebay-mcp-server
Create, write and publish Printify products from chat, after a preview you approve.
Read-only BYO-key MTG/TCG pricing MCP with repricing suggestions. AI-authored.
Provide detailed Pokémon data and information through a standardized MCP interface. Enable LLMs an…
Related MCP Servers
AlicenseAqualityBmaintenanceEnables LLM clients to query live TCG inventory, pricing, alerts, profit and loss, and eBay listings directly through natural language tool calls.11MIT
@pokemontcgapi/mcpofficial
AlicenseAqualityBmaintenanceEnables agents to search and query Pokémon TCG cards and sets, retrieve priced card data with provenance, and identify cards from images through eight read-only tools.8368 npmMIT- AlicenseAqualityCmaintenanceEnables 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.9MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.1MIT