@topolo/mcp 0.6.0 → 0.7.1

package/README.md

@@ -26,9 +26,10 @@ Either:
 
 - **Long-lived**: mint an API key at the Topolo Developers console
   (`TOPOLO_API_KEY=topo_live_...`). Preferred for persistent agent installs.
-- **Short-lived**: `topolo auth login` with the CLI, then copy the access token
-  from `~/.config/topolo/config.json`. Useful for dev and testing. MCP does
-  not read the CLI config directly; pass the token in `TOPOLO_ACCESS_TOKEN`.
+- **Short-lived**: run `topolo auth login`. The stdio MCP reads and refreshes
+  the same environment-specific credential store, so no token copying is
+  needed. Explicit `TOPOLO_API_KEY` or `TOPOLO_ACCESS_TOKEN` values still take
+  precedence for headless installations.
 
 ## Register with an MCP client
 
@@ -89,9 +90,9 @@ wins.
 1. Resolve the credential from env. **Refuse to start** if none is set.
 2. Call `GET /api/me` to load the user's granted scopes + role.
 3. Connect the stdio transport and begin serving MCP requests.
-4. On tool listing and tool calls, filter static tools by those scopes and load
-   the live action catalog for the credential. Agents never see an action tool
-   they cannot use.
+4. Advertise a fixed, bounded discovery/invocation surface. Agents search one
+   application at a time and call exact action IDs; the server never expands
+   one MCP tool per action or materializes the global catalog.
 
 Startup is synchronous and fast (< 500 ms typical). If the credential is
 rejected, the process logs the error to stderr and exits non-zero — host
@@ -102,44 +103,64 @@ clients surface that as a failed server launch.
 | Tool                         | Required scopes       | Destructive hint |
 | ---------------------------- | --------------------- | ---------------- |
 | `topolo_whoami`              | (none)                | no               |
-| `topolo_list_services`       | (none)                | no               |
-| `topolo_list_applications`   | (none)                | no               |
+| `topolo_search_applications` | (none)                | no               |
 | `topolo_get_application`     | (none)                | no               |
 | `topolo_list_application_requirements` | (none)      | no               |
 | `topolo_audit_applications`  | (none)                | no               |
-| `topolo_list_actions`        | (credential-scoped)   | no               |
-| Dynamic action tools         | action permission     | action-defined   |
+| `topolo_search_actions`      | (credential-scoped)   | no               |
+| `topolo_get_action`          | (credential-scoped)   | no               |
+| `topolo_read_action`         | catalog or target policy | no            |
+| `topolo_call_action`         | catalog or target policy | yes           |
 | `topolo_api_call`            | (service-enforced)    | yes              |
 
 Applications publish machine-action definitions through Topolo Developers.
 TopoloAuth projects those into a credential-scoped action catalog using the
 same service permissions already used for API keys and application access. MCP
-turns each visible catalog entry into a tool named by the action catalog, such
-as `topolo_mail_messages_send`, with the action's input schema and destructive
-hint.
+keeps six stable application/action tools regardless of whether the platform
+contains ten actions or one billion: search applications, search actions within
+one app, inspect exact applications/actions, safely invoke automatic reads, and
+invoke confirmation-gated actions.
+
+Most actions use `authorizationMode: static` and are filtered by one declared
+application permission before discovery. Operations whose authority depends on
+request input (for example, organization admin OR `grants:write` in the target
+application) use `authorizationMode: runtime`: the catalog exposes the typed
+capability without inventing a global permission, and the target service checks
+the current database-backed policy for the supplied organization/application on
+every call.
 
 `topolo_api_call` is the escape hatch for endpoints without typed MCP tools
 yet. GET requests work without confirmation; mutating HTTP methods must pass
 `confirm: true` or the SDK rejects the call. Backing services still enforce
 permissions for every request. The tool schema intentionally does not embed a
-large service enum; agents should call `topolo_list_services` first, then pass a
+large service enum; agents should call `topolo_search_applications` first, then pass an
 app ID/slug from that credential-scoped result. New services become callable
 without an MCP release once Auth grants the organization and credential the
