scry-terminal 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pigar Mahdar
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,335 @@
1
+ Metadata-Version: 2.4
2
+ Name: scry-terminal
3
+ Version: 1.0.0
4
+ Summary: Instant, offline Magic: The Gathering card lookups and deck diagnostics from your terminal.
5
+ Author: Pigar Mahdar
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/pigarmahdar/Scry-Terminal
8
+ Project-URL: Repository, https://github.com/pigarmahdar/Scry-Terminal.git
9
+ Project-URL: Issues, https://github.com/pigarmahdar/Scry-Terminal/issues
10
+ Keywords: magic-the-gathering,mtg,scryfall,cli,mcp,model-context-protocol,deckbuilding,commander,terminal
11
+ Classifier: Development Status :: 5 - Production/Stable
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: End Users/Desktop
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Games/Entertainment
23
+ Classifier: Topic :: Utilities
24
+ Requires-Python: >=3.9
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Dynamic: license-file
28
+
29
+ # Scry Terminal
30
+
31
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
32
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
33
+ [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-8A2BE2.svg)](https://modelcontextprotocol.io)
34
+ [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
35
+
36
+ **Instant Magic: The Gathering card lookups from your terminal. No API key, no rate limits, no internet.**
37
+
38
+ `scry` searches the full Scryfall Oracle database (~38,000 cards) from a local copy on your disk. Results come back in **~50 ms** — fast enough to fire a dozen lookups while you're mid-deckbuild — and the tool works completely offline once installed.
39
+
40
+ It's built for two audiences at once:
41
+
42
+ - **Players** — clean, colour-coded answers for deckbuilding, theorycrafting, and kitchen-table rules questions.
43
+ - **AI agents & scripts** — pipe it and it becomes a JSONL data source: stable fields, warnings on stderr, pure data on stdout. See [AGENT.md](AGENT.md).
44
+
45
+ For MTG brewers, script writers, and AI assistants who want instant, distraction-free answers, Scry Terminal is an offline diagnostic engine and CLI toolkit that validates card rules, deck architecture, and mana math in sub-50ms—without web bloat, rate limits, or context switching.
46
+
47
+ ---
48
+
49
+ [Features](#what-it-can-do) •
50
+ [Install](#install) •
51
+ [Try It](#try-it) •
52
+ [Command Reference](#command-reference) •
53
+ [Deck Diagnostics](#deck-diagnostics--architecture-the-deck-linter) •
54
+ [AI Agents & MCP](#for-developers-agents-and-scripts) •
55
+ [How It Works](#how-it-works) •
56
+ [Contributing](#contributing) •
57
+ [License](#license)
58
+
59
+ ---
60
+
61
+ ## Install
62
+
63
+ Requires Python 3.9+ and ~200 MB for the card cache (downloaded separately — installing the package itself fetches ~0 bytes of card data).
64
+
65
+ ### Recommended: pipx (isolated CLI)
66
+
67
+ ```shell
68
+ pipx install scry-terminal
69
+ scry update # one-time: downloads the Oracle cache & builds the search index
70
+ ```
71
+
72
+ ### Alternative: pip
73
+
74
+ ```shell
75
+ pip install scry-terminal
76
+ scry update
77
+ ```
78
+
79
+ Both `scry` and `scryfall` (backwards-compatible alias) are placed on your PATH automatically.
80
+
81
+ ### Developer: git clone
82
+
83
+ ```shell
84
+ git clone https://github.com/pigarmahdar/Scry-Terminal.git
85
+ cd Scry-Terminal
86
+ pip install -e .
87
+ scry update
88
+ ```
89
+
90
+ ### Packaging & Distribution Roadmap
91
+
92
+ - **pip / pipx**: `pip install scry-terminal` ✅ (this release)
93
+ - **Homebrew tap** *(Planned)*: `brew tap pigarmahdar/tap && brew install scry`
94
+ - **Pre-compiled standalone binaries** *(Planned)*: Self-contained single binaries distributed via GitHub Releases.
95
+
96
+ > **Offline / Manual Cache Setup**: If you prefer not to use `scry update`, you can fetch the dataset directly:
97
+ > ```shell
98
+ > mkdir -p ~/.hermes/scryfall
99
+ > curl -o ~/.hermes/scryfall/oracle-cards.jsonl \
100
+ > "https://data.scryfall.io/oracle-cards/oracle-cards.jsonl"
101
+ > ```
102
+
103
+ ## Try it
104
+
105
+ ```shell
106
+ scry name "Sol Ring" # every printing of a card
107
+ scry fuzzy "sol rng" # typos and partial names just work
108
+ scry oracle "Sol Ring" # just the rules text
109
+ scry text "create a treasure token" # find cards that do a thing
110
+ scry type "enchantment" --commander WG # browse by type, colour identity
111
+ scry cmc <=2 --legal commander --limit 5 # cheap commander staples
112
+ scry image "Sol Ring" # high-res art to your Desktop
113
+ scry random # a random card
114
+ scry deck "my_deck.txt" # instant mana, engine, posture & vintage audit
115
+ ```
116
+
117
+ Piped output flips to JSONL automatically:
118
+
119
+ ```shell
120
+ scry search "counter target spell" --limit 500 \
121
+ | jq -r 'select(.legalities.modern=="legal") | .name'
122
+ ```
123
+
124
+ ## What it can do
125
+
126
+ | | |
127
+ |---|---|
128
+ | **Search** | name, oracle text, type line, colour identity, mana value, keyword, or all of the above at once |
129
+ | **Fuzzy** | `fuzzy "thragtuskk"` → Thragtusk; misspellings, partials, and near-misses resolve to the right card |
130
+ | **Deck** | `deck <file>` or `pbpaste \| scry deck`: Karsten mana balance, table posture, engine fuel/payoff ratios, vintage heritage, legality |
131
+ | **Prices** | USD, EUR, and MTGO tickets with foil variants, sorted most-expensive-first |
132
+ | **Images** | Download PNG/JPG art straight to disk (`--size`, `--out`, `--border`) |
133
+ | **Filters** | `--commander WUBRG` colour identity, `--legal <format>` for 15+ formats, `--sort name/cmc/price` |
134
+ | **Offline** | Every search runs against your local cache — no network, no API key, no rate limit |
135
+ | **Agent-ready** | Auto-detects pipes and emits compact JSONL; human-readable colour output in a terminal |
136
+
137
+ ## For developers, agents, and scripts
138
+
139
+ The output format is chosen for you:
140
+
141
+ | Situation | Output |
142
+ |---|---|
143
+ | Typed in a terminal | Styled, colour-coded text |
144
+ | Piped or redirected (`\| jq`, scripts, LLM tools) | Compact **JSONL**, one card per line |
145
+ | `--json` / `--csv` / `--tsv` / `SCRY_FORMAT=json` | Explicit override |
146
+
147
+ Stdout is **always pure data** — warnings and progress go to stderr, so parsing never breaks. Every record uses the same stable fields (`name`, `oracle_text`, `color_identity`, `legalities`, `prices`, `image_uris`, …), roughly half the tokens of the styled output. Commands that normally prompt (`fuzzy`, `image`) return structured objects instead, so they never hang a pipeline.
148
+
149
+ **Agents:** the repo ships [AGENT.md](AGENT.md) — a compact instruction set written for models, covering the output contract, record schema, and rules against hallucinating card text. Point your system prompt at it and tell the model to prefer it over its own memory.
150
+
151
+ ```text
152
+ You have access to the `scry` CLI (Scry Terminal) for Magic: The Gathering card data.
153
+ Follow AGENT.md exactly. Prefer it over your memory for card text,
154
+ legality, or prices.
155
+ ```
156
+
157
+ Works out of the box with Open WebUI, Claude Code, Ollama, LM Studio, Antigravity, or any tool that can run a shell command.
158
+
159
+ ### Model Context Protocol (MCP) Server
160
+
161
+ `scry` includes a built-in MCP server running over stdio with **zero external dependencies**:
162
+
163
+ ```shell
164
+ scry mcp
165
+ ```
166
+
167
+ Add it to your MCP client configuration (Claude Desktop, Cursor, Windsurf, Claude Code):
168
+
169
+ **`claude_desktop_config.json`**:
170
+ ```json
171
+ {
172
+ "mcpServers": {
173
+ "scry": {
174
+ "command": "/path/to/scry",
175
+ "args": ["mcp"]
176
+ }
177
+ }
178
+ }
179
+ ```
180
+
181
+ Exposed native tools:
182
+ - `scryfall_oracle`: Canonical card text, mana cost, and types (token-efficient).
183
+ - `scryfall_search`: Search cards with format legality (`legal`), commander color identity (`commander`), and sorting.
184
+ - `scryfall_fuzzy`: Typo-tolerant card name resolution.
185
+ - `scryfall_deck`: Full 4-pillar decklist audit and format legality verification.
186
+ - `scryfall_price`: Market pricing in USD, EUR, and TIX.
187
+ - `scryfall_doctor`: Local SQLite index and cache health check.
188
+
189
+ ## Command reference
190
+
191
+ | Command | Description | Example |
192
+ |---|---|---|
193
+ | `name` | Search by card name (partial match) | `scry name "Gilded Drake"` |
194
+ | `text` | Search by oracle text | `scry text "destroy all creatures"` |
195
+ | `type` | Search by type line | `scry type "enchantment"` |
196
+ | `color` | Search by colour identity (WUBRG letters) | `scry color WG` |
197
+ | `cmc` | Search by mana value (`=`, `<=`, `>=`) | `scry cmc <=3` |
198
+ | `keyword` | Search by keyword ability | `scry keyword flash` |
199
+ | `search` | General search across name + text + type | `scry search "2 mana green creature"` |
200
+ | `oracle` | Canonical card text only, deduplicated across printings | `scry oracle "Sol Ring"` |
201
+ | `fuzzy` | Fuzzy name search (handles typos, partial names) | `scry fuzzy "sol rng"` |
202
+ | `price` | Search by name with market prices | `scry price "Rhystic Study"` |
203
+ | `image` | Download a card's image (PNG to Desktop) | `scry image "Sol Ring"` |
204
+ | `deck` | Static analysis & diagnostic audit across 4 pillars | `scry deck deck.txt` |
205
+ | `random` | Get a random card | `scry random` |
206
+ | `mcp` | Start Model Context Protocol server on stdio | `scry mcp` |
207
+ | `update` | Update the Oracle cache from Scryfall | `scry update` |
208
+ | `reindex` | Rebuild the local search index | `scry reindex` |
209
+ | `doctor` | Report index health and staleness | `scry doctor` |
210
+
211
+ ### Flags
212
+
213
+ | Flag | Description |
214
+ |---|---|
215
+ | `--limit N` | Max results (default: 10) |
216
+ | `--commander WUBRG` | Cards whose colour identity fits within these colours |
217
+ | `--commander-card <name>` | Explicit commander card name override (for `deck`) |
218
+ | `--legal <format>` | Only cards legal in a format (default `commander` for `deck`) |
219
+ | `--exact` | Exact name match (for `name`) |
220
+ | `--sort <field>` | Sort by `name`, `cmc`, or `price` |
221
+ | `--size <s\|n\|l\|png>` | Image size for `image` (default: png) |
222
+ | `--out <dir>` | Output directory for `image` (default: `~/Desktop`) |
223
+ | `--border <color>` | Prefer a specific border colour for `image` |
224
+ | `--format <fmt>` | `pretty`, `json`, `jsonl`, `csv`, `tsv` |
225
+ | `--json` / `--jsonl` / `--csv` / `--tsv` | Shorthands for `--format` |
226
+ | `--pretty` | Force human-styled output even when piped |
227
+ | `--no-db` | Bypass the search index (debugging) |
228
+ | `--help` / `-h` | Display usage and options text |
229
+
230
+ ## Deck Diagnostics & Architecture (The Deck Linter)
231
+
232
+ ```shell
233
+ scry deck deck.txt # audit decklist file
234
+ cat deck.txt | scry deck # audit from pipe
235
+ pbpaste | scry deck # audit macOS clipboard directly
236
+ scry deck deck.txt --json # machine-readable diagnostic schema
237
+ ```
238
+
239
+ ### Why We Made It
240
+ Web deckbuilders (Moxfield, Archidekt) already excel at visual drag-and-drop card grids and image galleries. We did not build `scry deck` to be an inferior ASCII clone of a web browser.
241
+
242
+ Instead, it is designed as a **Deck Architecture & Health Linter** (`cargo check` / `eslint` for Magic: The Gathering):
243
+ - **Instant Terminal Speed (<20 ms):** Run instant sanity checks while editing `.txt` decklists in VS Code or Vim without context switching.
244
+ - **100% Offline & Private:** Validates and audits full 100-card decks using local SQLite batch queries with zero external network calls.
245
+ - **Respect for Diverse Wincons:** Rather than grading every deck against a rigid, hyper-efficient cEDH aggro template, it analyzes a deck against **its own internal engine and playstyle** (Group Hug, alternate wincons, mill, or 90s retro themes).
246
+
247
+ ### The 4 Diagnostic Pillars
248
+ 1. **Vitals & Mana Architecture:** Compares Frank Karsten colored mana production (lands and rocks) against colored pip demands. Detects early-turn multi-pip hurdles (e.g. `{U}{U}` at CMC 2 Counterspell with insufficient blue sources) and measures Turn 1–3 playables density.
249
+ 2. **Table Dynamic & Political Posture:** Quantifies table influence by parsing card targeting into **Self-Focused** (advancing own board), **Targeted** (adversarial removal/interaction), and **Symmetrical** (table-wide effects, group hug, sweepers).
250
+ 3. **Engine Balance ("Fuel vs. Payoff"):** Models universal action generators (draw, sacrifice, tokens, counters, color alteration) against reward listeners (`"Whenever you..."`). Flags fuel chokes or payoff deficits.
251
+ 4. **Deck Heritage & Vintage Spectrum:** Partitions cards into **Classic (Pre-2003)**, **Modern Frame (2003–2014)**, and **Contemporary (2015+)**, identifying the deck's Heritage Anchor Card and celebrating retro brews.
252
+
253
+ ### Superpower for LLMs & AI Agents
254
+ When AI assistants (Claude Code, Cursor, ChatGPT) are asked to tune a deck or suggest cuts/adds, models routinely hallucinate card legality, mana values, and curve math, or exhaust web rate limits across 100 API calls.
255
+
256
+ With `scry deck deck.txt --json` (or the native `scryfall_deck` MCP tool), the agent receives an authoritative, ground-truth architectural diagnostic in **one single tool call (<20 ms)**. The agent can then reason with 100% mathematical accuracy without guessing.
257
+
258
+ ## How it works
259
+
260
+ A local **SQLite index** built from the Oracle cache answers queries with full-text search, replacing the old approach of parsing all 38,700 cards on every call:
261
+
262
+ | | Before | Now |
263
+ |---|---|---|
264
+ | Typical lookup | ~1.6 s | **43–58 ms** |
265
+ | Peak memory per call | ~920 MB | **22–39 MB** |
266
+
267
+ The index (~102 MB) lives beside the cache and is **derived data** — delete it and it rebuilds on the next query. It builds itself the first time you search after installing or running `scry update`; `scry doctor` reports its health, and `scry reindex` forces a rebuild. If SQLite or its full-text extension is unavailable, or the index is stale or corrupt, the tool silently falls back to a full-file scan — you get yesterday's speed, never a wrong answer. Searching is offline; only `update`, `image`, and `fuzzy` resolution need internet.
268
+
269
+ ## Updating the cache
270
+
271
+ Scryfall refreshes its bulk data every 12–24 hours; prices are freshest after an update. Any of these work:
272
+
273
+ ```shell
274
+ scry update # built-in updater (~200 MB)
275
+ ./update_cache.sh # curl + gunzip wrapper for cron
276
+ 0 3 1 * * /path/to/scry update # crontab example: 1st of the month
277
+ ```
278
+
279
+ The updater backs up your existing cache and restores it automatically if anything fails. Note that prices reflect the last update — treat them as approximate.
280
+
281
+ ## Development
282
+
283
+ Two test gates run from the repo root:
284
+
285
+ ```shell
286
+ python3 tests/parity.py # 221 checks: index results == full-scan results, ordered
287
+ python3 tests/cli_golden.py # 22 cases: CLI stdout/stderr/exit byte-identical to baseline
288
+ ```
289
+
290
+ `parity.py` proves the SQLite path and the legacy full-scan path return the same cards in the same order. `cli_golden.py` replays a recorded baseline of real invocations and diffs stdout, stderr, and exit codes byte-for-byte.
291
+
292
+ ### Project layout
293
+
294
+ ```
295
+ scry # primary executable shim
296
+ scryfall # backwards-compatibility symlink -> scry
297
+ scry_cli/ # implementation package
298
+ state.py # shared state: paths, output mode, query state
299
+ project.py # slim_card/text_card projections + output emitters
300
+ store.py # SQLite sidecar: build/status/open, query helpers
301
+ search.py # search_* functions + filters/sort
302
+ api.py # Scryfall HTTP API + offline name resolution
303
+ display.py # pretty-mode rendering + image download
304
+ cli.py # argument parsing, command routing, main()
305
+ tests/
306
+ test_deck.py # unit tests for decklist parsing & diagnostics
307
+ test_mcp.py # MCP protocol & tool execution tests
308
+ parity.py # index-vs-full-scan parity gate
309
+ cli_golden.py # byte-identical CLI baseline gate
310
+ ```
311
+
312
+ Imports only point downward: `state → project → store → search → api/display → cli`. `state.py` is the only module allowed to hold mutable state; everything else reads and writes `state.<NAME>` attribute access so every module sees one object.
313
+
314
+ ## Contributing
315
+
316
+ Contributions, bug reports, and pull requests are welcome!
317
+
318
+ Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on code style (Ruff), architectural constraints (downward imports), and running the test gates.
319
+
320
+ ## Data source and Disclaimers
321
+
322
+ Card data comes from [Scryfall](https://scryfall.com), the open MTG card database (~38,000 unique cards).
323
+
324
+ **Scry Terminal is an unofficial, community-made tool.** It is not produced, endorsed, supported, or affiliated with Scryfall LLC or Wizards of the Coast.
325
+ - Magic: The Gathering is a trademark and copyright of Wizards of the Coast LLC, a subsidiary of Hasbro, Inc.
326
+ - Card data and imagery are subject to Wizards of the Coast's Fan Content Policy.
327
+ - Scryfall bulk data is provided under [Scryfall's API Guidelines and Terms](https://scryfall.com/docs/api).
328
+
329
+ ## License
330
+
331
+ MIT License. See [LICENSE](LICENSE) for details.
332
+
333
+ ---
334
+
335
+ *Built as part of [Kwain.gg](https://kwain.gg/) — a project about generosity, attention, and play.*
@@ -0,0 +1,307 @@
1
+ # Scry Terminal
2
+
3
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
4
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
5
+ [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-8A2BE2.svg)](https://modelcontextprotocol.io)
6
+ [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
7
+
8
+ **Instant Magic: The Gathering card lookups from your terminal. No API key, no rate limits, no internet.**
9
+
10
+ `scry` searches the full Scryfall Oracle database (~38,000 cards) from a local copy on your disk. Results come back in **~50 ms** — fast enough to fire a dozen lookups while you're mid-deckbuild — and the tool works completely offline once installed.
11
+
12
+ It's built for two audiences at once:
13
+
14
+ - **Players** — clean, colour-coded answers for deckbuilding, theorycrafting, and kitchen-table rules questions.
15
+ - **AI agents & scripts** — pipe it and it becomes a JSONL data source: stable fields, warnings on stderr, pure data on stdout. See [AGENT.md](AGENT.md).
16
+
17
+ For MTG brewers, script writers, and AI assistants who want instant, distraction-free answers, Scry Terminal is an offline diagnostic engine and CLI toolkit that validates card rules, deck architecture, and mana math in sub-50ms—without web bloat, rate limits, or context switching.
18
+
19
+ ---
20
+
21
+ [Features](#what-it-can-do) •
22
+ [Install](#install) •
23
+ [Try It](#try-it) •
24
+ [Command Reference](#command-reference) •
25
+ [Deck Diagnostics](#deck-diagnostics--architecture-the-deck-linter) •
26
+ [AI Agents & MCP](#for-developers-agents-and-scripts) •
27
+ [How It Works](#how-it-works) •
28
+ [Contributing](#contributing) •
29
+ [License](#license)
30
+
31
+ ---
32
+
33
+ ## Install
34
+
35
+ Requires Python 3.9+ and ~200 MB for the card cache (downloaded separately — installing the package itself fetches ~0 bytes of card data).
36
+
37
+ ### Recommended: pipx (isolated CLI)
38
+
39
+ ```shell
40
+ pipx install scry-terminal
41
+ scry update # one-time: downloads the Oracle cache & builds the search index
42
+ ```
43
+
44
+ ### Alternative: pip
45
+
46
+ ```shell
47
+ pip install scry-terminal
48
+ scry update
49
+ ```
50
+
51
+ Both `scry` and `scryfall` (backwards-compatible alias) are placed on your PATH automatically.
52
+
53
+ ### Developer: git clone
54
+
55
+ ```shell
56
+ git clone https://github.com/pigarmahdar/Scry-Terminal.git
57
+ cd Scry-Terminal
58
+ pip install -e .
59
+ scry update
60
+ ```
61
+
62
+ ### Packaging & Distribution Roadmap
63
+
64
+ - **pip / pipx**: `pip install scry-terminal` ✅ (this release)
65
+ - **Homebrew tap** *(Planned)*: `brew tap pigarmahdar/tap && brew install scry`
66
+ - **Pre-compiled standalone binaries** *(Planned)*: Self-contained single binaries distributed via GitHub Releases.
67
+
68
+ > **Offline / Manual Cache Setup**: If you prefer not to use `scry update`, you can fetch the dataset directly:
69
+ > ```shell
70
+ > mkdir -p ~/.hermes/scryfall
71
+ > curl -o ~/.hermes/scryfall/oracle-cards.jsonl \
72
+ > "https://data.scryfall.io/oracle-cards/oracle-cards.jsonl"
73
+ > ```
74
+
75
+ ## Try it
76
+
77
+ ```shell
78
+ scry name "Sol Ring" # every printing of a card
79
+ scry fuzzy "sol rng" # typos and partial names just work
80
+ scry oracle "Sol Ring" # just the rules text
81
+ scry text "create a treasure token" # find cards that do a thing
82
+ scry type "enchantment" --commander WG # browse by type, colour identity
83
+ scry cmc <=2 --legal commander --limit 5 # cheap commander staples
84
+ scry image "Sol Ring" # high-res art to your Desktop
85
+ scry random # a random card
86
+ scry deck "my_deck.txt" # instant mana, engine, posture & vintage audit
87
+ ```
88
+
89
+ Piped output flips to JSONL automatically:
90
+
91
+ ```shell
92
+ scry search "counter target spell" --limit 500 \
93
+ | jq -r 'select(.legalities.modern=="legal") | .name'
94
+ ```
95
+
96
+ ## What it can do
97
+
98
+ | | |
99
+ |---|---|
100
+ | **Search** | name, oracle text, type line, colour identity, mana value, keyword, or all of the above at once |
101
+ | **Fuzzy** | `fuzzy "thragtuskk"` → Thragtusk; misspellings, partials, and near-misses resolve to the right card |
102
+ | **Deck** | `deck <file>` or `pbpaste \| scry deck`: Karsten mana balance, table posture, engine fuel/payoff ratios, vintage heritage, legality |
103
+ | **Prices** | USD, EUR, and MTGO tickets with foil variants, sorted most-expensive-first |
104
+ | **Images** | Download PNG/JPG art straight to disk (`--size`, `--out`, `--border`) |
105
+ | **Filters** | `--commander WUBRG` colour identity, `--legal <format>` for 15+ formats, `--sort name/cmc/price` |
106
+ | **Offline** | Every search runs against your local cache — no network, no API key, no rate limit |
107
+ | **Agent-ready** | Auto-detects pipes and emits compact JSONL; human-readable colour output in a terminal |
108
+
109
+ ## For developers, agents, and scripts
110
+
111
+ The output format is chosen for you:
112
+
113
+ | Situation | Output |
114
+ |---|---|
115
+ | Typed in a terminal | Styled, colour-coded text |
116
+ | Piped or redirected (`\| jq`, scripts, LLM tools) | Compact **JSONL**, one card per line |
117
+ | `--json` / `--csv` / `--tsv` / `SCRY_FORMAT=json` | Explicit override |
118
+
119
+ Stdout is **always pure data** — warnings and progress go to stderr, so parsing never breaks. Every record uses the same stable fields (`name`, `oracle_text`, `color_identity`, `legalities`, `prices`, `image_uris`, …), roughly half the tokens of the styled output. Commands that normally prompt (`fuzzy`, `image`) return structured objects instead, so they never hang a pipeline.
120
+
121
+ **Agents:** the repo ships [AGENT.md](AGENT.md) — a compact instruction set written for models, covering the output contract, record schema, and rules against hallucinating card text. Point your system prompt at it and tell the model to prefer it over its own memory.
122
+
123
+ ```text
124
+ You have access to the `scry` CLI (Scry Terminal) for Magic: The Gathering card data.
125
+ Follow AGENT.md exactly. Prefer it over your memory for card text,
126
+ legality, or prices.
127
+ ```
128
+
129
+ Works out of the box with Open WebUI, Claude Code, Ollama, LM Studio, Antigravity, or any tool that can run a shell command.
130
+
131
+ ### Model Context Protocol (MCP) Server
132
+
133
+ `scry` includes a built-in MCP server running over stdio with **zero external dependencies**:
134
+
135
+ ```shell
136
+ scry mcp
137
+ ```
138
+
139
+ Add it to your MCP client configuration (Claude Desktop, Cursor, Windsurf, Claude Code):
140
+
141
+ **`claude_desktop_config.json`**:
142
+ ```json
143
+ {
144
+ "mcpServers": {
145
+ "scry": {
146
+ "command": "/path/to/scry",
147
+ "args": ["mcp"]
148
+ }
149
+ }
150
+ }
151
+ ```
152
+
153
+ Exposed native tools:
154
+ - `scryfall_oracle`: Canonical card text, mana cost, and types (token-efficient).
155
+ - `scryfall_search`: Search cards with format legality (`legal`), commander color identity (`commander`), and sorting.
156
+ - `scryfall_fuzzy`: Typo-tolerant card name resolution.
157
+ - `scryfall_deck`: Full 4-pillar decklist audit and format legality verification.
158
+ - `scryfall_price`: Market pricing in USD, EUR, and TIX.
159
+ - `scryfall_doctor`: Local SQLite index and cache health check.
160
+
161
+ ## Command reference
162
+
163
+ | Command | Description | Example |
164
+ |---|---|---|
165
+ | `name` | Search by card name (partial match) | `scry name "Gilded Drake"` |
166
+ | `text` | Search by oracle text | `scry text "destroy all creatures"` |
167
+ | `type` | Search by type line | `scry type "enchantment"` |
168
+ | `color` | Search by colour identity (WUBRG letters) | `scry color WG` |
169
+ | `cmc` | Search by mana value (`=`, `<=`, `>=`) | `scry cmc <=3` |
170
+ | `keyword` | Search by keyword ability | `scry keyword flash` |
171
+ | `search` | General search across name + text + type | `scry search "2 mana green creature"` |
172
+ | `oracle` | Canonical card text only, deduplicated across printings | `scry oracle "Sol Ring"` |
173
+ | `fuzzy` | Fuzzy name search (handles typos, partial names) | `scry fuzzy "sol rng"` |
174
+ | `price` | Search by name with market prices | `scry price "Rhystic Study"` |
175
+ | `image` | Download a card's image (PNG to Desktop) | `scry image "Sol Ring"` |
176
+ | `deck` | Static analysis & diagnostic audit across 4 pillars | `scry deck deck.txt` |
177
+ | `random` | Get a random card | `scry random` |
178
+ | `mcp` | Start Model Context Protocol server on stdio | `scry mcp` |
179
+ | `update` | Update the Oracle cache from Scryfall | `scry update` |
180
+ | `reindex` | Rebuild the local search index | `scry reindex` |
181
+ | `doctor` | Report index health and staleness | `scry doctor` |
182
+
183
+ ### Flags
184
+
185
+ | Flag | Description |
186
+ |---|---|
187
+ | `--limit N` | Max results (default: 10) |
188
+ | `--commander WUBRG` | Cards whose colour identity fits within these colours |
189
+ | `--commander-card <name>` | Explicit commander card name override (for `deck`) |
190
+ | `--legal <format>` | Only cards legal in a format (default `commander` for `deck`) |
191
+ | `--exact` | Exact name match (for `name`) |
192
+ | `--sort <field>` | Sort by `name`, `cmc`, or `price` |
193
+ | `--size <s\|n\|l\|png>` | Image size for `image` (default: png) |
194
+ | `--out <dir>` | Output directory for `image` (default: `~/Desktop`) |
195
+ | `--border <color>` | Prefer a specific border colour for `image` |
196
+ | `--format <fmt>` | `pretty`, `json`, `jsonl`, `csv`, `tsv` |
197
+ | `--json` / `--jsonl` / `--csv` / `--tsv` | Shorthands for `--format` |
198
+ | `--pretty` | Force human-styled output even when piped |
199
+ | `--no-db` | Bypass the search index (debugging) |
200
+ | `--help` / `-h` | Display usage and options text |
201
+
202
+ ## Deck Diagnostics & Architecture (The Deck Linter)
203
+
204
+ ```shell
205
+ scry deck deck.txt # audit decklist file
206
+ cat deck.txt | scry deck # audit from pipe
207
+ pbpaste | scry deck # audit macOS clipboard directly
208
+ scry deck deck.txt --json # machine-readable diagnostic schema
209
+ ```
210
+
211
+ ### Why We Made It
212
+ Web deckbuilders (Moxfield, Archidekt) already excel at visual drag-and-drop card grids and image galleries. We did not build `scry deck` to be an inferior ASCII clone of a web browser.
213
+
214
+ Instead, it is designed as a **Deck Architecture & Health Linter** (`cargo check` / `eslint` for Magic: The Gathering):
215
+ - **Instant Terminal Speed (<20 ms):** Run instant sanity checks while editing `.txt` decklists in VS Code or Vim without context switching.
216
+ - **100% Offline & Private:** Validates and audits full 100-card decks using local SQLite batch queries with zero external network calls.
217
+ - **Respect for Diverse Wincons:** Rather than grading every deck against a rigid, hyper-efficient cEDH aggro template, it analyzes a deck against **its own internal engine and playstyle** (Group Hug, alternate wincons, mill, or 90s retro themes).
218
+
219
+ ### The 4 Diagnostic Pillars
220
+ 1. **Vitals & Mana Architecture:** Compares Frank Karsten colored mana production (lands and rocks) against colored pip demands. Detects early-turn multi-pip hurdles (e.g. `{U}{U}` at CMC 2 Counterspell with insufficient blue sources) and measures Turn 1–3 playables density.
221
+ 2. **Table Dynamic & Political Posture:** Quantifies table influence by parsing card targeting into **Self-Focused** (advancing own board), **Targeted** (adversarial removal/interaction), and **Symmetrical** (table-wide effects, group hug, sweepers).
222
+ 3. **Engine Balance ("Fuel vs. Payoff"):** Models universal action generators (draw, sacrifice, tokens, counters, color alteration) against reward listeners (`"Whenever you..."`). Flags fuel chokes or payoff deficits.
223
+ 4. **Deck Heritage & Vintage Spectrum:** Partitions cards into **Classic (Pre-2003)**, **Modern Frame (2003–2014)**, and **Contemporary (2015+)**, identifying the deck's Heritage Anchor Card and celebrating retro brews.
224
+
225
+ ### Superpower for LLMs & AI Agents
226
+ When AI assistants (Claude Code, Cursor, ChatGPT) are asked to tune a deck or suggest cuts/adds, models routinely hallucinate card legality, mana values, and curve math, or exhaust web rate limits across 100 API calls.
227
+
228
+ With `scry deck deck.txt --json` (or the native `scryfall_deck` MCP tool), the agent receives an authoritative, ground-truth architectural diagnostic in **one single tool call (<20 ms)**. The agent can then reason with 100% mathematical accuracy without guessing.
229
+
230
+ ## How it works
231
+
232
+ A local **SQLite index** built from the Oracle cache answers queries with full-text search, replacing the old approach of parsing all 38,700 cards on every call:
233
+
234
+ | | Before | Now |
235
+ |---|---|---|
236
+ | Typical lookup | ~1.6 s | **43–58 ms** |
237
+ | Peak memory per call | ~920 MB | **22–39 MB** |
238
+
239
+ The index (~102 MB) lives beside the cache and is **derived data** — delete it and it rebuilds on the next query. It builds itself the first time you search after installing or running `scry update`; `scry doctor` reports its health, and `scry reindex` forces a rebuild. If SQLite or its full-text extension is unavailable, or the index is stale or corrupt, the tool silently falls back to a full-file scan — you get yesterday's speed, never a wrong answer. Searching is offline; only `update`, `image`, and `fuzzy` resolution need internet.
240
+
241
+ ## Updating the cache
242
+
243
+ Scryfall refreshes its bulk data every 12–24 hours; prices are freshest after an update. Any of these work:
244
+
245
+ ```shell
246
+ scry update # built-in updater (~200 MB)
247
+ ./update_cache.sh # curl + gunzip wrapper for cron
248
+ 0 3 1 * * /path/to/scry update # crontab example: 1st of the month
249
+ ```
250
+
251
+ The updater backs up your existing cache and restores it automatically if anything fails. Note that prices reflect the last update — treat them as approximate.
252
+
253
+ ## Development
254
+
255
+ Two test gates run from the repo root:
256
+
257
+ ```shell
258
+ python3 tests/parity.py # 221 checks: index results == full-scan results, ordered
259
+ python3 tests/cli_golden.py # 22 cases: CLI stdout/stderr/exit byte-identical to baseline
260
+ ```
261
+
262
+ `parity.py` proves the SQLite path and the legacy full-scan path return the same cards in the same order. `cli_golden.py` replays a recorded baseline of real invocations and diffs stdout, stderr, and exit codes byte-for-byte.
263
+
264
+ ### Project layout
265
+
266
+ ```
267
+ scry # primary executable shim
268
+ scryfall # backwards-compatibility symlink -> scry
269
+ scry_cli/ # implementation package
270
+ state.py # shared state: paths, output mode, query state
271
+ project.py # slim_card/text_card projections + output emitters
272
+ store.py # SQLite sidecar: build/status/open, query helpers
273
+ search.py # search_* functions + filters/sort
274
+ api.py # Scryfall HTTP API + offline name resolution
275
+ display.py # pretty-mode rendering + image download
276
+ cli.py # argument parsing, command routing, main()
277
+ tests/
278
+ test_deck.py # unit tests for decklist parsing & diagnostics
279
+ test_mcp.py # MCP protocol & tool execution tests
280
+ parity.py # index-vs-full-scan parity gate
281
+ cli_golden.py # byte-identical CLI baseline gate
282
+ ```
283
+
284
+ Imports only point downward: `state → project → store → search → api/display → cli`. `state.py` is the only module allowed to hold mutable state; everything else reads and writes `state.<NAME>` attribute access so every module sees one object.
285
+
286
+ ## Contributing
287
+
288
+ Contributions, bug reports, and pull requests are welcome!
289
+
290
+ Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on code style (Ruff), architectural constraints (downward imports), and running the test gates.
291
+
292
+ ## Data source and Disclaimers
293
+
294
+ Card data comes from [Scryfall](https://scryfall.com), the open MTG card database (~38,000 unique cards).
295
+
296
+ **Scry Terminal is an unofficial, community-made tool.** It is not produced, endorsed, supported, or affiliated with Scryfall LLC or Wizards of the Coast.
297
+ - Magic: The Gathering is a trademark and copyright of Wizards of the Coast LLC, a subsidiary of Hasbro, Inc.
298
+ - Card data and imagery are subject to Wizards of the Coast's Fan Content Policy.
299
+ - Scryfall bulk data is provided under [Scryfall's API Guidelines and Terms](https://scryfall.com/docs/api).
300
+
301
+ ## License
302
+
303
+ MIT License. See [LICENSE](LICENSE) for details.
304
+
305
+ ---
306
+
307
+ *Built as part of [Kwain.gg](https://kwain.gg/) — a project about generosity, attention, and play.*