@adaptabletools/adaptable-mcp 0.1.0-canary.0 → 0.1.0-canary.2

package/README.md

@@ -1,96 +1,93 @@
-# AdapTable MCP Server
+# @adaptabletools/adaptable-mcp
 
-An [MCP](https://modelcontextprotocol.io) server that helps coding agents write correct [AdapTable](https://www.adaptabletools.com) code for the version a project actually uses.
+One package, two modes, for coding agents working on [AdapTable](https://www.adaptabletools.com) projects:
 
-It looks things up and checks them; the agent still writes the code:
+- **`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](https://modelcontextprotocol.io) server over stdio, for harnesses and chat clients that discover MCP tools better than skills, or have no shell.
 
-- detects the project's AdapTable, framework and AG Grid versions, and flags setup mistakes
-- searches the docs for that version and framework
-- validates AdapTableQL expressions and Initial State with the installed AdapTable package
-- migrates expressions and state from older versions
+The agent still writes the code; this package looks things up and checks them. For AG Grid itself (column definitions, AG Grid modules, row models, grid API) use AG Grid's `ag-dev` skill or [ag-mcp](https://www.ag-grid.com/javascript-data-grid/mcp-server/) alongside it.
 
-For AG Grid itself (column definitions, AG Grid modules, row models, grid API), use AG Grid's [ag-mcp](https://www.ag-grid.com/javascript-data-grid/mcp-server/) alongside this server.
+Requires Node 20+. Full guide: [getting-started-ai-cli](https://www.adaptabletools.com/docs/getting-started-ai-cli).
 
-## Setup
+> This package is being rebuilt. The commands below describe the target contract; the published `canary` line fills them in milestone by milestone, and `adaptable --help` lists what the installed version supports.
 
-Requires Node 20+. The checks need AdapTable 24 or later installed in the project.
+## Skills first
 
-Cursor (`.cursor/mcp.json`) and other clients that take an `mcpServers` map:
+Install the AdapTable Agent Skills into a project; they tell the agent when to run the CLI and how to read its output:
 
-```json
-{
-  "mcpServers": {
-    "adaptable": {
-      "command": "npx",
-      "args": ["-y", "@adaptabletools/adaptable-mcp"]
-    }
-  }
-}
+```bash
+npx skills add https://www.adaptabletools.com
 ```
 
-Claude Code:
+Nothing else is required: the skills invoke `npx -y @adaptabletools/adaptable-mcp@^1 …` on demand.
+
+## The CLI
 
 ```bash
-claude mcp add adaptable -- npx -y @adaptabletools/adaptable-mcp
+npx -y @adaptabletools/adaptable-mcp@^1 <command> [options]
 ```
 
-The server finds the project from the client's workspace roots, then the current directory. Pass `projectPath` to any tool, or set `ADAPTABLE_MCP_PROJECT`, to point it elsewhere.
+| 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.
+
+Install it as a devDependency for restricted networks, cold-start avoidance and CI:
 
-## Tools
+```bash
+npm i -D @adaptabletools/adaptable-mcp
+npx adaptable cache add 24   # for machines without registry access later
+```
 
-| Tool | What it does |
-| --- | --- |
-| `detect_environment` | AdapTable and AG Grid packages, framework, peer range, documented AG Grid pairing, warnings |
-| `search_docs` | Docs sections for the project's version and framework, with URLs |
-| `get_doc` | One docs page (or one section of it) as markdown |
-| `check_expression` | Validates an AdapTableQL expression: syntax, functions, types, aggregation rules, the functions its Module offers, columns |
-| `migrate_expression` | Rewrites a pre-v24 expression to v24 syntax |
-| `list_expression_functions` | Built-in AdapTableQL functions with signatures and examples |
-| `check_state` | Initial State: type check against the installed `InitialState`, pre-v24 shapes, Layouts, column references, embedded expressions |
-| `migrate_state` | Upgrades state from an older major version (`AdaptableUpgradeHelper`) |
+## The MCP server
 
-Resources: `adaptable://docs/{major}/{slug}`, `adaptable://api/{major}/{typeName}`, `adaptable://aql/functions`.
+Point an MCP client at the same binary with the `mcp` argument (without it the binary prints help and exits):
 
-Prompts: `setup-adaptable` (framework), `upgrade-adaptable` (from, to).
+```json
+{
+  "mcpServers": {
+    "adaptable": { "command": "npx", "args": ["-y", "@adaptabletools/adaptable-mcp@^1", "mcp"] }
+  }
+}
+```
+
+Cursor reads this from `.cursor/mcp.json`, Claude Code from `.mcp.json`; 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.
 
 ## How it works
 
-- Docs come from the build-time export of the docs site: `/llms/manifest.json`, `/llms-full.txt` and `/llms/pages.json`. The server picks the site that matches the project's major version (`www` for the latest major, `v{major}` for older ones, `canary` for a major that only has canary releases), caches the files, and re-downloads only when the manifest hash changes.
-- Checks use the `@adaptabletools/adaptable/aql` and `@adaptabletools/adaptable/upgrade` entry points of the installed package, so they match the project's exact version. The package ships as bundler ESM, so each entry is bundled once with esbuild and cached.
+- 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 a cached copy of the right major; nothing is bundled from an older version of AdapTable's types.
+- No telemetry; the only writer is `scaffold --out`.
 
 ## Environment variables
 
 | Variable | Default | Use |
 | --- | --- | --- |
-| `ADAPTABLE_MCP_PROJECT` | workspace root | Project to inspect |
-| `ADAPTABLE_MCP_DOCS_URL` | matched docs site | Docs site to read, e.g. `https://dev.adaptabletools.com` |
-| `ADAPTABLE_MCP_DOCS_DIR` | | Local docs build (`documentation/public`) instead of a site |
-| `ADAPTABLE_MCP_ADAPTABLE_SRC` | | AdapTable source folder (`packages/adaptable`) instead of the installed package |
-| `ADAPTABLE_MCP_CACHE_DIR` | `~/.cache/adaptable-mcp` | Cache for docs and bundled entries |
+| `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
 
 ```bash
 npm install
 npm run build
+npm run lint
 npm test
-npm run inspect   # MCP Inspector
-```
-
-### Eval
-
-`eval/tasks.json` holds the eval tasks: setup per framework, AdapTableQL, state, option placement and upgrades. `eval/grade.mjs` grades a folder of answers (`<task-id>.md`), checking expressions and Initial State (including the type check) with the same code as the tools.
-
-`npm test` checks the checks in both directions: every Initial State in the docs demos must pass `check_state` (`test/docsExamples.test.mjs`; known docs issues are listed there until the demos are fixed), and every answer in `eval/known-wrong` (stale answers from a run without the MCP) must fail grading.
-
-Eval runs write their answers to `eval/results/<run>/` (gitignored):
-
-```bash
-node eval/grade.mjs eval/results/baseline
+npm run inspect   # MCP Inspector against dist/bin.js mcp
 ```
 
-`eval/mcp-call.mjs` calls one tool from the command line, for agents that run the eval without MCP support:
-
-```bash
-ADAPTABLE_MCP_PROJECT=eval/fixture node eval/mcp-call.mjs search_docs '{"query":"pivot layout"}'
-```
+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/`.