jaml-mcp

MCP server for Balatro seed search and analysis using MotelyJAML (motely-wasm-compat). Deploys cleanly on Vercel (HTTP MCP) or runs locally over stdio (Claude Desktop, VS Code, Copilot).

Tests

pnpm install
pnpm test

Runs Vitest against motely-wasm-compat: boot, getVersion, loadJaml, presence of startRandomSearchFromJaml, and a small searchSeeds integration sample. CI runs the same on push/PR (.github/workflows/test.yml).

Tools

| Tool | Description | |------|-------------| | search_seeds | Random search up to 1M seeds against JAML or Jummy; returns JSON + MCP App UI in supported hosts | | analyze_seed | Full ante-by-ante breakdown for one seed | | validate_jaml | MotelyWasmHost.loadJaml — rejects invalid JAML | | get_version | Engine version string |

JAML and Jummy

• JAML must be JSON that Motely accepts (canonical enum names as in jaml.schema.json / Motely docs). The server does not rewrite or “fix” casing in JS.
• Jummy (jummy field) is compiled only by MotelyWasmHost.compileJummy in WASM — not by a second YAML parser in this repo.

Example Jummy-powered search

Use search_seeds with jummy:

{
  "jummy": "what: blueprint in ante 1\nwhere: deck red, stake white",
  "seed_count": 50000
}

MCP Apps (inline UI)

search_seeds registers an MCP Apps extension (Model Context Protocol Apps):

• Resource: ui://jaml-mcp/jaml-search-app.html — single-file bundle (text/html;profile=mcp-app)
• View: React 19 + Vercel json-render — generative UI catalog (Stack, StatsBlock, SeedRow, Button, Text) so you can evolve layouts from structured JSON
• Hosts: Claude, ChatGPT, VS Code, and others that negotiate the Apps extension — behavior falls back to plain JSON text where UI is not available

Build (UI + CLI)

The server reads mcp-ui/dist/jaml-search-app.html at runtime and runs the compiled CLI from dist/. Build before deploy or running pnpm start (artifacts are gitignored by default):

pnpm install
pnpm run build

pnpm run build runs build:mcp-ui (Vite) and build:cli (tsc → dist/). UI only: pnpm run build:mcp-ui. Vercel: set Build Command to pnpm run build (or at least pnpm run build:mcp-ui) so the HTML exists when the function cold-starts. vercel.json includes mcp-ui/dist/** for api/server.ts.

Local MCP (stdio)

pnpm run build
pnpm start

Development without compiling: pnpm dev (runs tsx cli.ts).

npm install / global CLI

After pnpm run build, jaml-mcp points at dist/cli.js (no tsx required). Publishing runs prepack → full build. Install globally with npm install -g jaml-mcp once the package is on the registry, or npm pack / pnpm link from a clone.

HTTP MCP on Vercel

Endpoint: https://<deployment>.vercel.app/mcp

Optional: set MCP_API_KEY and send Authorization: Bearer <key>.

Public demo API

• POST /api/search — body { "jaml": "<json string>", "seed_count": 100000 }

JAML format

Filters are JSON objects (same shape as Motely JAML-on-disk, expressed as JSON). Example:

{
  "deck": "Red",
  "stake": "White",
  "must": [{ "joker": "Blueprint", "antes": [1], "sources": { "shopItems": [0, 1] } }]
}

License

MIT