meguro-mcp 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
 
+## 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,20 +9,31 @@ 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, new evaluators should read `meguro://docs/getting-started/v1`; agents answering
+general Meguro questions should read `meguro://docs/product-guide/v1`. Both are available through
+`resources/read` and the matching `docs_read` topic.
 
-## Transport and entry point
+The hosted server exposes 42 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.
 
@@ -36,7 +47,7 @@ This table is generated from the server's live `tools/list` response (44 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 |
@@ -87,10 +98,13 @@ 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/getting-started/v1` | `afd19ca6576ae2a8fb03c2e143d25d47fb739682f44180541dd13f779a5f29df` |
+| `meguro://docs/product-guide/v1` | `e5450c1b4181cec4d6ed0a498dbff1cb25d2e223ff2228928aecbbce9674f074` |
+| `meguro://docs/receipt-guide/v1` | `9d8150258765d252cb7cc3bad307acdc429b0435ca22f0362b69cf7471e3a333` |
+| `meguro://docs/receipt-guide/v2` | `7df261021b48ce732e6043a8917f8a2673b1f83ff1d8790927abc18f34fb3f6f` |
 
 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.
@@ -150,7 +164,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 44-tool local
+surface. Pin the exact public version in client configuration so a quickstart stays reproducible:
+
+```bash
+npx -y meguro-mcp@0.2.5
+```
+
+### Environment
 
 ```
 MEGURO_API_BASE_URL=https://api-dev.meguro.io
@@ -158,24 +182,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.5
 ```
 
-## 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.5"],
       "env": {
         "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
         "MEGURO_API_TOKEN": "meg_sk_...",

package/RELEASING.md

@@ -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 the `0.2.5` candidate, also record the five-resource `resources/list` result, the pinned
+   product-guide SHA-256 digest, and proof that the four earlier resource bytes and digests remain
+   unchanged.
+
 5. Stop at the worker handoff. The authenticated publisher confirms npm authentication and the
    intended identity:
 

package/package.json

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

package/src/docs.mjs

@@ -4,12 +4,15 @@ const RECEIPT_GUIDE_VERSION = 1;
 const RECEIPT_GUIDE_LATEST_VERSION = 2;
 const GATE_POLICY_VERSION = 1;
 const GETTING_STARTED_VERSION = 1;
+const PRODUCT_GUIDE_VERSION = 1;
 const RECEIPT_GUIDE_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_VERSION}`;
 const RECEIPT_GUIDE_LATEST_URI = `meguro://docs/receipt-guide/v${RECEIPT_GUIDE_LATEST_VERSION}`;
 const GATE_POLICY_URI = `meguro://docs/gate-policy/v${GATE_POLICY_VERSION}`;
 const GETTING_STARTED_URI = `meguro://docs/getting-started/v${GETTING_STARTED_VERSION}`;
+const PRODUCT_GUIDE_URI = `meguro://docs/product-guide/v${PRODUCT_GUIDE_VERSION}`;
 
