meguro-mcp 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
 
+## 0.2.2 — 2026-08-01
+
+- Enforces each tool's declared top-level argument boundary before API transport, with bounded errors
+  that do not echo attacker-controlled property names.
+- Rejects practice-store ids and oversized or malformed practice-run ids locally across run,
+  continuation, and Exam entry tools while preserving supported historical run-id shapes.
+- Keeps well-formed missing and cross-workspace run ids on the same generic
+  `practice-run-unavailable` response so validation does not create an existence oracle.
+
+## 0.2.1 — 2026-08-01
+
+- Preserves the API's approved wrong/revoked workspace-key code and actionable Connection settings
+  guidance through MCP tool errors while keeping malformed authentication responses fail-closed.
+- Keeps authentication failures secret-free, single-attempt, and explicitly classified as HTTP 401
+  or 403 without changing unrelated tool-error projections.
+- Pins Console and customer scenario fixtures to the exact `meguro-mcp@0.2.1` artifact.
+
 ## 0.2.0 — 2026-08-01
 
 - Publishes the frozen 43-tool control-plane registry already present in the repository, without

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.0
+npx -y meguro-mcp@0.2.2
 ```
 
 Pin the version in client configuration. A pinned quickstart stays reproducible and never changes its
@@ -161,7 +161,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.0
+  -- npx -y meguro-mcp@0.2.2
 ```
 
 ## Register — Cursor (`.cursor/mcp.json`)
