meguro-mcp 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.4 — 2026-08-02
+
+- Adds the immutable `meguro://docs/getting-started/v1` resource and matching `getting-started`
+  `docs_read` topic with the exact discovery-first evaluator workflow.
+- Adds concise MCP `initialize.instructions` that directs new clients to the same in-band guide.
+- Keeps the public registry at exactly 44 tools and preserves every non-documentation tool contract.
+
+## 0.2.3 — 2026-08-01
+
+- Adds `templates_list`, a read-only closed-world projection of the ordered practice-store template
+  catalog, so customers can discover supported templates without duplicating registry data.
+- Preserves only the documented public template fields and excludes profiles, scenario presets,
+  credentials, and private route payload from MCP responses.
+- Pins Console connection guidance to the exact `meguro-mcp@0.2.3` artifact.
+
 ## 0.2.2 — 2026-08-01
 
 - Enforces each tool's declared top-level argument boundary before API transport, with bounded 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.2.2
+npx -y meguro-mcp@0.2.4
 ```
 
 Pin the version in client configuration. A pinned quickstart stays reproducible and never changes its
@@ -32,11 +32,12 @@ Console provides fast trusted proof and evidence inspection; the agency agent no
 
 <!-- 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).
+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 |
+| `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 |
 | `store_delete` | Delete a practice store | read-write · destructive · non-idempotent · closed-world |
