@topolo/mcp 0.10.2 → 0.11.0

package/README.md

@@ -11,14 +11,18 @@ tools rather than shelling out.
   them typed tool schemas, scope-filtered tool advertisement, and structured
   error responses. Both wrap the same `@topolo/sdk`.
 
-## Install
+## Install and register
 
 ```bash
-npm install -g @topolo/mcp
+npm install -g @topolo/cli
+topolo setup
+topolo auth login
+topolo doctor
 ```
 
-You don't have to install globally — the registration snippets below use `npx`
-so the server downloads on demand.
+Customers install only `@topolo/cli`; it owns an exact compatible MCP and SDK.
+`topolo setup` registers the resolved local Node entry point, so agent startup
+does not depend on `npx`, network access, or a separately synchronized package.
 
 ## Get a credential
 
@@ -33,45 +37,10 @@ Either:
 
 ## Register with an MCP client
 
-### Claude Code
-
-```bash
-claude mcp add topolo -- npx -y @topolo/mcp
-```
-
-Then set the credential and (optional) agent label in your shell profile so
-Claude Code inherits them when it spawns the server:
-
-```bash
-export TOPOLO_API_KEY=topo_live_...
-export TOPOLO_AGENT_NAME=claude-code
-```
-
-### Claude Desktop
-
-`claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "topolo": {
-      "command": "npx",
-      "args": ["-y", "@topolo/mcp"],
-      "env": {
-        "TOPOLO_API_KEY": "topo_live_...",
-        "TOPOLO_AGENT_NAME": "claude-desktop"
-      }
-    }
-  }
-}
-```
-
-### Codex / Cursor / generic MCP host
-
-Any MCP host that spawns a stdio subprocess works. Point `command` at
-`npx -y @topolo/mcp` and pass the same env vars. Most Codex-style setups also
-read `AGENTS.md` files — see `@topolo/cli`'s `skills/codex/AGENTS.md` for a
-ready-made agent guide that covers both the CLI and this MCP.
+Run `topolo setup`; it configures Claude Code and Codex with an absolute Node
+entry point resolved from the installed CLI dependency graph. Advanced hosts
+may execute the exported `@topolo/mcp/stdio` entry directly, but customer setup
+must not use an `npx` launcher because that makes startup network-dependent.
 
 ## Supported env vars
 
@@ -147,8 +116,6 @@ deletion, encryption, and audit storage for the data they own.
 | `topolo_whoami`              | (none)                | no               |
 | `topolo_search_applications` | (none)                | no               |
 | `topolo_get_application`     | (none)                | no               |
-| `topolo_list_application_requirements` | (none)      | no               |
-| `topolo_audit_applications`  | (none)                | no               |
 | `topolo_search_actions`      | (credential-scoped)   | no               |
 | `topolo_get_action`          | (credential-scoped)   | no               |
 | `topolo_read_action`         | catalog or target policy | no            |
@@ -217,9 +184,8 @@ sent.
   catalog. They do not expose the global generated platform catalog.
 - **Credential-scoped action discovery.** `topolo_search_actions` reads only one
   app partition and returns at most 100 permission-filtered actions per page.
-  Search, capability discovery, validation, planning, and application audit
-  return compact agent guidance by default; pass `detail: true` only when the
-  full contracts or findings are needed.
+  Search, capability discovery, validation, and planning return compact agent
+  guidance by default; pass `detail: true` only when full contracts are needed.
 - **Audit headers.** Every request sends `X-Topolo-Client: topolo-mcp/<ver>`,
   `X-Topolo-Agent: <label>`, `X-Topolo-Request-Id: <uuid>`.
 - **Write-action confirmation.** The SDK refuses mutating HTTP methods unless

package/dist/dispatch.d.ts

