meguro-mcp 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.6 — 2026-08-08
+
+- Adds immutable `meguro://docs/getting-started/v6` and `meguro://docs/product-guide/v3` resources
+  that lead with the practice world, Store time, and the receipt as the store's memory of a run.
+- Keeps the executable discovery sequence and evidence boundaries while stating which account,
+  plan, OAuth, and workspace-key actions require the human.
+- Gives both resource URIs and `docs_read` fallbacks in the initialization instructions, with no
+  default evaluator address.
+- Consolidates the current 46-tool source. Against public 0.2.5, 23 definitions remain byte-identical,
+  21 carry already-landed contracts, and the exact new identities are `gate_configure` plus
+  `gate_evaluate`. This release changes no base tool contract except registry-derived `docs_read`
+  metadata for the two new immutable guides.
+
+## 0.2.5 — 2026-08-02
+
+- Adds the immutable `meguro://docs/product-guide/v1` resource and matching `product-guide`
+  `docs_read` topic for stable product concepts, evidence boundaries, and question routing.
+- Expands `docs_read` metadata from receipt-and-Gate-only wording to general Meguro documentation
+  while retaining the existing tool identity and behavior annotations.
+- Directs new evaluators to Getting Started and general Meguro questions to Product Guide through
+  byte-identical public and hosted initialize instructions.
+- Keeps the public registry at exactly 44 tools, the hosted registry at exactly 42 remote-safe tools,
+  and all four previously published documentation byte streams and digests unchanged.
+
 ## 0.2.4 — 2026-08-02
 
 - Adds the immutable `meguro://docs/getting-started/v1` resource and matching `getting-started`

package/README.md

