{
  "markdown": "# tabnas/mcp\n\nThe tabnas agent tooling: **one TypeScript codebase, two front-ends** —\nan [MCP](https://modelcontextprotocol.io) server (stdio) and the unified\n`tabnas` CLI — sharing a single core (`ts/src/core.ts`) so the two can\nnever disagree. For each operation the CLI's `--json` output and the MCP\ntool result are **byte-identical**, and the test suite holds them to it.\n\nThe website page for this package — per-client setup, the tool contracts, the hosted endpoint's bounds: **[tabnas.dev/mcp](https://tabnas.dev/mcp/)**.\n\nPublished as `@tabnas/mcp`. This repo is TypeScript-only: it is tooling\nover the engine, not a parity package, so there is no Go port.\n\n## Install\n\n```bash\nnpm install -g @tabnas/mcp     # the `tabnas` CLI\nnpx --yes @tabnas/mcp          # run the MCP server directly (stdio)\n```\n\nMCP client configuration (stdio):\n\n```json\n{\n  \"mcpServers\": {\n    \"tabnas\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"@tabnas/mcp@<x.y.z>\", \"mcp\"]\n    }\n  }\n}\n```\n\nFill in `<x.y.z>` with the current version — `npm view @tabnas/mcp\nversion`. This README does not name it: a repo cannot carry an exact pin\nof its own published version, because the commit that updates it becomes\nthe next release's content, leaving it one release behind forever.\n\nThe server is started by the `mcp` subcommand of the CLI\n(`tabnas mcp`), which is exactly what the skills package's `mcp.json`\ninvokes as `npx --yes @tabnas/mcp@<x.y.z> mcp`. (`--yes` matters: on a\ncache miss `npx` would otherwise prompt on the stdin the MCP transport\nowns. Pin an exact version so the tools cannot drift under an installed\nclient — `skills/mcp.json` carries the real one, written from the\nregistry by its `tools/sync-mcp-pin.js` and checked by\n`tools/validate.js --online`.)\n\n## The seven tools\n\n| Tool | Answers | Result |\n| --- | --- | --- |\n| `parse` | does this input parse, and to what tree? | `{ok:true, tree}` \\| `{ok:false, diagnostic}` |\n| `validate_grammar` | is this serialized GrammarSpec valid? | `{ok:true, v}` \\| `{ok:false, errors:[{path,message}]}` |\n| `explain_parse_error` | why did this parse fail? | `{failed:false}` \\| `{failed:true, diagnostic, registry}` |\n| `test_grammar` | do these TSV fixtures pass? | `{pass, fail, rows:[{row,input,expected,got,ok}]}` |\n| `list_plugins` | what grammar plugins exist? | `{plugins:[...]}` |\n| `describe_plugin` | one plugin's full descriptor | the `tabnas.plugin.json` object |\n| `compare_grammars` | does a grammar change still accept what the old one accepted, and build the same trees? | `{normalForm, proven[], observed[], changes[], counterexamples[], confidence, why}` |\n\nNotes on the contracts:\n\n- Every operation builds a **fresh engine instance** per call. `parse`\n  applies `options` first, then `grammar`. With no grammar the instance\n  is exactly what `new Tabnas()` gives — the bare engine defines no\n  rules, so every input yields an undefined tree (serialized as\n  `{\"ok\":true}`).\n- A `grammar` argument is **validated before it is used**, by every\n  operation that accepts one; an invalid grammar is rejected with the\n  `validate_grammar` error shape `{ok:false, errors:[{path,message}]}`.\n- `validate_grammar` layers: an ADR-10 security scan (below), structural\n  validation against the bundled `grammar.schema.json` (Ajv,\n  draft 2020-12), then an engine load in a fresh instance whose thrown\n  message becomes the error. `v` is the grammar's declared builtin\n  config-schema version (absent means 1).\n- **Security (ADR-10):** a serialized grammar and its options are data,\n  never code. A firewall runs first on every grammar-accepting op and on\n  request options, rejecting: any own key named `__proto__`,\n  `constructor`, or `prototype` anywhere in the tree (prototype-pollution\n  defense — the engine's grammar merge has no `__proto__` guard); a `ref`\n  key (live functions are not JSON); any function reference that is not a\n  `$`-suffixed engine builtin; a `plugins` key, whether a request option\n  or inside `grammar.options` (a plugin is live code); and grammars over\n  5000 rules (a CPU bound). \"Validate this grammar\" never becomes \"run\n  this code\", or \"pollute this process\".\n- A non-diagnostic engine throw (e.g. `options.parser.start` set to a\n  non-function) is caught and returned as the same clean\n  `{ok:false, errors:[{path:\"\",message}]}` shape, so the CLI and the MCP\n  tool agree.\n- `explain_parse_error` joins the diagnostic with the bundled error-code\n  registry entry (`{code, message, hint}`); `registry` is `null` for a\n  code the registry does not know (e.g. a plugin-declared code).\n- `test_grammar` takes TSV **content** in the fleet fixture convention\n  (`@tabnas/support`): line 1 is a header, the input column is\n  escape-decoded, the expected column is JSON or `ERROR` /\n  `ERROR:<code>`. Columns default to positions 0 and 1;\n  `options.inputCol` / `options.expectedCol` select by position or\n  header name. Specs over 10000 rows are refused.\n\nMCP **resources** (served verbatim from the bundled [`data/`](data)):\n`tabnas://schema/grammar`, `tabnas://schema/diagnostic`,\n`tabnas://errors`, `tabnas://plugins`, `tabnas://divergence`.\n\n## CLI\n\n```\ntabnas parse    [file|-] [--grammar g.json] [--json]\ntabnas validate --grammar g.json [--json]\ntabnas diagnose [file|-] [--grammar g.json] [--json]\ntabnas test     --spec fixtures.tsv [--grammar g.json] [--json]\ntabnas plugins  [name] [--json]\ntabnas compare  --a old.json --b new.json [--corpus dir|file] [--depth n] [--json]\ntabnas mcp                                        # run the MCP server (stdio)\n```\n\nInput comes from `file`, or stdin when the argument is `-` or absent.\nThe CLI never touches the network. `tabnas mcp` starts the stdio MCP\nserver (the same server as `npx @tabnas/mcp`); it speaks JSON-RPC on\nstdout and prints nothing else there.\n\n`--json` prints **exactly** the core result JSON — the same bytes the\nMCP tool returns for the same request (stable key order; the golden\ncontract, enforced by `ts/test/golden.test.js`). Without `--json` you\nget a readable rendering; a parse failure prints the engine's own\nrendered error message.\n\nExit codes:\n\n| Code | Meaning |\n| --- | --- |\n| 0 | success: parse succeeded / grammar valid / all fixture rows passed |\n| 1 | the operation said no: parse failure, invalid grammar, fixture failures, unknown plugin |\n| 2 | usage error: unknown flags or command, missing/unreadable files, malformed grammar JSON |\n\n## Passing a grammar that isn't already a GrammarSpec\n\nEvery tool takes a **serialized GrammarSpec** — pure JSON. It does not take\nABNF, EBNF, GBNF or jsonic source, and it never will: compiling those means\nrunning a compiler, and the tools' one hard rule is that a grammar is data,\nnever code (ADR-10). Compile first, then pass the result.\n\n```js\nconst { abnfConvert, toPureSpec } = require('@tabnas/abnf')\n\nconst spec = toPureSpec(abnfConvert(abnfSource, { builtins: true }))\n// -> { options, rule, v, meta } — validates clean, safe to send\n```\n\n**Use `toPureSpec`.** It is the function for this, and the two obvious\nalternatives are both wrong:\n\n- `abnfCompile()` returns **jsonic text**, not an object. Useful for writing\n  a grammar file; not what a tool argument wants.\n- `abnfConvert()` alone returns a spec carrying `ref` (empty, when converted\n  with `builtins: true`) and mark fields. The firewall rejects the *presence*\n  of `ref`, not just its contents — deliberately, since \"empty enough\" is not\n  a property worth reasoning about at a security boundary — and `m` marks are\n  not part of the serialized form. `toPureSpec` strips both and stamps `v`.\n\n`toRecognitionSpec` is the same thing for a grammar that only needs to decide\naccept/reject, without the tree-building builtins.\n\nThe equivalent for the other front-ends is `tabnas parse --grammar g.json`,\nwhere `g.json` is whatever your build step wrote.\n\n## Grammar compatibility (`compare`)\n\nTwo questions, reported separately, because they fail differently:\n\n1. **Acceptance** — does the candidate still accept what the baseline\n   accepted?\n2. **Output** — for inputs both accept, is the resulting tree the same?\n\nThe second is the one users feel. A change that still accepts every\nhistorical document but reshapes the tree silently breaks every downstream\nconsumer, and an acceptance-only test reports success.\n\n**The report carries evidence and confidence, never a bare verdict.** There\nis deliberately no `compatible: true` field. Language inclusion is\nundecidable in general, so a tool that printed one would eventually be wrong\nin production:\n\n- `proven[]` — what was established statically, and on what basis. Anything\n  outside the decidable subset is `not-proven`, which is a statement about\n  this tool, **not** a claim that the grammars are incompatible.\n- `observed[]` — what actually ran, and how much of it.\n- `changes[]` / `counterexamples[]` — concrete differences, with inputs.\n- `confidence` + `why` — how much weight the *absence* of findings can bear.\n  `confidence: \"low\"` with a stated reason is a **successful** run.\n\nThe check that earns its keep is alternate **ordering**. Alternates are\nfirst-match-wins, so one inserted earlier can shadow a later one and narrow\nthe accepted language while a set comparison calls it an addition. `compare`\nwalks positions, not membership, and reports a shadowed alternate that used\nto be reachable.\n\n`--corpus` takes a `.tsv` fixture file or a directory of them, loaded through\n`@tabnas/support` — the same loader the fixture runners use. Real inputs are\nthe only tier that measures what your documents actually do:\n\n```bash\ntabnas compare --a v1.json --b v2.json --corpus ../json/test/spec\n```\n\nExit code is 1 when any change is found, so it works as a release gate.\n\n## The hosted endpoint\n\n`mcp.tabnas.dev` serves the same seven tools over streamable HTTP\n(`POST /mcp`, plus `GET /health` and `GET /.well-known/mcp`), for agents\nthat cannot run `npx`. **Local stdio stays the recommended path** — it is\nfree, private, reproducible and unlimited.\n\nThe hosted service is the same core, so it answers identically; it is\nalso bounded, because it parses attacker-controlled text on shared\ninfrastructure. A 256 KB body cap and 60 requests per minute per IP,\nboth reported up front by `/.well-known/mcp` and named in the refusal\n(`limit_exceeded` / `rate_limited`) along with the local alternative.\nThe rate limit is Cloudflare's, which counts per IP **per data centre**\nand approximately — so it is a shield against sustained abuse, not an\nexact quota, and a short burst may exceed 60 before refusals begin.\nDocument content is never logged, stored, or used for training;\ntelemetry records shape only — tool name, size *bucket*, duration,\nstatus, error code.\n\n## Bundled data\n\nPublished packages do not carry the fleet's contract files (the parser's\nnpm files exclude `schema/`; plugin packages do not ship\n`tabnas.plugin.json`), so this repo commits generated copies in\n[`data/`](data): the grammar and diagnostic schemas, the error-code\nregistry, `DIVERGENCE.md`, and every fleet plugin descriptor\n(`plugins.json`, sorted by name). Regenerate from sibling checkouts\n(`../<repo>` beside this repo) with:\n\n```bash\ncd ts && npm run gen-data\n```\n\nThe build compiles `data/` into `ts/src/data-bundle.ts` (generated,\ngitignored) and the code reads that static import — never the\nfilesystem, because the hosted Worker does not have one. The test suite\nfails on a stale regeneration or a stale embed, and checks the embedded\nset against the directory rather than a hand-kept list. Derive, never\nduplicate (ADR-10).\n\n`data/grammar.schema.json` gets the same treatment for a different\nreason: Ajv validates by generating JavaScript and calling\n`new Function`, which Cloudflare Workers forbid outright, so\n`tools/build-validator.js` precompiles the schema into\n`ts/src/grammar-validator.js` at build time. Same Ajv, same error\nshapes, compiled earlier.\n\n## Build & test\n\n```bash\ncd ts\nnpm install\nnpm test        # builds first, then runs every test/*.test.js\n```\n\n`npm test` ends with `test/workerd.test.js`, which boots the real\n`wrangler.json` in real workerd and speaks HTTP to it. It is the only\ntest whose failure means \"the hosted endpoint will not deploy\", and it\nneeds the `wrangler` devDependency (and the `workerd` binary npm\ninstalls alongside it). It adds a few seconds; a Node-level test cannot\nreplace it, because every deploy-blocking defect this repo has had was\ngreen under Node.\n\nWorking in the fleet layout (sibling checkouts beside this repo),\nsymlink the siblings after `npm install` so you test against source\n(npm replaces these on every install, so re-make them after one):\n\n```bash\nrm -rf node_modules/@tabnas/parser node_modules/@tabnas/support\nln -s ../../../../parser/ts node_modules/@tabnas/parser\nln -s ../../../../support/ts node_modules/@tabnas/support\n```\n\n## CI\n\n[`.github/workflows/ci.yml`](.github/workflows/ci.yml) — a caller of the\norg's `tabnas/.github` `polyglot-ci.yml` (ts-only, with `parser` and\n`support` cloned as siblings), promoted from `ci/ci.yml` in `0abc17e`.\nAutomation cannot push workflow files (admin ADR-8), so any future change\nis staged in `ci/` for a maintainer to promote via the admin rollout\nscripts.\n\nCI runs `test/workerd.test.js`, which boots the real `wrangler.json` in\nreal workerd — so the hosted endpoint's deployability is gated on every\npush, not discovered at deploy time.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 13416,
  "sha": "999682455761add7b7c417844977b9ec88ac21d47ab70be7efe0598c9e35f3e0",
  "repo_slug": "tabnas/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_dev_tabnas_mcp_f556b8a0/readme"
}