meguro-mcp 0.2.12 → 0.2.13

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.13 — 2026-08-11
+
+- Preserves server-owned structured tier-enforcement facts, same-tier remedies, and conditional
+  Plans & Billing handoffs across MCP errors without quoting or inferring plan prices.
+- Keeps the existing tool registry and call shapes unchanged. This is a prepared package candidate
+  only; it is not published, tagged, or deployed.
+
 ## 0.2.12 — 2026-08-11
 
 - Adds a credential-safe, state-aware `adminExecutionGuide` to `get_connection_details`, separating

package/README.md

@@ -21,9 +21,12 @@ The configured hosted endpoints are environment-specific: dev uses
 `https://mcp-dev.meguro.io/mcp`, stage uses `https://mcp-stage.meguro.io/mcp`, and production uses
 `https://mcp.meguro.io/mcp`. Use the URL shown by the Console for the environment you intend to access.
 
-After connecting, read `meguro://docs/getting-started/v13` for the world-first operating sequence;
-for general Meguro questions, read `meguro://docs/product-guide/v10`. Both are available through
+<!-- BEGIN GENERATED MCP README CURRENT DOCUMENTATION -->
+<!-- Run `npm run docs:tools --workspace meguro-mcp` to refresh this section from documentation currency. -->
+After connecting, read `meguro://docs/getting-started/v39` for the world-first operating sequence;
+for general Meguro questions, read `meguro://docs/product-guide/v36`. Both are available through
 `resources/read` or the matching `docs_read({ topic, version })` fallback.
+<!-- END GENERATED MCP README CURRENT DOCUMENTATION -->
 
 The hosted server exposes 39 customer-safe tools and deliberately excludes `admin_probe`. Active
 grants are visible and revocable under Console → Settings → Connection → MCP
@@ -37,18 +40,19 @@ fallback, separate from the hosted Streamable HTTP OAuth endpoint.
 
 Practice stores separately expose a Storefront shopper/data-plane MCP endpoint at `https://<worldId>.meguro.io/api/mcp`. That endpoint is not this server and cannot start runs, reveal Admin connection details, inspect schemas, or collect receipts.
 
-Console provides fast trusted proof and evidence inspection; the agency agent normally remains in its own environment. A practice-store endpoint/token remains stable while commerce time moves through explicit run tools. Practice evidence is deterministic scenario simulation, not merchant forecasting. Console-proof actions are not credited to the agent, and Receipt Gate evidence is not public certification.
+Console provides fast trusted proof and evidence inspection; the agency agent normally remains in its own environment. A practice-store endpoint/token remains stable while commerce time moves through explicit run tools. Practice evidence is deterministic scenario simulation, not merchant forecasting. Console-proof actions are not credited to the agent, and Configured Receipt Gate evidence is not public certification.
 
 ## Tools
 
 <!-- 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 (48 tools).
+This table is generated from the server's live `tools/list` response (45 tools).
 
 | Tool | Title | Behavior annotations |
 |---|---|---|
 | `docs_read` | Read Meguro product and evidence documentation | read-only · non-destructive · idempotent · closed-world |
 | `templates_list` | List practice-store templates | read-only · non-destructive · idempotent · closed-world |
+| `template_get` | Read one practice-store template | 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 |
@@ -57,11 +61,6 @@ This table is generated from the server's live `tools/list` response (48 tools).
 | `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 |
@@ -73,9 +72,9 @@ This table is generated from the server's live `tools/list` response (48 tools).
 | `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 history-run receipts | read-only · non-destructive · idempotent · closed-world |
-| `gate_configure` | Configure the Receipt Gate | read-write · non-destructive · idempotent · closed-world |
-| `gate_evaluate` | Evaluate the Receipt Gate | read-write · non-destructive · non-idempotent · closed-world |
-| `gate_verdict` | Read a Gate verdict | read-only · non-destructive · idempotent · closed-world |
+| `gate_configure` | Configure Configured Receipt Gate | read-write · non-destructive · idempotent · closed-world |
+| `gate_evaluate` | Evaluate Configured Receipt Gate | read-write · non-destructive · non-idempotent · closed-world |
+| `gate_verdict` | Read Configured Receipt Gate verdict | read-only · non-destructive · idempotent · closed-world |
 | `runs_list` | List history 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 |
