@topolo/mcp 0.10.3 → 0.11.1

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,12 +116,18 @@ 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_get_resource_types`  | credential-scoped     | no               |
+| `topolo_list_resources`      | credential-scoped     | no               |
 | `topolo_search_actions`      | (credential-scoped)   | no               |
+| `topolo_discover_capabilities` | credential-scoped   | no               |
 | `topolo_get_action`          | (credential-scoped)   | no               |
+| `topolo_get_action_examples` | credential-scoped     | no               |
+| `topolo_validate_action`     | credential-scoped     | no               |
+| `topolo_plan_action`         | credential-scoped     | no               |
+| `topolo_prepare_action`      | credential-scoped     | no               |
 | `topolo_read_action`         | catalog or target policy | no            |
 | `topolo_call_action`         | catalog or target policy | yes           |
+| `topolo_upload_action`       | catalog or target policy | yes           |
 | `topolo_list_workspaces`     | target app runtime policy | no            |
 | `topolo_create_workspace`    | target app runtime policy | yes           |
 | `topolo_rename_workspace`    | target app runtime policy | yes           |
@@ -217,9 +192,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
@@ -242,54 +216,4 @@ sent.
   disagrees with startup introspection (rare, but possible across scope
   changes). Re-spawn the server to refresh the cached scope set.
 
-## Development
-
-```bash
-cd TopoloMCP
-npm install
-npm run build
-TOPOLO_API_KEY=topo_live_... node dist/index.js
-```
-
-The server speaks MCP over stdio; when running standalone it just blocks
-waiting for JSON-RPC on stdin. To drive it manually, use the MCP Inspector:
-
-```bash
-npx @modelcontextprotocol/inspector node dist/index.js
-```
-
-## Release Flow
-
-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)
-
-- Hosted action catalog administration in Developers UI.
-- HTTP transport in addition to stdio, for hosted (non-subprocess) deployments.
 - Optional `--provenance` on npm publish once the repo is public.

package/dist/dispatch.js

@@ -9,28 +9,16 @@ import {
 
 // 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);
@@ -623,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",
@@ -803,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) {