Skip to main content
Glama

ptcgp-mcp-server

Servidor MCP local para un catálogo de Pokémon TCG Pocket y una colección personal en SQLite. Usa el estándar MCP con transporte stdio; no depende de Claude, Anthropic, OpenAI ni de ningún modelo concreto — cualquier cliente compatible con MCP puede lanzar el proceso.

Este es un proyecto en fase de preparación, todavía no publicado. No lo instales pensando en usarlo como paquete público: hoy es un checkout local (package.json marcado como "private": true, sin remoto Git configurado).

Qué funciona hoy (verificado)

  • Arranca como servidor MCP sobre stdio y expone 17 tools (tabla más abajo). Verificado con npm run smoke, que levanta el binario compilado contra un directorio de datos temporal y lista las tools reales.

  • Crea una base SQLite local en PTCGP_DATA_DIR (o en ~/.local/share/ptcgp-mcp por defecto) con WAL, claves foráneas y migraciones versionadas forward-only.

  • Todas las escrituras de colección (individual, masiva, por rango) usan sentencias SQL parametrizadas y corren dentro de una transacción cuando afectan a varias filas.

  • Las rondas de captura validan un contador de cabecera contra los huecos detectados/confirmados y solo aplican cambios a la colección de forma transaccional, con confirm=true explícito.

  • Normaliza capturas PNG/JPEG/WebP (con corrección de orientación) y ejecuta OCR local con Tesseract; ninguna imagen sale de la máquina. HEIC/HEIF está en la lista de formatos aceptados en el código pero no está soportado por el build de Sharp instalado en este entorno — no lo des por bueno sin comprobarlo tú mismo.

  • Incluye tools de sincronización/enriquecimiento de catálogo y de consulta de mazos meta, que dependen de fuentes de red de terceros (GitHub, TCGdex, Limitless TCG) y son la parte menos robusta del proyecto: ver OPEN_SOURCE_GAP_ANALYSIS.md para el detalle de por qué.

Related MCP server: mcp-tcgdex

Instalación para desarrollo

Node 22 o 24 (.nvmrc fija 24 como preferido; CI cubre ambas). better-sqlite3 es una dependencia nativa: tras cambiar de versión de Node, vuelve a instalar.

npm ci
export PTCGP_DATA_DIR="$(mktemp -d)"
npm test
npm run smoke
  • npm test compila y ejecuta la suite (node --test) sobre un directorio de datos que tú controlas.

  • npm run smoke arranca el servidor stdio compilado en un directorio temporal propio, lista sus tools y ejecuta PRAGMA quick_check sobre esa base temporal.

  • npm run verify añade formato (prettier --check), lint (eslint) y npm pack --dry-run — no publica nada.

Nunca ejecutes tests, sync o rondas contra tu PTCGP_DATA_DIR real sin backup previo.

Configurar un cliente MCP

{
  "command": "node",
  "args": ["/ruta/absoluta/a/ptcgp-mcp-server/dist/index.js"],
  "env": {
    "PTCGP_DATA_DIR": "/ruta/absoluta/fuera-del-repo/ptcgp-mcp-data"
  }
}

El servidor usa stdout exclusivamente para el protocolo MCP; nunca escribas ahí manualmente. PTCGP_LOG_LEVEL acepta fatal|error|warn|info|debug|trace|silent (por defecto info) y controla logs estructurados en stderr — hoy el logging operativo es mínimo (solo arranque/errores fatales), así que no confíes en él para depurar el comportamiento de una tool concreta todavía.

Transporte HTTP (fase inicial)

Existe un segundo entrypoint pensado para clientes remotos (ChatGPT en Developer Mode, MCP Inspector desde otra máquina, etc.). Expone en /mcp el mismo McpServer pero registrando solo 7 tools de lectura (ptcgp_search_cards, ptcgp_get_card, ptcgp_list_expansions, ptcgp_collection_stats, ptcgp_missing_cards, ptcgp_meta_decks, ptcgp_get_decklist). Las 17 tools de stdio siguen intactas.