@@ -75,6 +75,11 @@ type ToolDispatchResult = {
     reason: ToolDispatchFailureReason;
     durationMs: number;
     requiredScopes?: string[];
+    code?: string;
+    status?: number;
+    requestId?: string;
+    details?: unknown;
+    hint?: string;
 };
 interface ToolAdvertisement {
     name: string;

package/dist/dispatch.js

@@ -1,29 +1,24 @@
 // src/dispatch.ts
-import { TopoloAuthError, TopoloPermissionError } from "@topolo/sdk";
+import {
+  TopoloAuthError,
+  TopoloHttpError,
+  TopoloPermissionError,
+  publicTopoloErrorMessage,
+  topoloErrorHint
+} from "@topolo/sdk";
 
 // src/tools.ts
 import {
-  APPLICATION_REQUIREMENTS,
-  APPLICATION_REQUIREMENTS_VERSION,
-  auditApplicationEntries,
-  applicationRequirementScopes,
   compactActionCatalogEntry,
+  compactActionPreparation,
   compactActionPlan,
   compactActionValidation,
-  compactApplicationAudit,
   friendlyAppId,
-  listApplicationDirectory,
-  requirementsForApplication,
-  resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl
 } from "@topolo/sdk";
 
 // src/gating.ts
-function hasPlatformAccess(set) {
-  return (set.role === "platform_super_admin" || set.role === "platform_admin") && set.orgSlug === "admin";
-}
 function hasScope(set, required) {
-  if (hasPlatformAccess(set)) return true;
   if (set.permissions.includes("*")) return true;
   const [servicePart, actionPart] = splitPermission(required);
   if (!servicePart) return set.permissions.includes(required);
@@ -373,6 +368,38 @@ var TOOLS = [
       return args["detail"] === true ? result : compactActionValidation(result.action.actionId, result.validation);
     }
   },
+  {
+    name: "topolo_prepare_action",
+    title: "Prepare one Topolo action",
+    description: "Fetches one exact live action contract once and returns one valid published example, missing fields, exact request, confirmation state, verification, and rollback without executing it.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        resourceType: { type: "string" },
+        resourceId: { type: "string" },
+        confirm: { type: "boolean", description: "Include confirmation in the plan without executing the action." }
+      },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = requiredString(args, "actionId");
+      const resource = optionalResourceContext(args);
+      const preparation = await topolo.client.prepareAction(
+        actionId,
+        args["input"] === void 0 ? void 0 : coerceObjectParam(args["input"], "input"),
+        {
+          confirm: args["confirm"] === true,
+          ...resource ? { resource } : {}
+        }
+      );
+      return compactActionPreparation(preparation);
+    }
+  },
   {
     name: "topolo_plan_action",
     title: "Plan one Topolo action",
@@ -584,87 +611,6 @@ var TOOLS = [
       args["confirm"] === true
     )
   },