-relevant permissions, and new actions become typed tools without an MCP release
-once the application publishes them.
+relevant permissions, and new actions become discoverable/callable without an
+MCP release once the application publishes them.
+
+`topolo_read_action` and `topolo_call_action` accept an optional paired
+`resourceType` / `resourceId` context for app-local workspace boundaries. The
+SDK sends it as resource headers without changing the credential's personal or
+organization context. This lets agents address many workspaces independently;
+providing only one of the pair is rejected before the request is sent.
 
 ## Safety rails
 
 - **No `orgId` parameter** on any tool. The organization is derived entirely
   from the credential by each backend app. There is no path for Org A's agent
   to see Org B's data.
-- **Scope-gated tool advertisement.** Agents never see tools they can't use —
-  fewer wasted attempts and less prompt noise.
-- **Credential-scoped catalog discovery.** `topolo_list_services` and
-  `topolo_list_applications` use TopoloAuth's live organization/permission
+- **Credential-bound context.** OAuth tokens and refresh rotation retain their
+  own personal/org context. CLI/MCP context switches do not move the user's web
+  session, and browser switches cannot redirect a running agent credential.
+- **Scope-gated tool advertisement.** Static actions are removed unless their
+  permission is granted. Input-dependent runtime actions remain discoverable
+  and are authorized by the target service for the concrete request.
+- **Credential-scoped catalog discovery.** `topolo_search_applications` uses
+  TopoloAuth's live organization/permission
   catalog. They do not expose the global generated platform catalog.
-- **Credential-scoped action discovery.** Dynamic action tools are loaded from
-  the live Auth action catalog and filtered by existing service permissions.
+- **Credential-scoped action discovery.** `topolo_search_actions` reads only one
+  app partition and returns at most 100 permission-filtered actions per page.
 - **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
@@ -180,10 +201,33 @@ npx @modelcontextprotocol/inspector node dist/index.js
 
 ## Release Flow
 
-Preferred flow: push a `v<x.y.z>` tag to `main`; GitHub Actions typechecks,
-tests, builds, verifies the tag matches `package.json`, and publishes to npm via
-the `NPM_TOKEN` secret. Operators may publish directly with an npm token only
-after running the same package checks and `npm pack --dry-run`.
+Agent packages are released locally from the `staging` branch after its package
+gates pass. Publish in dependency order (`@topolo/sdk`, `@topolo/cli`, then
+`@topolo/mcp`) so every public dependency already exists in the registry.
+
+For each package, run its tests, typecheck, build, and tarball verification:
+
+```bash
+pnpm --dir packages/topolo-mcp test
+pnpm --dir packages/topolo-mcp typecheck
+pnpm --dir packages/topolo-mcp build
+node tooling/verify-npm-package.mjs packages/topolo-mcp
+```
+
+The npm token is stored in the macOS Keychain under `registry.npmjs.org`. Use a
+temporary npm config so the token is never written into the repository or
+printed:
+
+```bash
+printf '//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}\n' > /tmp/topolo-release.npmrc
+NODE_AUTH_TOKEN="$(security find-generic-password -s registry.npmjs.org -w)" \
+  NPM_CONFIG_USERCONFIG=/tmp/topolo-release.npmrc \
+  sh -c 'cd packages/topolo-mcp && npm publish --access public'
+```
+
+After publishing, install exact versions into an empty temporary directory and
+exercise the SDK exports, CLI version command, MCP exports, and `topolo-mcp`
+executable before updating `topoloPublishedVersion`.
 
 ## Phase 2 (planned)
 

package/dist/dispatch.js

