meguro-mcp 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,10 +2,27 @@
 
 All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.0 — 2026-08-01
+
+- Publishes the frozen 43-tool control-plane registry already present in the repository, without
+  changing any tool name, input schema, resource, or protocol behavior.
+- Includes every registry title and all four MCP behavior annotations, the universal `docs_read`
+  tool, and the versioned immutable documentation resources in the public artifact.
+- Generates the complete README tool table from the server's actual `tools/list` response and fails
+  publish verification when that generated documentation is stale.
+- Pins Console and customer quickstarts to the exact `meguro-mcp@0.2.0` artifact.
+
 ## 0.1.0 — 2026-07-19
 
 - First public distribution of the dependency-free Meguro control-plane MCP server.
-- Exposes the 15 documented store, run, receipt, connection, probe, and schema tools.
+- Exposes the documented store, run, receipt, Gate, Shopify Exam, connection, probe, and schema tools.
+- Adds the bounded Shopify Exam lifecycle quartet: `exam_preflight`, `exam_start`, `exam_status`, and `exam_report`.
+- Adds account-scoped workspace list/create/archive/unarchive tools and explicit, server-verified
+  non-default workspace selection for store-fleet, share, catalog-slice, and claim tools.
+- Adds the complete evidence-share lifecycle, live and saved catalog-slice tools, and Shopify
+  development-store claim-by-code parity. Publish and re-share are explicitly outward-facing;
+  direct domain claim remains an honestly exposed operator-only repair lane.
+- Publishes the immutable receipt guide and Gate policy v1 through standard MCP resources and the
+  universal read-only `docs_read` tool in both local stdio and hosted OAuth lanes.
 - Supports account-scoped `meg_sk_…` credentials and the self-hosted operator fallback.
 - Redacts control credentials and practice-store credentials from protocol and tool errors.
-

package/README.md

@@ -14,7 +14,7 @@ Dependency-free, no build step: the server is plain Node ≥ 20.
 Customer MCP clients run the exact public version directly from npm:
 
 ```bash
-npx -y meguro-mcp@0.1.0
+npx -y meguro-mcp@0.2.0
 ```
 
 Pin the version in client configuration. A pinned quickstart stays reproducible and never changes its
@@ -30,26 +30,85 @@ Console provides fast trusted proof and evidence inspection; the agency agent no
 
 ## Tools
 
-| Tool | Does | Auth |
+<!-- BEGIN GENERATED MCP TOOL TABLE -->
+<!-- Run `npm run docs:tools --workspace meguro-mcp` to refresh this section from `tools/list`. -->
+This table is generated from the server's live `tools/list` response (43 tools).
+
+| Tool | Title | Behavior annotations |
 |---|---|---|
