@topolo/mcp 0.2.4 → 0.3.0

package/dist/dispatch.d.ts

@@ -0,0 +1,89 @@
+import { Topolo } from '@topolo/sdk';
+
+/**
+ * Scope-based tool gating.
+ *
+ * Each MCP tool declares the Topolo platform permissions it requires (same
+ * service.resource.action format TopoloAuth uses). On startup the server
+ * introspects the credential to get the actual granted permission set, and
+ * filters the advertised tool list down to what this caller can actually use.
+ *
+ * This is defence-in-depth — the backend still enforces permissions on every
+ * call — but it also means the agent never sees tools that would 403 on use,
+ * which dramatically reduces prompt noise and wasted attempts.
+ */
+interface ScopeSet {
+    permissions: string[];
+    role: string;
+    orgSlug?: string;
+}
+declare function hasScope(set: ScopeSet, required: string): boolean;
+declare function hasAnyScope(set: ScopeSet, required: string[]): boolean;
+
+/**
+ * Tool registry. Each entry declares its MCP schema plus the platform scopes
+ * required to use it. The server filters the advertised list by the caller's
+ * granted scopes on startup.
+ *
+ * Tools NEVER take `orgId` as an input — the platform derives it from the
+ * credential. Write tools MUST set `destructive: true`; host clients are
+ * expected to surface confirmation UI before invoking them.
+ *
+ * Phase 1 ships read-only tools. Write tools will be added per-domain in
+ * subsequent phases alongside the corresponding SDK modules.
+ */
+interface ToolDef {
+    name: string;
+    title: string;
+    description: string;
+    requiredScopes: string[];
+    destructive: boolean;
+    inputSchema: Record<string, unknown>;
+    handler: (topolo: Topolo, args: Record<string, unknown>) => Promise<unknown>;
+}
+declare const TOOLS: ToolDef[];
+declare function filterToolsByScopes(tools: ToolDef[], scopes: ScopeSet): ToolDef[];
+
+/**
+ * Transport-agnostic Topolo tool dispatch.
+ *
+ * The MCP stdio server (server.ts) and any non-MCP host (e.g. the TopoloChat
+ * Cloudflare Worker driving a persona agent loop) must NOT reimplement the
+ * tool registry — they share `TOOLS` and call `dispatchTopoloTool` so a tool
+ * added here lights up everywhere automatically.
+ *
+ * This module is deliberately free of MCP protocol imports so it bundles
+ * cleanly into a Worker. server.ts wraps these primitives with the MCP SDK.
+ */
+
+interface ToolDispatchInput {
+    toolName: string;
+    args?: Record<string, unknown>;
+    topolo: Topolo;
+    scopes: ScopeSet;
+    tools?: ToolDef[];
+}
+type ToolDispatchFailureReason = 'not_available' | 'missing_scope' | 'auth' | 'permission' | 'handler';
+type ToolDispatchResult = {
+    ok: true;
+    data: unknown;
+    durationMs: number;
+} | {
+    ok: false;
+    error: string;
+    reason: ToolDispatchFailureReason;
+    durationMs: number;
+    requiredScopes?: string[];
+};
+interface ToolAdvertisement {
+    name: string;
+    title: string;
+    description: string;
+    requiredScopes: string[];
+    destructive: boolean;
+    inputSchema: Record<string, unknown>;
+}
+declare function listAvailableTopoloTools(scopes: ScopeSet, tools?: ToolDef[]): ToolAdvertisement[];
+declare function dispatchTopoloTool(input: ToolDispatchInput): Promise<ToolDispatchResult>;
+
+export { type ScopeSet, TOOLS, type ToolAdvertisement, type ToolDef, type ToolDispatchFailureReason, type ToolDispatchInput, type ToolDispatchResult, dispatchTopoloTool, filterToolsByScopes, hasAnyScope, hasScope, listAvailableTopoloTools };

package/dist/dispatch.js

