meguro-mcp 0.2.10 → 0.2.13

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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
+  hosted OAuth/public STDIO control-plane authentication from the per-store Admin data plane.
+- Adds authority-derived `admin_schema` execution requirements for run state, the exact inventory
+  read-before-write cursor, valid next calls, and the two-root `@idempotent` contract.
+- Adds immutable getting-started v13, product-guide v10, and documentation-index v9 resources while
+  preserving every prior documentation byte and digest. This is a prepared package candidate only;
+  it is not published or deployed.
+
+## 0.2.11 — 2026-08-11
+
+- Adds registry-derived `admin_recipes_list` discovery without exposing tenant or store data or
+  executing Admin probes.
+- Adds bounded authored-alias teaching for recipe misses and schema-authority-derived root-type
+  recovery while preserving exact successful `admin_schema` lookup behavior.
+- Adds immutable getting-started v12 and documentation-index v8 resources for the discovery path;
+  every prior documentation resource remains byte-identical.
+
 ## 0.2.10 — 2026-08-10
 
 - Adds immutable getting-started v8, product-guide v5, and documentation-index v4 resources that

package/README.md

@@ -21,12 +21,15 @@ 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/v6` for the world-first operating sequence;
-for general Meguro questions, read `meguro://docs/product-guide/v3`. 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 44 customer-safe tools and deliberately excludes `admin_probe` and
-`admin_schema`. Active grants are visible and revocable under Console → Settings → Connection → MCP
+The hosted server exposes 39 customer-safe tools and deliberately excludes `admin_probe`. Active
+grants are visible and revocable under Console → Settings → Connection → MCP
 authorizations.
 
 ## Transport boundaries
@@ -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 (47 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 (47 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 (47 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 |
@@ -94,6 +93,8 @@ This table is generated from the server's live `tools/list` response (47 tools).
 | `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 |
+| `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
@@ -160,11 +161,11 @@ Use these tool names in order:
 
 1. `templates_list()` to discover the supported template keys.
 2. `stores_list()`, then reuse an owned store or call `store_create({ templateKey })`.
-3. `get_connection_details({ storeId })` through the explicit secure flow (`worldId` remains a legacy alias). Keep the returned values out of model/chat logs.
+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.
 
@@ -173,6 +174,12 @@ data-plane credential your commerce agent needs for the exact returned `*.meguro
 it as a secret, provide it only to that agent process, and keep it out of model/chat logs. It is not the
 account-scoped `MEGURO_API_TOKEN` and cannot control other stores or account resources.
 
+Hosted OAuth and the public package's `MEGURO_API_TOKEN` authenticate MCP/control-plane calls only.
+Admin GraphQL calls use the returned Admin URL and the per-store token in
+`X-Shopify-Access-Token`; never send the OAuth bearer to the Admin URL. Before one bounded write,
+read `admin_schema`'s `match.executionRequirements` for the required run state, any exact preflight
+read, valid next calls, and the authority-derived idempotency example.
+
 `manual`, `harness`, and `scheduled` are clock ownership modes. Raw Admin GraphQL requests do not each
 advance time. Practice-run status, checkpoint, and receipt responses deliberately exclude raw private
 evidence and credentials; `get_connection_details` is the one explicit credential-returning tool.
@@ -187,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.10
+npx -y meguro-mcp@0.2.13
 ```
 
 ### Environment
@@ -210,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.10
+  -- npx -y meguro-mcp@0.2.13
 ```
 
 ### Register — Cursor (`.cursor/mcp.json`)
@@ -220,7 +230,7 @@ claude mcp add meguro \
   "mcpServers": {
     "meguro": {
       "command": "npx",
-      "args": ["-y", "meguro-mcp@0.2.10"],
+      "args": ["-y", "meguro-mcp@0.2.13"],
       "env": {
         "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
         "MEGURO_API_TOKEN": "meg_sk_...",
@@ -240,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 46 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.10",
+  "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)`);
 }