-| `run_start` | write `months` of dated history onto the configured store (requires typing the shop domain in `confirm_shop`) | account API key |
-| `run_status` | live progress: orders/total, watermark, status, lastError | account API key |
-| `run_ledger` | the run's attributed diary | account API key |
-| `run_report` | verdict + summary + S3 keys | account API key |
-| `run_resume` | resume a failed run after raising budgets | account API key |
-| `runs_diff` | twin comparison: shared prefix, fork, deltas | account API key |
-| `practice_run_start` | start an `external-agent` practice run; the agent remains in your environment | account API key |
-| `practice_run_status` | read the server-authoritative practice-run contract | account API key |
-| `practice_run_checkpoint` | capture immutable temporal evidence and return a bounded summary | account API key |
-| `practice_run_advance` | advance by days or a closed-set event condition with both concurrency cursors | account API key |
-| `practice_run_finish` | explicitly finish without inventing time or evidence | account API key |
-| `practice_run_report` | read the run's **receipt** — a bounded receipt summary without raw private payloads | account API key |
-| `get_connection_details` | fetch the three Shopify Admin values for a practice store | account API key |
-| `admin_probe` | run one isolated, ungraded Admin GraphQL read or confirmed mutation and return a durable Console URL | account API key |
-| `admin_schema` | look up one exact bounded Admin type, field, mutation, or commerce recipe | account API key |
+| `docs_read` | Read Meguro receipt and Gate documentation | read-only · non-destructive · idempotent · closed-world |
+| `stores_list` | List practice stores | read-only · non-destructive · idempotent · closed-world |
+| `store_create` | Create a practice store | read-write · non-destructive · non-idempotent · closed-world |
+| `store_delete` | Delete a practice store | read-write · destructive · non-idempotent · closed-world |
+| `store_passport` | Read Store Passport | read-only · non-destructive · idempotent · closed-world |
+| `workspaces_list` | List account workspaces | read-only · non-destructive · idempotent · closed-world |
+| `workspace_create` | Create a workspace | read-write · non-destructive · non-idempotent · closed-world |
+| `workspace_archive` | Archive a workspace | read-write · destructive · idempotent · closed-world |
+| `workspace_unarchive` | Restore a workspace | read-write · non-destructive · idempotent · closed-world |
+| `share_create` | Create or update a private share draft | read-write · non-destructive · non-idempotent · closed-world |
+| `shares_list` | List evidence shares | read-only · non-destructive · idempotent · closed-world |
+| `share_status` | Read an evidence share | read-only · non-destructive · idempotent · closed-world |
+| `share_publish` | Publish evidence to client viewers | read-write · non-destructive · non-idempotent · open-world |
+| `share_revoke` | Revoke client-viewer evidence access | read-write · destructive · idempotent · open-world |
+| `catalog_slice_read` | Read a live Shopify catalog slice | read-only · non-destructive · idempotent · open-world |
+| `catalog_slice_snapshot` | Mint a catalog slice snapshot | read-write · non-destructive · non-idempotent · open-world |
+| `catalog_slices_saved` | Manage saved catalog slices | read-write · destructive · non-idempotent · open-world |
+| `store_claim_by_code` | Claim a Shopify dev store by code | read-write · non-destructive · non-idempotent · closed-world |
+| `store_claim` | Admin-claim a Shopify dev store | read-write · destructive · non-idempotent · closed-world |
+| `run_start` | Start a Shopify dev-store history run | read-write · non-destructive · non-idempotent · open-world |
+| `run_status` | Read run status | read-only · non-destructive · idempotent · closed-world |
+| `run_ledger` | Read run ledger | read-only · non-destructive · idempotent · closed-world |
+| `run_report` | Read run receipt | read-only · non-destructive · idempotent · closed-world |
+| `run_resume` | Resume a Shopify dev-store run | read-write · non-destructive · non-idempotent · open-world |
+| `runs_diff` | Compare run receipts | read-only · non-destructive · idempotent · closed-world |
+| `gate_verdict` | Read a Gate verdict | read-only · non-destructive · idempotent · closed-world |
+| `runs_list` | List runs | read-only · non-destructive · idempotent · closed-world |
+| `usage_read` | Read usage headroom | read-only · non-destructive · idempotent · closed-world |
+| `twin_diff` | Read a twin impact receipt | read-only · non-destructive · idempotent · closed-world |
+| `exam_preflight` | Check Shopify Exam readiness | read-only · non-destructive · idempotent · open-world |
+| `exam_start` | Start or continue a Shopify Exam | read-write · non-destructive · idempotent · open-world |
+| `exam_status` | Read Shopify Exam status | read-only · non-destructive · idempotent · closed-world |
+| `exam_report` | Read a Shopify Exam receipt | read-only · non-destructive · idempotent · closed-world |
+| `practice_run_start` | Start a practice run | read-write · non-destructive · non-idempotent · closed-world |
+| `practice_run_status` | Read practice-run status | read-only · non-destructive · idempotent · closed-world |
+| `practice_run_checkpoint` | Capture a practice-run checkpoint | read-write · non-destructive · non-idempotent · closed-world |
+| `practice_run_advance` | Advance store time | read-write · non-destructive · non-idempotent · closed-world |
+| `practice_run_finish` | Finish a practice run | read-write · non-destructive · non-idempotent · closed-world |
+| `practice_run_report` | Read a compatibility receipt | read-only · non-destructive · idempotent · closed-world |
+| `practice_run_impact` | Read a practice-run impact receipt | read-only · non-destructive · idempotent · closed-world |
+| `get_connection_details` | Get practice-store connection details | read-only · non-destructive · idempotent · closed-world |
+| `admin_probe` | Run an Admin API probe | read-write · non-destructive · non-idempotent · closed-world |
+| `admin_schema` | Look up the Admin API schema | read-only · non-destructive · idempotent · closed-world |
+<!-- END GENERATED MCP TOOL TABLE -->
+
+## Documentation resources
+
+The same versioned customer documentation is available through standard MCP resources in both the
+local stdio server and the hosted OAuth resource server:
+
+- `meguro://docs/receipt-guide/v1`
+- `meguro://docs/receipt-guide/v2`
+- `meguro://docs/gate-policy/v1`
+
+Use `resources/list` and `resources/read` when the client supports MCP resources. Use
+`docs_read({ topic, version })` in every client, including clients without a resource browser.
+Published versions are immutable and carry a SHA-256 digest; later versions are appended under a
+new URI instead of replacing an existing document.
 
 ## Identity model
 