Arranque local:

export PTCGP_HTTP_TOKEN="$(openssl rand -hex 32)"
export PTCGP_DATA_DIR=/ruta/absoluta/fuera-del-repo/ptcgp-mcp-data
npm run start:http     # escucha en 127.0.0.1:8787 por defecto

Prueba con el Inspector: npm run inspect:http (pasa el token en Authorization: Bearer … en la UI). El binario stdio se sigue publicando en bin; el HTTP no.

Guardias implementadas dentro del server:

  • Token estático obligatorio comparado con crypto.timingSafeEqual.

  • Allowlist de Host (defensa contra DNS rebinding) y de Origin (por defecto vacía → deniega cualquier cross-site).

  • Body limit y timeout configurables por env.

  • Rate limit en memoria por IP (60 peticiones/minuto/IP por defecto), antes de autenticar.

  • Solo POST/GET en /mcp; el resto devuelve 405 con JSON-RPC válido.

  • GET /healthz devuelve 200 text/plain "ok" sin filtrar rutas ni versión.

Fuera de alcance de esta fase: OAuth 2.1, acceso multiusuario, publicación en directorios MCP y despliegue automatizado. Antes de exponer datos privados a un endpoint público real hace falta OAuth 2.1 según el spec MCP. Para pruebas privadas puedes tunelizar con OpenAI Secure MCP Tunnel o Cloudflare Tunnel y el token estático. Los templates de systemd, Caddy y environment file viven en deploy/.

Variables (todas opcionales salvo PTCGP_HTTP_TOKEN): PTCGP_HTTP_HOST (default 127.0.0.1), PTCGP_HTTP_PORT (default 8787), PTCGP_HTTP_TOKEN (>= 32 caracteres, obligatoria), PTCGP_HTTP_ALLOWED_HOSTS (CSV, default localhost,127.0.0.1), PTCGP_HTTP_ALLOWED_ORIGINS (CSV, default vacío), PTCGP_HTTP_BODY_LIMIT_KIB (default 1024), PTCGP_HTTP_REQUEST_TIMEOUT_MS (default 30000), PTCGP_HTTP_RATE_LIMIT_MAX (default 60), PTCGP_HTTP_RATE_LIMIT_WINDOW_MS (default 60000) y PTCGP_HTTP_RATE_LIMIT_MAX_KEYS (default 10000).

Tools MCP

Grupo

Tools

Catálogo

ptcgp_search_cards, ptcgp_get_card, ptcgp_list_expansions, ptcgp_sync_catalog, ptcgp_enrich_catalog

Colección

ptcgp_collection_stats, ptcgp_missing_cards, ptcgp_set_card_quantity, ptcgp_bulk_update_collection, ptcgp_mark_range

Mazos

ptcgp_meta_decks, ptcgp_get_decklist

Rondas de captura

ptcgp_round_start, ptcgp_round_analyze_screenshots, ptcgp_round_record, ptcgp_round_status, ptcgp_round_finalize

Flujo seguro de una ronda: round_start → round_analyze_screenshots → revisión humana con round_record → round_status → round_finalize(confirm=true). La comprobación de contadores protege contra muchas lecturas incompletas, pero no prueba por sí sola que las capturas cubran toda la expansión: la revisión visual sigue siendo obligatoria.

Datos y privacidad

  • No se versiona ninguna base de datos, backup, captura real, .env ni log — .gitignore los excluye y esto se verificó contra git ls-files, no solo se asume.

  • Haz backup de una base SQLite con WAL usando herramientas conscientes de SQLite y con el servidor parado; copiar solo el .db mientras está activo puede dejarlo inconsistente.

  • El proyecto no requiere ninguna clave de API. Está bajo licencia MIT pero marcado "private": true para evitar una publicación accidental en npm mientras dure esta fase de preparación.

Límites actuales

