meguro-mcp 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to `meguro-mcp` are recorded here. Versions follow Semantic Versioning.
 
+## 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.1
 ```
 
 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.1
 ```
 
 ## 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.1"],
       "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.1",
   "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.1' };
 const PROTOCOL_VERSION = '2025-03-26';
 
 const tools = createTools({

package/src/tools.mjs

@@ -11,6 +11,10 @@ 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 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 +97,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 +153,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') {
@@ -664,6 +697,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 +821,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 +921,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 +933,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,
@@ -1999,12 +2040,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 +2066,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: [{