Skip to main content
Glama

optcg-knowledge

Local, data-only MCP server (Python 3.12 + stdio) providing a searchable knowledge base for the One Piece Card Game (OPTCG): Comprehensive Rules, canonical cards, official Bandai FAQs & errata, and curated judge rulings with hybrid search (SQLite FTS5 BM25 + sqlite-vec local embeddings + Reciprocal Rank Fusion).

optcg-knowledge never calls external/paid LLM or embedding APIs and contains no game-engine simulation logic. The connected agent (Claude Code, Antigravity, Gemini CLI) performs reasoning using structured tools and prompts exposed by this server.


Authority Hierarchy

Every rule and ruling follows a strict authority order:

authority

source

Description

1

rules

Official Comprehensive Rules (highest)

2

official_faq / errata

Official Bandai card FAQs and errata

3

judge

Certified Bandai judge rulings (tier_0 > tier_2 > tier_1)

4

community

Community rulings (optional, lowest)

  • Judge tiers (within authority = 3): tier_0 (highest) > tier_2 (senior) > tier_1 (basic). Only the role ("judge") and optional judge_tier are persisted—personal names, Discord handles, and user IDs are never stored.

  • No silent deletion: outdated rulings retain date and rules_version and are linked via superseded_by (excluded by default unless include_superseded=True).

  • Interoperability: canonical card_id (OP05-119, ST10-001, P-001), canonical rule_id (7-1-4-1), and versioned export_rulings JSON (schema_version = "1.0") are designed for downstream projects such as an external optcg-engine.


Related MCP server: rag-hub-mcp

Installation

Requires Python 3.12+ and uv.

# Core installation (CLI, SQLite FTS5 + sqlite-vec, lexical search, MCP server)
uv sync

# Optional: install local sentence-transformers + PyTorch for hybrid vector search
uv sync --extra embeddings

Copy .env.example to .env if you want to customize paths or local embedding settings:

cp .env.example .env

Default local embedding model is BAAI/bge-m3 (1024 dims, FP16 on CUDA with batch_size=8 to fit 4 GB VRAM GPUs, automatic CPU fallback). You can switch to intfloat/multilingual-e5-base (768 dims) via OPTCG_EMBEDDING_MODEL.


Ingestion Pipeline (optcg-ingest)

All ingestion commands are idempotent and safe to re-run without duplicating rows or re-embedding unchanged chunks. Raw Bandai PDFs/HTML and chat dumps live under data/raw/ (gitignored).

1. Download official Bandai rules, FAQ PDFs, and errata HTML

