Initial MCP

Author: joshwooding

.changeset/mcp-initial-beta.md

@@ -0,0 +1,11 @@
+---
+"@salt-ds/cli": minor
+"@salt-ds/mcp": minor
+---
+
+Publish the initial beta release of the public Salt AI tooling packages.
+
+- `@salt-ds/mcp` packages the canonical Salt Design System MCP server with the beta five-tool workflow surface for repo-aware Salt context, create, review, migrate, and upgrade guidance.
+- `@salt-ds/cli` packages the workflow CLI fallback and support surface with `init`, `info`, `create`, `review`, `migrate`, `upgrade`, `doctor`, and `runtime inspect`.
+
+Treat both packages as beta while the workflow contract, generated registry artifacts, and consumer setup continue to settle.

.github/workflows/test.yml

@@ -92,16 +92,29 @@ jobs:
           cache: "yarn"
       - name: Install dependencies
         run: yarn
+      - name: Generate site snapshot inputs
+        run: yarn workspace @salt-ds/site gen:snapshot
       - run: yarn run test
+  consumer-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: "yarn"
+      - name: Install dependencies
+        run: yarn
+      - name: Consumer smoke test
+        run: yarn smoke:consumer
   cypress-tests:
     strategy:
       fail-fast: false
       matrix:
         react: [16, 17, 18]
     runs-on: ubuntu-latest
-    container:
-      image: cypress/browsers:node-22.14.0-chrome-133.0.6943.126-1-ff-135.0.1-edge-133.0.3065.82-1
-      options: --user 1001
     steps:
       - name: Checkout
         uses: actions/checkout@v6

.gitignore

@@ -48,3 +48,7 @@ yarn-error.log*
 /docs/css/salt-lab.css
 /docs/css/salt-countries.css
 /docs/css/salt-embla-carousel.css
+
+# MCP registry
+
+/packages/mcp/generated

package.json

@@ -40,6 +40,7 @@
     "lint:style:theme": "yarn stylelint -f verbose \"packages/theme/css/**/*.css\"",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "yarn build:ag-grid-theme && yarn bundle:css && storybook build --stats-json",
+    "smoke:consumer": "node ./scripts/consumerRepoSmoke.mjs",
     "typecheck": "tsc --noEmit",
     "chromatic": "chromatic"
   },

packages/cli/README.md