@@ -9,34 +9,45 @@ This is the **control plane** (world/run management, for the developer's tools).
 
 Dependency-free, no build step: the server is plain Node ≥ 20.
 
-## Install and run
+## Recommended: hosted Streamable HTTP + OAuth
 
-Customer MCP clients run the exact public version directly from npm:
+For an interactive client that supports Streamable HTTP and browser OAuth, open Meguro Console → Settings →
+Connection and copy the hosted MCP URL for that environment. Add it as a Streamable HTTP MCP server,
+save or restart if the client asks, then choose Authenticate. Your browser opens so you can sign in to
+Meguro and authorize the requested access. The default path needs no API key, environment variable,
+package command, or pasted token.
 
-```bash
-npx -y meguro-mcp@0.2.4
-```
+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.
 
-Pin the version in client configuration. A pinned quickstart stays reproducible and never changes its
-tool contract because npm published a newer release.
+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
+`resources/read` or the matching `docs_read({ topic, version })` fallback.
 
-## Transport and entry point
+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
+authorizations.
 
-The public control-plane MCP server is the local stdio command shown below. It speaks newline-delimited JSON-RPC over stdin/stdout and uses `MEGURO_API_BASE_URL` plus `MEGURO_API_TOKEN` for its authenticated HTTP calls. There is no control-plane `POST ${MEGURO_API_BASE_URL}/mcp` endpoint.
+## Transport boundaries
+
+The public package speaks newline-delimited JSON-RPC over stdin/stdout and uses
+`MEGURO_API_BASE_URL` plus `MEGURO_API_TOKEN` for its authenticated HTTP calls. It is the local/CI
+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 rehearsal, not merchant forecasting. Console-proof actions are not credited to the agent, and Release 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 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 (44 tools).
+This table is generated from the server's live `tools/list` response (46 tools).
 
 | Tool | Title | Behavior annotations |
 |---|---|---|
-| `docs_read` | Read Meguro receipt and Gate documentation | read-only · non-destructive · idempotent · closed-world |
+| `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 |
 | `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 |
@@ -61,9 +72,11 @@ This table is generated from the server's live `tools/list` response (44 tools).
 | `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 |
+| `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 |
-| `runs_list` | List runs | 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 |
 | `exam_preflight` | Check Shopify Exam readiness | read-only · non-destructive · idempotent · open-world |
@@ -87,10 +100,26 @@ This table is generated from the server's live `tools/list` response (44 tools).
 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`
-- `meguro://docs/getting-started/v1`
+| Resource | SHA-256 |
+|---|---|
+| `meguro://docs/gate-policy/v1` | `6d647b3c78fd4e2d93f59a85b90a853096cc73e9cdfd6ba5e3ea505dc07b4aaf` |
+| `meguro://docs/gate-policy/v2` | `e49378fd745f71aab893db34864aefeb7345c9a25000ad328dfba4e44d007469` |
+| `meguro://docs/getting-started/v1` | `afd19ca6576ae2a8fb03c2e143d25d47fb739682f44180541dd13f779a5f29df` |
+| `meguro://docs/getting-started/v2` | `70fdbf36d68a6dd7abb93fe9b403f85c9c0323b3dc3472ab638c6cbe5982ec61` |
+| `meguro://docs/getting-started/v3` | `765cba2b68806f0b1d83255a1742d83ce71ebf7f65f8095e7076cd36e4a1ba6c` |
+| `meguro://docs/getting-started/v4` | `db534eb544e414be353d6cd4db8dfb9e8dba772dcb10d8287a1a27f8736e5307` |
+| `meguro://docs/getting-started/v5` | `156dcf81266f2bd4e4203dbd09661e49a481395ba4a63528f0540d8ea89bc285` |
+| `meguro://docs/getting-started/v6` | `34cf3ab48a32714b0c3edb24a7920843954172c0d5501e60574adc5a1058071f` |
+| `meguro://docs/product-guide/v1` | `e5450c1b4181cec4d6ed0a498dbff1cb25d2e223ff2228928aecbbce9674f074` |
+| `meguro://docs/product-guide/v2` | `b15590df7699f7ad685a30b0698e2c25b5b7b1531afa4e43e9f04a4b38ab9db2` |
+| `meguro://docs/product-guide/v3` | `8dc9e0fae91a2433ea7ca02b9278484250be0d336e2daac96f949da577487dc9` |
+| `meguro://docs/receipt-guide/v1` | `9d8150258765d252cb7cc3bad307acdc429b0435ca22f0362b69cf7471e3a333` |
+| `meguro://docs/receipt-guide/v2` | `7df261021b48ce732e6043a8917f8a2673b1f83ff1d8790927abc18f34fb3f6f` |
+| `meguro://docs/receipt-guide/v3` | `c76b823aed8187834c8ae79a751b53d2720fe7245a31b0b195f440deac9b75cb` |
+| `meguro://docs/receipt-guide/v4` | `4a754c5d2de9899ffaafb704e8174617c9c3dc4aa7c4588811a2a0f37faa9133` |
+| `meguro://docs/receipt-guide/v5` | `b3b3c83390b1a95ab9e0ec926fb84010070e703cd3a3cef8cecd9fef1c50adfe` |
+| `meguro://docs/receipt-guide/v6` | `bda3ef240bdf5e6ca075bd00e51253d5d574621cb3feabf11c070aaf7e40ede2` |
+| `meguro://docs/receipt-guide/v7` | `6dba5de1130382c77cccd4be117c002e531863955dea85d4950b36eeb8ecb6fd` |
 
 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.
@@ -131,7 +160,6 @@ Use these tool names in order:
 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.
 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.
-10. Optionally execute an immutable temporal probe-set revision through the HTTP surface and inspect/export it in Gate.
 
 `get_connection_details` deliberately returns `SHOPIFY_ADMIN_ACCESS_TOKEN`: it is the store-scoped
 data-plane credential your commerce agent needs for the exact returned `*.meguro.io` Admin URL. Treat
@@ -150,7 +178,17 @@ node byo-ci-test/phase7-snippets.mjs mcp
 
 See [the agency quickstart](../../docs/agency-practice-run-quickstart.md) and [HTTP reference](../../docs/practice-run-http-api.md).
 
-## Environment
+## Advanced: CI or local STDIO
+
+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 46-tool local
+surface. Pin the exact public version in client configuration so a quickstart stays reproducible:
+
+```bash
+npx -y meguro-mcp@0.2.6
+```
+
+### Environment
 
 ```
 MEGURO_API_BASE_URL=https://api-dev.meguro.io
@@ -158,24 +196,24 @@ MEGURO_API_TOKEN=<meg_sk account key from Console → Settings>
 MEGURO_DASHBOARD_URL=https://<dashboard-distribution>.cloudfront.net   # optional, enables dashboard links
 ```
 
-## Register — Claude Code
+### Register — Claude Code
 
 ```bash
 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.4
+  -- npx -y meguro-mcp@0.2.6
 ```
 
-## Register — Cursor (`.cursor/mcp.json`)
+### Register — Cursor (`.cursor/mcp.json`)
 
 ```json
 {
   "mcpServers": {
     "meguro": {
       "command": "npx",
-      "args": ["-y", "meguro-mcp@0.2.4"],
+      "args": ["-y", "meguro-mcp@0.2.6"],
       "env": {
         "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
         "MEGURO_API_TOKEN": "meg_sk_...",
@@ -196,6 +234,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 44 tools without leaking supplied
+installed binary, and requires `tools/list` to return exactly 46 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

@@ -7,9 +7,9 @@ available from the public npm registry.
 ## Release checklist
 
 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`, pinned README examples,
-   Console expectations, and `CHANGELOG.md` in one commit.
+2. Update `version` in `package.json`, `SERVER_INFO.version` in `src/server.mjs`, pinned README
+   examples, and `CHANGELOG.md` in one commit. The Console build derives its exact package spec
+   from `package.json`; do not add a second version literal to Console source or tests.
 3. Regenerate the README table from the server's actual `tools/list` response. Never add, remove,
    summarize, or reorder tool rows by hand:
 
@@ -29,6 +29,10 @@ available from the public npm registry.
    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.
 
+   For a documentation release, also record the resource count derived from `resources/list`, the
+   new immutable URI and SHA-256 pairs, and proof that every earlier resource byte stream and digest
+   remains unchanged. Record any registry delta against the preceding public artifact explicitly.
+
 5. Stop at the worker handoff. The authenticated publisher confirms npm authentication and the
    intended identity:
 
@@ -56,8 +60,9 @@ available from the public npm registry.
    `resources/list` returns the versioned documentation resources. Never put the key in shell history,
    logs, tickets, or chat.
 
-8. 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, build and deploy the manifest-derived 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
+If any step fails, do not deploy the quickstart, tag the release, or publish a
 directory listing.

package/package.json

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

package/src/admin-versions.generated.mjs

@@ -0,0 +1,32 @@
+// Generated by scripts/generate-shopify-served-version-corpora.mjs from the reviewed served-version config.
+// Do not hand-edit this file; change the configuration/corpus artifacts and regenerate.
+
+export const ADMIN_API_DEFAULT_VERSION = "2026-07";
+export const ADMIN_API_CONFIGURED_VERSION_REGISTRY = Object.freeze([
+  {
+    "apiVersion": "2026-04",
+    "releaseDate": "2026-04-01T17:00:00.000Z",
+    "supportedUntil": "2027-04-16T15:00:00.000Z",
+    "supportSourceUrl": "https://shopify.dev/docs/api/usage/versioning"
+  },
+  {
+    "apiVersion": "2026-07",
+    "releaseDate": "2026-07-01T17:00:00.000Z",
+    "supportedUntil": "2027-07-16T15:00:00.000Z",
+    "supportSourceUrl": "https://shopify.dev/docs/api/usage/versioning"
+  }
+]);
+
+export function deriveAdminApiVersionRegistry(entries, at = new Date()) {
+  const instant = at instanceof Date ? at.getTime() : Date.parse(String(at));
+  if (!Number.isFinite(instant)) throw new Error('Admin API version policy requires a valid instant');
+  return Object.freeze(entries.map((entry) => Object.freeze({
+    ...entry,
+    lifecycle: instant < Date.parse(entry.supportedUntil) ? 'active' : 'retired',
+  })));
+}
+
+export const ADMIN_API_VERSION_REGISTRY = deriveAdminApiVersionRegistry(ADMIN_API_CONFIGURED_VERSION_REGISTRY);
+export const ADMIN_API_SUPPORTED_VERSIONS = Object.freeze(ADMIN_API_VERSION_REGISTRY.filter((entry) => entry.lifecycle === 'active').map((entry) => entry.apiVersion));
+if (!ADMIN_API_SUPPORTED_VERSIONS.includes(ADMIN_API_DEFAULT_VERSION)) throw new Error("The default Admin API version is outside Shopify's published support window.");
+export const ADMIN_API_SUPPORTED_VERSION_LABEL = ADMIN_API_SUPPORTED_VERSIONS.join(' and ');