No hay CLI, transporte Streamable HTTP, backup/restore como funcionalidad del servidor, ni proceso de publicación. Las tools que dependen de red (sync de catálogo, enriquecimiento, mazos meta) no tienen tests de contrato ni protección ante cambios de esquema/maquetación upstream. Antes de ampliar el proyecto, lee HANDOFF.md, ARCHITECTURE.md, ROADMAP.md y OPEN_SOURCE_GAP_ANALYSIS.md.

Available Tools

17 tools
ptcgp_bulk_update_collectionActualización masivaA
Destructive

Actualiza la cantidad poseída de múltiples cartas en una sola llamada transaccional. Cada item: {card_id, quantity}. mode='set' fija valores, mode='add' suma. Ideal al procesar capturas de pantalla de la colección o dictados del usuario. Ids inexistentes se reportan en 'errors' sin abortar el resto.

Inputs: items (required), mode.

ptcgp_collection_statsEstadísticas de colecciónA
Read-onlyIdempotent

Resumen global de la colección del usuario: cartas únicas poseídas vs total del catálogo, copias totales, desglose por expansión y por rareza. Es el punto de partida para cualquier pregunta general tipo "cómo va mi colección".

Inputs: no named parameters.

ptcgp_enrich_catalogEnriquecer catálogo (datos de combate)A
Idempotent

Descarga de TCGdex los datos de combate (ataques, habilidades, debilidades, retirada, stage, efectos de trainers) para las cartas que aún no los tienen. Incremental: solo procesa cartas pendientes salvo force=true. Con 'expansion' limita a un set (recomendado para llamadas desde conversación; el catálogo completo tarda minutos y conviene hacerlo con 'npm run sync' en shell). Fuentes en cascada: TCGdex primero, y para lo que TCGdex no cubra (sets recién salidos) scrapea las páginas de carta de Limitless TCG, que siempre tiene los sets nuevos. pending_total=0 significa catálogo completo.

Inputs: force, limit, expansion.

ptcgp_get_cardDetalle de cartaA
Read-onlyIdempotent

Detalle completo de una carta por id (ej. 'a1-036'): stats, ataques (coste, daño, efecto), habilidades, debilidades, retirada, stage, línea evolutiva, efecto (trainers), copias poseídas e imagen. El campo battle_data indica si la carta tiene datos de combate (sets muy recientes pueden no tenerlos hasta ejecutar ptcgp_enrich_catalog).

Inputs: card_id (required).

ptcgp_get_decklistDecklist de torneo (Limitless)A
Read-only

Descarga una decklist real de torneo para un arquetipo (slug de ptcgp_meta_decks) y la cruza con la colección del usuario: cada carta indica 'owned' (copias poseídas) y el resumen 'buildable' dice si el mazo es montable, qué cartas faltan y cuántas. finish_index selecciona qué resultado de torneo usar (0 = mejor finish reciente).

Ejemplo de flujo: ptcgp_meta_decks -> elegir slug -> ptcgp_get_decklist(slug) -> "te faltan 2 Espeon (b3a-020) y 1 Cyrus (a2-150)". Requiere red.

Inputs: slug (required), finish_index.

ptcgp_list_expansionsListar expansionesA
Read-onlyIdempotent

Lista todas las expansiones del juego con sus sobres y el progreso de colección del usuario en cada una: total de cartas, poseídas únicas y porcentaje. Útil como visión general o para decidir en qué set centrarse.

Inputs: no named parameters.

ptcgp_mark_rangeMarcar rango de cartasA
Destructive

Marca como poseídas (o ajusta) cartas de una expansión por números: numbers acepta lista y rangos, ej. "1,3,7-15,22". Pensado para volcado rápido manual: "del set a1 tengo de la 1 a la 50 menos la 33" se resuelve con dos llamadas (set 1-50, luego set 33 a 0) o una llamada "1-32,34-50". Números que no existan en la expansión se reportan en 'errors'.

Inputs: numbers (required), expansion (required), mode, quantity.

ptcgp_meta_decksMazos meta (Limitless)A
Read-only

