dev.tabnasPublished by tabnas.devOfficial publisherv0.1.20Updated Oct 24, 2026
Seven tools over the tabnas parsing engine: parse, validate, diagnose, fixtures, compare.
tabnas exposes seven tools over the tabnas parsing engine so an assistant can parse input, validate grammars, explain parse errors, run fixtures and compare…
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/dev.tabnas%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"tabnas": {
"type": "http",
"url": "https://mcp.tabnas.dev/mcp"
}
}
}The tabnas agent tooling: one TypeScript codebase, two front-ends:
an MCP server (stdio) and the unified
tabnas CLI, sharing a single core (ts/src/core.ts) so the two can
never disagree. For each operation the CLI's --json output and the MCP
tool result are byte-identical, and the test suite holds them to it.
The website page for this package: per-client setup, the tool contracts, the hosted endpoint's bounds: tabnas.dev/mcp.
Published as @tabnas/mcp. This repo is TypeScript-only: it is tooling
over the engine, not a parity package, so there is no Go port.
MCP client configuration (stdio):
Fill in <x.y.z> with the current version: npm view @tabnas/mcp version. This README does not name it: a repo cannot carry an exact pin
of its own published version, because the commit that updates it becomes
the next release's content, leaving it one release behind forever.
The server is started by the mcp subcommand of the CLI
(tabnas mcp), which is exactly what the skills package's mcp.json
invokes as npx --yes @tabnas/mcp@<x.y.z> mcp. (--yes matters: on a
cache miss npx would otherwise prompt on the stdin the MCP transport
owns. Pin an exact version so the tools cannot drift under an installed
client: skills/mcp.json carries the real one, written from the
registry by its tools/sync-mcp-pin.js and checked by
tools/validate.js --online.)
Notes on the contracts:
parse
applies options first, then grammar. With no grammar the instance
is exactly what new Tabnas() gives: the bare engine defines no
rules, so every input yields an undefined tree (serialized as
{"ok":true}).grammar argument is validated before it is used, by every
operation that accepts one; an invalid grammar is rejected with the
validate_grammar error shape {ok:false, errors:[{path,message}]}.validate_grammar layers: an ADR-10 security scan (below), structural
validation against the bundled grammar.schema.json (Ajv,
draft 2020-12), then an engine load in a fresh instance whose thrown
message becomes the error. v is the grammar's declared builtin
config-schema version (absent means 1).__proto__,
constructor, or prototype anywhere in the tree (prototype-pollution
defense, since the engine's grammar merge has no __proto__ guard); a ref
key (live functions are not JSON); any function reference that is not a
$-suffixed engine builtin; a plugins key, whether a request option
or inside grammar.options (a plugin is live code); and grammars over
5000 rules (a CPU bound). "Validate this grammar" never becomes "run
this code", or "pollute this process".options.parser.start set to a
non-function) is caught and returned as the same clean
{ok:false, errors:[{path:"",message}]} shape, so the CLI and the MCP
tool agree.explain_parse_error joins the diagnostic with the bundled error-code
registry entry ({code, message, hint}); registry is null for a
code the registry does not know (for example, a plugin-declared code).test_grammar takes TSV content in the fleet fixture convention
(@tabnas/support): line 1 is a header, the input column is
escape-decoded, the expected column is JSON or ERROR /
ERROR:<code>. Columns default to positions 0 and 1;
options.inputCol / options.expectedCol select by position or
header name. Specs over 10000 rows are refused.MCP resources (served verbatim from the bundled data/):
tabnas://schema/grammar, tabnas://schema/diagnostic,
tabnas://errors, tabnas://plugins, tabnas://divergence.
Input comes from file, or stdin when the argument is - or absent.
The CLI never touches the network. tabnas mcp starts the stdio MCP
server (the same server as npx @tabnas/mcp); it speaks JSON-RPC on
stdout and prints nothing else there.
--json prints exactly the core result JSON: the same bytes the
MCP tool returns for the same request (stable key order; the golden
contract, enforced by ts/test/golden.test.js). Without --json you
get a readable rendering; a parse failure prints the engine's own
rendered error message.
Exit codes:
Every tool takes a serialized GrammarSpec, pure JSON. It does not take ABNF, EBNF, GBNF or jsonic source, and it never will: compiling those means running a compiler, and the tools' one hard rule is that a grammar is data, never code (ADR-10). Compile first, then pass the result.
Use toPureSpec. It is the function for this, and the two obvious
alternatives are both wrong:
abnfCompile() returns jsonic text, not an object. Useful for writing
a grammar file; not what a tool argument wants.abnfConvert() alone returns a spec carrying ref (empty, when converted
with builtins: true) and mark fields. The firewall rejects the presence
of ref, not merely its contents, deliberately, since "empty enough" is not
a property worth reasoning about at a security boundary, and m marks are
not part of the serialized form. toPureSpec strips both and stamps v.toRecognitionSpec is the same thing for a grammar that only needs to decide
accept/reject, without the tree-building builtins.
The equivalent for the other front-ends is tabnas parse --grammar g.json,
where g.json is whatever your build step wrote.
compare)Two questions, reported separately, because they fail differently:
The second is the one users feel. A change that still accepts every historical document but reshapes the tree silently breaks every downstream consumer, and an acceptance-only test reports success.
The report carries evidence and confidence, never a bare verdict. There
is deliberately no compatible: true field. Language inclusion is
undecidable in general, so a tool that printed one would eventually be wrong
in production:
proven[]. What was established statically, and on what basis. Anything
outside the decidable subset is not-proven, which is a statement about
this tool, not a claim that the grammars are incompatible.observed[]. What actually ran, and how much of it.changes[] / counterexamples[]. Concrete differences, with inputs.confidence + why. How much weight the absence of findings can bear.
confidence: "low" with a stated reason is a successful run.The check that earns its keep is alternate ordering. Alternates are
first-match-wins, so one inserted earlier can shadow a later one and narrow
the accepted language while a set comparison calls it an addition. compare
walks positions, not membership, and reports a shadowed alternate that used
to be reachable.
--corpus takes a .tsv fixture file or a directory of them, loaded through
@tabnas/support, the same loader the fixture runners use. Real inputs are
the only tier that measures what your documents actually do:
Exit code is 1 when any change is found, so it works as a release gate.
mcp.tabnas.dev serves the same seven tools over streamable HTTP
(POST /mcp, plus GET /health and GET /.well-known/mcp), for agents
that cannot run npx. Local stdio stays the recommended path: it is
free, private, reproducible, and unlimited.
The hosted service is the same core, so it answers identically; it is
also bounded, because it parses attacker-controlled text on shared
infrastructure. A 256 KB body cap and 60 requests per minute per IP,
both reported up front by /.well-known/mcp and named in the refusal
(limit_exceeded / rate_limited) along with the local alternative.
The rate limit is Cloudflare's, which counts per IP per data centre
and approximately, so it is a shield against sustained abuse, not an
exact quota, and a short burst may exceed 60 before refusals begin.
Document content is never logged, stored, or used for training;
telemetry records shape only: tool name, size bucket, duration,
status, error code.
Published packages do not carry the fleet's contract files (the parser's
npm files exclude schema/; plugin packages do not ship
tabnas.plugin.json), so this repo commits generated copies in
data/: the grammar and diagnostic schemas, the error-code
registry, DIVERGENCE.md, and every fleet plugin descriptor
(plugins.json, sorted by name). Regenerate from sibling checkouts
(../<repo> beside this repo) with:
The build compiles data/ into ts/src/data-bundle.ts (generated,
gitignored) and the code reads that static import, never the
filesystem, because the hosted Worker does not have one. The test suite
fails on a stale regeneration or a stale embed, and checks the embedded
set against the directory rather than a hand-kept list. Derive, never
duplicate (ADR-10).
data/grammar.schema.json gets the same treatment for a different
reason: Ajv validates by generating JavaScript and calling
new Function, which Cloudflare Workers forbid outright, so
tools/build-validator.js precompiles the schema into
ts/src/grammar-validator.js at build time. Same Ajv, same error
shapes, compiled earlier.
npm test ends with test/workerd.test.js, which boots the real
wrangler.json in real workerd and speaks HTTP to it. It is the only
test whose failure means "the hosted endpoint will not deploy", and it
needs the wrangler devDependency (and the workerd binary npm
installs alongside it). It adds a few seconds; a Node-level test cannot
replace it, because every deploy-blocking defect this repo has had was
green under Node.
Working in the fleet layout (sibling checkouts beside this repo),
symlink the siblings after npm install so you test against source
(npm replaces these on every install, so re-make them after one):
.github/workflows/ci.yml, a caller of the
org's tabnas/.github polyglot-ci.yml (ts-only, with parser and
support cloned as siblings), promoted from ci/ci.yml in a14741c.
A change to it is made in .github/workflows/ directly, in a reviewed
pull request (admin ADR-8, as amended 2026-09-24).
CI runs test/workerd.test.js, which boots the real wrangler.json in
real workerd, so the hosted endpoint's deployability is gated on every
push, not discovered at deploy time.
MIT. See LICENSE.
Source: README.md at commit 3cc5c8c
Parse input with the tabnas engine. Returns {ok:true, tree} or, on parse failure, {ok:false, diagnostic} — the structured diagnostic described by resource tabnas://schema/diagnostic. An invalid grammar is rejected as {ok:false, errors:[{path,message}]}. Without a grammar the bare engine is used, which defines no rules and produces an undefined tree for every input.
inputrequiredgrammaroptionsValidate a serialized GrammarSpec. Structural validation against the bundled grammar schema, an engine load in a fresh instance, and a check that every rule reference (`p`, `r`) names a rule the grammar actually defines — a dangling reference loads cleanly and then fails at parse time with `unknown_rule`. Returns {ok:true, v} (v = declared builtin config-schema version, absent means 1) or {ok:false, errors:[{path,message}]}. Security: a grammar carrying a `ref` key, or any function reference that is not a $-suffixed engine builtin, is rejected — validating a grammar never runs supplied code.
grammarrequiredParse input and explain the failure. Returns {failed:false} when the input parses; otherwise {failed:true, diagnostic, registry} where registry is the error-code registry entry {code,message,hint} for the diagnostic code (resource tabnas://errors), or null for a code the bundled registry does not know (e.g. a plugin-declared code).
inputrequiredgrammarRun TSV fixture content against a grammar in a fresh instance, using the fleet fixture convention (@tabnas/support): line 1 is a header, the input column is escape-decoded, the expected column is JSON or ERROR / ERROR:<code>. Returns {pass, fail, rows:[{row,input,expected,got,ok}]}. Refuses more than 10000 rows.
specrequiredgrammaroptionsList every bundled tabnas plugin descriptor (tabnas.plugin.json of each fleet repo), sorted by name. Returns {plugins:[...]}.
Takes no parameters.
The full descriptor for one plugin, by package name ('@tabnas/csv') or bare fleet name ('csv'). Unknown names get {ok:false, errors} naming the known plugins.
namerequiredGrammar compatibility (AX plan Phase 5): does candidate grammar B still accept what baseline A accepted, and does it build the same tree for inputs both accept? Returns EVIDENCE AND CONFIDENCE, never a bare verdict: {normalForm, proven[], observed[], changes[], counterexamples[], confidence, why}. confidence:'low' with a stated reason is a successful run, not a failure — language inclusion is undecidable in general, so anything outside the decidable subset is reported not-proven rather than incompatible. Supply `corpus` (real inputs) for the tier that measures what your documents actually do.
arequiredbrequireddepthcorpusoptions100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
npm install -g @tabnas/mcp # the `tabnas` CLInpx --yes @tabnas/mcp # run the MCP server directly (stdio){ "mcpServers": { "tabnas": { "command": "npx", "args": ["--yes", "@tabnas/mcp@<x.y.z>", "mcp"] } }}tabnas parse [file|-] [--grammar g.json] [--json]tabnas validate --grammar g.json [--json]tabnas diagnose [file|-] [--grammar g.json] [--json]tabnas test --spec fixtures.tsv [--grammar g.json] [--json]tabnas plugins [name] [--json]tabnas compare --a old.json --b new.json [--corpus dir|file] [--depth n] [--json]tabnas mcp # run the MCP server (stdio)const { abnfConvert, toPureSpec } = require('@tabnas/abnf')
const spec = toPureSpec(abnfConvert(abnfSource, { builtins: true }))// -> { options, rule, v, meta } — validates clean, safe to sendtabnas compare --a v1.json --b v2.json --corpus ../json/test/speccd ts && npm run gen-datacd tsnpm installnpm test # builds first, then runs every test/*.test.jsrm -rf node_modules/@tabnas/parser node_modules/@tabnas/supportln -s ../../../../parser/ts node_modules/@tabnas/parserln -s ../../../../support/ts node_modules/@tabnas/support