meguro-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
+
+## 0.1.0 — 2026-07-19
+
+- First public distribution of the dependency-free Meguro control-plane MCP server.
+- Exposes the 15 documented store, run, receipt, connection, probe, and schema tools.
+- Supports account-scoped `meg_sk_…` credentials and the self-hosted operator fallback.
+- Redacts control credentials and practice-store credentials from protocol and tool errors.
+

package/README.md

@@ -0,0 +1,141 @@
+# meguro-mcp — the control plane for your AI tools
+
+Drive Meguro worlds from Claude Code, Cursor, or any MCP client: start a run that writes months of
+believable history onto a real dev store, or orchestrate an external agent against a tenant-owned
+practice store and collect bounded receipt evidence.
+
+This is the **control plane** (world/run management, for the developer's tools). It is not the
+**data plane** (the practice-lane Shopify facade the agent under test talks to).
+
+Dependency-free, no build step: the server is plain Node ≥ 20.
+
+## Install and run
+
+Customer MCP clients run the exact public version directly from npm:
+
+```bash
+npx -y meguro-mcp@0.1.0
+```
+
+Pin the version in client configuration. A pinned quickstart stays reproducible and never changes its
+tool contract because npm published a newer release.
+
+## Transport and entry point
+
+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.
+
+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.
+
+## Tools
+
+| Tool | Does | Auth |
+|---|---|---|
+| `run_start` | write `months` of dated history onto the configured store (requires typing the shop domain in `confirm_shop`) | account API key |
+| `run_status` | live progress: orders/total, watermark, status, lastError | account API key |
+| `run_ledger` | the run's attributed diary | account API key |
+| `run_report` | verdict + summary + S3 keys | account API key |
+| `run_resume` | resume a failed run after raising budgets | account API key |
+| `runs_diff` | twin comparison: shared prefix, fork, deltas | account API key |
+| `practice_run_start` | start an `external-agent` practice run; the agent remains in your environment | account API key |
+| `practice_run_status` | read the server-authoritative practice-run contract | account API key |
+| `practice_run_checkpoint` | capture immutable temporal evidence and return a bounded summary | account API key |
+| `practice_run_advance` | advance by days or a closed-set event condition with both concurrency cursors | account API key |
+| `practice_run_finish` | explicitly finish without inventing time or evidence | account API key |
+| `practice_run_report` | read the run's **receipt** — a bounded receipt summary without raw private payloads | account API key |
+| `get_connection_details` | fetch the three Shopify Admin values for a practice store | account API key |
+| `admin_probe` | run one isolated, ungraded Admin GraphQL read or confirmed mutation and return a durable Console URL | account API key |
+| `admin_schema` | look up one exact bounded Admin type, field, mutation, or commerce recipe | account API key |
+
+## Identity model
+
+The whole assistant workflow uses exactly two identifiers:
+
+* **`storeId`** — the canonical public practice-store id. `get_connection_details` takes it and returns it, and `practice_run_start` consumes it verbatim, so connection-discovery output passes directly into run start. `worldId` is a **legacy alias for the same id** (both tools still accept it and connection results still include it); prefer `storeId` in new integrations.
+* **`attemptId`** — the run identity returned by `practice_run_start`. Every later `practice_run_*` tool takes `attemptId`, never the store id.
+
+Receipt retrieval is `practice_run_report`: **receipt** is the user-facing noun; `report` (the tool suffix, the `/report` route, and the `operation: "report"` result field) is the protocol/route **implementation compatibility name** for the same artifact.
+
+## External-agent practice sequence
+
+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.
+
+`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.
+
+`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.
+
+Generate the exact placeholder-only MCP sequence from the repo:
+
+```bash
+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
+
+```
+MEGURO_API_BASE_URL=https://api-dev.meguro.io
+MEGURO_API_TOKEN=<meg_sk account key from Console → Settings>
+MEGURO_DASHBOARD_URL=https://<dashboard-distribution>.cloudfront.net   # optional, enables dashboard links
+
+# Self-hosted/operator fallback only; customer MCP clients should omit it.
+MEGURO_CONTROL_API_KEY=<from infra/params.env or deployment secrets>
+```
+
+## 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.1.0
+```
+
+## Register — Cursor (`.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "meguro": {
+      "command": "npx",
+      "args": ["-y", "meguro-mcp@0.1.0"],
+      "env": {
+        "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
+        "MEGURO_API_TOKEN": "meg_sk_...",
+        "MEGURO_DASHBOARD_URL": "https://..."
+      }
+    }
+  }
+}
+```
+
+Then, in your assistant: *"Start a Meguro world with 12 months of history on `<SHOP_DOMAIN>`,
+seed `bfcm-regression`, and give me the dashboard link."*
+
+## Tests
+
+```bash
+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 15 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