Obtiene el ranking actual de arquetipos de mazo de Pokémon TCG Pocket desde Limitless (play.limitlesstcg.com, datos de torneos reales). Devuelve { decks: [{rank, name, slug, count, share}] } donde 'count' es nº de apariciones en torneos y 'share' el porcentaje del meta. El 'slug' se usa con ptcgp_get_decklist para ver la lista concreta. Requiere red.

Inputs: limit.

ptcgp_missing_cardsCartas faltantes / mejor sobreA
Read-onlyIdempotent

Analiza qué cartas faltan al usuario, agrupadas por sobre (pack), ordenando los sobres por número de faltantes descendente — responde directamente a "qué sobre me conviene abrir". Filtros opcionales por expansión y rareza máxima (ej. max_rarity='d4' ignora ☆/♕, que en la práctica salen por rareza visual, no por pack normal).

Devuelve { packs: [{pack, expansion, missing_count, total_in_pack, missing: [{id, name, rarity}] }] }. Con include_cards=false omite el listado de cartas y devuelve solo el ranking (más compacto).

Inputs: expansion, max_rarity, include_cards, limit_per_pack.

ptcgp_round_analyze_screenshotsAnalizar capturas de una rondaA
Idempotent

Analiza capturas móviles PNG/JPEG/WebP/HEIC, corrige orientación y normaliza cualquier resolución. Detecta los huecos de la cuadrícula y lee sus números con OCR local, sin enviar imágenes a Internet. Las detecciones quedan en revisión y NO cambian la colección. Las rutas deben ir en el mismo orden en que se recorrió la expansión.

Inputs: round_id (required), image_paths (required).

ptcgp_round_finalizeFinalizar y aplicar rondaA
Destructive

Aplica una ronda completa de forma transaccional. Requiere confirm=true y que el total esperado de poseídas coincida exactamente con total_catálogo - huecos. Por defecto solo usa huecos confirmados; use_auto_detections permite detecciones OCR con confianza >=0.84. En modo minimum conserva cantidades superiores existentes.

Inputs: confirm (required), round_id (required), use_auto_detections, expected_owned_unique.

ptcgp_round_recordConfirmar o corregir una rondaA
Idempotent

Registra observaciones confirmadas tras revisar las capturas. missing_numbers son huecos numerados; owned_numbers permite corregir falsos positivos del OCR. En quantity_mode='minimum', una carta visible equivale a cantidad mínima 1. En modo exact debe proporcionarse quantity por carta poseída. Esta operación aún no altera la colección.

Inputs: round_id (required), quantities, owned_numbers, missing_numbers.

ptcgp_round_startIniciar ronda de capturasA

Crea una ronda para una expansión completa. Una ronda empieza en la primera carta y termina en la última captura de esa expansión. expected_owned_unique debe ser la suma de los contadores visibles de la cabecera (diamantes + estrellas + shiny/corona); se usa para impedir que un OCR incompleto altere la colección. quantity_mode='minimum' es el adecuado para la cuadrícula normal: una carta visible prueba al menos una copia y conserva cantidades superiores ya registradas.

Inputs: expansion (required), label, quantity_mode, expected_owned_unique.

ptcgp_round_statusEstado y previsualización de rondasA
Read-onlyIdempotent

Muestra una ronda concreta o las rondas recientes, con capturas, detecciones confirmadas y pendientes. No modifica datos.

Inputs: round_id.

ptcgp_search_cardsBuscar cartasA
Read-onlyIdempotent

Busca cartas en el catálogo completo de Pokémon TCG Pocket, con cantidad poseída incluida en cada resultado.