Downloads the official Comprehensive Rules PDF (data/raw/rules/rule_comprehensive.pdf), all official FAQ PDFs (data/raw/faq/*.pdf), and the text-only errata HTML page (data/raw/faq/errata_card.html) directly from Bandai's English website (skips unchanged files on re-run, never downloads card images):

uv run optcg-ingest fetch-official
# Or fetch only one category: --only rules | faq | errata

2. Ingest Comprehensive Rules PDF (authority = 1)

uv run optcg-ingest rules data/raw/rules/rule_comprehensive.pdf

3. Ingest canonical cards (text/stats + image_url only)

From punk-records JSON packs:

uv run optcg-ingest cards --source punk-records
# Optional subset of packs:
uv run optcg-ingest cards --source punk-records --packs OP01,OP05,ST10

Or from local JSON files in data/raw/cards/:

uv run optcg-ingest cards --source local --path data/raw/cards

4. Ingest official FAQs & errata (authority = 2)

uv run optcg-ingest faq data/raw/faq/

Supports single files or directories containing .pdf (Bandai tabular Excel-exported PDFs and Q:/A:/Before:/After: PDFs), .html/.htm (official errata_card page), and .txt.

Optional flags: --source auto|official_faq|errata, --date YYYY-MM-DD, --rules-version 1.24, --url https://....

5. Generate local embeddings (incremental)

uv run optcg-ingest embed

Useful flags: --batch-size 8, --device auto|cuda|cpu, --fp16/--no-fp16, --force. Only new or modified chunks (tracked via content_hash) are embedded.

6. Import & export curated rulings (collaborative JSON workflow)

Tracked, anonymized judge rulings live in data/rulings/ (TEMPLATE.md, threads/, and judge_rulings.json) so collaborators can contribute new rulings via Pull Requests without committing raw Bandai PDFs or un-anonymized chat logs:

# Import curated judge rulings from the repository into your local DB
uv run optcg-ingest import-rulings data/rulings/judge_rulings.json
uv run optcg-ingest embed

# Export only curated judge rulings back to the repository after curating & approving
uv run optcg-ingest export-rulings --source judge --out data/rulings/judge_rulings.json

# Export vetted rulings for downstream consumers (e.g., optcg-engine)
uv run optcg-ingest export-rulings --card-id OP05-119 --min-authority 3 --since 2025-01-01 --out rulings.json

By default export-rulings exports only reviewed = True, non-superseded rulings. Pass --include-superseded and/or --include-unreviewed to include them.


Judge Ruling Curation Workflow

  1. Save raw Discord forum threads under data/raw/judge_chats/ (gitignored) using the lightweight thread template:

---
Thread: OP05-119 extra turn vs OP04-083 Sabo
Date: 2026-11-18

[PLAYER]
<Question copied from forum post>

[JUDGE T2]
<Judge answer>

[JUDGE T0]
<Optional higher-tier clarification>
---
  1. Trigger the MCP prompt curar(arquivo="2026-11-judge-forum.md") in your agent. It extracts Q&A pairs, strips all personal names/@handles/Discord IDs, verifies canonical card_ids and rule_refs, applies judge tier precedence (tier_0 > tier_2 > tier_1), and calls add_ruling(...) (entering with reviewed = False).

  2. Review pending entries via list_unreviewed_rulings, approve via mark_ruling(ruling_id, reviewed=True), link outdated rulings via mark_ruling(old_id, superseded_by=new_id), and run uv run optcg-ingest embed.


MCP Tools & Prompts

Category

Name

Purpose

Query

search

Hybrid search (exact OPTCG tokens + FTS5 BM25 + sqlite-vec + RRF + authority/tier tie-breaking)

Query

get_rule

Look up a Comprehensive Rule by rule_id with ancestors and ordered children

Query

get_card

Look up canonical card(s) by exact card_id or fuzzy name

Query

search_cards

Filter cards by name, color, cost, trait, keyword, set_code

Query

get_card_rulings

List rulings linked to a card_id ordered by authority, judge_tier, date DESC

Curation

add_ruling

Insert anonymized curated ruling (reviewed=False), indexed immediately in FTS5

Curation

mark_ruling

Update reviewed, superseded_by (cycle-checked), and/or judge_tier

Curation

list_unreviewed_rulings

Inspect curated rulings awaiting manual approval

Interop

export_rulings

Export vetted rulings using the exact same versioned JSON schema as the CLI

Prompt

juiz

OPTCG rules judge workflow citing authority, exact IDs, conflicts, and staleness

Prompt

curar(arquivo)

Anonymized judge chat curation workflow targeting data/raw/judge_chats/<arquivo>


Connecting the MCP Server

Claude Code

Register the local stdio server with claude mcp add:

claude mcp add optcg-knowledge -- \
  /absolute/path/to/optcg-knowledge/.venv/bin/optcg-mcp \
  --db /absolute/path/to/optcg-knowledge/data/optcg.db

Or via uv:

claude mcp add optcg-knowledge -- \
  uv --directory /absolute/path/to/optcg-knowledge run optcg-mcp \
  --db /absolute/path/to/optcg-knowledge/data/optcg.db

Antigravity

Create .agents/plugins/optcg-knowledge/plugin.json:

{
  "name": "optcg-knowledge",
  "description": "Local One Piece Card Game rules, cards, FAQs, and judge rulings MCP server."
}

And .agents/plugins/optcg-knowledge/mcp_config.json:

{
  "mcpServers": {
    "optcg-knowledge": {
      "command": "/absolute/path/to/optcg-knowledge/.venv/bin/optcg-mcp",
      "args": [
        "--db",
        "/absolute/path/to/optcg-knowledge/data/optcg.db"
      ]
    }
  }
}

Option B — Global configuration

Add the optcg-knowledge entry above inside mcpServers in ~/.gemini/config/mcp_config.json.


Development & Tests

Tests run fast and 100% offline (no large embedding model downloads):

uv run ruff check
uv run pytest -v

License & Disclaimer

  • License: This project's source code and community-curated rulings under data/rulings/ are licensed under the MIT License.

  • Third-party dependency note: PDF parsing uses PyMuPDF (pymupdf), which is dual-licensed under AGPL-3.0 / commercial license. Review AGPL-3.0 obligations if you distribute bundled binaries or operate a hosted network service using PyMuPDF.

  • Disclaimer: optcg-knowledge is an unofficial, non-commercial community project and is not affiliated with, endorsed by, or sponsored by Bandai Co., Ltd., Eiichiro Oda, Shueisha, or Toei Animation. One Piece and the One Piece Card Game are trademarks and copyrights of their respective owners. This repository does not host or redistribute official Bandai PDFs or card images.

Available Tools

9 tools
add_rulingB

Add a curated OPTCG ruling (always enters with reviewed=False) and index its chunk immediately in FTS5. Authority is derived from source ('official_faq'/'errata'=2, 'judge'=3, 'community'=4). Optional judge_tier ('tier_0' | 'tier_2' | 'tier_1', precedence tier_0 > tier_2 > tier_1) is valid for source='judge'. Never pass personal names, @handles, or Discord user IDs.

Inputs: answer (required), source (required), question (required), url, +6 more. Returns: object

export_rulingsA

Export rulings in a stable, versioned JSON envelope (shared with optcg-ingest export-rulings) for downstream consumers such as optcg-engine. Defaults to reviewed, non-superseded rulings; filter optionally by card_id, since (YYYY-MM-DD), min_authority (authority <= N), and source ('official_faq'|'errata'|'judge'|'community').

Inputs: since, source, card_id, min_authority, +2 more. Returns: object

get_cardA

Look up an OPTCG card by canonical card_id (e.g. 'OP05-119', 'ST10-001', 'P-001') or by name (exact or fuzzy, ignoring punctuation differences like 'Monkey D Luffy'). Returns all matching canonical card printings/versions.

Inputs: id_or_name (required). Returns: object

get_card_rulingsA

Retrieve official FAQs, errata, and judge rulings linked to a canonical card_id (e.g. 'OP05-119'), ordered by authority ASC (1 highest .. 4 lowest), judge_tier (tier_0 > tier_2 > tier_1), then date DESC. Excludes superseded rulings by default unless include_superseded=True.

Inputs: card_id (required), include_superseded. Returns: object

get_ruleA

Retrieve a specific OPTCG Comprehensive Rule by canonical rule_id (e.g. '7-1-4' or '7-1-4-1'), including its ancestor chain and, when include_children=True, all descendant sub-rules ordered numerically.

Inputs: rule_id (required), include_children. Returns: object

list_unreviewed_rulingsA

List curated rulings pending human review (reviewed=False), ordered by authority, judge_tier (tier_0 > tier_2 > tier_1), and date DESC (default limit=20, max 100).

Inputs: limit. Returns: object

mark_rulingA

Update a ruling's reviewed status, link it as superseded_by a newer ruling_id, and/or set judge_tier ('tier_0' | 'tier_2' | 'tier_1' for source='judge'). Never deletes outdated rulings; rejects self-superseding and circular chains.

Inputs: ruling_id (required), reviewed, judge_tier, superseded_by. Returns: object

search_cardsA

Filter canonical OPTCG cards by name substring, color, exact cost, trait substring, effect/trigger keyword (e.g. '[Blocker]' or 'Rush'), and set_code (e.g. 'OP05'). Defaults to returning up to 25 matches (max 100).

Inputs: cost, name, color, limit, +3 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool targets a distinct resource or workflow: rule lookup, card lookup, card-specific rulings, hybrid search, structured card filtering, and ruling curation/export. The broad `search` tool is clearly positioned as a hybrid fallback, while `search_cards`, `get_card`, and `get_card_rulings` have specific structured purposes.

    Naming Consistency4/5

    Most tools follow a predictable snake_case verb_noun pattern (`get_rule`, `add_ruling`, `export_rulings`). Minor deviations include the bare `search` and mixed noun ordering between `get_card_rulings` and `search_cards`, but the set remains readable and consistent overall.

    Tool Count5/5

    Nine tools is well-scoped for a rules/card/ruling knowledge base, with retrieval, search, curation, review, and export all earning their place. There is no obvious bloat or thin coverage.

    Completeness4/5

    The surface covers core read paths for rules, cards, and rulings, plus a complete ruling curation lifecycle including review, supersession, and export. Minor gaps remain, such as no direct `get_ruling` by ruling_id and no explicit bulk rule/card listing beyond search/filter tools.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables coding agents to query local notes, decisions, docs, and code with hybrid retrieval (BM25 + embeddings + reranking) and get path:line citations. It provides tools like rag_query for full-corpus search and search_knowledge for project-scoped knowledge recall.
      2
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables agents to build self-hosted knowledge bases from document folders and search them via hybrid vector and keyword retrieval, with eight tools for listing, adding, deleting, and reindexing content.
      59 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents and MCP hosts to query locally indexed notes, docs, chat logs, and other files via hybrid vector/BM25 retrieval with section-level citations. Exposes tools, resources, and prompts for searching and asking over the indexed content.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents and MCP hosts to query a locally built hybrid (vector + BM25) index of scattered notes, docs, and chat logs, retrieving answers with section-level citations. It exposes 8 tools plus resources and prompts so hosts like Claude Desktop, Cursor, and Cline can search, ask, and browse the user's personal knowledge base directly.
      -