@@ -0,0 +1,49 @@
+# Releasing `meguro-mcp`
+
+The public package name is `meguro-mcp`. Customer configurations invoke an exact version with
+`npx -y meguro-mcp@<version>`; do not deploy a Console quickstart for a version that is not already
+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`, and `CHANGELOG.md` in one commit.
+3. From the repository root, run:
+
+   ```bash
+   npm test --workspace meguro-mcp
+   npm run verify:publish --workspace meguro-mcp
+   npm pack --workspace meguro-mcp --dry-run
+   ```
+
+4. Confirm npm authentication and the intended identity:
+
+   ```bash
+   npm whoami
+   ```
+
+5. From `packages/meguro-mcp`, publish the exact version. npm will run the complete test suite and
+   package validator through the package lifecycle before it uploads anything:
+
+   ```bash
+   npm publish --access public
+   ```
+
+6. Verify the public artifact from a directory outside this repository:
+
+   ```bash
+   npm view meguro-mcp@<version> version dist.integrity
+   npx -y meguro-mcp@<version>
+   ```
+
+   For the protocol smoke, use the copy-ready Console configuration with a disposable workspace key
+   and confirm `tools/list` returns exactly 15 tools. Never put the key in shell history, logs, tickets,
+   or chat.
+
+7. Only after the registry and clean-room checks pass, deploy the 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
+directory listing.
+

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "meguro-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Meguro control-plane MCP server: drive worlds, runs, and verdicts from your own AI tools.",
+  "homepage": "https://meguro.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/darko2006/meguro.git",
+    "directory": "packages/meguro-mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "shopify",
+    "testing",
+    "commerce-agents"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src/",
+    "scripts/verify-package.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "RELEASING.md"
+  ],
+  "bin": {
+    "meguro-mcp": "src/server.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "pretest": "npm run build -w @meguro/core",
+    "test": "node --test test/*.test.mjs",
+    "verify:publish": "node scripts/verify-package.mjs",
+    "prepack": "npm run verify:publish",
+    "prepublishOnly": "npm test"
+  }
+}

package/scripts/verify-package.mjs

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+const server = readFileSync(join(root, 'src/server.mjs'), 'utf8');
+const readme = readFileSync(join(root, 'README.md'), 'utf8');
+const changelog = readFileSync(join(root, 'CHANGELOG.md'), 'utf8');
+const releasing = readFileSync(join(root, 'RELEASING.md'), 'utf8');
+
+assert.equal(pkg.name, 'meguro-mcp');
+assert.equal(pkg.private, false);
+assert.equal(pkg.bin?.['meguro-mcp'], 'src/server.mjs');
+assert.equal(pkg.engines?.node, '>=20');
+assert.equal(pkg.publishConfig?.access, 'public');
+assert.match(server, /^#!\/usr\/bin\/env node/);
+assert.ok((statSync(join(root, 'src/server.mjs')).mode & 0o111) !== 0, 'server entry point must be executable');
+assert.ok(server.includes(`const SERVER_INFO = { name: 'meguro', version: '${pkg.version}' };`), 'server version must match package version');
+assert.match(readme, new RegExp(`npx -y meguro-mcp@${pkg.version.replaceAll('.', '\\.')}`));
+assert.match(readme, /SHOPIFY_ADMIN_ACCESS_TOKEN/);
+assert.match(readme, /store-scoped\s+data-plane credential/);
+assert.match(changelog, new RegExp(`## ${pkg.version.replaceAll('.', '\\.')}`));
+assert.match(releasing, /npm publish --access public/);
+
+console.log(`meguro-mcp@${pkg.version} publish contract verified`);

