{
  "markdown": "# mtg-mcp\n<!-- mcp-name: io.github.nccurry/mtg-mcp -->\n\n`mtg-mcp` gives an LLM grounded Magic: The Gathering card, deck, provider, and\nstatistical evidence. The LLM makes deckbuilding decisions.\n\nThe clean-break `0.9.0` server uses stdio. It exposes 96 tools, one\ncapability resource, and no prompts. It does not migrate `0.8.x` data or tool\nschemas.\n\n## Status\n\nThe evidence-first rewrite is complete. `0.9.0` is the first stable release of\nthe new surface.\n\n| Capability | Tools | Default | Storage or writes |\n| --- | ---: | --- | --- |\n| Local decks and interchange | 28 | Yes | Local |\n| Scryfall evidence | 18 | Yes | Local cache and card data |\n| Exact statistics | 8 | Yes | No |\n| Archidekt | 23 | No | Remote |\n| Playgroup | 16 | No | Remote |\n| Commander Spellbook evidence | 3 | No | Local cache only |\n\nThe packaged acceptance run before the Spellbook addition passed 88 tool calls.\nTwo Scryfall card-data download operations are fixture-backed, Scryfall rollback\nawaits a second provider generation, and two Playgroup writes remain fixture-only\nbecause the public API has no cleanup. Commander Spellbook has its own bounded,\nread-only live check.\nSee [live acceptance](docs/llms/plcs/completed/rewrite-stabilization-cutover/LIVE_ACCEPTANCE.md).\n\n## Start the server\n\nBootstrap the repository, then run the MCP smoke test:\n\n```powershell\n.\\bootstrap.ps1\ntask smoke:mcp\n```\n\nOn Linux or macOS:\n\n```bash\n./bootstrap.sh\ntask smoke:mcp\n```\n\nBootstrap installs Mise when needed. Mise installs Task and PowerShell from\n`mise.toml` and the .NET SDK from `global.json` in an isolated tool directory.\nAfter bootstrap, run `task <command>` normally. The Taskfile invokes Mise for\n.NET; if a fresh shell cannot find Task, activate Mise or temporarily use\n`mise exec -- task <command>`.\n\nCommitted Mise and NuGet lock files keep setup repeatable. Version pins live in\n`mise.toml`, `global.json`, `Directory.Packages.props`, and `dotnet-tools.json`.\nUse `task deps:check` to inspect available updates. Use `task deps:update` only\nwhen you intend to review the related pin and lock-file changes.\n\nUse `mtg-mcp` as the MCP command. The default invocation is equivalent to:\n\n```text\nmtg-mcp --mode=local --toolsets=default\n```\n\nUse `--smoke` for a one-shot configuration check. It does not start an MCP\nsession.\n\n## Choose a mode\n\nModes control authority.\n\n| Mode | Reads | Local writes | Remote writes |\n| --- | --- | --- | --- |\n| `read-only` | Yes | No | No |\n| `local` | Yes | Yes | No |\n| `remote` | Yes | Yes | Yes |\n\n`local` is the default. Scryfall cache misses can require a local write for\npacing and evidence persistence. In `read-only`, those misses return\n`local-write-required` before HTTP.\n\nCommander Spellbook reads are available in all three modes. They never change a\ndeck or make a write request to the source. Successful responses use a short-lived\nlocal cache so repeated exact requests do not create needless provider traffic.\n\n## Choose toolsets\n\nToolsets control relevance. They do not grant authority.\n\n| Value | Result |\n| --- | --- |\n| `default` or omitted | Enable `decks`, `scryfall`, and `stats` |\n| `all` | Enable every implemented toolset |\n| `none` | Expose no tools |\n| Comma-separated list | Enable the exact named toolsets |\n\nAvailable toolsets are `decks`, `scryfall`, `stats`, `archidekt`, `playgroup`,\nand `spellbook`. Selection is fixed for the MCP session.\n\n| Profile | `read-only` | `local` | `remote` |\n| --- | ---: | ---: | ---: |\n| `default` | 32 | 54 | 54 |\n| `all` | 60 | 83 | 96 |\n| `none` | 0 | 0 | 0 |\n\nRead `mtg://server/capabilities` to inspect the active mode, toolsets, counts,\ncredential state, package version, and data-store state. Reading the resource\ndoes not contact a provider.\n\n## Configure the server\n\nPass configuration on the command line, in environment variables, or in an\noptional `mtg-mcp.json` in the working directory. Command-line values win over\nenvironment values. Environment values win over JSON.\n\n| Setting | Command line | Environment | JSON key |\n| --- | --- | --- | --- |\n| Operation mode | `--mode` | `MTGMCP__MODE` | `MODE` |\n| Toolsets | `--toolsets` | `MTGMCP__TOOLSETS` | `TOOLSETS` |\n| Data root | `--data-dir` | `MTGMCP__DATA_DIR` | `DATA_DIR` |\n| Scryfall TTL | `--scryfall-ttl-hours` | `MTGMCP__SCRYFALL_TTL_HOURS` | `SCRYFALL_TTL_HOURS` |\n| Commander Spellbook TTL | `--spellbook-ttl-minutes` | `MTGMCP__SPELLBOOK__TTL_MINUTES` | `SPELLBOOK_TTL_MINUTES` |\n\nThe default data root is the platform application-data directory under\n`mtg-mcp/v0.9`. All MCP processes that use the same root reuse `decks.db` and\n`scryfall.db`. Reads do not create the root.\n\n### Configure Archidekt\n\nUse `MTGMCP__ARCHIDEKT__USERNAME` and `MTGMCP__ARCHIDEKT__PASSWORD`, or create:\n\n```text\n~/.mtg-mcp/archidekt.json\n```\n\nThe provider origin is fixed. Authentication output never contains credentials,\naccount identity, or a credential path.\n\n### Configure Playgroup\n\nUse `MTGMCP__PLAYGROUP__API_KEY`, or create:\n\n```text\n~/.mtg-mcp/playgroup.json\n```\n\nThe file contains one `apiKey` property. The provider origin is fixed to the\nofficial public API.\n\n## Work with local decks\n\nThe `decks` toolset supports:\n\n- revisioned deck, entry, zone, category, and provider-binding changes;\n- atomic ordered batches;\n- guarded backup, restore, and delete;\n- native JSON and generic text import and export;\n- Archidekt and Moxfield manual artifacts;\n- exact Scryfall identity reconciliation; and\n- deterministic tag-rule categorization.\n\nEvery existing-deck mutation requires `expectedRevision`. The store is\nformat-neutral. Validation checks structure, not Commander legality, card\nquality, or strategic fit.\n\nUse `deck_identity_reconcile_preview` before apply. Resolution uses printing ID,\nset and collector number, Oracle ID, then exact name. It never uses fuzzy\nmatching or selects an arbitrary printing.\n\nUse `deck_category_rules_validate`, `deck_category_rules_preview`, and\n`deck_category_rules_apply` to evaluate caller-owned tag rules. Rules can be\ninline or use the transparent `common-v1` preset. The MCP does not decide what a\ncategory means.\n\n## Import and export decks\n\nUse `deck_interchange_formats` to inspect preservation limits.\n\n| Format | Notes |\n| --- | --- |\n| `mtg-mcp-json-v1` | Lossless native format |\n| `generic-text-v1` | Quantity, name, zone headings, and printing hints |\n| `archidekt-text-v1` | Manual import plus native/category companions |\n| `moxfield-bulk-edit-v1` | Bulk Edit text plus native/tag companions |\n\nProvider artifacts do not perform network automation. Excluded entries remain\nin the native companion and are omitted from provider text.\n\n## Query Scryfall\n\nThe `scryfall` toolset supports search, exact card lookup, collection lookup,\nprints, rulings, sets, catalogs, autocomplete, bulk metadata, tag evidence,\nimmutable snapshots, and explicit card-data download operations.\n\nThe local card-data store contains All Cards, Rulings, Oracle Tags, and Art\nTags. Card-data downloads are explicit. They never run at startup or in the\nbackground.\n\nFreshness policies are `default`, `cache-only`, and `refresh`. The default TTL\nis 24 hours. Immutable snapshots do not expire.\n\n`scryfall_card_collection` accepts 150 ordered lookup rows. It uses local card-data\nhits first, deduplicates provider misses, and sends provider batches of at most\n75. Results use stable cursor pagination.\n\nArbitrary Scryfall queries remain provider-authoritative. The cache reuses only\nthe exact same request. Card facts and community tags remain separate evidence\nclasses.\n\n## Read Commander Spellbook evidence\n\nEnable the `spellbook` toolset for three source-evidence tools:\n\n- `spellbook_variant_search` returns one bounded page for an exact Commander\n  Spellbook query.\n- `spellbook_variant_get` returns one exact source variant by ID.\n- `spellbook_deck_combos_find` sends only the `commander` and `main` entries\n  from one exact saved deck revision, then reports the entries it skipped.\n\nThe tools preserve Commander Spellbook JSON and name the source, request,\nretrieval time, cache state, checksum, and limits. They do not rank results,\ninfer card roles, or recommend a combo or card change. The cache lasts 15\nminutes by default; configure it with a whole number from 1 through 1,440\nminutes.\n\n## Calculate exact statistics\n\nThe `stats` toolset provides eight read-only tools for:\n\n- univariate and multivariate hypergeometric probability;\n- probability-by-turn tables;\n- caller-defined mana-source availability;\n- package and combo assembly;\n- explicit mulligan schedules;\n- minimum-copy and minimum-source solving; and\n- deterministic deck composition summaries.\n\nEvery probability returns an exact reduced fraction and a stable decimal. The\ncaller supplies the population, groups, turn draws, mana capabilities, and keep\nrules. The MCP does not infer legality, roles, or whether a result is good.\n\nDeck-backed statistics can select entries by entry ID, zone name, or category\nID. This lets an LLM use existing Archidekt groups or deterministic categories\nwithout hiding the selected cards.\n\n## Synchronize Archidekt\n\nEnable the `archidekt` toolset. Use `remote` mode for remote writes.\n\nThe adapter supports owned deck list/get/create/delete, pull, push, diff,\nfolders, and named snapshots. Apply operations require current revisions,\nfingerprints, and preview evidence. The MCP never chooses a conflict winner.\n\nRequests start at least two seconds apart per configured account. The adapter\nallows at most 30 starts in 60 seconds and 150 requests per tool invocation.\nIt stops on `403` and `429`. Ambiguous mutations are not retried.\n\nArchidekt may renumber category positions. Content equality therefore compares\ncategory identity, membership, flags, and primary assignment, not the\nprovider-controlled numeric rank.\n\n## Read Playgroup evidence\n\nEnable the `playgroup` toolset. It exposes the pinned Public API 1.0.0 surface.\nAll modes include 14 safe read tools. `remote` adds two write tools.\n\nResults preserve provider JSON and include operation, API version, retrieval\ntime, checksums, and limitations. The adapter does not rank decks or infer\nquality.\n\nRequest starts are at least 250 milliseconds apart. Reads have bounded retry.\nWrites are single-attempt. Live acceptance does not invoke writes because the\npublic API provides no cleanup operation.\n\n## Evidence and safety\n\nThe server keeps these output classes distinct:\n\n- provider facts;\n- provider evidence;\n- exact derivations;\n- parser classifications;\n- heuristics; and\n- sampled estimates.\n\nStable `0.9.0` contains no advisor prompts, intent inference, weak-card\njudgments, replacement recommendations, blended quality scores, or strategic\nsimulation. Deferred work is listed in [Potential Features](docs/potential-features.md).\n\n## Develop and verify\n\nUse Task as the command menu:\n\n```bash\ntask --list\ntask lint\ntask test\ntask surface:report\ntask coverage\ntask pack\ntask smoke:process\ntask smoke:mcp\ntask release:tool-smoke\n```\n\nNormal tests are deterministic and offline. Live tests require explicit opt-in.\nEach production assembly must maintain at least 90 percent line coverage.\n\n## Architecture\n\n| Project | Ownership |\n| --- | --- |\n| `MtgMcp.Core` | Provider-neutral contracts and evidence |\n| `MtgMcp.Decks` | Local SQLite decks and interchange |\n| `MtgMcp.Scryfall` | Official transport, card data, snapshots, and pacing |\n| `MtgMcp.Archidekt` | Observed provider contract and synchronization |\n| `MtgMcp.Playgroup` | Pinned official API evidence |\n| `MtgMcp.Spellbook` | Bounded Commander Spellbook source evidence and cache |\n| `MtgMcp.Statistics` | BCL-only exact calculations |\n| `MtgMcp.App` | MCP host, configuration, composition, and schemas |\n\nRead [North Star](docs/north-star.md), [Design Goals](docs/design-goals.md), and\nthe [rewrite guide](docs/rewrite-guide.md) for durable constraints.\n\n## License\n\nLicensed under the [GNU Affero General Public License v3.0 or later](LICENSE).\n",
  "bytes": 11951,
  "sha": "53bca4879230d05e39bb16d420125aa810efbf9c87fbdb1b2acd9cf8fdb083b8",
  "repo_slug": "nccurry/mtg-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nccurry_mtg_mcp_db5f56a8/readme"
}