Filtros (todos opcionales, combinables):

  • query: texto parcial del nombre (case-insensitive)

  • text_search: busca en efectos de ataques, habilidades y cartas trainer (ej. "heal", "discard", "draw")

  • expansion: id de expansión (a1, a1a, a2, a2a, a2b, a3, a3a, a3b, a4, a4a, a4b, b1, b1a, b2, b2a, b2b, b3, pa, pb)

  • pack: nombre del sobre (Mewtwo, Charizard, Pikachu, etc.)

  • rarity: símbolo o alias (d1=◊, d2=◊◊, d3=◊◊◊, d4=◊◊◊◊, s1=☆, s2=☆☆, s3=☆☆☆, crown=♕, promo)

  • type: Grass|Fire|Water|Lightning|Psychic|Fighting|Darkness|Metal|Dragon|Colorless|Trainer

  • category: Pokemon|Trainer

  • stage: Basic|Stage1|Stage2

  • min_damage: daño mínimo del mejor ataque (para construcción de mazos)

  • has_ability: true para solo cartas con habilidad

  • owned_filter: 'all' (defecto) | 'owned' (quantity>0) | 'missing' (quantity=0) | 'duplicates' (quantity>1)

  • ex: true para solo cartas ex

  • limit/offset para paginación

Cada resultado incluye max_damage y has_ability. Para ataques/habilidades/efectos completos usa ptcgp_get_card. Los datos de combate provienen de TCGdex; sets muy recientes pueden no tenerlos aún (ejecutar ptcgp_enrich_catalog periódicamente).

Ejemplos: "atacantes de fuego para mi mazo que ya tenga" -> type="Fire", min_damage=100, owned_filter="owned". "cartas que curen" -> text_search="heal".

Inputs: ex, pack, type, limit, +10 more.

ptcgp_set_card_quantityFijar cantidad de una cartaA
Destructive

Registra cuántas copias de una carta posee el usuario. mode='set' fija el valor exacto (defecto); mode='add' suma (admite negativos para restar, nunca baja de 0). Usa ptcgp_bulk_update_collection para varias cartas o ptcgp_mark_range para rangos de números consecutivos.

Inputs: card_id (required), quantity (required), mode.

ptcgp_sync_catalogSincronizar catálogoA
Idempotent

Descarga el catálogo completo de cartas y expansiones desde el dataset comunitario (chase-manning/pokemon-tcg-pocket-cards, scrapeado de Limitless TCG) y actualiza la base local. Ejecutar tras el primer arranque y cuando salga una expansión nueva. No toca la colección del usuario. Requiere red.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 17 tools

    Disambiguation3/5

    The core resources are separated by domain (catalog, collection, decks, round-based OCR import), but several tools blur together: sync_catalog vs enrich_catalog, collection_stats vs list_expansions, and missing_cards vs search_cards with owned_filter=missing all have overlapping coverage and rely heavily on descriptions to disambiguate. The round_* workflow is clearly differentiated.

    Naming Consistency3/5

    All tools share the ptcgp_ prefix and snake_case, but the internal convention is mixed: most use verb_object (search_cards, set_card_quantity) while some are noun phrases (collection_stats, missing_cards, meta_decks) and the round tools are noun-first (round_start, round_finalize). Still readable, but not a consistent verb_noun pattern throughout.

    Tool Count4/5

    17 tools is slightly above the ideal range, but the scope is broad enough that most tools earn a place: catalog sync/enrich, card searching, collection updates, deck data, and a deliberate OCR round workflow. It feels somewhat heavy, especially with five round_* tools, but not bloated.

    Completeness4/5

    The surface covers the full collection-management lifecycle: ingest catalog, search/get cards, track owned quantities, analyze missing cards, and import via OCR rounds, plus metagame deck lookup. Minor gaps exist such as no way to discard/delete a round or manage custom saved decks, but these are workable and outside the core stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables extraction of structured data from documents like invoices, receipts, and bank statements using local Vision AI (Ollama) or cloud providers (Gemini), with data stored in a local SQLite database.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables querying multi-language trading card game data (Pokémon TCG and more) through natural language or direct tools, integrated with Pipeworx MCP gateway.
      79 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Lets AI assistants search every Pokémon TCG Pocket card by name, type, rarity, set, evolution stage, ability effect and attack, in six languages, with typo tolerance and semantic search.
      1
      MIT