package/src/server.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// Meguro control-plane MCP server — stdio transport, newline-delimited JSON-RPC 2.0.
+// Dependency-free on purpose: the protocol subset we need (initialize, tools/list,
+// tools/call, ping) is small and stable; no lockfile churn, no build step.
+
+import { createInterface } from 'node:readline';
+import { createTools, redactSecrets } from './tools.mjs';
+
+const SERVER_INFO = { name: 'meguro', version: '0.1.0' };
+const PROTOCOL_VERSION = '2025-03-26';
+
+const tools = createTools({
+  apiBaseUrl: process.env.MEGURO_API_BASE_URL,
+  controlApiKey: process.env.MEGURO_CONTROL_API_KEY,
+  practiceApiToken: process.env.MEGURO_API_TOKEN,
+  dashboardUrl: process.env.MEGURO_DASHBOARD_URL,
+});
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function reply(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: '2.0', id, error: { code, message: redactSecrets(message) } });
+}
+
+async function handle(message) {
+  const { id, method, params } = message;
+  const isNotification = id === undefined || id === null;
+
+  switch (method) {
+    case 'initialize':
+      return reply(id, {
+        protocolVersion: typeof params?.protocolVersion === 'string' ? params.protocolVersion : PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: SERVER_INFO,
+      });
+    case 'notifications/initialized':
+    case 'notifications/cancelled':
+      return; // notifications need no reply
+    case 'ping':
+      return reply(id, {});
+    case 'tools/list':
+      return reply(id, { tools: tools.definitions });
+    case 'tools/call': {
+      const result = await tools.call(params?.name, params?.arguments ?? {});
+      return reply(id, result);
+    }
+    default:
+      if (!isNotification) replyError(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+let pending = 0;
+let stdinClosed = false;
+
+function maybeExit() {
+  // Exit only after stdout has flushed every queued reply (write callbacks run in order).
+  if (stdinClosed && pending === 0) process.stdout.write('', () => process.exit(0));
+}
+
+const rl = createInterface({ input: process.stdin, terminal: false });
+rl.on('line', (line) => {
+  const text = line.trim();
+  if (!text) return;
+  let message;
+  try {
+    message = JSON.parse(text);
+  } catch {
+    return replyError(null, -32700, 'Parse error');
+  }
+  pending += 1;
+  handle(message)
+    .catch((error) => {
+      if (message.id !== undefined && message.id !== null) {
+        replyError(message.id, -32603, error instanceof Error ? error.message : String(error));
+      }
+    })
+    .finally(() => {
+      pending -= 1;
+      maybeExit();
+    });
+});
+// Drain in-flight requests before exiting — a closed stdin ends the session, not mid-air replies.
+rl.on('close', () => { stdinClosed = true; maybeExit(); });

package/src/tools.mjs

@@ -0,0 +1,671 @@
+// Meguro control-plane MCP tools — a thin, dependency-free wrapper over the deployed control API.
+// Vocabulary discipline (docs/fable/teaching.md): store, run, receipt, gate.
+// Customer control-plane calls use an account-scoped MEGURO_API_TOKEN (meg_sk_...).
+// MEGURO_CONTROL_API_KEY remains a self-hosted/operator fallback; there is no public run share surface.
+
+const AGED_BUDGET = (months) => Math.max(100, months * 31 * 8 + 50);
+const SECRET_VALUE = /\bmeg_(?:pw|sk)_[a-z0-9_-]+\b|\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=:-]+/giu;
+const SECRET_HEADER = /\b(?:authorization|cookie|set-cookie|x-shopify-access-token|signed-snapshot-token)\s*[:=]\s*[^\s,;]+/giu;
+const SECRET_KEY = /(?:authorization|cookie|password|secret|token|api[_-]?key|signedsnapshot)/iu;
+const PRIVATE_RESPONSE_KEY = /^(?:raw|rawBody|rawBodyPreview|responsePayload|requestHeaders|responseHeaders|headers|cookies)$/iu;
+const RESERVED_WORLD_IDS = new Set(['api', 'api-dev', 'www', 'dev', 'hooks', 'control']);
+
+function textResult(value) {
+  return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] };
+}
+
+function errorResult(message) {
+  return { content: [{ type: 'text', text: scrubString(message) }], isError: true };
+}
+
+function scrubString(value) {
+  return String(value ?? '').replace(SECRET_VALUE, '[REDACTED]').replace(SECRET_HEADER, '[REDACTED]');
+}
+
+export function redactSecrets(value) {
+  return scrubString(value);
+}
+
+function secretSafe(value, depth = 0) {
+  if (depth > 12) return '[TRUNCATED]';
+  if (typeof value === 'string') return scrubString(value).slice(0, 10_000);
+  if (Array.isArray(value)) return value.slice(0, 100).map((child) => secretSafe(child, depth + 1));
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value)
+      .filter(([key]) => !SECRET_KEY.test(key) && !PRIVATE_RESPONSE_KEY.test(key))
+      .slice(0, 100)
+      .map(([key, child]) => [key, secretSafe(child, depth + 1)]));
+  }
+  return value;
+}
+
+function practiceErrorResult(status, value, retryAfterSeconds) {
+  const body = value && typeof value === 'object' ? value : {};
+  const stable = { httpStatus: status };
+  if (body.practiceRunError && typeof body.practiceRunError === 'object') {
+    stable.practiceRunError = secretSafe({
+      code: body.practiceRunError.code,
+      message: body.practiceRunError.message,
+    });
+  } else if (body.error && typeof body.error === 'object') {
+    stable.error = secretSafe({ code: body.error.code, message: body.error.message });
+  } else if (Array.isArray(body.errors) && body.errors.length) {
+    stable.errors = body.errors.slice(0, 5).map((error) => secretSafe({ code: error?.code, message: error?.message }));
+  } else {
+    stable.error = { message: scrubString(typeof value === 'string' ? value : 'Meguro practice request failed.') };
+  }
+  const bodyRetryAfter = Number(body.retryAfterSeconds ?? body.retry?.afterSeconds);
+  if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds >= 0) stable.retryAfterSeconds = retryAfterSeconds;
+  else if (Number.isFinite(bodyRetryAfter) && bodyRetryAfter >= 0) stable.retryAfterSeconds = bodyRetryAfter;
+  if (typeof body.retryable === 'boolean') stable.retryable = body.retryable;
+  return { content: [{ type: 'text', text: JSON.stringify(stable, null, 2) }], isError: true };
+}
+
+function requiredString(args, key) {
+  const value = args?.[key];
+  if (typeof value !== 'string' || value.trim().length === 0) throw new Error(`${key} is required`);
+  return value.trim();
+}
+
+function validatedStoreId(value, key) {
+  if (!/^[a-z0-9-]+$/.test(value)) throw new Error(`${key} must match ^[a-z0-9-]+$`);
+  if (RESERVED_WORLD_IDS.has(value)) throw new Error(`${key} uses a reserved Meguro hostname`);
+  return value;
+}
+
+function requiredWorldId(args) {
+  return validatedStoreId(requiredString(args, 'worldId'), 'worldId');
+}
+
+// MEG-256: `storeId` is the one canonical public practice-store identifier across the assistant
+// workflow (connection discovery → run start → receipt). `worldId` names the same identifier and
+// stays accepted as a bounded legacy alias so existing callers keep working.
+function requiredPracticeStoreId(args) {
+  const provided = ['storeId', 'worldId'].filter((key) => args?.[key] !== undefined && args?.[key] !== null);
+  if (provided.length === 0) throw new Error('storeId is required (worldId is accepted as a legacy alias for the same practice-store id)');
+  const canonical = requiredString(args, provided[0]);
+  if (provided.length === 2 && requiredString(args, provided[1]) !== canonical) {
+    throw new Error('storeId and worldId name the same practice store; they were both provided with different values');
+  }
+  return validatedStoreId(canonical, provided[0]);
+}
+
+function optionalPositiveInteger(args, key) {
+  const value = args?.[key];
+  if (value === undefined) return undefined;
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error(`${key} must be a positive integer`);
+  return value;
+}
+
+function requiredNonNegativeInteger(args, key, minimum = 0) {
+  const value = args?.[key];
+  if (!Number.isSafeInteger(value) || value < minimum) throw new Error(`${key} must be a whole number of ${minimum} or greater`);
+  return value;
+}
+
+function practiceRunProjection(value) {
+  return value && typeof value === 'object' ? secretSafe(value) : null;
+}
+
+function checkpointProjection(value) {
+  if (!value || typeof value !== 'object') return null;
+  const observations = Array.isArray(value.observations) ? value.observations.slice(0, 3).map((observation) => ({
+    captureId: observation.captureId,
+    observationId: observation.observationId,
+    label: observation.label,
+    simulatedDay: observation.simulatedDay,
+    referenceFidelity: observation.lanes?.reference?.result?.result?.fidelity,
+    treatedFidelity: observation.lanes?.treated?.result?.result?.fidelity,
+    diffEntries: observation.diff?.truncation?.originalEntries ?? observation.diff?.entries?.length ?? 0,
+    diffTruncated: observation.diff?.truncation?.truncated === true,
+  })) : [];
+  return secretSafe({
+    schemaVersion: value.schemaVersion,
+    version: value.version,
+    checkpointId: value.checkpointId,
+    attemptId: value.attemptId,
+    sequence: value.sequence,
+    trigger: value.trigger,
+    simulatedDay: value.simulatedDay,
+    simulatedDate: value.simulatedDate,
+    throughCallSequence: value.throughCallSequence,
+    actionLogVersion: value.actionLogVersion,
+    treatedStateDigest: value.treatedStateDigest,
+    metrics: value.metrics,
+    cursors: value.cursors,
+    observationCount: observations.length,
+    ...(observations.length ? { observations } : {}),
+    createdAt: value.createdAt,
+  });
+}
+
+function receiptProjection(value) {
+  const attempt = value?.attempt && typeof value.attempt === 'object' ? value.attempt : {};
+  const practiceRun = attempt.practiceRun ?? value?.practiceRun ?? null;
+  const calls = Array.isArray(value?.events?.calls) ? value.events.calls : [];
+  const actions = Array.isArray(value?.events?.actions) ? value.events.actions : [];
+  const assertions = Array.isArray(value?.receiptEvidence?.assertions)
+    ? value.receiptEvidence.assertions.slice(0, 50).map((assertion) => ({
+      id: assertion.id,
+      status: assertion.status,
+      label: assertion.label,
+    }))
+    : [];
+  const verdict = value?.report?.verdict && typeof value.report.verdict === 'object'
+    ? Object.fromEntries(['status', 'outcome', 'grade', 'score', 'headline', 'horizonDays']
+      .filter((key) => value.report.verdict[key] !== undefined)
+      .map((key) => [key, value.report.verdict[key]]))
+    : undefined;
+  return secretSafe({
+    schemaVersion: value?.schemaVersion,
+    attemptId: attempt.attemptId ?? practiceRun?.attemptId,
+    practiceRun,
+    evidenceStatus: practiceRun?.evidenceStatus,
+    recordedAt: value?.recordedAt ?? attempt.recordedAt,
+    clock: value?.clock,
+    summary: {
+      calls: calls.length,
+      actions: actions.length,
+      rejectedCalls: calls.filter((call) => call?.rejected === true || Number(call?.status) >= 400).length,
+      acceptedWrites: calls.filter((call) => Number(call?.actionCount ?? 0) > 0).length,
+    },
+    receipt: {
+      summary: value?.receiptEvidence?.summary,
+      assertions,
+    },
+    ...(verdict ? { verdict } : {}),
+  });
+}
+
+export function createTools(config) {
+  const apiBaseUrl = String(config.apiBaseUrl ?? '').replace(/\/+$/, '');
+  const controlApiKey = config.controlApiKey ?? '';
+  const dashboardUrl = String(config.dashboardUrl ?? '').replace(/\/+$/, '');
+  const practiceApiToken = String(config.practiceApiToken ?? '').trim();
+  const fetchImpl = config.fetchImpl ?? fetch;
+
+  if (!apiBaseUrl) throw new Error('MEGURO_API_BASE_URL is required');
+
+  function controlAuthHeaders() {
+    if (practiceApiToken.startsWith('meg_sk_')) return { authorization: `Bearer ${practiceApiToken}` };
+    if (controlApiKey) return { 'x-meguro-key': controlApiKey };
+    throw new Error('MEGURO_API_TOKEN (meg_sk account key) or MEGURO_CONTROL_API_KEY is required for this tool');
+  }
+
+  async function api(method, path, body, options = {}) {
+    const headers = { accept: 'application/json' };
+    const needsControlCredential = Boolean(options.auth || method !== 'GET');
+    if (needsControlCredential) Object.assign(headers, controlAuthHeaders());
+    if (method !== 'GET') {
+      headers['content-type'] = 'application/json';
+    }
+    // Cache-bust reads: status URLs sit behind caches that have lied to us before.
+    const bust = method === 'GET' ? `${path.includes('?') ? '&' : '?'}_=${Date.now()}` : '';
+    const response = await fetchImpl(`${apiBaseUrl}${path}${bust}`, {
+      method,
+      headers,
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await response.text();
+    let json;
+    try { json = JSON.parse(text); } catch { json = { raw: text }; }
+    if (!response.ok) {
+      const message = json.errors?.[0]?.message ?? json.error ?? text.slice(0, 300);
+      throw new Error(`${response.status} ${path}: ${message}`);
+    }
+    return json;
+  }
+
+  // Like `api`, but returns { ok, status, json } instead of throwing on !ok — so a structured control-route
+  // error body (e.g. the meguro.admin-probe.v1 error envelope) can be preserved verbatim to the caller.
+  async function apiRaw(method, path, body) {
+    const headers = { accept: 'application/json', ...controlAuthHeaders() };
+    if (method !== 'GET') headers['content-type'] = 'application/json';
+    const response = await fetchImpl(`${apiBaseUrl}${path}`, {
+      method,
+      headers,
+      ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await response.text();
+    let json;
+    try { json = JSON.parse(text); } catch { json = { raw: text }; }
+    return { ok: response.ok, status: response.status, json };
+  }
+
+  async function practiceApi(method, path, body) {
+    if (!practiceApiToken) throw new Error('MEGURO_API_TOKEN is required for practice-run tools');
+    const headers = { accept: 'application/json', authorization: `Bearer ${practiceApiToken}` };
+    if (method !== 'GET') headers['content-type'] = 'application/json';
+    let response;
+    try {
+      response = await fetchImpl(`${apiBaseUrl}${path}`, {
+        method,
+        headers,
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      });
+    } catch (error) {
+      throw new Error(scrubString(error instanceof Error ? error.message : String(error)));
+    }
+    const text = await response.text();
+    let json;
+    try { json = text ? JSON.parse(text) : null; } catch { json = { error: { message: 'Meguro returned a non-JSON response.' } }; }
+    const retryHeader = response.headers?.get?.('retry-after');
+    const retryAfterSeconds = retryHeader === null || retryHeader === undefined || retryHeader === '' ? undefined : Number(retryHeader);
+    return { ok: response.ok, status: response.status, json, retryAfterSeconds };
+  }
+
+  function dashboardLink(runId) {
+    if (!dashboardUrl) return undefined;
+    return `${dashboardUrl}/?api=${encodeURIComponent(apiBaseUrl)}&run=${encodeURIComponent(runId)}`;
+  }
+
+  // MEG-34: map a minted mcp-probe reference to a Console URL that reopens the exact historical probe. The
+  // URL carries only the opaque reference — never the query, variables, token, result, worldId, or
+  // operation name. If MEGURO_DASHBOARD_URL is unset the probe still succeeds; consoleUrl is null.
+  function consoleUrlFields(consoleRef, consoleRefExpiresAt) {
+    if (!consoleRef) return { consoleUrl: null };
+    if (!dashboardUrl) return { consoleUrl: null, consoleUrlError: 'MEGURO_DASHBOARD_URL is not configured' };
+    return {
+      consoleUrl: `${dashboardUrl}/index.html#console?ref=${encodeURIComponent(consoleRef)}`,
+      ...(consoleRefExpiresAt ? { consoleUrlExpiresAt: consoleRefExpiresAt } : {}),
+    };
+  }
+
+  const definitions = [
+    {
+      name: 'run_start',
+      description: 'Start a new Meguro store: writes `months` of believable, dated commerce history onto the configured real dev store (the fastest backdating run — the past is data). Deterministic by seed: same seed, same year. Requires typing the shop domain in confirm_shop (safety ritual). Returns runId, plan size, estimated wall-clock, and a dashboard link to watch the store being created.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          months: { type: 'integer', minimum: 1, maximum: 25, description: 'How many months of history to write (12 = a full seasonal year incl. BFCM).' },
+          confirm_shop: { type: 'string', description: 'The exact myshopify.com domain of the target dev store, typed out — the SafetyGate confirmation.' },
+          seed: { type: 'string', description: 'The store seed — any string; yours. Same seed, same year, every time. Omit to use the server default.' },
+          today: { type: 'string', description: 'ISO date (YYYY-MM-DD) the history ends at. Defaults to the server\'s today.' },
+          catalog: {
+            type: 'array',
+            description: 'Optional product fixtures to write the history across. Omit to use the run\'s configured variant/catalog.',
+            items: { type: 'object' },
+          },
+        },
+        required: ['months', 'confirm_shop'],
+      },
+    },
+    {
+      name: 'run_status',
+      description: 'Live progress of a run: orders written / total, sim-date watermark, status, lastError. Account-key-gated, read-only, cache-busted. Use this instead of guessing.',
+      inputSchema: {
+        type: 'object',
+        properties: { runId: { type: 'string', description: 'The run id, e.g. cultivate-2026-06-10t15-51-31-737z' } },
+        required: ['runId'],
+      },
+    },
+    {
+      name: 'run_ledger',
+      description: 'The run\'s ledger — its complete attributed diary (every event, every actor). Account-key-gated and read-only.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          runId: { type: 'string' },
+          limit: { type: 'integer', minimum: 1, maximum: 500, description: 'Max entries (default 50).' },
+        },
+        required: ['runId'],
+      },
+    },
+    {
+      name: 'run_report',
+      description: 'Generate and fetch the run\'s receipt (verdict, summary, S3 keys). The receipt never claims more than the ledger can prove.',
+      inputSchema: {
+        type: 'object',
+        properties: { runId: { type: 'string' } },
+        required: ['runId'],
+      },
+    },
+    {
+      name: 'run_resume',
+      description: 'Resume a failed Meguro run after raising budgets. Mutates the real run control plane, so it requires an account API key. Use it for budget-stopped stores, not completed history.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          runId: { type: 'string' },
+          maxEvents: { type: 'integer', minimum: 1, description: 'Optional replacement events budget.' },
+          maxShopifyApiCalls: { type: 'integer', minimum: 1, description: 'Optional replacement Shopify API-call budget.' },
+        },
+        required: ['runId'],
+      },
+    },
+    {
+      name: 'runs_diff',
+      description: 'Diff two runs of the same store. Verifies the shared prefix, finds the fork, and returns the deltas. "Not comparable" is an honest answer, not an error in your usage.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          a: { type: 'string', description: 'Baseline runId (the twin without the intervention).' },
+          b: { type: 'string', description: 'Treatment runId.' },
+        },
+        required: ['a', 'b'],
+      },
+    },
+    {
+      name: 'practice_run_start',
+      description: 'Start an external-agent practice run on an existing Meguro practice store. Takes the canonical practice-store id (`storeId`) exactly as returned by get_connection_details, and returns the run identity (`attemptId`) every later practice_run_* tool uses — the store id and the run id are different identifiers. Meguro Console is quick proof, while the agency agent still runs in the caller\'s own environment. Returns the same server-authoritative practice-run contract without connection credentials.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          storeId: { type: 'string', minLength: 1, description: 'Canonical Meguro practice-store id (tenant-owned), as returned by get_connection_details.' },
+          worldId: { type: 'string', minLength: 1, description: 'Legacy alias for storeId — the same practice-store id under its old name. Prefer storeId.' },
+          clock: { type: 'object', description: 'Existing hosted practice-run clock contract.' },
+          externalAgent: { type: 'object', description: 'Optional bounded external-agent identity metadata.' },
+          observationPlan: { type: 'object', description: 'Optional trusted read-only checkpoint observation plan.' },
+          graphqlThrottleMode: { type: 'string', enum: ['off', 'standard-1000', 'plus-2000'], description: 'Optional Meguro compatibility GraphQL throttle mode.' },
+        },
+        required: [],
+        anyOf: [{ required: ['storeId'] }, { required: ['worldId'] }],
+      },
+    },
+    {
+      name: 'practice_run_status',
+      description: 'Read the server-authoritative state of an external-agent practice run. Use Console for quick proof; the tested agent remains in the caller\'s environment.',
+      inputSchema: {
+        type: 'object', additionalProperties: false,
+        properties: { attemptId: { type: 'string', minLength: 1, description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
+        required: ['attemptId'],
+      },
+    },
+    {
+      name: 'practice_run_checkpoint',
+      description: 'Capture an immutable checkpoint for an external-agent practice run and return a bounded evidence summary. Console is quick proof; agent execution remains in the caller\'s environment.',
+      inputSchema: {
+        type: 'object', additionalProperties: false,
+        properties: { attemptId: { type: 'string', minLength: 1, description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
+        required: ['attemptId'],
+      },
+    },
+    {
+      name: 'practice_run_advance',
+      description: 'Advance an external-agent practice run by whole days or until one closed-set commerce condition, using both optimistic concurrency cursors. Console is quick proof; agent execution remains in the caller\'s environment.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          attemptId: { type: 'string', minLength: 1, description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' },
+          days: { type: 'integer', minimum: 1, description: 'Whole simulated days to advance.' },
+          until: { type: 'object', description: 'Existing meguro.practice-run-until.v1 event-gated request.' },
+          expectedDay: { type: 'integer', minimum: 0, description: 'Current practiceRun.time.watermarkDay.' },
+          expectedCallSeq: { type: 'integer', minimum: -1, description: 'Current practiceRun.latestCallSequence, or -1 before any call.' },
+        },
+        required: ['attemptId', 'expectedDay', 'expectedCallSeq'],
+        oneOf: [{ required: ['days'] }, { required: ['until'] }],
+      },
+    },
+    {
+      name: 'practice_run_finish',
+      description: 'Explicitly finish an external-agent practice run without inventing additional time or evidence. Console is quick proof; agent execution remains in the caller\'s environment.',
+      inputSchema: {
+        type: 'object', additionalProperties: false,
+        properties: { attemptId: { type: 'string', minLength: 1, description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
+        required: ['attemptId'],
+      },
+    },
+    {
+      name: 'practice_run_report',
+      description: 'Read the run\'s receipt — a bounded receipt summary for a completed external-agent practice run. `report` is the protocol/route compatibility name for the receipt (the tool name and the `operation: "report"` field keep it for wire stability); user-facing language is "receipt". Raw private request and response payloads stay out of MCP; use Console for quick proof while the agent remains in the caller\'s environment.',
+      inputSchema: {
+        type: 'object', additionalProperties: false,
+        properties: { attemptId: { type: 'string', minLength: 1, description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
+        required: ['attemptId'],
+      },
+    },
+    {
+      name: 'get_connection_details',
+      description: 'Fetch the Shopify-shaped Admin GraphQL URL, access token, and shop domain for an existing Meguro practice store so an assistant can configure a user agent without opening the dashboard. Takes the canonical practice-store id (`storeId`) and returns it back, so the result passes directly into practice_run_start({ storeId }) — no identifier translation. The practice-store id is not an `attemptId` (run identity). Requires an account API key because it reveals the per-store token.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          storeId: { type: 'string', description: 'Canonical Meguro practice-store id, e.g. w-abc123. Pass the returned storeId straight into practice_run_start.' },
+          worldId: { type: 'string', description: 'Legacy alias for storeId — the same practice-store id under its old name. Prefer storeId.' },
+        },
+        required: [],
+        anyOf: [{ required: ['storeId'] }, { required: ['worldId'] }],
+      },
+    },
+    {
+      name: 'admin_probe',
+      description: 'Run an isolated Admin GraphQL probe against a Meguro practice store and get the shared meguro.admin-probe.v1 result envelope: fidelity, note, top-level errors, userErrors, cost/throttle, and deterministic truncation. Reads run immediately; a mutation runs only when confirmMutation is true and changes just isolated probe state — never graded runs, receipts, or gate evidence. The per-store token stays server-side and never appears in the result. Also returns a consoleUrl that reopens this exact historical, ungraded probe in the Console without re-running it.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          worldId: { type: 'string', minLength: 1, description: 'Meguro practice store id, e.g. w-abc123.' },
+          query: { type: 'string', maxLength: 30000, description: 'The Admin GraphQL query or mutation document to run.' },
+          apiVersion: { type: 'string', pattern: '^\\d{4}-\\d{2}$', description: 'Admin API version as YYYY-MM. Defaults to 2026-04.' },
+          variables: { type: 'object', description: 'GraphQL variables object (max 20,000 serialized characters).' },
+          operationName: { type: 'string', minLength: 1, maxLength: 200, description: 'Which operation to run when the document defines more than one.' },
+          confirmMutation: { type: 'boolean', description: 'Set true to run a mutation in isolated probe state. Reads ignore it.' },
+        },
+        required: ['worldId', 'query'],
+      },
+    },
+    {
+      name: 'admin_schema',
+      description: 'Look up an exact, bounded slice of the Admin GraphQL surface Meguro models: a type and its direct fields, a Type.field or root mutation with its arguments and return type, or a shared commerce recipe. Deterministic — it never returns the full schema, tenant data, catalog, or credentials, and on a miss it suggests only exact prefix/substring alternatives.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          lookup: { type: 'string', enum: ['type', 'field', 'mutation', 'recipe'], description: 'What to look up: a type, a Type.field, a root mutation, or a commerce recipe.' },
+          name: { type: 'string', minLength: 1, maxLength: 200, description: 'Exact name: e.g. ProductVariant, ProductVariant.inventoryQuantity, inventoryAdjustQuantities, or a recipe id/operationName like low-inventory or LowInventory.' },
+          apiVersion: { type: 'string', pattern: '^\\d{4}-\\d{2}$', description: 'Admin API version YYYY-MM. Defaults to 2026-04, the only modeled version.' },
+        },
+        required: ['lookup', 'name'],
+      },
+    },
+  ];
+
+  async function call(name, args = {}) {
+    try {
+      switch (name) {
+        case 'run_start': {
+          const months = Number(args.months);
+          const budget = AGED_BUDGET(months);
+          const body = {
+            mode: 'cultivate',
+            scenario: 'aged-history',
+            windowMonths: months,
+            confirmShop: args.confirm_shop,
+            acknowledge: true,
+            ...(args.seed ? { seed: args.seed } : {}),
+            ...(args.today ? { today: args.today } : {}),
+            ...(Array.isArray(args.catalog) && args.catalog.length > 0 ? { catalog: args.catalog } : {}),
+            budgets: {
+              maxEvents: budget,
+              maxShopifyApiCalls: budget,
+              maxProductsCreated: Math.max(2, (args.catalog?.length ?? 0) + 1),
+              maxVariantsCreated: Math.max(10, (args.catalog?.length ?? 0) + 2),
+              maxInventoryMutations: 10,
+            },
+          };
+          const started = await api('POST', '/runs', body);
+          return textResult({
+            runId: started.runId,
+            planLength: started.planLength,
+            estimatedWallClockSeconds: started.agedHistoryPlan?.estimatedWallClockSeconds,
+            dashboard: dashboardLink(started.runId),
+            reminder: 'Enable the cultivate schedule if it is disabled — the run advances on scheduled ticks.',
+          });
+        }
+        case 'run_status': {
+          const status = await api('GET', `/runs/${encodeURIComponent(args.runId)}`, undefined, { auth: true });
+          return textResult({ ...status, dashboard: dashboardLink(args.runId) });
+        }
+        case 'run_ledger': {
+          const limit = Number.isInteger(args.limit) ? args.limit : 50;
+          return textResult(await api('GET', `/runs/${encodeURIComponent(args.runId)}/ledger?limit=${limit}`, undefined, { auth: true }));
+        }
+        case 'run_report':
+          return textResult(await api('GET', `/runs/${encodeURIComponent(args.runId)}/report`, undefined, { auth: true }));
+        case 'run_resume': {
+          const runId = requiredString(args, 'runId');
+          const maxEvents = optionalPositiveInteger(args, 'maxEvents');
+          const maxShopifyApiCalls = optionalPositiveInteger(args, 'maxShopifyApiCalls');
+          const body = {
+            ...(maxEvents === undefined ? {} : { maxEvents }),
+            ...(maxShopifyApiCalls === undefined ? {} : { maxShopifyApiCalls }),
+          };
+          return textResult(await api('POST', `/runs/${encodeURIComponent(runId)}/resume`, body));
+        }
+        case 'runs_diff':
+          return textResult(await api('GET', `/runs/${encodeURIComponent(args.a)}/diff/${encodeURIComponent(args.b)}`, undefined, { auth: true }));
+        case 'practice_run_start': {
+          const storeId = requiredPracticeStoreId(args);
+          const body = {
+            purpose: 'external-agent',
+            ...(args.clock !== undefined ? { clock: args.clock } : {}),
+            ...(args.externalAgent !== undefined ? { externalAgent: args.externalAgent } : {}),
+            ...(args.observationPlan !== undefined ? { observationPlan: args.observationPlan } : {}),
+            ...(args.graphqlThrottleMode !== undefined ? { graphqlThrottleMode: args.graphqlThrottleMode } : {}),
+          };
+          const response = await practiceApi('POST', `/practice/stores/${encodeURIComponent(storeId)}/playbacks`, body);
+          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          const started = response.json ?? {};
+          return textResult(secretSafe({
+            operation: 'start',
+            attemptId: started.attemptId ?? started.practiceRun?.attemptId,
+            practiceRun: practiceRunProjection(started.practiceRun),
+            paths: {
+              state: started.statePath,
+              checkpoints: started.checkpointsPath,
+              advance: started.advancePath,
+              report: started.reportPath,
+            },
+            ...consoleUrlFields(started.consoleRef, started.consoleRefExpiresAt),
+          }));
+        }
+        case 'practice_run_status': {
+          const attemptId = requiredString(args, 'attemptId');
+          const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/state`);
+          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          const state = response.json ?? {};
+          return textResult(secretSafe({
+            operation: 'status',
+            attemptId,
+            practiceRun: practiceRunProjection(state.practiceRun),
+            ...consoleUrlFields(state.consoleRef, state.consoleRefExpiresAt),
+          }));
+        }
+        case 'practice_run_checkpoint': {
+          const attemptId = requiredString(args, 'attemptId');
+          const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/checkpoint`, {});
+          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          return textResult(secretSafe({
+            operation: 'checkpoint',
+            attemptId,
+            alreadyCaptured: response.json?.alreadyCaptured === true,
+            checkpoint: checkpointProjection(response.json?.checkpoint),
+            ...consoleUrlFields(response.json?.consoleRef, response.json?.consoleRefExpiresAt),
+          }));
+        }
+        case 'practice_run_advance': {
+          const attemptId = requiredString(args, 'attemptId');
+          const hasDays = args.days !== undefined;
+          const hasUntil = args.until !== undefined;
+          if (hasDays === hasUntil) throw new Error('practice_run_advance requires exactly one of days or until');
+          const expectedDay = requiredNonNegativeInteger(args, 'expectedDay');
+          const expectedCallSeq = requiredNonNegativeInteger(args, 'expectedCallSeq', -1);
+          if (hasDays && (!Number.isSafeInteger(args.days) || args.days < 1)) throw new Error('days must be a positive integer');
+          if (hasUntil && (!args.until || typeof args.until !== 'object' || Array.isArray(args.until))) throw new Error('until must be an object');
+          const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/advance`, {
+            ...(hasDays ? { days: args.days } : { until: args.until }), expectedDay, expectedCallSeq,
+          });
+          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          const advanced = response.json ?? {};
+          return textResult(secretSafe({
+            operation: 'advance',
+            attemptId,
+            watermarkDay: advanced.watermarkDay,
+            isComplete: advanced.isComplete,
+            alreadyApplied: advanced.alreadyApplied === true,
+            ...(advanced.until ? { until: advanced.until } : {}),
+            practiceRun: practiceRunProjection(advanced.practiceRun),
+            ...consoleUrlFields(advanced.consoleRef, advanced.consoleRefExpiresAt),
+          }));
+        }
+        case 'practice_run_finish': {
+          const attemptId = requiredString(args, 'attemptId');
+          const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/finish`, {});
+          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          return textResult(secretSafe({
+            operation: 'finish',
+            attemptId,
+            practiceRun: practiceRunProjection(response.json),
+            ...consoleUrlFields(response.json?.consoleRef, response.json?.consoleRefExpiresAt),
+          }));
+        }
+        case 'practice_run_report': {
+          const attemptId = requiredString(args, 'attemptId');
+          const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/report`);
+          if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
+          return textResult({
+            operation: 'report',
+            ...receiptProjection(response.json ?? {}),
+            ...consoleUrlFields(response.json?.consoleRef, response.json?.consoleRefExpiresAt),
+          });
+        }
+        case 'get_connection_details': {
+          const requestedStoreId = requiredPracticeStoreId(args);
+          const details = await api('GET', `/practice/${encodeURIComponent(requestedStoreId)}/connection`, undefined, { auth: true });
+          const storeId = details.storeId ?? details.worldId ?? requestedStoreId;
+          const shopDomain = details.host ?? `${details.worldId ?? requestedStoreId}.meguro.io`;
+          return textResult({
+            // Canonical practice-store id first: pass it straight into practice_run_start({ storeId }).
+            storeId,
+            // Legacy alias for the same id, kept for existing callers.
+            worldId: details.worldId ?? requestedStoreId,
+            shopDomain,
+            env: {
+              SHOPIFY_ADMIN_GRAPHQL_URL: details.adminUrl,
+              SHOPIFY_ADMIN_ACCESS_TOKEN: details.token,
+              SHOPIFY_SHOP_DOMAIN: shopDomain,
+            },
+          });
+        }
+        case 'admin_probe': {
+          const worldId = requiredWorldId(args);
+          const body = {
+            query: typeof args.query === 'string' ? args.query : '',
+            ...(args.apiVersion !== undefined ? { apiVersion: args.apiVersion } : {}),
+            ...(args.variables !== undefined ? { variables: args.variables } : {}),
+            ...(args.operationName !== undefined ? { operationName: args.operationName } : {}),
+            ...(args.confirmMutation !== undefined ? { confirmMutation: args.confirmMutation } : {}),
+            // MEG-34: always ask the server to mint a durable Console reference for a successful probe.
+            createConsoleReference: true,
+          };
+          const { ok, json } = await apiRaw('POST', `/practice/${encodeURIComponent(worldId)}/probe/admin`, body);
+          if (ok) {
+            // Replace the internal reference id with a ready-to-open Console URL (opaque ref only).
+            const { consoleRef, consoleRefExpiresAt, ...envelope } = json;
+            return textResult({ ...envelope, ...consoleUrlFields(consoleRef, consoleRefExpiresAt) });
+          }
+          // Preserve the structured meguro.admin-probe.v1 error body (code + message) with isError: true,
+          // instead of collapsing it to an unstructured thrown message.
+          return { content: [{ type: 'text', text: JSON.stringify(secretSafe(json), null, 2) }], isError: true };
+        }
+        case 'admin_schema': {
+          const lookup = requiredString(args, 'lookup');
+          const lookupName = requiredString(args, 'name');
+          const body = {
+            lookup,
+            name: lookupName,
+            ...(args.apiVersion !== undefined ? { apiVersion: args.apiVersion } : {}),
+          };
+          return textResult(await api('POST', '/practice/admin-schema', body, { auth: true }));
+        }
+        default:
+          return errorResult(`Unknown tool: ${name}`);
+      }
+    } catch (error) {
+      return errorResult(error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  return { definitions, call };
+}