-export const GETTING_STARTED_INSTRUCTIONS = 'New to Meguro? Read `meguro://docs/getting-started/v1` with `resources/read`, or call `docs_read({ topic: "getting-started", version: 1 })`, before starting for the exact tool sequence from template discovery to receipt.';
+export const MCP_INITIALIZE_INSTRUCTIONS = 'New evaluators: read `meguro://docs/getting-started/v1`; general Meguro questions: read `meguro://docs/product-guide/v1`.';
+export const PRODUCT_GUIDE_SHA256 = 'e5450c1b4181cec4d6ed0a498dbff1cb25d2e223ff2228928aecbbce9674f074';
 
 function deepFreeze(value) {
   if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
@@ -810,8 +813,94 @@ All published documentation resources are immutable. Cite the exact URI, version
 digest returned by Meguro.
 `;
 
+const PRODUCT_GUIDE_TEXT = `# Meguro product guide v1
+
+Published URI: \`${PRODUCT_GUIDE_URI}\`
+
+## What Meguro is—and is not
+
+Meguro is a technical evaluation environment for commerce agents. Its core product primitives are
+practice stores, deterministic Store time, recorded API behavior, immutable receipts, and Gate
+evidence.
+
+Practice results do not prove live-market demand, future revenue, production performance, or live
+Shopify acceptance. Live-platform claims are established only by the relevant real-platform or
+Shopify Exam evidence; never infer them from practice compatibility or modeled outcomes.
+
+## Core nouns
+
+- **Template:** a supported, versioned starting scenario used to create a practice store.
+- **Practice store / \`storeId\`:** an owned synthetic commerce environment and its canonical public
+  identifier. It is not a merchant's production store.
+- **Store time:** the deterministic scenario clock advanced through the run lifecycle. It is distinct
+  from wall-clock request time.
+- **Run / \`attemptId\`:** one bounded evaluation window and the identifier used by its lifecycle,
+  status, and evidence tools.
+- **Receipt:** the immutable record of what the agent called, what was accepted or rejected, and what
+  the declared evidence establishes. For field-level interpretation, read
+  \`meguro://docs/receipt-guide/v1\` or \`meguro://docs/receipt-guide/v2\`.
+- **Modeled outcome / Impact context:** scenario-derived context that compares recorded behavior with
+  a declared model. It is not a merchant forecast, causal claim, or production result.
+- **Gate:** a release signal computed from named receipt facts, thresholds, and precedence. For the
+  exact policy, read \`meguro://docs/gate-policy/v1\`.
+- **Shopify Exam:** a captured API-shape fidelity exam against an eligible Shopify development store.
+  Its evidence establishes only the bounded live-platform facts recorded by that exam, not blanket
+  Shopify acceptance or merchant outcomes.
+
+## Product surfaces and boundaries
+
+- **Console** provides visual setup, receipt inspection, account administration, client revocation,
+  plans, billing, and payment actions.
+- **Hosted OAuth MCP** is the recommended control plane for interactive agents.
+- **Public STDIO MCP** is the local and CI fallback.
+- **Practice-store Admin endpoint** is the Shopify-shaped data plane used by the commerce agent under
+  evaluation; it is separate from the MCP control plane.
+- **MCP does not perform money actions:** it does not check out, buy or change a subscription, manage
+  payment methods, or make another payment.
+
+## Question-to-source routing
+
+| User asks | Agent must do |
+|---|---|
+| What is Meguro or what does it prove? | Answer from this product guide and preserve its evidence boundary. |
+| How do I start an evaluation? | Read \`meguro://docs/getting-started/v1\`. |
+| What does this receipt or verdict mean? | Read the appropriate receipt guide and \`meguro://docs/gate-policy/v1\`. |
+| What stores exist? | Call \`stores_list\`. |
+| What runs exist or what happened? | Call \`runs_list\` and the relevant status, report, or impact tool. |
+| What workspaces exist? | Call \`workspaces_list\`. |
+| What is my current usage or cap? | Call \`usage_read\`; do not answer from static values. |
+| Which templates are available? | Call \`templates_list\`. |
+| How much does a plan cost, or how do I subscribe or change plans? | Direct the user to Console → Plans & Billing. Do not quote immutable pricing or attempt payment through MCP. |
+| How do I manage or revoke an MCP connection? | Direct the user to Console → Connection → MCP authorizations. |
+| How do I delete my account? | Direct the user to the Console-only account-deletion flow and [Meguro Help](https://meguro.io/help.html). |
+| Where can I learn more or get support? | Use [Meguro Help](https://meguro.io/help.html) or [hello@meguro.io](mailto:hello@meguro.io); do not invent another location. |
+
+## Answering discipline
+
+- Use live MCP tools for user-, workspace-, store-, run-, usage-, and template-specific facts.
+- Use immutable guides for stable concepts and evidence interpretation.
+- Use Console for money actions and explicitly Console-only account actions.
+- Never infer an undocumented capability, price, limit, legal conclusion, Shopify acceptance, or
+  merchant outcome.
+- If neither an in-band document nor a tool result establishes the answer, say that it is not
+  established and direct the user to Meguro Help or support.
+
+## Stable concepts versus changing facts
+
+Do not hardcode plan prices, current tier allowances, trial length, supported-country lists, current
+account state, or current fleet state. Read changing values from the appropriate live tool or the
+canonical Console surface.
+
+Do not reproduce or interpret legal terms. Link to the canonical [Terms](https://meguro.io/terms) and
+[Privacy Notice](https://meguro.io/privacy).
+`;
+
 function entry(input) {
   const text = String(input.text);
+  const digest = sha256(text);
+  if (input.expectedSha256 && input.expectedSha256 !== digest) {
+    throw new Error(`Documentation digest drift for ${input.uri}: expected ${input.expectedSha256}, received ${digest}`);
+  }
   return deepFreeze({
     topic: input.topic,
     version: input.version,
@@ -821,7 +910,7 @@ function entry(input) {
     description: input.description,
     mimeType: 'text/markdown',
     text,
-    sha256: sha256(text),
+    sha256: digest,
   });
 }
 
@@ -875,6 +964,16 @@ const CATALOG = buildDocumentationCatalog([
     description: 'Discovery-first technical-evaluator sequence from template selection through an immutable practice receipt.',
     text: GETTING_STARTED_TEXT,
   },
+  {
+    topic: 'product-guide',
+    version: PRODUCT_GUIDE_VERSION,
+    uri: PRODUCT_GUIDE_URI,
+    name: 'Meguro product guide v1',
+    title: 'Meguro product guide v1',
+    description: 'Stable product concepts, evidence boundaries, surface responsibilities, and question-to-source routing.',
+    text: PRODUCT_GUIDE_TEXT,
+    expectedSha256: PRODUCT_GUIDE_SHA256,
+  },
   {
     topic: 'receipt-guide',
     version: RECEIPT_GUIDE_VERSION,

package/src/server.mjs

@@ -4,10 +4,10 @@
 // tools/call, resources/list, resources/read, ping) is small and stable; no lockfile churn, no build step.
 
 import { createInterface } from 'node:readline';
-import { GETTING_STARTED_INSTRUCTIONS, documentationResource, documentationResources } from './docs.mjs';
+import { MCP_INITIALIZE_INSTRUCTIONS, documentationResource, documentationResources } from './docs.mjs';
 import { createTools, redactSecrets } from './tools.mjs';
 
-const SERVER_INFO = { name: 'meguro', version: '0.2.4' };
+const SERVER_INFO = { name: 'meguro', version: '0.2.5' };
 const PROTOCOL_VERSION = '2025-03-26';
 
 const tools = createTools({
@@ -38,7 +38,7 @@ async function handle(message) {
         protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : PROTOCOL_VERSION,
         capabilities: { tools: {}, resources: { listChanged: false } },
         serverInfo: SERVER_INFO,
-        instructions: GETTING_STARTED_INSTRUCTIONS,
+        instructions: MCP_INITIALIZE_INSTRUCTIONS,
       });
     case 'notifications/initialized':
     case 'notifications/cancelled':

package/src/tools.mjs

@@ -53,7 +53,7 @@ const TOOL_PRESENTATION = Object.freeze({
   runs_list: { title: 'List runs', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   usage_read: { title: 'Read usage headroom', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   twin_diff: { title: 'Read a twin impact receipt', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-  docs_read: { title: 'Read Meguro receipt and Gate documentation', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  docs_read: { title: 'Read Meguro product and evidence documentation', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   exam_preflight: { title: 'Check Shopify Exam readiness', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   exam_start: { title: 'Start or continue a Shopify Exam', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   exam_status: { title: 'Read Shopify Exam status', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
@@ -1037,20 +1037,20 @@ export function createTools(config) {
   const rawDefinitions = [
     {
       name: 'docs_read',
-      description: 'Read Meguro customer documentation in-band. Topics: getting-started version 1 (the exact discovery-first evaluator sequence), receipt-guide versions 1 and 2 (immutable receipt interpretation), and gate-policy version 1 (immutable named checks, receipt facts, thresholds, precedence, flip conditions, and self-gating). Account deletion is deliberately not an MCP tool. Pass the exact published version so cited documentation never resolves to mutable latest content.',
+      description: 'Read immutable Meguro product and evidence documentation in-band. Topics: getting-started version 1 (discovery-first evaluator sequence), product-guide version 1 (stable concepts, evidence boundaries, surfaces, and question routing), receipt-guide versions 1 and 2 (receipt interpretation), and gate-policy version 1 (named checks, thresholds, precedence, and self-gating). Account deletion is deliberately not an MCP tool. Pass the exact published version so cited documentation never resolves to mutable latest content.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
         properties: {
           topic: {
             type: 'string',
-            enum: ['getting-started', 'receipt-guide', 'gate-policy'],
-            description: 'getting-started, receipt-guide, or gate-policy.',
+            enum: ['getting-started', 'product-guide', 'receipt-guide', 'gate-policy'],
+            description: 'getting-started, product-guide, receipt-guide, or gate-policy.',
           },
           version: {
             type: 'integer',
             enum: [1, 2],
-            description: 'Published immutable document version. Getting started and Gate policy have version 1; Receipt guide has versions 1 and 2.',
+            description: 'Published immutable document version. Getting started, Product guide, and Gate policy have version 1; Receipt guide has versions 1 and 2.',
           },
         },
         required: ['topic', 'version'],
@@ -1620,8 +1620,8 @@ export function createTools(config) {
       switch (name) {
         case 'docs_read': {
           const topic = requiredString(args, 'topic');
-          if (!['getting-started', 'receipt-guide', 'gate-policy'].includes(topic)) {
-            throw new Error('topic must be getting-started, receipt-guide, or gate-policy');
+          if (!['getting-started', 'product-guide', 'receipt-guide', 'gate-policy'].includes(topic)) {
+            throw new Error('topic must be getting-started, product-guide, receipt-guide, or gate-policy');
           }
           if (!Number.isSafeInteger(args.version) || args.version < 1) {
             throw new Error('version must be the exact published positive integer');