@@ -171,7 +171,7 @@ claude mcp add meguro \
   "mcpServers": {
     "meguro": {
       "command": "npx",
-      "args": ["-y", "meguro-mcp@0.2.0"],
+      "args": ["-y", "meguro-mcp@0.2.2"],
       "env": {
         "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
         "MEGURO_API_TOKEN": "meg_sk_...",

package/package.json

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

package/src/server.mjs

@@ -7,7 +7,7 @@ import { createInterface } from 'node:readline';
 import { documentationResource, documentationResources } from './docs.mjs';
 import { createTools, redactSecrets } from './tools.mjs';
 
-const SERVER_INFO = { name: 'meguro', version: '0.2.0' };
+const SERVER_INFO = { name: 'meguro', version: '0.2.2' };
 const PROTOCOL_VERSION = '2025-03-26';
 
 const tools = createTools({

package/src/tools.mjs

@@ -11,6 +11,11 @@ const SECRET_HEADER = /\b(?:authorization|cookie|set-cookie|x-shopify-access-tok
 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']);
+const PRACTICE_ATTEMPT_ID = /^pa-[a-z0-9][a-z0-9-]{0,124}$/u;
+const AUTH_TEACHING = Object.freeze({
+  'workspace-api-key-invalid': 'This workspace API key is invalid or revoked. Create or replace it in Connection settings.',
+  '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',
   'workspaces_list', 'workspace_create', 'workspace_archive', 'workspace_unarchive',
@@ -93,6 +98,33 @@ function secretSafe(value, depth = 0) {
   return value;
 }
 
+function authenticationErrorResult(status, value) {
+  if (status !== 401 && status !== 403) return null;
+  const body = value && typeof value === 'object' ? value : {};
+  const candidates = [body.practiceRunError, body.error, body];
+  const source = candidates.find((candidate) => candidate && typeof candidate === 'object'
+    && typeof candidate.code === 'string' && typeof candidate.message === 'string');
+  const routeCode = source?.code
+    ?? (typeof body.code === 'string' ? body.code : undefined)
+    ?? (typeof body.error === 'string' && body.error !== 'unauthorized' ? body.error : undefined);
+  if (routeCode && !Object.hasOwn(AUTH_TEACHING, routeCode)) return null;
+  const expectedMessage = source ? AUTH_TEACHING[source.code] : undefined;
+  const error = expectedMessage && source.message === expectedMessage
+    ? { code: source.code, message: expectedMessage }
+    : { message: 'Meguro practice request failed.' };
+  return {
+    content: [{ type: 'text', text: JSON.stringify({ httpStatus: status, error }, null, 2) }],
+    isError: true,
+  };
+}
+
+class ToolResultError extends Error {
+  constructor(result) {
+    super('Meguro request failed.');
+    this.result = result;
+  }
+}
+
 // A store-deletion preview intentionally returns one narrow capability for the caller to
 // present back on the second step. Keep every other response field behind the normal secret
 // scrubber and opt this single, format-checked value back in explicitly.
@@ -122,6 +154,8 @@ function catalogSnapshotProjection(value) {
 }
 
 function practiceErrorResult(status, value, retryAfterSeconds) {
+  const authenticationError = authenticationErrorResult(status, value);
+  if (authenticationError) return authenticationError;
   const body = value && typeof value === 'object' ? value : {};
   const stable = { httpStatus: status };
   if (body.practiceRunError && typeof body.practiceRunError === 'object') {
@@ -248,6 +282,14 @@ function requiredPracticeStoreId(args) {
   return validatedStoreId(canonical, provided[0]);
 }
 
+function requiredPracticeAttemptId(args, key = 'attemptId') {
+  const attemptId = requiredString(args, key);
+  if (!PRACTICE_ATTEMPT_ID.test(attemptId)) {
+    throw new Error(`${key} must be the pa-... run identity returned by practice_run_start, not a practice-store id (storeId)`);
+  }
+  return attemptId;
+}
+
 function optionalPositiveInteger(args, key) {
   const value = args?.[key];
   if (value === undefined) return undefined;
@@ -664,6 +706,8 @@ export function createTools(config) {
     let json;
     try { json = JSON.parse(text); } catch { json = { raw: text }; }
     if (!response.ok) {
+      const authenticationError = authenticationErrorResult(response.status, json);
+      if (authenticationError) throw new ToolResultError(authenticationError);
       const message = json.errors?.[0]?.message ?? json.error ?? text.slice(0, 300);
       throw new Error(`${response.status} ${path}: ${message}`);
     }
@@ -786,7 +830,10 @@ export function createTools(config) {
 
   async function fleetRequest(toolName, method, path, body, options = {}) {
     const response = await apiRaw(method, path, body, options);
-    if (!response.ok) return { error: await fleetErrorResult(toolName, path, response.status, response.json, response.requestId) };
+    if (!response.ok) {
+      const authenticationError = authenticationErrorResult(response.status, response.json);
+      return { error: authenticationError ?? await fleetErrorResult(toolName, path, response.status, response.json, response.requestId) };
+    }
     return { value: response.json };
   }
 
@@ -883,7 +930,8 @@ export function createTools(config) {
     const response = await practiceApi(method, path, body);
     return response.ok
       ? { value: response.json ?? {} }
-      : { error: await examErrorResult(toolName, path, response, attemptId) };
+      : { error: authenticationErrorResult(response.status, response.json)
+        ?? await examErrorResult(toolName, path, response, attemptId) };
   }
 
   async function examReceiptArtifact(examId, kind, expectedDigest) {
@@ -894,6 +942,8 @@ export function createTools(config) {
       const text = await response.text();
       let json;
       try { json = text ? JSON.parse(text) : null; } catch { json = { examError: { message: 'Meguro returned a non-JSON receipt error.' } }; }
+      const authenticationError = authenticationErrorResult(response.status, json);
+      if (authenticationError) return { error: authenticationError };
       const error = await examErrorResult('exam_report', path, {
         status: response.status,
         json,
@@ -1317,7 +1367,7 @@ export function createTools(config) {
       inputSchema: {
         type: 'object', additionalProperties: false,
         properties: {
-          attemptId: { type: 'string', minLength: 1, description: 'Completed practice-run attempt id carrying immutable Exam capture.' },
+          attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Completed practice-run attempt id carrying immutable Exam capture.' },
           shopDomain: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$', description: 'Exact lowercase connected Shopify development-store domain.' },
         },
         required: ['attemptId', 'shopDomain'],
@@ -1329,7 +1379,7 @@ export function createTools(config) {
       inputSchema: {
         type: 'object', additionalProperties: false,
         properties: {
-          attemptId: { type: 'string', minLength: 1, description: 'Completed practice-run attempt id carrying immutable Exam capture.' },
+          attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Completed practice-run attempt id carrying immutable Exam capture.' },
           shopDomain: { type: 'string', pattern: '^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$', description: 'Exact lowercase connected Shopify development-store domain; this is the typed target confirmation.' },
         },
         required: ['attemptId', 'shopDomain'],
@@ -1362,7 +1412,7 @@ export function createTools(config) {
         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.' },
-          continueFromAttemptId: { type: 'string', minLength: 1, description: 'Completed prior segment to continue on the same aging practice store. Available only when the server tier policy allows continuation.' },
+          continueFromAttemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Completed prior segment to continue on the same aging practice store. Available only when the server tier policy allows continuation.' },
           clock: { type: 'object', description: 'Existing hosted practice-run clock contract.' },
           externalAgent: { type: 'object', description: 'Optional bounded external-agent identity metadata.' },
           subject: {
@@ -1388,7 +1438,7 @@ export function createTools(config) {
       description: 'Read the server-authoritative state of an external-agent practice run, including its announced run-conclusion deadlines and immutable conclusion receipt after any exit. 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).' } },
+        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
         required: ['attemptId'],
       },
     },
@@ -1397,7 +1447,7 @@ export function createTools(config) {
       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).' } },
+        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
         required: ['attemptId'],
       },
     },
@@ -1408,7 +1458,7 @@ export function createTools(config) {
         type: 'object',
         additionalProperties: false,
         properties: {
-          attemptId: { type: 'string', minLength: 1, description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' },
+          attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', 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.' },
@@ -1423,7 +1473,7 @@ export function createTools(config) {
       description: 'Explicitly finish an external-agent practice run without inventing additional time or evidence. The response includes the immutable conclusion receipt and echoes the deadlines announced at start. 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).' } },
+        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
         required: ['attemptId'],
       },
     },
@@ -1432,7 +1482,7 @@ export function createTools(config) {
       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". The payload includes an unguessable public receipt id, canonical unauthenticated fetch path, and SHA-256: gate a deploy by fetching that id and verifying the exact bytes before promotion. Raw private request and response payloads stay out of MCP; use Console for quick proof while the agent remains in the caller\'s environment. Receipts remain fetchable for 7 days on Free, 90 days on Solo, and 365 days on Builder; an expired response teaches the applicable upgrade or a fresh run.',
       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).' } },
+        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
         required: ['attemptId'],
       },
     },
@@ -1441,7 +1491,7 @@ export function createTools(config) {
       description: 'Read the impact receipt for a completed external-agent practice run: the base year — the same store, same days, without your agent — compared with your agent\'s year, showing what changed because of your agent (orders, units, and revenue), a footprint of every write, and an integrity gate that reports a reason instead of numbers when the comparison is not clean. The payload includes an unguessable public receipt id, canonical unauthenticated fetch path, and SHA-256: gate a deploy by fetching that id and verifying the exact bytes before promotion. Read-only; never mutates the run and returns no credentials. Takes the run\'s attemptId (from practice_run_start), not the practice-store id (storeId). Receipts remain fetchable for 7 days on Free, 90 days on Solo, and 365 days on Builder; an expired response teaches the applicable upgrade or a fresh run.',
       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).' } },
+        properties: { attemptId: { type: 'string', minLength: 4, maxLength: 128, pattern: '^pa-[a-z0-9][a-z0-9-]{0,124}$', description: 'Run identity returned by practice_run_start — not the practice-store id (storeId).' } },
         required: ['attemptId'],
       },
     },
@@ -1494,9 +1544,25 @@ export function createTools(config) {
     const { title, ...annotations } = presentation;
     return { ...definition, title, annotations };
   });
+  const definitionsByName = new Map(definitions.map((definition) => [definition.name, definition]));
+
+  function validateTopLevelArguments(name, args) {
+    const definition = definitionsByName.get(name);
+    if (!definition) return;
+    if (!args || typeof args !== 'object' || Array.isArray(args)) {
+      throw new Error(`${name} arguments must be an object`);
+    }
+    if (definition.inputSchema.additionalProperties !== false) return;
+    const allowed = new Set(Object.keys(definition.inputSchema.properties ?? {}));
+    const unexpected = Object.keys(args).filter((key) => !allowed.has(key)).sort();
+    if (unexpected.length > 0) {
+      throw new Error(`${name} arguments must match the declared top-level properties: ${[...allowed].join(', ') || '(none)'}`);
+    }
+  }
 
   async function call(name, args = {}) {
     try {
+      validateTopLevelArguments(name, args);
       switch (name) {
         case 'docs_read': {
           const topic = requiredString(args, 'topic');
@@ -1778,13 +1844,13 @@ export function createTools(config) {
           )));
         }
         case 'exam_preflight': {
-          const attemptId = requiredString(args, 'attemptId');
+          const attemptId = requiredPracticeAttemptId(args);
           const shopDomain = requiredShopifyDevDomain(args);
           const response = await examRequest(name, 'POST', '/practice-exams/preflight', { attemptId, shopDomain }, attemptId);
           return 'error' in response ? response.error : textResult(secretSafe(response.value));
         }
         case 'exam_start': {
-          const attemptId = requiredString(args, 'attemptId');
+          const attemptId = requiredPracticeAttemptId(args);
           const shopDomain = requiredShopifyDevDomain(args);
           const created = await examRequest(name, 'POST', '/practice-exams', { attemptId, shopDomain }, attemptId);
           if ('error' in created) return created.error;
@@ -1869,7 +1935,7 @@ export function createTools(config) {
           const storeId = requiredPracticeStoreId(args);
           const body = {
             purpose: 'external-agent',
-            ...(args.continueFromAttemptId !== undefined ? { continueFromAttemptId: args.continueFromAttemptId } : {}),
+            ...(args.continueFromAttemptId !== undefined ? { continueFromAttemptId: requiredPracticeAttemptId(args, 'continueFromAttemptId') } : {}),
             ...(args.clock !== undefined ? { clock: args.clock } : {}),
             ...(args.externalAgent !== undefined ? { externalAgent: args.externalAgent } : {}),
             ...(args.subject !== undefined ? { subject: args.subject } : {}),
@@ -1893,7 +1959,7 @@ export function createTools(config) {
           }));
         }
         case 'practice_run_status': {
-          const attemptId = requiredString(args, 'attemptId');
+          const attemptId = requiredPracticeAttemptId(args);
           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 ?? {};
@@ -1905,7 +1971,7 @@ export function createTools(config) {
           }));
         }
         case 'practice_run_checkpoint': {
-          const attemptId = requiredString(args, 'attemptId');
+          const attemptId = requiredPracticeAttemptId(args);
           const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/checkpoint`, {});
           if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
           return textResult(secretSafe({
@@ -1917,7 +1983,7 @@ export function createTools(config) {
           }));
         }
         case 'practice_run_advance': {
-          const attemptId = requiredString(args, 'attemptId');
+          const attemptId = requiredPracticeAttemptId(args);
           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');
@@ -1942,7 +2008,7 @@ export function createTools(config) {
           }));
         }
         case 'practice_run_finish': {
-          const attemptId = requiredString(args, 'attemptId');
+          const attemptId = requiredPracticeAttemptId(args);
           const response = await practiceApi('POST', `/practice/playbacks/${encodeURIComponent(attemptId)}/finish`, {});
           if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
           return textResult(secretSafe({
@@ -1953,7 +2019,7 @@ export function createTools(config) {
           }));
         }
         case 'practice_run_report': {
-          const attemptId = requiredString(args, 'attemptId');
+          const attemptId = requiredPracticeAttemptId(args);
           const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/report?v=2`);
           if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
           return textResult({
@@ -1963,7 +2029,7 @@ export function createTools(config) {
           });
         }
         case 'practice_run_impact': {
-          const attemptId = requiredString(args, 'attemptId');
+          const attemptId = requiredPracticeAttemptId(args);
           const response = await practiceApi('GET', `/practice/playbacks/${encodeURIComponent(attemptId)}/impact`);
           if (!response.ok) return practiceErrorResult(response.status, response.json, response.retryAfterSeconds);
           // T1 owns the shape and the API already ran the public-safe scan; pass it through verbatim
@@ -1999,12 +2065,14 @@ export function createTools(config) {
             // 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);
+          const { ok, status, 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) });
           }
+          const authenticationError = authenticationErrorResult(status, json);
+          if (authenticationError) return authenticationError;
           // 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 };
@@ -2023,6 +2091,7 @@ export function createTools(config) {
           return errorResult(`Unknown tool: ${name}`);
       }
     } catch (error) {
+      if (error instanceof ToolResultError) return error.result;
       if (FLEET_TOOL_NAMES.has(name)) {
         return fleetErrorResult(name, `mcp:${name}`, 0, {
           errors: [{