+Hosted OAuth grants are issued only to an active account owner and are **account-bound**, not pinned to
+one workspace. Account-scoped tools such as `workspaces_list` and `workspace_create` need no selector.
+Store-fleet, share, catalog-slice, and claim tools accept an optional `workspaceId`: omit it for the
+default workspace, or pass an exact id from `workspaces_list` for a non-default workspace. The hosted
+resource server verifies that selection against the token account before dispatch.
+
+Local `meg_sk_…` API keys remain **workspace-bound**. A key may omit `workspaceId` or repeat its own
+binding, but cannot switch workspaces; use a key issued from the intended workspace instead. Tier
+capacity and workspace ownership are always server-derived. Workspace-bound keys may list account
+workspaces through the existing read route, but account-level create/archive/unarchive requires the
+owner-only OAuth lane.
+
 The whole assistant workflow uses exactly two identifiers:
 
 * **`storeId`** — the canonical public practice-store id. `get_connection_details` takes it and returns it, and `practice_run_start` consumes it verbatim, so connection-discovery output passes directly into run start. `worldId` is a **legacy alias for the same id** (both tools still accept it and connection results still include it); prefer `storeId` in new integrations.
@@ -93,9 +152,6 @@ See [the agency quickstart](../../docs/agency-practice-run-quickstart.md) and [H
 MEGURO_API_BASE_URL=https://api-dev.meguro.io
 MEGURO_API_TOKEN=<meg_sk account key from Console → Settings>
 MEGURO_DASHBOARD_URL=https://<dashboard-distribution>.cloudfront.net   # optional, enables dashboard links
-
-# Self-hosted/operator fallback only; customer MCP clients should omit it.
-MEGURO_CONTROL_API_KEY=<from infra/params.env or deployment secrets>
 ```
 
 ## Register — Claude Code
@@ -105,7 +161,7 @@ claude mcp add meguro \
   -e MEGURO_API_BASE_URL=https://api-dev.meguro.io \
   -e MEGURO_API_TOKEN=meg_sk_... \
   -e MEGURO_DASHBOARD_URL=https://... \
-  -- npx -y meguro-mcp@0.1.0
+  -- npx -y meguro-mcp@0.2.0
 ```
 
 ## Register — Cursor (`.cursor/mcp.json`)
@@ -115,7 +171,7 @@ claude mcp add meguro \
   "mcpServers": {
     "meguro": {
       "command": "npx",
-      "args": ["-y", "meguro-mcp@0.1.0"],
+      "args": ["-y", "meguro-mcp@0.2.0"],
       "env": {
         "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
         "MEGURO_API_TOKEN": "meg_sk_...",
@@ -136,6 +192,6 @@ npm test --workspace meguro-mcp
 ```
 
 The test suite packs the public artifact, installs it into a temporary clean-room project, starts the
-installed binary, and requires `tools/list` to return exactly 15 tools without leaking supplied
+installed binary, and requires `tools/list` to return exactly 43 tools without leaking supplied
 credentials to stdout or stderr. Maintainers should follow [RELEASING.md](./RELEASING.md) for every
 version; release notes are in [CHANGELOG.md](./CHANGELOG.md).

package/RELEASING.md

@@ -8,29 +8,42 @@ available from the public npm registry.
 
 1. Choose the next Semantic Versioning number.
 2. Update `version` in `package.json`, `SERVER_INFO.version` in `src/server.mjs`, the pinned
-   `MEGURO_MCP_PACKAGE` value in `packages/dashboard/src/console.js`, and `CHANGELOG.md` in one commit.
-3. From the repository root, run:
+   `MEGURO_MCP_PACKAGE` value in `packages/dashboard/src/console.js`, pinned README examples,
+   Console expectations, and `CHANGELOG.md` in one commit.
+3. Regenerate the README table from the server's actual `tools/list` response. Never add, remove,
+   summarize, or reorder tool rows by hand:
+
+   ```bash
+   npm run docs:tools --workspace meguro-mcp
+   ```
+
+4. From the exact commit intended for publication, run:
 
    ```bash
    npm test --workspace meguro-mcp
    npm run verify:publish --workspace meguro-mcp
-   npm pack --workspace meguro-mcp --dry-run
+   npm pack --workspace meguro-mcp --json
    ```
 
-4. Confirm npm authentication and the intended identity:
+   Record the commit SHA plus the pack result's filename, file count, unpacked size, SHA-512
+   integrity, and negative credential-leak result. The clean-room distribution test is the
+   authoritative expected tool count before publication; do not duplicate that count here.
+
+5. Stop at the worker handoff. The authenticated publisher confirms npm authentication and the
+   intended identity:
 
    ```bash
    npm whoami
    ```
 
-5. From `packages/meguro-mcp`, publish the exact version. npm will run the complete test suite and
+6. From `packages/meguro-mcp` at that exact commit, publish the exact version. npm will run the complete test suite and
    package validator through the package lifecycle before it uploads anything:
 
    ```bash
    npm publish --access public
    ```
 
-6. Verify the public artifact from a directory outside this repository:
+7. Verify the public artifact from a clean directory outside this repository:
 
    ```bash
    npm view meguro-mcp@<version> version dist.integrity
@@ -38,12 +51,13 @@ available from the public npm registry.
    ```
 
    For the protocol smoke, use the copy-ready Console configuration with a disposable workspace key
-   and confirm `tools/list` returns exactly 15 tools. Never put the key in shell history, logs, tickets,
-   or chat.
+   and confirm `tools/list` matches the authoritative expected count in the distribution test, every
+   tool carries a title and all four behavior annotations, `docs_read` is present, and
+   `resources/list` returns the versioned documentation resources. Never put the key in shell history,
+   logs, tickets, or chat.
 
-7. Only after the registry and clean-room checks pass, deploy the Console quickstart, tag the commit as
+8. Only after the registry and clean-room checks pass, deploy the Console quickstart, tag the commit as
    `meguro-mcp-v<version>`, and publish MCP directory listings.
 
 If any step fails, do not bump the Console pin, deploy the quickstart, tag the release, or publish a
 directory listing.
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meguro-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "description": "Meguro control-plane MCP server: drive worlds, runs, and verdicts from your own AI tools.",
@@ -22,6 +22,7 @@
   },
   "files": [
     "src/",
+    "scripts/generate-readme-tools.mjs",
     "scripts/verify-package.mjs",
     "README.md",
     "CHANGELOG.md",
@@ -36,6 +37,8 @@
   "scripts": {
     "pretest": "npm run build -w @meguro/core",
     "test": "node --test test/*.test.mjs",
+    "docs:tools": "node scripts/generate-readme-tools.mjs",
+    "docs:tools:check": "node scripts/generate-readme-tools.mjs --check",
     "verify:publish": "node scripts/verify-package.mjs",
     "prepack": "npm run verify:publish",
     "prepublishOnly": "npm test"

package/scripts/generate-readme-tools.mjs

@@ -0,0 +1,86 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const readmePath = join(root, 'README.md');
+const startMarker = '<!-- BEGIN GENERATED MCP TOOL TABLE -->';
+const endMarker = '<!-- END GENERATED MCP TOOL TABLE -->';
+
+function escapeCell(value) {
+  return String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+}
+
+function behaviorLabel(annotations) {
+  return [
+    annotations.readOnlyHint ? 'read-only' : 'read-write',
+    annotations.destructiveHint ? 'destructive' : 'non-destructive',
+    annotations.idempotentHint ? 'idempotent' : 'non-idempotent',
+    annotations.openWorldHint ? 'open-world' : 'closed-world',
+  ].join(' · ');
+}
+
+async function toolsList() {
+  const child = spawn(process.execPath, [join(root, 'src/server.mjs')], {
+    cwd: root,
+    env: {
+      ...process.env,
+      MEGURO_API_BASE_URL: 'https://api.example.invalid',
+      MEGURO_API_TOKEN: '',
+      MEGURO_DASHBOARD_URL: '',
+    },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  let stdout = '';
+  let stderr = '';
+  child.stdout.setEncoding('utf8');
+  child.stderr.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => { stdout += chunk; });
+  child.stderr.on('data', (chunk) => { stderr += chunk; });
+  child.stdin.end(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' })}\n`);
+  const exitCode = await new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('close', resolve);
+  });
+  assert.equal(exitCode, 0, `tools/list server exited ${exitCode}: ${stderr}`);
+  assert.equal(stderr, '', `tools/list server wrote to stderr: ${stderr}`);
+  const response = stdout.trim().split('\n').map((line) => JSON.parse(line)).find((message) => message.id === 1);
+  assert.ok(Array.isArray(response?.result?.tools), 'tools/list did not return a tools array');
+  return response.result.tools;
+}
+
+const tools = await toolsList();
+const rows = tools.map((tool) => {
+  assert.equal(typeof tool.name, 'string');
+  assert.equal(typeof tool.title, 'string', `${tool.name} is missing its title`);
+  assert.deepEqual(Object.keys(tool.annotations ?? {}).sort(), [
+    'destructiveHint', 'idempotentHint', 'openWorldHint', 'readOnlyHint',
+  ], `${tool.name} is missing behavior annotations`);
+  return `| \`${escapeCell(tool.name)}\` | ${escapeCell(tool.title)} | ${behaviorLabel(tool.annotations)} |`;
+});
+const generated = [
+  startMarker,
+  '<!-- Run `npm run docs:tools --workspace meguro-mcp` to refresh this section from `tools/list`. -->',
+  `This table is generated from the server's live \`tools/list\` response (${tools.length} tools).`,
+  '',
+  '| Tool | Title | Behavior annotations |',
+  '|---|---|---|',
+  ...rows,
+  endMarker,
+].join('\n');
+
+const readme = readFileSync(readmePath, 'utf8');
+const start = readme.indexOf(startMarker);
+const end = readme.indexOf(endMarker);
+assert.ok(start >= 0 && end > start, 'README generated tool-table markers are missing or out of order');
+const nextReadme = `${readme.slice(0, start)}${generated}${readme.slice(end + endMarker.length)}`;
+
+if (process.argv.includes('--check')) {
+  assert.equal(readme, nextReadme, 'README tool table is stale; run npm run docs:tools --workspace meguro-mcp');
+  console.log(`README tools/list table is current (${tools.length} tools)`);
+} else {
+  writeFileSync(readmePath, nextReadme);
+  console.log(`README tools/list table generated (${tools.length} tools)`);
+}

package/scripts/verify-package.mjs

@@ -1,4 +1,5 @@
 import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
 import { readFileSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -23,5 +24,7 @@ assert.match(readme, /SHOPIFY_ADMIN_ACCESS_TOKEN/);
 assert.match(readme, /store-scoped\s+data-plane credential/);
 assert.match(changelog, new RegExp(`## ${pkg.version.replaceAll('.', '\\.')}`));
 assert.match(releasing, /npm publish --access public/);
+assert.doesNotMatch(releasing, /exactly\s+\d+\s+tools/i, 'RELEASING must defer to the distribution test for the expected tool count');
+execFileSync(process.execPath, [join(root, 'scripts/generate-readme-tools.mjs'), '--check'], { stdio: 'inherit' });
 
 console.log(`meguro-mcp@${pkg.version} publish contract verified`);