@topolo/mcp 0.7.2 → 0.9.0

package/README.md

@@ -79,15 +79,43 @@ ready-made agent guide that covers both the CLI and this MCP.
 | ---------------------------- | ----------------------------------------------------- |
 | `TOPOLO_API_KEY`             | Platform API key (preferred)                          |
 | `TOPOLO_ACCESS_TOKEN`        | Short-lived JWT (dev/testing)                         |
+| `TOPOLO_ENV`                 | Credential environment (production by default)       |
+| `TOPOLO_CONTEXT`             | Pin one stored personal/org context without activating it |
 | `TOPOLO_AGENT_NAME`          | Human-readable agent label for audit logs             |
 | `TOPOLO_SERVICE_URL_<ID>`    | Override a service base URL (e.g. `_AUTH`, `_MAIL`)   |
 
 Exactly one credential var must be set. If both are present, `TOPOLO_API_KEY`
 wins.
 
+For concurrent organization or environment operation, run one named MCP server
+per stored context. `TOPOLO_CONTEXT` accepts an exact key from `topolo context
+list --json` (for example `personal` or `org:org_topolo`) or a unique stored
+organization id, slug, or name. The server reads and refreshes that credential
+without changing the CLI's active context, so separate agent processes cannot
+race one shared context pointer:
+
+```json
+{
+  "mcpServers": {
+    "topolo-topolo": {
+      "command": "topolo-mcp",
+      "env": { "TOPOLO_ENV": "production", "TOPOLO_CONTEXT": "org:org_topolo" }
+    },
+    "topolo-personal": {
+      "command": "topolo-mcp",
+      "env": { "TOPOLO_ENV": "production", "TOPOLO_CONTEXT": "personal" }
+    }
+  }
+}
+```
+
+Do not combine `TOPOLO_CONTEXT` with an injected API key or access token: those
+credentials already carry their own immutable context.
+
 ## Startup sequence
 
-1. Resolve the credential from env. **Refuse to start** if none is set.
+1. Resolve an injected credential, a pinned stored context, or the environment's
+   active stored credential. **Refuse to start** if none is available.
 2. Call `GET /api/me` to load the user's granted scopes + role.
 3. Connect the stdio transport and begin serving MCP requests.
 4. Advertise a fixed, bounded discovery/invocation surface. Agents search one

package/dist/dispatch.js

@@ -260,6 +260,148 @@ var TOOLS = [
       );
     }
   },
+  {
+    name: "topolo_validate_action",
+    title: "Validate Topolo action input",
+    description: "Validates input locally against the exact JSON Schema published for one credential-scoped action. Does not invoke the action.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        actionId: { type: "string", minLength: 1 },
+        input: { type: "object", additionalProperties: true }
+      },
+      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 topolo.client.validateActionInput(actionId, input ?? {});
+    }
+  },
+  {
+    name: "topolo_plan_action",
+    title: "Plan one Topolo action",
+    description: "Validates one credential-scoped action and returns its exact request, confirmation state, verification steps, rollback action, and next actions without executing it.",
+    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." },
+        confirm: { type: "boolean", description: "Include confirmation in the plan without executing the action." }
+      },
+      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 resource = optionalResourceContext(args);
+      return topolo.client.planAction(
+        actionId,
+        input ?? {},
+        {
+          confirm: args["confirm"] === true,
+          ...resource ? { resource } : {}
+        }
+      );
+    }
+  },
+  {
+    name: "topolo_get_action_examples",
+    title: "Get Topolo action examples and documentation",
+    description: "Returns the public documentation URL and inline examples published for one action.",
+    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.");
+      const action = await topolo.client.getAction(actionId);
+      return {
+        actionId: action.actionId,
+        docsUrl: action.agentContract?.docsUrl ?? null,
+        examples: action.agentContract?.examples ?? []
+      };
+    }
+  },
+  {
+    name: "topolo_discover_capabilities",
+    title: "Discover one Topolo application capability contract",
+    description: "Discovers capability and schema actions published by one application. Use the actionService value returned by topolo_search_applications as service.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: { service: { type: "string", minLength: 1 } },
+      required: ["service"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const service = typeof args["service"] === "string" ? args["service"].trim() : "";
+      if (!service) throw new Error("service is required.");
+      return topolo.client.searchActions({ service, query: "capabilities", limit: 100 });
+    }
+  },
+  {
+    name: "topolo_get_resource_types",
+    title: "Get application resource-scoping types",
+    description: "Returns the canonical resource-scoping metadata published for one application, including aliases accepted by resource-scoped API keys and action calls.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: { application: { type: "string", minLength: 1 } },
+      required: ["application"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const application = typeof args["application"] === "string" ? args["application"].trim() : "";
+      if (!application) throw new Error("application is required.");
+      const entry = await topolo.client.getService(application);
+      return {
+        application: { appId: entry.appId, slug: entry.slug, name: entry.name },
+        resourceTypes: entry.apiKeyResources
+      };
+    }
+  },
+  {
+    name: "topolo_list_resources",
+    title: "List bindable Topolo resource ids",
+    description: "Returns credential-scoped resource ids for one application. OAuth credentials use the published Auth resource catalog; API keys return only their own bound resources.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: { application: { type: "string", minLength: 1 } },
+      required: ["application"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const application = typeof args["application"] === "string" ? args["application"].trim() : "";
+      if (!application) throw new Error("application is required.");
+      return topolo.client.listBindableResources(application);
+    }
+  },
   {
     name: "topolo_list_application_requirements",
     title: "List Topolo application build requirements",