@@ -0,0 +1,444 @@
+// src/dispatch.ts
+import { TopoloAuthError, TopoloPermissionError } from "@topolo/sdk";
+
+// src/tools.ts
+import {
+  APPLICATION_REQUIREMENTS,
+  APPLICATION_REQUIREMENTS_VERSION,
+  APPLICATIONS,
+  DEFAULT_SERVICE_URLS,
+  auditAllApplicationRequirements,
+  applicationRequirementScopes,
+  requirementsForApplication,
+  resolveServiceUrl
+} 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);
+  const [serviceId, resource] = splitService(servicePart);
+  const candidates = new Set([
+    required,
+    "*",
+    serviceId ? `${serviceId}.*` : null,
+    serviceId && resource && actionPart ? `${serviceId}.${resource}:*` : null,
+    serviceId && resource && actionPart ? `${serviceId}.${resource}.${actionPart}` : null,
+    resource && actionPart ? `${resource}:*` : null,
+    resource && actionPart ? `${resource}.${actionPart}` : null,
+    resource && actionPart ? `${resource}:${actionPart}` : null
+  ].filter((v) => v !== null));
+  return set.permissions.some((granted) => candidates.has(granted));
+}
+function hasAnyScope(set, required) {
+  if (required.length === 0) return true;
+  return required.some((r) => hasScope(set, r));
+}
+function splitPermission(permission) {
+  const idx = permission.indexOf(":");
+  if (idx === -1) return [permission, null];
+  return [permission.slice(0, idx), permission.slice(idx + 1)];
+}
+function splitService(servicePart) {
+  const idx = servicePart.indexOf(".");
+  if (idx === -1) return [null, servicePart];
+  return [servicePart.slice(0, idx), servicePart.slice(idx + 1)];
+}
+
+// src/tools.ts
+var APPLICATION_IDS = Object.keys(APPLICATIONS).sort();
+var SERVICE_IDS = Object.keys(DEFAULT_SERVICE_URLS).sort();
+var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
+var TOOLS = [
+  {
+    name: "topolo_whoami",
+    title: "Describe the current Topolo credential",
+    description: "Returns the user, organization, and granted permissions attached to the current Topolo credential. Useful for confirming which organization the agent is currently acting on behalf of before taking further action. Never targets a different organization.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async (topolo) => topolo.identity.whoami()
+  },
+  {
+    name: "topolo_list_services",
+    title: "List every Topolo service the agent can reach",
+    description: "Returns the service registry the SDK knows about: one entry per platform service with its stable service ID and current base URL. Use this to discover what `topolo_api_call` can address \u2014 the service IDs returned here are the exact values accepted by that tool. Pure metadata: no credential introspection, no permission check, no external call.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async () => {
+      const services = Object.keys(DEFAULT_SERVICE_URLS).sort().map((id) => ({
+        id,
+        defaultUrl: DEFAULT_SERVICE_URLS[id],
+        effectiveUrl: resolveServiceUrl(id)
+      }));
+      return { services };
+    }
+  },
+  {
+    name: "topolo_list_applications",
+    title: "List every Topolo platform application",
+    description: "Returns the generated Topolo application catalog, including pages-only apps, tooling apps, and API-backed apps. Use this before choosing a service-specific or generic API operation. Pure metadata: no credential introspection, no permission check, no external call.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    },
+    handler: async () => ({
+      applications: APPLICATION_IDS.map((id) => APPLICATIONS[id])
+    })
+  },
+  {
+    name: "topolo_get_application",
+    title: "Describe one Topolo platform application",
+    description: "Returns one application catalog entry with its package name, production URL, deploy targets, and SDK service IDs when the app has callable APIs. Pure metadata: no credential introspection, no permission check, no external call.",
+    requiredScopes: [],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        application: {
+          type: "string",
+          enum: APPLICATION_IDS,
+          description: "Application ID from topolo_list_applications."
+        }
+      },
+      required: ["application"],
+      additionalProperties: false
+    },
+    handler: async (_topolo, args) => {
+      const application = args["application"];
+      if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
+        throw new Error(
+          `Unknown application "${String(application)}". Known: ${APPLICATION_IDS.join(", ")}`
+        );
+      }
+      return { application: APPLICATIONS[application] };
+    }
+  },
+  {
+    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",
+          enum: APPLICATION_IDS,
+          description: "Optional application ID from topolo_list_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
+        };
+      }
+      if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
+        throw new Error(
+          `Unknown application "${String(application)}". Known: ${APPLICATION_IDS.join(", ")}`
+        );
+      }
+      const app = APPLICATIONS[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",
+          enum: APPLICATION_IDS,
+          description: "Optional application ID from topolo_list_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."
+        }
+      },
+      additionalProperties: false
+    },
+    handler: async (_topolo, args) => {
+      const application = args["application"];
+      const failOn = args["failOn"];
+      if (failOn !== void 0 && typeof failOn !== "string") {
+        throw new Error("failOn must be one of: missing, needs_review, partial");
+      }
+      const gate = failOn ? normalizeFailOn(failOn) : null;
+      let report;
+      if (application === void 0) {
+        report = auditAllApplicationRequirements();
+        return gate ? { ...report, conformanceGate: evaluateApplicationAuditGate(report, gate) } : report;
+      }
+      if (typeof application !== "string" || !APPLICATION_IDS.includes(application)) {
+        throw new Error(
+          `Unknown application "${String(application)}". Known: ${APPLICATION_IDS.join(", ")}`
+        );
+      }
+      report = auditAllApplicationRequirements([application]);
+      return gate ? { ...report, conformanceGate: evaluateApplicationAuditGate(report, gate) } : report;
+    }
+  },
+  {
+    name: "topolo_crm_list_contacts",
+    title: "List CRM contacts",
+    description: "List contacts in the authenticated organization from TopoloCRM. Supports full-text search and pagination. All results are scoped to the caller's organization \u2014 there is no way to query contacts from another org.",
+    requiredScopes: ["crm.contacts:read"],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Full-text search string" },
+        page: { type: "integer", minimum: 1, default: 1 },
+        pageSize: { type: "integer", minimum: 1, maximum: 200, default: 25 }
+      },
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      return topolo.crm.listContacts({
+        q: typeof args["query"] === "string" ? args["query"] : void 0,
+        page: typeof args["page"] === "number" ? args["page"] : void 0,
+        pageSize: typeof args["pageSize"] === "number" ? args["pageSize"] : void 0
+      });
+    }
+  },
+  {
+    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. Known services: ${SERVICE_IDS.join(", ")}.`,
+    requiredScopes: [],
+    destructive: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        service: {
+          type: "string",
+          enum: SERVICE_IDS,
+          description: "Target service ID from the platform registry."
+        },
+        method: {
+          type: "string",
+          enum: HTTP_METHODS,
+          default: "GET",
+          description: "HTTP method. Defaults to GET."
+        },
+        path: {
+          type: "string",
+          minLength: 1,
+          description: 'Request path including any leading slash, e.g. "/api/contacts".'
+        },
+        body: {
+          description: "JSON request body. Ignored for GET."
+        },
+        query: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Query string parameters as string values."
+        },
+        confirm: {
+          type: "boolean",
+          description: "Required for non-GET methods. Explicit human-in-the-loop acknowledgement for writes."
+        }
+      },
+      required: ["service", "path"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const service = args["service"];
+      const path = args["path"];
+      if (typeof service !== "string" || !SERVICE_IDS.includes(service)) {
+        throw new Error(`Unknown service "${String(service)}". Known: ${SERVICE_IDS.join(", ")}`);
+      }
+      if (typeof path !== "string" || !path) {
+        throw new Error("path is required");
+      }
+      const methodRaw = args["method"] ?? "GET";
+      if (typeof methodRaw !== "string" || !HTTP_METHODS.includes(methodRaw)) {
+        throw new Error(`Unknown HTTP method "${String(methodRaw)}"`);
+      }
+      const method = methodRaw;
+      const query = args["query"];
+      const normalisedQuery = query && typeof query === "object" && !Array.isArray(query) ? Object.fromEntries(
+        Object.entries(query).map(([k, v]) => [k, String(v)])
+      ) : void 0;
+      return topolo.client.request({
+        service,
+        method,
+        path,
+        body: args["body"],
+        ...normalisedQuery ? { query: normalisedQuery } : {},
+        confirm: Boolean(args["confirm"])
+      });
+    }
+  },
+  {
+    name: "topolo_crm_get_contact",
+    title: "Fetch a single CRM contact",
+    description: "Fetch a single contact by id from TopoloCRM, scoped to the caller's organization.",
+    requiredScopes: ["crm.contacts:read"],
+    destructive: false,
+    inputSchema: {
+      type: "object",
+      properties: {
+        contactId: { type: "string", minLength: 1 }
+      },
+      required: ["contactId"],
+      additionalProperties: false
+    },
+    handler: async (topolo, args) => {
+      const contactId = args["contactId"];
+      if (typeof contactId !== "string" || !contactId) {
+        throw new Error("contactId is required");
+      }
+      const contact = await topolo.crm.getContact(contactId);
+      if (!contact) throw new Error(`Contact not found: ${contactId}`);
+      return contact;
+    }
+  }
+];
+function filterToolsByScopes(tools, scopes) {
+  return tools.filter((t) => hasAnyScope(scopes, t.requiredScopes));
+}
+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 Error("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"];
+}
+
+// src/dispatch.ts
+function listAvailableTopoloTools(scopes, tools = TOOLS) {
+  return filterToolsByScopes(tools, scopes).map((t) => ({
+    name: t.name,
+    title: t.title,
+    description: t.description,
+    requiredScopes: t.requiredScopes,
+    destructive: t.destructive,
+    inputSchema: t.inputSchema
+  }));
+}
+async function dispatchTopoloTool(input) {
+  const started = Date.now();
+  const tools = input.tools ?? TOOLS;
+  const available = filterToolsByScopes(tools, input.scopes);
+  const tool = available.find((t) => t.name === input.toolName);
+  if (!tool) {
+    return {
+      ok: false,
+      reason: "not_available",
+      error: `Tool "${input.toolName}" is not available for this credential.`,
+      durationMs: Date.now() - started
+    };
+  }
+  if (!hasAnyScope(input.scopes, tool.requiredScopes)) {
+    return {
+      ok: false,
+      reason: "missing_scope",
+      error: `Tool "${tool.name}" requires one of: ${tool.requiredScopes.join(", ") || "(none)"}.`,
+      requiredScopes: tool.requiredScopes,
+      durationMs: Date.now() - started
+    };
+  }
+  try {
+    const data = await tool.handler(input.topolo, input.args ?? {});
+    return { ok: true, data, durationMs: Date.now() - started };
+  } catch (err) {
+    if (err instanceof TopoloPermissionError) {
+      return {
+        ok: false,
+        reason: "permission",
+        error: `Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`,
+        requiredScopes: err.required,
+        durationMs: Date.now() - started
+      };
+    }
+    if (err instanceof TopoloAuthError) {
+      return {
+        ok: false,
+        reason: "auth",
+        error: `Auth error: ${err.message}`,
+        durationMs: Date.now() - started
+      };
+    }
+    return {
+      ok: false,
+      reason: "handler",
+      error: err instanceof Error ? err.message : String(err),
+      durationMs: Date.now() - started
+    };
+  }
+}
+export {
+  TOOLS,
+  dispatchTopoloTool,
+  filterToolsByScopes,
+  hasAnyScope,
+  hasScope,
+  listAvailableTopoloTools
+};