@@ -53,6 +53,15 @@ function splitService(servicePart) {
 // src/tools.ts
 var APPLICATION_IDS = Object.keys(APPLICATIONS).sort();
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+function optionalResourceContext(args) {
+  const resourceType = typeof args["resourceType"] === "string" ? args["resourceType"].trim() : "";
+  const resourceId = typeof args["resourceId"] === "string" ? args["resourceId"].trim() : "";
+  if (!resourceType && !resourceId) return void 0;
+  if (!resourceType || !resourceId) {
+    throw new Error("resourceType and resourceId must be provided together.");
+  }
+  return { resourceType, resourceId };
+}
 var TOOLS = [
   {
     name: "topolo_whoami",
@@ -68,22 +77,32 @@ var TOOLS = [
     handler: async (topolo) => topolo.identity.whoami()
   },
   {
-    name: "topolo_list_services",
-    title: "List every Topolo service the agent can reach",
-    description: "Returns the credential-scoped service registry: one entry per platform service the current credential can use in its organization, with granted permissions, API URL, and launch URL. Use this to discover what `topolo_api_call` can address. This is not the global platform catalog.",
+    name: "topolo_search_applications",
+    title: "Search Topolo applications the agent can reach",
+    description: "Searches the credential-scoped application registry with a bounded page and continuation cursor. Returns actionService as the canonical selector for topolo_search_actions, plus granted permissions, API URL, and launch URL without loading the global platform catalog.",
     requiredScopes: [],
     destructive: false,
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        query: { type: "string" },
+        cursor: { type: "string" },
+        limit: { type: "integer", minimum: 1, maximum: 100, default: 25 }
+      },
       additionalProperties: false
     },
-    handler: async (topolo) => {
-      const services = (await topolo.client.listServices()).map((entry) => {
+    handler: async (topolo, args) => {
+      const result = await topolo.client.searchServices({
+        query: typeof args["query"] === "string" ? args["query"] : void 0,
+        cursor: typeof args["cursor"] === "string" ? args["cursor"] : void 0,
+        limit: typeof args["limit"] === "number" ? args["limit"] : void 0
+      });
+      const applications = result.services.map((entry) => {
         const id = displayAppId(entry);
         return {
           id,
           appId: entry.appId,
+          actionService: entry.appId,
           slug: entry.slug,
           name: entry.name,
           apiBaseUrl: entry.apiBaseUrl,
@@ -96,13 +115,13 @@ var TOOLS = [
           permissions: [...entry.permissions]
         };
       }).sort((left, right) => left.id.localeCompare(right.id));
-      return { services };
+      return { applications, page: result.page };
     }
   },
   {
-    name: "topolo_list_actions",
-    title: "List every Topolo action the agent can call",
-    description: "Returns the credential-scoped callable action catalog. Actions are published by applications through TopoloDevelopers and filtered by TopoloAuth against the current organization and effective permissions.",
+    name: "topolo_search_actions",
+    title: "Search Topolo actions the agent can call",
+    description: "Searches one application's credential-scoped actions with a bounded page and continuation cursor.",
     requiredScopes: [],
     destructive: false,
     inputSchema: {
@@ -110,31 +129,25 @@ var TOOLS = [
       properties: {
         service: {
           type: "string",
-          description: "Optional app id, slug, or name filter."
-        }
+          description: "Required application selector. Prefer actionService from topolo_search_applications; canonical app id, slug, and name are also accepted."
+        },
+        query: { type: "string" },
+        cursor: { type: "string" },
+        limit: { type: "integer", minimum: 1, maximum: 100, default: 25 }
       },
+      required: ["service"],
       additionalProperties: false
     },
-    handler: async (topolo, args) => ({
-      actions: await topolo.client.listActions({
-        service: typeof args["service"] === "string" ? args["service"] : void 0
-      })
-    })
-  },
-  {
-    name: "topolo_list_applications",
-    title: "List every Topolo platform application",
-    description: "Returns the live Topolo application catalog from the platform registry. Reflects apps as they are registered/removed with no client rebuild. Authenticated callers in an entitled org also see the developer_only apps their role permits. Falls back to a bundled snapshot only if the registry is unreachable.",
-    requiredScopes: [],
-    destructive: false,
-    inputSchema: {
-      type: "object",
-      properties: {},
-      additionalProperties: false
-    },
-    handler: async (topolo) => ({
-      applications: await topolo.client.listServices()
-    })
+    handler: async (topolo, args) => {
+      const service = typeof args["service"] === "string" ? args["service"].trim() : "";
+      if (!service) throw new Error("service is required for bounded action discovery.");
+      return topolo.client.searchActions({
+        service,
+        query: typeof args["query"] === "string" ? args["query"] : void 0,
+        cursor: typeof args["cursor"] === "string" ? args["cursor"] : void 0,
+        limit: typeof args["limit"] === "number" ? args["limit"] : void 0
+      });
+    }
   },
   {
     name: "topolo_get_application",
@@ -147,7 +160,7 @@ var TOOLS = [
       properties: {
         application: {
           type: "string",
-          description: "Application identifier: app id, slug, or name from topolo_list_applications."
+          description: "Application identifier: app id, slug, or name from topolo_search_applications."
         }
       },
       required: ["application"],
@@ -158,18 +171,98 @@ var TOOLS = [
       if (typeof application !== "string" || !application.trim()) {
         throw new Error("`application` must be a non-empty string.");
       }
-      const needle = application.trim().toLowerCase();
-      const catalog = await topolo.client.listServices();
-      const match = catalog.find(
-        (e) => e.appId.toLowerCase() === needle || e.slug && e.slug.toLowerCase() === needle || e.name && e.name.toLowerCase() === needle
+      return { application: await topolo.client.getService(application) };
+    }
+  },
+  {
+    name: "topolo_get_action",
+    title: "Describe one Topolo action",
+    description: "Returns one credential-scoped action by exact action id.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: { actionId: { type: "string", minLength: 1 } },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      if (!actionId) throw new Error("actionId is required.");
+      return { action: await topolo.client.getAction(actionId) };
+    }
+  },
+  {
+    name: "topolo_read_action",
+    title: "Call one read-only Topolo action",
+    description: "Calls one exact action id only when its published contract is read-only and needs no confirmation.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        resourceType: { type: "string", description: "Optional app-local resource alias, such as workspace." },
+        resourceId: { type: "string", description: "Resource id. Required when resourceType is provided." }
+      },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      if (!actionId) throw new Error("actionId is required.");
+      const input = args["input"];
+      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
+        throw new Error("input must be an object.");
+      }
+      const action = await topolo.client.getAction(actionId);
+      const agentAccess = action.agentAccess ?? (action.destructive ? "off" : action.readOnly && !action.requiresConfirmation ? "auto" : "confirm");
+      if (action.method !== "GET" || !action.readOnly || action.destructive || action.requiresConfirmation || agentAccess !== "auto") {
+        throw new Error(`Action "${actionId}" is not an automatic read-only action. Use topolo_call_action with confirmation.`);
+      }
+      const resource = optionalResourceContext(args);
+      return topolo.client.callAction(
+        actionId,
+        input ?? {},
+        resource ? { resource } : {}
       );
-      if (!match) {
-        const known = catalog.map((e) => e.slug || e.appId).sort().filter((value) => typeof value === "string" && value.length > 0);
-        throw new Error(
-          `Unknown application "${application}". ${formatKnownValues(known, "applications")}`
-        );
+    }
+  },
+  {
+    name: "topolo_call_action",
+    title: "Call one Topolo action",
+    description: "Calls one exact action id. Mutating actions require confirm:true.",
+    requiredScopes: [],
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true },
+        resourceType: { type: "string", description: "Optional app-local resource alias, such as workspace." },
+        resourceId: { type: "string", description: "Resource id. Required when resourceType is provided." },
+        confirm: { type: "boolean" }
+      },
+      required: ["actionId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const actionId = typeof args["actionId"] === "string" ? args["actionId"].trim() : "";
+      if (!actionId) throw new Error("actionId is required.");
+      const input = args["input"];
+      if (input !== void 0 && (!input || typeof input !== "object" || Array.isArray(input))) {
+        throw new Error("input must be an object.");
       }
-      return { application: match };
+      const resource = optionalResourceContext(args);
+      return topolo.client.callAction(
+        actionId,
+        input ?? {},
+        {
+          confirm: args["confirm"] === true,
+          ...resource ? { resource } : {}
+        }
+      );
     }
   },
   {
@@ -183,7 +276,7 @@ var TOOLS = [
       properties: {
         application: {
           type: "string",
-          description: "Optional application ID from topolo_list_applications."
+          description: "Optional application ID from topolo_search_applications."
         }
       },
       additionalProperties: false
@@ -223,7 +316,7 @@ var TOOLS = [
       properties: {
         application: {
           type: "string",
-          description: "Optional application ID from topolo_list_applications."
+          description: "Optional application ID from topolo_search_applications."
         },
         failOn: {
           type: "string",
@@ -257,7 +350,7 @@ var TOOLS = [
   {
     name: "topolo_api_call",
     title: "Call any Topolo platform service",
-    description: "Low-level passthrough to any Topolo service. Use when no domain-specific tool exists for the operation you need. The request is signed with the current credential and scoped to the caller's organization \u2014 the target service will return 403 if your scopes do not permit the operation, even though this tool is advertised. Mutating calls (non-GET methods) require confirm:true. Call topolo_list_services first to discover callable app IDs; the SDK can also resolve live Auth-catalog app ids/slugs for newly registered API surfaces.",
+    description: "Low-level passthrough to any Topolo service. Use when no domain-specific tool exists for the operation you need. The request is signed with the current credential and scoped to the caller's organization \u2014 the target service will return 403 if your scopes do not permit the operation, even though this tool is advertised. Mutating calls (non-GET methods) require confirm:true. Call topolo_search_applications first to discover callable app IDs; the SDK can also resolve live Auth-catalog app ids/slugs for newly registered API surfaces.",
     requiredScopes: [],
     destructive: true,
     inputSchema: {
@@ -288,7 +381,7 @@ var TOOLS = [
         },
         resourceType: {
           type: "string",
-          description: "Optional workspace resource alias from topolo_list_services apiKeyResources. Aliases are app-defined, e.g. brand, mailbox, venue, merchant, or any other cataloged alias."
+          description: "Optional workspace resource alias from topolo_search_applications apiKeyResources. Aliases are app-defined, e.g. brand, mailbox, venue, merchant, or any other cataloged alias."
         },
         resourceId: {
           type: "string",
@@ -306,7 +399,7 @@ var TOOLS = [
       const service = args["service"];
       const path = args["path"];
       if (typeof service !== "string" || !service.trim()) {
-        throw new Error("service is required. Call topolo_list_services first to discover callable services.");
+        throw new Error("service is required. Call topolo_search_applications first to discover callable services.");
       }
       if (typeof path !== "string" || !path) {
         throw new Error("path is required");
@@ -320,12 +413,7 @@ var TOOLS = [
       const normalisedQuery = query && typeof query === "object" && !Array.isArray(query) ? Object.fromEntries(
         Object.entries(query).map(([k, v]) => [k, String(v)])
       ) : void 0;
-      const resourceType = typeof args["resourceType"] === "string" ? args["resourceType"].trim() : "";
-      const resourceId = typeof args["resourceId"] === "string" ? args["resourceId"].trim() : "";
-      if (resourceType && !resourceId || !resourceType && resourceId) {
-        throw new Error("resourceType and resourceId must be provided together.");
-      }
-      const resource = resourceType && resourceId ? { resourceType, resourceId } : void 0;
+      const resource = optionalResourceContext(args);
       return topolo.client.request({
         service: service.trim(),
         method,
@@ -342,58 +430,8 @@ function filterToolsByScopes(tools, scopes) {
   return tools.filter((t) => hasAnyScope(scopes, t.requiredScopes));
 }
 async function buildTopoloTools(topolo, scopes, tools = TOOLS) {
-  const baseTools = filterToolsByScopes(tools, scopes);
-  const actions = await topolo.client.listActions().catch(() => []);
-  const actionTools = actionsToToolDefs(actions);
-  return filterToolsByScopes([...baseTools, ...actionTools], scopes);
-}
-function effectiveAgentAccess(a) {
-  if (a.agentAccess) return a.agentAccess;
-  if (a.destructive) return "off";
-  if (a.readOnly && !a.requiresConfirmation) return "auto";
-  return "confirm";
-}
-function actionsToToolDefs(actions) {
-  return actions.map((action) => ({ action, access: effectiveAgentAccess(action) })).filter(({ access }) => access !== "off").map(({ action, access }) => ({
-    name: action.toolName || toolNameForAction(action),
-    title: action.title,
-    description: action.description,
-    requiredScopes: action.requiredPermission ? [action.requiredPermission] : [],
-    destructive: access === "confirm",
-    inputSchema: actionInputSchema(action, access),
-    handler: async (topolo, args) => {
-      const confirm = Boolean(args["confirm"]);
-      const input = { ...args };
-      delete input["confirm"];
-      return topolo.client.callAction(action.actionId, input, { confirm });
-    }
-  }));
-}
-function toolNameForAction(action) {
-  const service = (action.appSlug || action.appId || "service").replace(/^topolo-/, "").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-  const name = action.name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-  return ["topolo", service, name].filter(Boolean).join("_").slice(0, 96);
-}
-function actionInputSchema(action, access = "auto") {
-  const schema = {
-    type: "object",
-    properties: {},
-    additionalProperties: false,
-    ...action.inputSchema
-  };
-  const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties) ? { ...schema.properties } : {};
-  if (access === "confirm") {
-    properties.confirm = {
-      type: "boolean",
-      description: "Required for mutating actions. Explicit human-in-the-loop acknowledgement."
-    };
-  }
-  return {
-    ...schema,
-    type: "object",
-    properties,
-    additionalProperties: schema.additionalProperties ?? false
-  };
+  void topolo;
+  return filterToolsByScopes(tools, scopes);
 }
 function evaluateApplicationAuditGate(report, threshold) {
   const counts = {