@@ -95,6 +94,7 @@ This table is generated from the server's live `tools/list` response (48 tools).
 | `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 |
 | `admin_recipes_list` | List Admin API recipes | read-only · non-destructive · idempotent · closed-world |
+| `plan_validate` | Check an intended Admin operation plan against Meguro | read-only · non-destructive · idempotent · closed-world |
 <!-- END GENERATED MCP TOOL TABLE -->
 
 ## Documentation resources
@@ -164,8 +164,8 @@ Use these tool names in order:
 3. `get_connection_details({ storeId })` through the explicit secure flow (`worldId` remains a legacy alias). Follow its structured `adminExecutionGuide`; keep returned credential values out of model/chat logs.
 4. `practice_run_start({ storeId, clock: { mode: "harness", simulationDays: 14, stepDays: 1 } })` — the same `storeId` the previous step took and returned.
 5. Launch the agency agent in its own environment with the stable returned `SHOPIFY_*` values.
-6. `practice_run_status({ attemptId })`, then `practice_run_checkpoint({ attemptId })`.
-7. `practice_run_advance({ attemptId, days: 1, expectedDay, expectedCallSeq })`, using the exact current state cursors. Supply `until` instead of `days` for a supported event stop.
+6. `practice_run_status({ attemptId })`, then `practice_run_checkpoint({ attemptId })`; retain the exact returned `practiceRun.advanceCursor`.
+7. `practice_run_advance({ attemptId, days: 1, advanceCursor })`, copying that object unchanged. Supply `until` instead of `days` for a supported event stop. Legacy flat `expectedDay` and `expectedCallSeq` remain accepted together.
 8. Inspect the aligned checkpoint evidence in Console or the run APIs.
 9. `practice_run_finish({ attemptId })`, then `practice_run_report({ attemptId })` for the run's receipt.
 
@@ -194,12 +194,15 @@ See [the agency quickstart](../../docs/agency-practice-run-quickstart.md) and [H
 
 ## Advanced: CI or local STDIO
 
+<!-- BEGIN GENERATED MCP README LOCAL TOOL COUNT -->
+<!-- Run `npm run docs:tools --workspace meguro-mcp` to refresh this section from `tools/list`. -->
 Use the public STDIO package for CI, local automation, or clients without hosted Streamable HTTP and
-OAuth support. It requires a workspace-bound `meg_sk_…` API key and exposes the full 47-tool local
+OAuth support. It requires a workspace-bound `meg_sk_…` API key and exposes the full 45-tool local
 surface. Pin the exact public version in client configuration so a quickstart stays reproducible:
+<!-- END GENERATED MCP README LOCAL TOOL COUNT -->
 
 ```bash
-npx -y meguro-mcp@0.2.12
+npx -y meguro-mcp@0.2.13
 ```
 
 ### Environment
@@ -217,7 +220,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.2.12
+  -- npx -y meguro-mcp@0.2.13
 ```
 
 ### Register — Cursor (`.cursor/mcp.json`)