@@ -89,6 +90,7 @@ 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`
 
 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.
@@ -120,14 +122,16 @@ Receipt retrieval is `practice_run_report`: **receipt** is the user-facing noun;
 
 Use these tool names in order:
 
-1. `get_connection_details({ storeId })` through the explicit secure flow (`worldId` remains a legacy alias). Keep the returned values out of model/chat logs.
-2. `practice_run_start({ storeId, clock: { mode: "harness", simulationDays: 14, stepDays: 1 } })` — the same `storeId` the previous step took and returned.
-3. Launch the agency agent in its own environment with the stable returned `SHOPIFY_*` values.
-4. `practice_run_status({ attemptId })`, then `practice_run_checkpoint({ attemptId })`.
-5. `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. Inspect the aligned checkpoint evidence in Console or the run APIs.
-7. `practice_run_finish({ attemptId })`, then `practice_run_report({ attemptId })` for the run's receipt.
-8. Optionally execute an immutable temporal probe-set revision through the HTTP surface and inspect/export it in Gate.
+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.
+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.
+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
@@ -161,7 +165,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.2
+  -- npx -y meguro-mcp@0.2.4
 ```
 
 ## Register — Cursor (`.cursor/mcp.json`)
@@ -171,7 +175,7 @@ claude mcp add meguro \
   "mcpServers": {
     "meguro": {
       "command": "npx",
-      "args": ["-y", "meguro-mcp@0.2.2"],
+      "args": ["-y", "meguro-mcp@0.2.4"],
       "env": {
         "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
         "MEGURO_API_TOKEN": "meg_sk_...",
@@ -192,6 +196,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 43 tools without leaking supplied
+installed binary, and requires `tools/list` to return exactly 44 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/package.json

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

package/src/docs.mjs

@@ -3,9 +3,13 @@ import { createHash } from 'node:crypto';
 const RECEIPT_GUIDE_VERSION = 1;
 const RECEIPT_GUIDE_LATEST_VERSION = 2;
 const GATE_POLICY_VERSION = 1;
+const GETTING_STARTED_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}`;
+
+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.';
 
 function deepFreeze(value) {
   if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
@@ -745,6 +749,67 @@ do not change. A future policy receives a new id, version, URI, and digest; it i
 instead of replacing it.
 `;
 
+const GETTING_STARTED_TEXT = `# Getting started with Meguro v1
+
+Published URI: \`${GETTING_STARTED_URI}\`
+
+## What Meguro is
+
+Meguro is a technical evaluation environment for commerce agents, with deterministic practice stores and Shopify-shaped interfaces that let you observe API behavior before production. Its receipts record what an agent called and changed inside the declared practice scenario; they do not predict merchant outcomes or certify production performance.
+
+## Identities
+
+- \`storeId\` is the canonical public id of a practice store. \`worldId\` is the legacy alias for the
+  same id; prefer \`storeId\` in new integrations.
+- \`attemptId\` is the run identity returned by \`practice_run_start\`. Pass it to every later
+  \`practice_run_*\` tool; it is not a store id.
+
+## Canonical discovery-first sequence
+
+1. Call \`templates_list()\` to discover the exact supported template keys.
+2. Call \`stores_list()\`; reuse an owned practice store or call
+   \`store_create({ templateKey })\` with a key returned by \`templates_list\`.
+3. Call \`get_connection_details({ storeId })\` for the selected store.
+
+   \`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
+   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.
+4. Call \`practice_run_start({ storeId, clock })\`. The fully typed clock shape is
+   \`{ mode: "manual" | "harness" | "scheduled", simulationDays: integer, stepDays: integer }\`;
+   for example,
+   \`practice_run_start({ storeId, clock: { mode: "harness", simulationDays: 14, stepDays: 1 } })\`.
+   Both day fields are positive whole Store-day counts.
+5. Run the commerce agent in its own environment against the Shopify-shaped Admin endpoint and
+   store-scoped credential returned by \`get_connection_details\`.
+6. Call \`practice_run_status({ attemptId })\`, then
+   \`practice_run_checkpoint({ attemptId })\`, to inspect and persist progress.
+7. Call \`practice_run_advance({ attemptId, days, expectedDay, expectedCallSeq })\` with the exact
+   current cursors, or replace \`days\` with a supported \`until\` condition. Never send both.
+8. Call \`practice_run_finish({ attemptId })\` when the evaluation window is complete.
+9. Call \`practice_run_report({ attemptId })\` to retrieve the receipt. **Receipt** is the customer
+   noun; **report** is the compatibility name retained by the tool and HTTP route.
+
+## Control and data planes
+
+The local \`meguro-mcp\` server is the Meguro control plane: it discovers stores and drives run
+lifecycle. The practice store's returned Shopify-shaped Admin endpoint is the data plane used by the
+commerce agent under evaluation. A practice store's storefront MCP endpoint is neither of those and
+cannot replace the local control plane or the Shopify-shaped Admin endpoint.
+
+## Deeper in-band documentation
+
+- Receipt interpretation: read \`meguro://docs/receipt-guide/v1\` or
+  \`meguro://docs/receipt-guide/v2\`, or call
+  \`docs_read({ topic: "receipt-guide", version: 1 })\` or
+  \`docs_read({ topic: "receipt-guide", version: 2 })\`.
+- Gate policy: read \`meguro://docs/gate-policy/v1\`, or call
+  \`docs_read({ topic: "gate-policy", version: 1 })\`.
+
+All published documentation resources are immutable. Cite the exact URI, version, and SHA-256
+digest returned by Meguro.
+`;
+
 function entry(input) {
   const text = String(input.text);
   return deepFreeze({
@@ -801,6 +866,15 @@ export function buildDocumentationCatalog(inputs) {
 }
 
 const CATALOG = buildDocumentationCatalog([
+  {
+    topic: 'getting-started',
+    version: GETTING_STARTED_VERSION,
+    uri: GETTING_STARTED_URI,
+    name: 'Getting started with Meguro v1',
+    title: 'Getting started with Meguro v1',
+    description: 'Discovery-first technical-evaluator sequence from template selection through an immutable practice receipt.',
+    text: GETTING_STARTED_TEXT,
+  },
   {
     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 { documentationResource, documentationResources } from './docs.mjs';
+import { GETTING_STARTED_INSTRUCTIONS, documentationResource, documentationResources } from './docs.mjs';
 import { createTools, redactSecrets } from './tools.mjs';
 
-const SERVER_INFO = { name: 'meguro', version: '0.2.2' };
+const SERVER_INFO = { name: 'meguro', version: '0.2.4' };
 const PROTOCOL_VERSION = '2025-03-26';
 
 const tools = createTools({
@@ -38,6 +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,
       });
     case 'notifications/initialized':
     case 'notifications/cancelled':

package/src/tools.mjs

@@ -17,13 +17,14 @@ const AUTH_TEACHING = Object.freeze({
   'workspace-api-key-revoked': 'This workspace API key is revoked. Create or replace it in Connection settings.',
 });
 const FLEET_TOOL_NAMES = new Set([
-  'stores_list', 'store_create', 'store_delete', 'store_passport',
+  'templates_list', 'stores_list', 'store_create', 'store_delete', 'store_passport',
   'workspaces_list', 'workspace_create', 'workspace_archive', 'workspace_unarchive',
   'share_create', 'shares_list', 'share_status', 'share_publish', 'share_revoke',
   'catalog_slice_read', 'catalog_slice_snapshot', 'catalog_slices_saved',
   'store_claim_by_code', 'store_claim',
 ]);
 const TOOL_PRESENTATION = Object.freeze({
+  templates_list: { title: 'List practice-store templates', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   stores_list: { title: 'List practice stores', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   store_create: { title: 'Create a practice store', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
   store_delete: { title: 'Delete a practice store', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
@@ -153,6 +154,47 @@ function catalogSnapshotProjection(value) {
     : safe;
 }
 
+const STORE_TEMPLATE_FIELDS = Object.freeze([
+  'key',
+  'label',
+  'category',
+  'recommended',
+  'bestFor',
+  'agentTypes',
+  'agentSees',
+  'recommendedRunDays',
+  'recommendedPaceMinutes',
+  'recommendedStepDays',
+  'eventWindowReason',
+  'shortDebugDays',
+  'extendedRunDays',
+  'whatAgentGets',
+  'supportedReads',
+  'liveRun',
+  'goodFirstAgents',
+  'supportedWrites',
+  'knownUnsupported',
+  'goodAgentShould',
+  'avoid',
+  'reportGrades',
+]);
+
+function storeTemplatesProjection(value) {
+  if (!Array.isArray(value?.storeTemplates)) {
+    throw new Error('Meguro template catalog response did not contain storeTemplates');
+  }
+  return {
+    storeTemplates: value.storeTemplates.map((template) => {
+      if (!template || typeof template !== 'object' || Array.isArray(template)) {
+        throw new Error('Meguro template catalog contained an invalid template entry');
+      }
+      return Object.fromEntries(STORE_TEMPLATE_FIELDS
+        .filter((field) => Object.hasOwn(template, field))
+        .map((field) => [field, secretSafe(template[field], 1)]));
+    }),
+  };
+}
+
 function practiceErrorResult(status, value, retryAfterSeconds) {
   const authenticationError = authenticationErrorResult(status, value);
   if (authenticationError) return authenticationError;
@@ -995,25 +1037,37 @@ export function createTools(config) {
   const rawDefinitions = [
     {
       name: 'docs_read',
-      description: 'Read Meguro customer documentation in-band. Topics: receipt-guide version 1 (the original immutable receipt interpretation), receipt-guide version 2 (adds the Console-only account-deletion and public-id invalidation contract), 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 a cited policy never resolves to mutable latest content.',
+      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.',
       inputSchema: {
         type: 'object',
         additionalProperties: false,
         properties: {
           topic: {
             type: 'string',
-            enum: ['receipt-guide', 'gate-policy'],
-            description: 'receipt-guide or gate-policy.',
+            enum: ['getting-started', 'receipt-guide', 'gate-policy'],
+            description: 'getting-started, receipt-guide, or gate-policy.',
           },
           version: {
             type: 'integer',
             enum: [1, 2],
-            description: 'Published immutable document version. Receipt guide versions 1 and 2 are available; Gate policy currently has version 1.',
+            description: 'Published immutable document version. Getting started and Gate policy have version 1; Receipt guide has versions 1 and 2.',
           },
         },
         required: ['topic', 'version'],
       },
     },
+    {
+      name: 'templates_list',
+      description: 'List the ordered, public-safe practice-store template catalog available for creating a store. The response is a bounded projection of storeTemplates only: it excludes customer profiles, scenario presets, credentials, and private route payload. An OAuth grant may select an owned non-default workspace; an API key remains bound to its own workspace.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          workspaceId: { type: 'string', minLength: 1, description: 'Optional OAuth selector for an account-owned non-default workspace. A workspace API key may omit it or repeat only its own binding.' },
+        },
+        required: [],
+      },
+    },
     {
       name: 'stores_list',
       description: 'List one workspace\'s practice-store fleet with ids, names, templates, generated-history span, readiness, active-run state, and deletion context. An OAuth grant is account-bound: omit workspaceId for the default workspace or provide an owned non-default workspace id. An API key remains bound to its own workspace.',
@@ -1566,14 +1620,19 @@ export function createTools(config) {
       switch (name) {
         case 'docs_read': {
           const topic = requiredString(args, 'topic');
-          if (!['receipt-guide', 'gate-policy'].includes(topic)) {
-            throw new Error('topic must be receipt-guide or gate-policy');
+          if (!['getting-started', 'receipt-guide', 'gate-policy'].includes(topic)) {
+            throw new Error('topic must be getting-started, receipt-guide, or gate-policy');
           }
           if (!Number.isSafeInteger(args.version) || args.version < 1) {
             throw new Error('version must be the exact published positive integer');
           }
           return textResult(documentationByTopic(topic, args.version));
         }
+        case 'templates_list': {
+          const workspaceId = optionalWorkspaceId(args);
+          const response = await fleetRequest(name, 'GET', '/practice/profiles', undefined, { workspaceId });
+          return 'error' in response ? response.error : textResult(storeTemplatesProjection(response.value));
+        }
         case 'stores_list': {
           const workspaceId = optionalWorkspaceId(args);
           const response = await fleetRequest(name, 'GET', '/practice/stores', undefined, { workspaceId });