@adaptabletools/adaptable-mcp

One package, two modes, for coding agents working on AdapTable projects:

• adaptable — a CLI that the AdapTable Agent Skills call. It reads the docs for the AdapTable version a project actually uses, checks Initial State, AdapTableQL expressions and setup against the installed package, migrates State and expressions between majors, lists what changed between versions, and scaffolds a grid from your data.
• adaptable mcp — the same capabilities as an MCP server over stdio, for harnesses and chat clients that discover MCP tools better than skills, or have no shell.

The agent still writes the code; this package looks things up and checks them. That includes the AG Grid side of an AdapTable grid — column definitions, gridOptions, AG Grid modules and the AG Grid version pairing — which AdapTable has its own rules for. AG Grid's ag-dev / ag-update skills or ag-mcp are a fallback for what the AdapTable docs and checks do not cover.

Requires Node 22.20 or later. Full guide: getting-started-ai-cli.

Skills first

Install the AdapTable Agent Skills into a project; they tell the agent when to run the CLI and how to read its output:

npx skills add https://www.adaptabletools.com

Then install this package in the project, at the repository root:

npm i -D @adaptabletools/adaptable-mcp

The Skills invoke npx -y @adaptabletools/adaptable-mcp@^1 …, and npx runs the project's copy when it satisfies ^1. That copy starts in about 0.5 s with no network, and the lockfile pins one version for the team and CI. Without it, npx asks the registry for the newest 1.x on every call: about 1 s warm, about 5 s on first use (114 MB download). If that copy is behind, detect names the npx cache folder (~/.npm/_npx/<hash>) to delete. A global install is not recommended. npx reaches it only after that same registry lookup, and nothing records which version each developer has.

For your own work across many folders, or before there is a project, configure the MCP server once for your user instead.

Keeping current

The Skills and the CLI release together under one version. Every Skill starts with detect, whose tooling block compares the installed Skills (VERSION.md in .agents/skills, .claude/skills and .cursor/skills), this CLI and the AGENTS.md block with the released version in the docs manifest. Each problem is a warning naming its fix: npx skills update -p -y, npm i -D @adaptabletools/adaptable-mcp@^1, deleting a stale npx cache folder, or a restart of the MCP server. status: update-available (the Skills or the CLI are behind that release) makes the Skill stop and ask: update both (recommended), then start a new session, or continue with the installed versions. status: incompatible (the Skills and the CLI are on different majors) makes the Skill stop, with no option to continue.

The CLI

npx -y @adaptabletools/adaptable-mcp@^1 <command> [options]

| Command | What it does | | --- | --- | | detect | AdapTable and AG Grid packages, framework, compatibility of the project | | compat --adaptable <major> | AG Grid pairing, wrapper versions and environment requirements for a major | | docs list\|search\|get\|demos\|demo | The docs for the project's version and framework, as Markdown | | check state\|expression\|setup | Initial State, AdapTableQL expressions and Adaptable Options against the installed package | | aql functions | The AdapTableQL function catalogue, per module | | migrate state\|expression | From an older major to a newer one, with leftovers reported | | changes --from <major> --to <major> | What changed between two majors, grepped against the project | | convert coldefs | AG Grid columnDefs → AdapTable Layout and Format Columns | | scaffold | A new grid project from a CSV / JSON / XLSX sample | | anonymise | Strip values from a State or Grid Info before sharing it | | cache add\|list\|clear | Download a major's package for offline use |

Global flags: --cwd <dir>, --major <n>, --framework <fw>, --offline, --quiet, --json, --docs-host <url>. Output is Markdown by default; --json returns a stable envelope. Exit codes: 0 ok · 1 findings · 2 usage · 3 environment.

With the devDependency installed, the adaptable bin is also on hand for CI and offline preparation:

npx adaptable cache add 24   # for machines without registry access later

The MCP server

Point an MCP client at the same binary with the mcp argument (without it the binary prints help and exits):

{
  "mcpServers": {
    "adaptable": { "command": "npx", "args": ["-y", "@adaptabletools/adaptable-mcp@latest", "mcp"] }
  }
}

Put it in the user-level config so it serves every folder: Cursor reads ~/.cursor/mcp.json (or .cursor/mcp.json per project), Claude Code takes claude mcp add --scope user adaptable -- npx -y @adaptabletools/adaptable-mcp@latest mcp (or .mcp.json per project); Codex takes the equivalent [mcp_servers.adaptable] block in ~/.codex/config.toml. The server exposes the checking, docs and migration capabilities as twelve tools (detect_environment, get_compatibility, search_docs, get_doc, get_demo, check_state, check_expression, list_expression_functions, check_setup, migrate_state, migrate_expression, list_changes) with the same envelope as the CLI's --json output; every tool also accepts the global options (cwd, major, framework, offline, docsHost). adaptable mcp --cwd <dir> --major <n> --offline … sets defaults for every call. There are no prompts or resources: the workflows live in the Skills.

In a long-lived server the docs manifest is re-validated at most once a minute before a manifest-dependent call, and the library package for a project is resolved per call, so one server serves projects on different majors. The server keeps the version it started with; detect_environment warns when a newer one is released, and a restart picks it up: npx looks the latest dist-tag up on every start. A range such as ^1 can keep the first copy it cached, and detect names that folder when the copy is behind. Its twelve tool definitions take about 4,500 tokens of every chat's context.

How it works

• Docs come from the build-time export of the docs site (/llms/manifest.json, pages.json, one .md per page, the demos index), re-validated with a conditional request on every call and cached under ~/.cache/adaptable-mcp/.
• Checks and migrations use the installed @adaptabletools/adaptable where the project has one, otherwise the newest cached release of the right major, checked against npm at most once a day (hourly while the cached copy is a pre-release); nothing is bundled from an older version of AdapTable's types.
• When ~/.cache/adaptable-mcp/ is read-only (an agent sandbox), the cache is written under the system temp folder and the existing packages are still read.
• No telemetry; the only writer is scaffold --out.

Environment variables

| Variable | Default | Use | | --- | --- | --- | | ADAPTABLE_MCP_CACHE_DIR | $XDG_CACHE_HOME/adaptable-mcp or ~/.cache/adaptable-mcp | Cache for docs, packages and bundled entries | | ADAPTABLE_MCP_DOCS_HOST | matched docs site | Docs site to read instead of the default one | | ADAPTABLE_MCP_ADAPTABLE_SRC | | AdapTable source folder (packages/adaptable) instead of the installed package (development) |

Development

npm install
npm run build
npm run lint
npm test
npm run inspect   # MCP Inspector against dist/bin.js mcp

Tests that exercise the AdapTable engine bundle packages/adaptable/{aql,upgrade}.ts from source, so build packages/aql and install packages/adaptable's dependencies first. The layout, the boundary rule between src/core and the two transports, and the task list are in design_docs/ai-tooling-v2/.