@@ -227,7 +230,7 @@ claude mcp add meguro \
   "mcpServers": {
     "meguro": {
       "command": "npx",
-      "args": ["-y", "meguro-mcp@0.2.12"],
+      "args": ["-y", "meguro-mcp@0.2.13"],
       "env": {
         "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
         "MEGURO_API_TOKEN": "meg_sk_...",
@@ -247,7 +250,10 @@ seed `bfcm-regression`, and give me the dashboard link."*
 npm test --workspace meguro-mcp
 ```
 
+<!-- BEGIN GENERATED MCP README DISTRIBUTION TOOL COUNT -->
+<!-- Run `npm run docs:tools --workspace meguro-mcp` to refresh this section from `tools/list`. -->
 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 48 tools without leaking supplied
+installed binary, and requires `tools/list` to return exactly 45 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).
+<!-- END GENERATED MCP README DISTRIBUTION TOOL COUNT -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meguro-mcp",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "private": false,
   "type": "module",
   "description": "Meguro control-plane MCP server: drive worlds, runs, and verdicts from your own AI tools.",

package/scripts/generate-readme-tools.mjs

@@ -3,11 +3,18 @@ import { spawn } from 'node:child_process';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { documentationResources, documentationToolContract } from '../src/docs.mjs';
 
 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 -->';
+const toolTableStartMarker = '<!-- BEGIN GENERATED MCP TOOL TABLE -->';
+const toolTableEndMarker = '<!-- END GENERATED MCP TOOL TABLE -->';
+const currentDocumentationStartMarker = '<!-- BEGIN GENERATED MCP README CURRENT DOCUMENTATION -->';
+const currentDocumentationEndMarker = '<!-- END GENERATED MCP README CURRENT DOCUMENTATION -->';
+const localToolCountStartMarker = '<!-- BEGIN GENERATED MCP README LOCAL TOOL COUNT -->';
+const localToolCountEndMarker = '<!-- END GENERATED MCP README LOCAL TOOL COUNT -->';
+const distributionToolCountStartMarker = '<!-- BEGIN GENERATED MCP README DISTRIBUTION TOOL COUNT -->';
+const distributionToolCountEndMarker = '<!-- END GENERATED MCP README DISTRIBUTION TOOL COUNT -->';
 
 function escapeCell(value) {
   return String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
@@ -51,6 +58,23 @@ async function toolsList() {
   return response.result.tools;
 }
 
+function currentDocumentationUri(topic) {
+  const version = documentationToolContract().currentByTopic[topic];
+  const resource = documentationResources().find((candidate) => (
+    candidate?._meta?.['meguro/topic'] === topic
+    && candidate?._meta?.['meguro/version'] === version
+  ));
+  assert.ok(resource, `Documentation currency has no published ${topic} resource at v${version}`);
+  return resource.uri;
+}
+
+function replaceGeneratedSection(readme, startMarker, endMarker, generated) {
+  const start = readme.indexOf(startMarker);
+  const end = readme.indexOf(endMarker);
+  assert.ok(start >= 0 && end > start, `README generated section ${startMarker} is missing or out of order`);
+  return `${readme.slice(0, start)}${generated}${readme.slice(end + endMarker.length)}`;
+}
+
 const tools = await toolsList();
 const rows = tools.map((tool) => {
   assert.equal(typeof tool.name, 'string');
@@ -60,27 +84,58 @@ const rows = tools.map((tool) => {
   ], `${tool.name} is missing behavior annotations`);
   return `| \`${escapeCell(tool.name)}\` | ${escapeCell(tool.title)} | ${behaviorLabel(tool.annotations)} |`;
 });
-const generated = [
-  startMarker,
+const generatedToolTable = [
+  toolTableStartMarker,
   '<!-- 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,
+  toolTableEndMarker,
+].join('\n');
+const gettingStartedUri = currentDocumentationUri('getting-started');
+const productGuideUri = currentDocumentationUri('product-guide');
+const generatedCurrentDocumentation = [
+  currentDocumentationStartMarker,
+  '<!-- Run `npm run docs:tools --workspace meguro-mcp` to refresh this section from documentation currency. -->',
+  `After connecting, read \`${gettingStartedUri}\` for the world-first operating sequence;`,
+  `for general Meguro questions, read \`${productGuideUri}\`. Both are available through`,
+  '`resources/read` or the matching `docs_read({ topic, version })` fallback.',
+  currentDocumentationEndMarker,
+].join('\n');
+const generatedLocalToolCount = [
+  localToolCountStartMarker,
+  '<!-- Run `npm run docs:tools --workspace meguro-mcp` to refresh this section from `tools/list`. -->',
+  'Use the public STDIO package for CI, local automation, or clients without hosted Streamable HTTP and',
+  `OAuth support. It requires a workspace-bound \`meg_sk_…\` API key and exposes the full ${tools.length}-tool local`,
+  'surface. Pin the exact public version in client configuration so a quickstart stays reproducible:',
+  localToolCountEndMarker,
+].join('\n');
+const generatedDistributionToolCount = [
+  distributionToolCountStartMarker,
+  '<!-- Run `npm run docs:tools --workspace meguro-mcp` to refresh this section from `tools/list`. -->',
+  '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 ${tools.length} 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).',
+  distributionToolCountEndMarker,
 ].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)}`;
+const nextReadme = [
+  [toolTableStartMarker, toolTableEndMarker, generatedToolTable],
+  [currentDocumentationStartMarker, currentDocumentationEndMarker, generatedCurrentDocumentation],
+  [localToolCountStartMarker, localToolCountEndMarker, generatedLocalToolCount],
+  [distributionToolCountStartMarker, distributionToolCountEndMarker, generatedDistributionToolCount],
+].reduce((current, [startMarker, endMarker, generated]) => (
+  replaceGeneratedSection(current, startMarker, endMarker, generated)
+), readme);
 
 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)`);
+  assert.equal(readme, nextReadme, 'README generated MCP claims are stale; run npm run docs:tools --workspace meguro-mcp');
+  console.log(`README generated MCP claims are current (${tools.length} tools)`);
 } else {
   writeFileSync(readmePath, nextReadme);
-  console.log(`README tools/list table generated (${tools.length} tools)`);
+  console.log(`README generated MCP claims refreshed (${tools.length} tools)`);
 }