@@ -0,0 +1,133 @@
+# @salt-ds/cli
+
+Salt Design System workflow CLI package.
+
+Use this package as the published fallback/support transport behind `salt-ds` when MCP is blocked or when you need direct manual support/debug access.
+
+Install options:
+
+```sh
+npx -y @salt-ds/cli@latest info . --json
+npm install -g @salt-ds/cli
+```
+
+After global install, use the `salt-ds` binary directly.
+
+Primary workflow commands:
+
+- `salt-ds init [rootDir]`
+  - supports `--json`
+  - supports `--output <path>`
+  - supports `--registry-dir <path>`
+  - supports `--project <name>`
+  - supports `--conventions-pack [<package[#export]>]`
+  - bootstraps `.salt/team.json` plus repo-local instructions for a new or newly-adopting repo without changing the workflow model
+  - can optionally scaffold a starter `.salt/stack.json` for repos using a shared conventions pack
+- `salt-ds info [rootDir]`
+  - supports `--json`
+  - supports `--output <path>`
+  - supports `--registry-dir <path>`
+  - reports detected repo context, declared Salt policy, runtime signals, and workflow capabilities
+- `salt-ds create <query>`
+  - supports `--json`
+  - supports `--output <path>`
+  - supports `--registry-dir <path>`
+  - supports `--include-starter-code`
+  - creates Salt-first UI recommendations for new or existing repos without colliding with normal project build commands
+- `salt-ds review [target ...]`
+  - supports `--url <url>`
+  - supports `--migration-report <path>`
+  - supports `--json`
+  - supports `--output <path>`
+  - supports `--registry-dir <path>`
+  - supports `--timeout <ms>`
+  - supports `--mode <auto|browser|fetched-html>`
+  - supports `--output-dir <path>`
+  - supports `--no-screenshot`
+  - runs source-first Salt review for existing Salt code and can attach runtime evidence in the same pass when `--url` is provided
+  - returns structured `confidence`, `raiseConfidence`, and `fixCandidates` in JSON output so the agent can judge whether to edit, inspect further, or ask follow-up questions without the CLI mutating files directly
+  - can load a saved migration report to verify preserved landmarks, action hierarchy, and other migration-contract checks during `review --url`
+- `salt-ds migrate <query>`
+  - supports `--url <url>`
+  - supports `--json`
+  - supports `--output <path>`
+  - supports `--registry-dir <path>`
+  - supports `--include-starter-code`
+  - supports `--timeout <ms>`
+  - supports `--mode <auto|browser|fetched-html>`
+  - supports `--output-dir <path>`
+  - supports `--no-screenshot`
+  - translates non-Salt UI intent into Salt-first targets and implementation guidance
+  - returns a familiarity contract, migration scope, post-migration verification guidance, delta categories, confidence signals, and optional runtime-scoping evidence so the agent can preserve important experience anchors without cloning the old visual system
+- `salt-ds upgrade`
+  - supports `--package <name>`
+  - supports `--component <name>`
+  - supports `--from-version <version>`
+  - supports `--to-version <version>`
+  - supports `--include-deprecations`
+  - supports `--json`
+  - supports `--output <path>`
+  - supports `--registry-dir <path>`
+  - compares Salt versions and turns the result into upgrade-oriented workflow output
+
+Support commands:
+
+- `salt-ds doctor [rootDir]`
+  - supports `--json`
+  - supports `--output <path>`
+  - supports `--bundle` and `--bundle-dir <path>`
+  - supports `--storybook-url <url>` and `--app-url <url>`
+  - supports `--check-detected-targets`
+  - supports `--timeout <ms>`
+  - can probe runtime target reachability for explicit or detected local targets
+  - validates layered Salt policy sources from `.salt/stack.json`, including package-backed shared conventions packs
+  - can write a support bundle containing the doctor report plus manifest, Salt config, and policy-layer summaries
+- `salt-ds runtime inspect <url>`
+  - supports `--json`
+  - supports `--output <path>`
+  - supports `--output-dir <path>`
+  - supports `--timeout <ms>`
+  - supports `--mode <auto|browser|fetched-html>`
+  - supports `--no-screenshot`
+  - tries browser-session inspection by default, including screenshots, console and page errors, computed layout evidence, bounding boxes, and flex/grid ancestry when a browser runtime is available
+  - falls back to `fetched-html` mode when browser-session inspection is unavailable, so consumers can still get structure, landmark, and accessible-name evidence even though computed layout evidence is unavailable
+
+Canonical Salt grounding now happens inside the public workflow commands and MCP tools. There is no second manual semantic CLI surface.
+
+The intended model is:
+
+- `salt-ds + MCP` when MCP is available
+- `salt-ds + CLI` when MCP is blocked
+- manual CLI use stays workflow-first
+- `review --url`, `doctor`, and `runtime inspect` are support and evidence tools, not the main consumer story
+
+Example workflow-oriented usage:
+
+```sh
+salt-ds init . --json
+salt-ds init . --conventions-pack @acme/salt-conventions#markets --json
+salt-ds info . --json
+salt-ds create "Link to another page from a toolbar action" --json
+salt-ds review src --json
+salt-ds review src --url http://127.0.0.1:3000/ --migration-report migration-plan.json --json
+salt-ds review src --url http://127.0.0.1:6006/?path=/story/example --json
+salt-ds migrate "Translate this external UI toolbar into Salt" --json
+salt-ds migrate "Translate this external UI toolbar into Salt" --url http://127.0.0.1:6006/legacy-toolbar --json --mode fetched-html
+salt-ds upgrade --package @salt-ds/core --from-version 1.1.0 --json
+```
+
+Support-only examples:
+
+```sh
+salt-ds doctor . --check-detected-targets --bundle
+salt-ds runtime inspect http://127.0.0.1:6006/?path=/story/example --json --output .salt-support/runtime-report.json
+```
+
+Interpreting runtime evidence:
+
+- `browser-session`
+  - stronger local evidence for screenshots, runtime/page errors, hydrated titles, landmarks, roles, rendered structure, and computed layout evidence such as boxes, centering clues, and flex/grid ancestry
+- `fetched-html`
+  - narrower fallback evidence for status, title, landmarks, roles, and coarse structure when browser-session inspection is unavailable
+  - does not include computed layout evidence
+- neither mode should be treated as canonical Salt policy; they are evidence inputs for create, review, migration, and support workflows

packages/cli/bin/salt-ds.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+const path = require("node:path");
+
+function loadCliModule() {
+  const candidatePaths = [
+    path.resolve(__dirname, "../dist-cjs/cli/src/index.js"),
+    path.resolve(
+      __dirname,
+      "../../../dist/salt-ds-cli/dist-cjs/cli/src/index.js",
+    ),
+  ];
+
+  for (const candidatePath of candidatePaths) {
+    try {
+      return require(candidatePath);
+    } catch (error) {
+      if (error && error.code === "MODULE_NOT_FOUND") {
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw new Error(
+    "Could not locate the built Salt DS CLI entrypoint. Run `yarn workspace @salt-ds/cli build` first.",
+  );
+}
+
+const { runCli } = loadCliModule();
+
+runCli(process.argv.slice(2))
+  .then((exitCode) => {
+    process.exit(exitCode);
+  })
+  .catch((error) => {
+    console.error("salt-ds cli error:", error);
+    process.exit(1);
+  });

packages/cli/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@salt-ds/cli",
+  "version": "0.0.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jpmorganchase/salt-ds.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": "https://github.com/jpmorganchase/salt-ds/issues",
+  "main": "src/index.ts",
+  "sideEffects": false,
+  "files": [
+    "bin"
+  ],
+  "publishBinEntrypoints": {
+    "bin/salt-ds.js": {
+      "requirePath": "../dist-cjs/cli/src/index.js",
+      "errorPrefix": "salt-ds cli error:"
+    }
+  },
+  "publishScriptExcludes": [
+    "build",
+    "doctor",
+    "prepack"
+  ],
+  "bin": {
+    "salt-ds": "bin/salt-ds.js"
+  },
+  "generateTypings": false,
+  "publishEntryPath": "cli/src/index.js",
+  "scripts": {
+    "build": "yarn node ../../scripts/build.mjs",
+    "doctor": "node ./bin/salt-ds.js doctor",
+    "prepack": "yarn build"
+  },
+  "publishConfig": {
+    "directory": "../../dist/salt-ds-cli",
+    "provenance": true
+  }
+}