@topolo/mcp 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# TopoloMCP
+
+Model Context Protocol server for the Topolo platform. Lets MCP-capable agents
+(Claude Desktop, Claude Code, Codex, Cursor, etc.) call Topolo APIs as native
+tools rather than shelling out.
+
+## Why both a CLI and an MCP server?
+
+- The **CLI** is for humans, shell scripts, and agents without MCP support.
+- The **MCP server** is for agents that speak the protocol natively — it gives
+  them typed tool schemas, scope-filtered tool advertisement, and structured
+  error responses. Both wrap the same `@topolo/sdk`.
+
+## Install
+
+```bash
+npm install -g @topolo/mcp
+```
+
+## Register with an MCP client
+
+Example (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"
+      }
+    }
+  }
+}
+```
+
+## Supported env vars
+
+| Var                          | Purpose                                               |
+| ---------------------------- | ----------------------------------------------------- |
+| `TOPOLO_API_KEY`             | Platform API key (preferred)                          |
+| `TOPOLO_ACCESS_TOKEN`        | Short-lived JWT (dev/testing)                         |
+| `TOPOLO_AGENT_NAME`          | Human-readable agent label for audit logs             |
+| `TOPOLO_SERVICE_URL_<ID>`    | Override a service base URL (`_AUTH`, `_CRM`, ...)    |
+
+On startup the server:
+
+1. Refuses to start if no credential is set.
+2. Introspects the credential against TopoloAuth to load granted scopes.
+3. Filters the advertised tool list to only those the credential can use.
+
+## Tools (Phase 1)
+
+| Tool                         | Required scopes       | Destructive |
+| ---------------------------- | --------------------- | ----------- |
+| `topolo_whoami`              | (none)                | no          |
+| `topolo_crm_list_contacts`   | `crm.contacts:read`   | no          |
+| `topolo_crm_get_contact`     | `crm.contacts:read`   | no          |
+
+Phase 1 is intentionally read-only. Write tools will be added per-domain in
+later phases alongside typed SDK modules, each annotated with
+`destructiveHint: true` so host clients can surface confirmation UI.
+
+## 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.
+- **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
+  the call explicitly passes `confirm: true`. Mutating tools (when introduced)
+  will require the host client to approve before invocation.
+
+## 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.
+
+## Phase 2 (planned)
+
+- Accept OAuth 2.1 access tokens minted via authorization-code + device grants
+  in TopoloAuth.
+- Dynamic tool registration as more `@topolo/sdk` modules ship.
+- HTTP transport in addition to stdio, for hosted (non-subprocess) deployments.

package/dist/index.js

@@ -0,0 +1,519 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// ../packages/topolo-sdk/dist/index.js
+function applyAuthHeaders(headers, credential) {
+  if (credential.kind === "api_key") {
+    headers.set("X-Api-Key", credential.apiKey);
+    return;
+  }
+  headers.set("Authorization", `Bearer ${credential.accessToken}`);
+}
+function applyAuditHeaders(headers, agent, requestId) {
+  headers.set("X-Topolo-Client", `${agent.clientName}/${agent.clientVersion}`);
+  if (agent.agentName) headers.set("X-Topolo-Agent", agent.agentName);
+  headers.set("X-Topolo-Request-Id", requestId);
+}
+function generateRequestId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+var TopoloSdkError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TopoloSdkError";
+    this.code = code;
+  }
+};
+var TopoloAuthError = class extends TopoloSdkError {
+  constructor(message, code = "auth_error") {
+    super(code, message);
+    this.name = "TopoloAuthError";
+  }
+};
+var TopoloPermissionError = class extends TopoloSdkError {
+  required;
+  constructor(message, required) {
+    super("permission_denied", message);
+    this.name = "TopoloPermissionError";
+    this.required = required;
+  }
+};
+var TopoloHttpError = class extends TopoloSdkError {
+  status;
+  body;
+  service;
+  path;
+  constructor(service, path, status, body, message) {
+    super("http_error", message ?? `HTTP ${status} from ${service}${path}`);
+    this.name = "TopoloHttpError";
+    this.status = status;
+    this.body = body;
+    this.service = service;
+    this.path = path;
+  }
+};
+var DEFAULT_SERVICE_URLS = {
+  auth: "https://auth.topolo.app",
+  crm: "https://topolo-crm-worker.topolo.workers.dev"
+};
+var PLATFORM_SERVICE_IDS = {
+  crm: "srv_iCwM4jGXcwlj"
+};
+function resolveServiceUrl(service, overrides) {
+  const override = overrides?.[service];
+  if (override) return override;
+  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+  if (envValue) return envValue;
+  return DEFAULT_SERVICE_URLS[service];
+}
+var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var TopoloClient = class {
+  credential;
+  agent;
+  serviceUrls;
+  requireConfirmForWrites;
+  timeoutMs;
+  fetchImpl;
+  constructor(options) {
+    if (!options.credential) throw new TopoloAuthError("credential is required");
+    if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
+    this.credential = options.credential;
+    this.agent = options.agent;
+    this.serviceUrls = options.serviceUrls;
+    this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
+   * for anything a caller would reach for; this stays exported for escape-hatch
+   * use and for the generic `topolo api` / MCP passthrough tool.
+   */
+  async request(opts) {
+    const method = opts.method ?? "GET";
+    if (this.requireConfirmForWrites && WRITE_METHODS.has(method) && !opts.confirm) {
+      throw new TopoloAuthError(
+        `Mutating ${method} requests require { confirm: true }. This guardrail prevents agents from issuing writes without an explicit human-in-the-loop acknowledgement.`
+      );
+    }
+    const baseUrl = resolveServiceUrl(opts.service, this.serviceUrls);
+    const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== void 0) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = new Headers();
+    headers.set("Accept", "application/json");
+    if (opts.body !== void 0) headers.set("Content-Type", "application/json");
+    const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
+    if (platformServiceId) headers.set("X-Service-ID", platformServiceId);
+    applyAuthHeaders(headers, this.credential);
+    applyAuditHeaders(headers, this.agent, generateRequestId());
+    if (opts.headers) {
+      for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
+    let res;
+    try {
+      res = await this.fetchImpl(url.toString(), {
+        method,
+        headers,
+        body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
+        signal
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    const contentType = res.headers.get("Content-Type") ?? "";
+    const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
+    if (!res.ok) {
+      if (res.status === 401) throw new TopoloAuthError(describeError(parsed, "Unauthorized"));
+      if (res.status === 403) {
+        throw new TopoloPermissionError(
+          describeError(parsed, "Permission denied"),
+          extractRequired(parsed)
+        );
+      }
+      throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
+    }
+    return parsed;
+  }
+  /**
+   * Introspect the current credential. Returns the caller's resolved identity,
+   * organization, and permission set. Used by CLI `whoami` and by MCP to gate
+   * advertised tools by scope.
+   *
+   * Both JWT access tokens and platform API keys are resolved via the unified
+   * `GET /api/auth/me` endpoint on TopoloAuth, which does not require service
+   * credentials. The caller's possession of the credential secret is proof.
+   */
+  async introspect() {
+    const res = await this.request({
+      service: "auth",
+      method: "GET",
+      path: "/api/auth/me"
+    });
+    const payload = res.data ?? res;
+    const user = payload.user;
+    const organization = payload.organization;
+    const kind = payload.credentialType === "api_key" ? "api_key" : "access_token";
+    return {
+      kind,
+      user: {
+        id: user.id,
+        email: user.email,
+        name: user.name ?? null,
+        role: user.role ?? (kind === "api_key" ? "service" : "member"),
+        permissions: payload.permissions ?? user.permissions ?? []
+      },
+      organization: organization ? {
+        id: organization.id,
+        slug: organization.slug,
+        name: organization.name ?? organization.slug
+      } : user.orgId && user.orgSlug ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug } : null
+    };
+  }
+};
+function describeError(body, fallback) {
+  if (body && typeof body === "object") {
+    const maybe = body;
+    const resolved = pickString(maybe.message) ?? pickString(maybe.error);
+    if (resolved) return resolved;
+  }
+  return fallback;
+}
+function pickString(value) {
+  if (typeof value === "string" && value.trim().length > 0) return value;
+  if (value && typeof value === "object") {
+    const nested = value;
+    if (typeof nested.message === "string" && nested.message.trim().length > 0) return nested.message;
+    if (typeof nested.description === "string" && nested.description.trim().length > 0)
+      return nested.description;
+  }
+  return void 0;
+}
+function extractRequired(body) {
+  if (body && typeof body === "object") {
+    const maybe = body;
+    if (Array.isArray(maybe.required)) return maybe.required.map(String);
+  }
+  return [];
+}
+function mergeSignals(a, b) {
+  if (a.aborted) return a;
+  if (b.aborted) return b;
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  a.addEventListener("abort", onAbort, { once: true });
+  b.addEventListener("abort", onAbort, { once: true });
+  return controller.signal;
+}
+var CrmModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async listContacts(options = {}) {
+    const res = await this.client.request({
+      service: "crm",
+      path: "/api/contacts",
+      query: {
+        q: options.q,
+        page: options.page,
+        pageSize: options.pageSize
+      }
+    });
+    const rows = Array.isArray(res?.contacts) ? res.contacts : Array.isArray(res?.data) ? res.data : [];
+    return {
+      contacts: rows.map(toSummary),
+      total: res?.total ?? res?.pagination?.total ?? rows.length,
+      page: res?.page ?? res?.pagination?.page ?? options.page ?? 1,
+      pageSize: res?.pageSize ?? res?.pagination?.pageSize ?? options.pageSize ?? rows.length
+    };
+  }
+  async getContact(contactId) {
+    if (!contactId) throw new Error("contactId is required");
+    const res = await this.client.request({
+      service: "crm",
+      path: `/api/contacts/${encodeURIComponent(contactId)}`
+    });
+    const row = res.data ?? res;
+    return row ? toSummary(row) : null;
+  }
+};
+function toSummary(row) {
+  return {
+    id: row.id,
+    firstName: row.first ?? null,
+    lastName: row.last ?? null,
+    email: row.email ?? null,
+    phone: row.phone ?? null,
+    company: row.company ?? null,
+    leadStatus: row.lead_status ?? null,
+    lifecycleStage: row.lifecycle_stage ?? null,
+    updatedAt: row.updated_at ?? null
+  };
+}
+var IdentityModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Returns the resolved user, organization, and permission set for the
+   *  current credential. Equivalent to `TopoloClient.introspect()` — exposed
+   *  on this module for symmetry with the other domain modules. */
+  whoami() {
+    return this.client.introspect();
+  }
+};
+function createTopolo(options) {
+  const client = new TopoloClient(options);
+  return {
+    client,
+    identity: new IdentityModule(client),
+    crm: new CrmModule(client)
+  };
+}
+
+// src/auth.ts
+function resolveCredentialFromEnv() {
+  const apiKey = process.env.TOPOLO_API_KEY;
+  if (apiKey) return { kind: "api_key", apiKey };
+  const accessToken = process.env.TOPOLO_ACCESS_TOKEN;
+  if (accessToken) return { kind: "access_token", accessToken };
+  return null;
+}
+function resolveServiceUrlsFromEnv() {
+  const out = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (k.startsWith("TOPOLO_SERVICE_URL_") && v) {
+      out[k.slice("TOPOLO_SERVICE_URL_".length).toLowerCase()] = v;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+
+// src/gating.ts
+function hasScope(set, required) {
+  if (set.role === "super_admin") 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,
+    resource && actionPart ? `${resource}:*` : 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 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_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_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));
+}
+
+// src/version.ts
+var MCP_VERSION = "0.1.0";
+
+// src/index.ts
+async function main() {
+  const credential = resolveCredentialFromEnv();
+  if (!credential) {
+    process.stderr.write(
+      "TopoloMCP: TOPOLO_API_KEY or TOPOLO_ACCESS_TOKEN must be set in the environment.\n"
+    );
+    process.exit(1);
+  }
+  const agentName = process.env.TOPOLO_AGENT_NAME;
+  const serviceUrls = resolveServiceUrlsFromEnv();
+  const topolo = createTopolo({
+    credential,
+    agent: {
+      clientName: "topolo-mcp",
+      clientVersion: MCP_VERSION,
+      ...agentName ? { agentName } : {}
+    },
+    serviceUrls,
+    requireConfirmForWrites: true
+  });
+  const scopes = await loadScopes(topolo);
+  const availableTools = filterToolsByScopes(TOOLS, scopes);
+  const server = new Server(
+    {
+      name: "topolo",
+      version: MCP_VERSION
+    },
+    {
+      capabilities: { tools: {} }
+    }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: availableTools.map((t) => ({
+      name: t.name,
+      title: t.title,
+      description: t.description,
+      inputSchema: t.inputSchema,
+      annotations: {
+        destructiveHint: t.destructive,
+        readOnlyHint: !t.destructive
+      }
+    }))
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const params = request.params;
+    const tool = availableTools.find((t) => t.name === params.name);
+    if (!tool) {
+      return toolError(
+        `Tool "${params.name}" is not available for this credential. Either the tool does not exist or the current scopes do not permit it.`
+      );
+    }
+    if (!hasAnyScope(scopes, tool.requiredScopes)) {
+      return toolError(
+        `Tool "${tool.name}" requires one of: ${tool.requiredScopes.join(", ")}. Current credential does not grant any of these.`
+      );
+    }
+    try {
+      const result = await tool.handler(topolo, params.arguments ?? {});
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(result, null, 2) }
+        ]
+      };
+    } catch (err) {
+      if (err instanceof TopoloPermissionError) {
+        return toolError(`Permission denied. Required: ${err.required.join(", ") || "(unknown)"}`);
+      }
+      if (err instanceof TopoloAuthError) {
+        return toolError(`Auth error: ${err.message}`);
+      }
+      return toolError(err instanceof Error ? err.message : String(err));
+    }
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(
+    `TopoloMCP v${MCP_VERSION} connected. Tools available: ${availableTools.map((t) => t.name).join(", ") || "(none)"}
+`
+  );
+}
+async function loadScopes(topolo) {
+  try {
+    const info = await topolo.identity.whoami();
+    return {
+      permissions: info.user.permissions,
+      role: info.user.role
+    };
+  } catch (err) {
+    if (err instanceof TopoloAuthError) {
+      process.stderr.write(`TopoloMCP: credential rejected \u2014 ${err.message}
+`);
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+function toolError(message) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }]
+  };
+}
+main().catch((err) => {
+  process.stderr.write(`TopoloMCP fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@topolo/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for the Topolo platform. Exposes scope-gated tools that third-party agents (Claude, Codex, etc.) can call natively.",
+  "type": "module",
+  "bin": {
+    "topolo-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@topolo/sdk": "file:../packages/topolo-sdk",
+    "@types/node": "^20.12.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}