-  {
-    name: "topolo_list_application_requirements",
-    title: "List Topolo application build requirements",
-    description: "Returns the current versioned Topolo application-build contract, optionally filtered to one application. Use this before creating or expanding a Topolo app so the agent follows shared metadata, docs, auth, shell, service registration, deployment, observability, and verification requirements.",
-    requiredScopes: [],
-    destructive: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        application: {
-          type: "string",
-          description: "Optional application ID from topolo_search_applications."
-        }
-      },
-      additionalProperties: false
-    },
-    handler: async (topolo, args) => {
-      const application = args["application"];
-      if (application === void 0) {
-        return {
-          version: APPLICATION_REQUIREMENTS_VERSION,
-          application: null,
-          scopes: ["all", "browser", "api", "tooling", "agent_surface"],
-          requirements: APPLICATION_REQUIREMENTS
-        };
-      }
-      const resolved = await resolveDirectoryApplication(topolo, application);
-      const app = resolved.application;
-      return {
-        version: APPLICATION_REQUIREMENTS_VERSION,
-        application: app,
-        scopes: applicationRequirementScopes(app),
-        requirements: requirementsForApplication(app)
-      };
-    }
-  },
-  {
-    name: "topolo_audit_applications",
-    title: "Audit Topolo applications against platform requirements",
-    description: "Returns catalog-backed conformance scores and migration-queue items for all Topolo apps, or one application when provided. Use this to see which shared platform requirements need implementation, verification, or deeper review.",
-    requiredScopes: [],
-    destructive: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        application: {
-          type: "string",
-          description: "Optional application ID from topolo_search_applications."
-        },
-        failOn: {
-          type: "string",
-          enum: ["missing", "needs_review", "partial"],
-          description: "Optional conformance gate. Returns conformanceGate.passed=false when findings at this severity or worse exist."
-        },
-        detail: {
-          type: "boolean",
-          description: "Include every finding and migration item. Defaults to per-app scores and a queue count."
-        }
-      },
-      additionalProperties: false
-    },
-    handler: async (topolo, args) => {
-      const application = args["application"];
-      const failOn = args["failOn"];
-      if (failOn !== void 0 && typeof failOn !== "string") {
-        throw new TopoloMcpPublicError("failOn must be one of: missing, needs_review, partial");
-      }
-      const gate = failOn ? normalizeFailOn(failOn) : null;
-      let report;
-      if (application === void 0) {
-        const directory = await listApplicationDirectory(topolo.client);
-        report = auditApplicationEntries(directory.applications.map((app) => app.application));
-        const output2 = args["detail"] === true ? report : compactApplicationAudit(report);
-        return gate ? { ...output2, conformanceGate: evaluateApplicationAuditGate(report, gate) } : output2;
-      }
-      const resolved = await resolveDirectoryApplication(topolo, application);
-      report = auditApplicationEntries([resolved.application]);
-      const output = args["detail"] === true ? report : compactApplicationAudit(report);
-      return gate ? { ...output, conformanceGate: evaluateApplicationAuditGate(report, gate) } : output;
-    }
-  },
   {
     name: "topolo_api_call",
     title: "Call any Topolo platform service",
@@ -764,57 +710,9 @@ async function buildTopoloTools(topolo, scopes, tools = TOOLS) {
   void topolo;
   return filterToolsByScopes(tools, scopes);
 }
-function evaluateApplicationAuditGate(report, threshold) {
-  const counts = {
-    met: 0,
-    partial: 0,
-    missing: 0,
-    needs_review: 0
-  };
-  for (const audit of report.applications) {
-    for (const finding of audit.findings) {
-      counts[finding.status] += 1;
-    }
-  }
-  const failingFindings = statusesAtOrWorse(threshold).reduce(
-    (total, status) => total + counts[status],
-    0
-  );
-  return {
-    threshold,
-    passed: failingFindings === 0,
-    message: failingFindings === 0 ? `No findings at or above ${threshold}.` : `${failingFindings} finding(s) at or above ${threshold}.`,
-    failingFindings,
-    counts
-  };
-}
-function normalizeFailOn(value) {
-  const normalized = value.trim().toLowerCase().replace(/-/g, "_");
-  if (normalized === "missing" || normalized === "needs_review" || normalized === "partial") {
-    return normalized;
-  }
-  throw new TopoloMcpPublicError("failOn must be one of: missing, needs_review, partial");
-}
-function statusesAtOrWorse(threshold) {
-  if (threshold === "missing") return ["missing"];
-  if (threshold === "needs_review") return ["missing", "needs_review"];
-  return ["missing", "needs_review", "partial"];
-}
 function displayAppId(entry) {
   return friendlyAppId(entry);
 }
-async function resolveDirectoryApplication(topolo, application) {
-  if (typeof application !== "string" || !application.trim()) {
-    throw new TopoloMcpPublicError("`application` must be a non-empty string.");
-  }
-  try {
-    return await resolveApplicationDirectoryEntry(topolo.client, application);
-  } catch (error) {
-    throw new TopoloMcpPublicError(
-      error instanceof Error ? error.message : `Unknown application "${application}".`
-    );
-  }
-}
 
 // src/dispatch.ts
 function listAvailableTopoloTools(scopes, tools = TOOLS) {
@@ -867,8 +765,13 @@ async function dispatchTopoloTool(input) {
       return {
         ok: false,
         reason: "permission",
-        error: `Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`,
+        error: publicTopoloErrorMessage(err),
         requiredScopes: err.required,
+        code: err.code,
+        status: err.status,
+        requestId: err.requestId,
+        details: err.details,
+        hint: topoloErrorHint(err),
         durationMs: Date.now() - started
       };
     }
@@ -877,6 +780,24 @@ async function dispatchTopoloTool(input) {
         ok: false,
         reason: "auth",
         error: "Authentication failed.",
+        code: err.code,
+        status: err.status,
+        requestId: err.requestId,
+        details: err.details,
+        hint: topoloErrorHint(err),
+        durationMs: Date.now() - started
+      };
+    }
+    if (err instanceof TopoloHttpError) {
+      return {
+        ok: false,
+        reason: "handler",
+        error: publicTopoloErrorMessage(err),
+        code: err.code,
+        status: err.status,
+        requestId: err.requestId,
+        details: err.details,
+        hint: topoloErrorHint(err),
         durationMs: Date.now() - started
       };
     }

package/dist/http.d.ts

@@ -1,5 +1,5 @@
+import { TopoloRuntimeEnvironment, TopoloCredential, Topolo } from '@topolo/sdk';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
-import { TopoloCredential, Topolo } from '@topolo/sdk';
 
 /**
  * Hosted, multi-tenant MCP Streamable HTTP transport for the Topolo platform.
@@ -18,9 +18,11 @@ import { TopoloCredential, Topolo } from '@topolo/sdk';
  * Mcp-Session-Id continuity, GET SSE stream, DELETE to terminate) over pure
  * Web-Standard Request/Response — so it runs unchanged in a Cloudflare Worker.
  */
-interface TopoloMcpHttpOptions {
+interface TopoloMcpHttpInternalOptions {
     /** Path the MCP endpoint is mounted at. Defaults to '/mcp'. */
     path?: string;
+    /** Effective Topolo environment. Defaults to production and is always surfaced to the MCP client. */
+    environment?: TopoloRuntimeEnvironment;
     /** Per-service URL overrides (e.g. staging). Passed through to createTopolo. */
     serviceUrls?: Record<string, string>;
     /** Per-service TopoloAuth app-id overrides. Passed through to createTopolo. */
@@ -52,12 +54,33 @@ interface McpSession {
  *   const handler = createTopoloMcpHttpHandler();
  *   export default { fetch: handler.fetch };
  */
-declare function createTopoloMcpHttpHandler(options?: TopoloMcpHttpOptions): {
+declare function createTopoloMcpHttpHandlerInternal(options?: TopoloMcpHttpInternalOptions): {
     /** Cloudflare Worker / fetch-compatible entrypoint. */
     fetch: (request: Request) => Promise<Response>;
     /** Exposed for tests/introspection. */
     sessions: Map<string, McpSession>;
 };
+type TopoloMcpHttpHandlerInternal = ReturnType<typeof createTopoloMcpHttpHandlerInternal>;
+
+interface TopoloMcpHttpOptions {
+    /** Path the MCP endpoint is mounted at. Defaults to '/mcp'. */
+    path?: string;
+    /** Effective Topolo environment. Defaults to production and is always surfaced to the MCP client. */
+    environment?: TopoloRuntimeEnvironment;
+    /** Per-service URL overrides (e.g. staging). Passed through to createTopolo. */
+    serviceUrls?: Record<string, string>;
+    /** Per-service TopoloAuth app-id overrides. Passed through to createTopolo. */
+    appIds?: Record<string, string>;
+    /** Human-readable agent label for audit logs (forwarded to the SDK). */
+    agentName?: string;
+    /** Validated network transport for the SDK client. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Create the public hosted MCP handler. The SDK client is always constructed
+ * here from the validated effective environment and per-request credential.
+ */
+declare function createTopoloMcpHttpHandler(options?: TopoloMcpHttpOptions): TopoloMcpHttpHandlerInternal;
 type TopoloMcpHttpHandler = ReturnType<typeof createTopoloMcpHttpHandler>;
 
 export { type TopoloMcpHttpHandler, type TopoloMcpHttpOptions, createTopoloMcpHttpHandler };