optcg-knowledge
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., "@optcg-knowledge Can OP05-119's effect target a card that can't be K.O.'d by effects?"
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.
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:
|
| Description |
|
| Official Comprehensive Rules (highest) |
|
| Official Bandai card FAQs and errata |
|
| Certified Bandai judge rulings ( |
|
| Community rulings (optional, lowest) |
Judge tiers (within
authority = 3):tier_0(highest) >tier_2(senior) >tier_1(basic). Only the role ("judge") and optionaljudge_tierare persisted—personal names, Discord handles, and user IDs are never stored.No silent deletion: outdated rulings retain
dateandrules_versionand are linked viasuperseded_by(excluded by default unlessinclude_superseded=True).Interoperability: canonical
card_id(OP05-119,ST10-001,P-001), canonicalrule_id(7-1-4-1), and versionedexport_rulingsJSON (schema_version = "1.0") are designed for downstream projects such as an externaloptcg-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 embeddingsCopy .env.example to .env if you want to customize paths or local embedding settings:
cp .env.example .envDefault 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 | errata2. Ingest Comprehensive Rules PDF (authority = 1)
uv run optcg-ingest rules data/raw/rules/rule_comprehensive.pdf3. 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,ST10Or from local JSON files in data/raw/cards/:
uv run optcg-ingest cards --source local --path data/raw/cards4. 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 embedUseful 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.jsonBy default export-rulings exports only reviewed = True, non-superseded rulings. Pass --include-superseded and/or --include-unreviewed to include them.
Judge Ruling Curation Workflow
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>
---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 canonicalcard_idsandrule_refs, applies judge tier precedence (tier_0 > tier_2 > tier_1), and callsadd_ruling(...)(entering withreviewed = False).Review pending entries via
list_unreviewed_rulings, approve viamark_ruling(ruling_id, reviewed=True), link outdated rulings viamark_ruling(old_id, superseded_by=new_id), and runuv run optcg-ingest embed.
MCP Tools & Prompts
Category | Name | Purpose |
Query |
| Hybrid search (exact OPTCG tokens + FTS5 BM25 + |
Query |
| Look up a Comprehensive Rule by |
Query |
| Look up canonical card(s) by exact |
Query |
| Filter cards by |
Query |
| List rulings linked to a |
Curation |
| Insert anonymized curated ruling ( |
Curation |
| Update |
Curation |
| Inspect curated rulings awaiting manual approval |
Interop |
| Export vetted rulings using the exact same versioned JSON schema as the CLI |
Prompt |
| OPTCG rules judge workflow citing authority, exact IDs, conflicts, and staleness |
Prompt |
| Anonymized judge chat curation workflow targeting |
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.dbOr 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.dbAntigravity
Option A — Workspace-scoped plugin (recommended for project-only use)
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 -vLicense & 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 usingPyMuPDF.Disclaimer:
optcg-knowledgeis 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 toolsadd_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
searchA
Hybrid search across OPTCG Comprehensive Rules, cards, FAQs, and judge rulings using exact-match OPTCG token detection (card IDs, rule numbers, [Keywords]), FTS5 BM25, and local sqlite-vec embeddings fused with RRF and authority tie-breaking. min_authority filters authority <= N (1=rules only, 2=rules+official_faq/errata, 3=+judge, 4=all). Superseded rulings are excluded unless include_superseded=True.
Inputs: query (required), k, doc_types, min_authority, +1 more. 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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Search your knowledge bases from any AI assistant using hybrid RAG.
Sourced public knowledge for AI agents: search and read records with evidence; moderated writes.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables 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.21MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npm1MIT
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- FlicenseNot gradedqualityAmaintenanceEnables 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.-