@topolo/mcp 0.1.0 → 0.1.2

package/README.md

@@ -6,8 +6,8 @@ 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
+- The **CLI** (`@topolo/cli`) is for humans, shell scripts, and agents without MCP support.
+- The **MCP server** (`@topolo/mcp`) 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`.
 
@@ -17,9 +17,37 @@ tools rather than shelling out.
 npm install -g @topolo/mcp
 ```
 
+You don't have to install globally — the registration snippets below use `npx`
+so the server downloads on demand.
+
+## Get a credential
+
+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.
+
 ## Register with an MCP client
 
-Example (Claude Desktop, `claude_desktop_config.json`):
+### 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
 {
@@ -36,6 +64,13 @@ Example (Claude Desktop, `claude_desktop_config.json`):
 }
 ```
 
+### 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.
+
 ## Supported env vars
 
 | Var                          | Purpose                                               |
@@ -43,13 +78,21 @@ Example (Claude Desktop, `claude_desktop_config.json`):
 | `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`, ...)    |
+| `TOPOLO_SERVICE_URL_<ID>`    | Override a service base URL (e.g. `_AUTH`, `_CRM`)    |
 
-On startup the server:
+Exactly one credential var must be set. If both are present, `TOPOLO_API_KEY`
+wins.
 
-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.
+## Startup sequence
+
+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. Filter `TOOLS` by those scopes — agents never see a tool they cannot use.
+4. Connect the stdio transport and begin serving MCP requests.
+
+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
+clients surface that as a failed server launch.
 
 ## Tools (Phase 1)
 
@@ -76,6 +119,22 @@ later phases alongside typed SDK modules, each annotated with
   the call explicitly passes `confirm: true`. Mutating tools (when introduced)
   will require the host client to approve before invocation.
 
+## Troubleshooting
+
+- **"TOPOLO_API_KEY or TOPOLO_ACCESS_TOKEN must be set"** — no credential
+  reached the subprocess. In Claude Desktop, double-check the `env` block in
+  `claude_desktop_config.json`. In Claude Code, the server inherits your shell
+  env, so make sure the var is exported in the profile your launcher reads.
+- **"credential rejected"** — token is expired or revoked. For API keys, mint
+  a fresh one. For access tokens, re-run `topolo auth login` and copy the new
+  token.
+- **Tool missing from the list** — the credential doesn't grant the required
+  scope. Check `topolo whoami` to see the current scopes; either broaden the
+  API key's permissions or switch to one that already has them.
+- **Tool call returns `Permission denied`** — the scope check on the backend
+  disagrees with startup introspection (rare, but possible across scope
+  changes). Re-spawn the server to refresh the cached scope set.
+
 ## Development
 
 ```bash
@@ -86,7 +145,17 @@ 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.
+waiting for JSON-RPC on stdin. To drive it manually, use the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js
+```
+
+## Release flow
+
+Pushing a `v<x.y.z>` tag to `main` triggers GitHub Actions to typecheck, test,
+build, verify the tag matches `package.json`, and publish to npm via the
+`NPM_TOKEN` secret. No developer-machine credentials involved.
 
 ## Phase 2 (planned)
 
@@ -94,3 +163,4 @@ waiting for JSON-RPC on stdin.
   in TopoloAuth.
 - Dynamic tool registration as more `@topolo/sdk` modules ship.
 - HTTP transport in addition to stdio, for hosted (non-subprocess) deployments.
+- Optional `--provenance` on npm publish once the repo is public.

package/dist/index.js

@@ -1,14 +1,9 @@
 #!/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
+// node_modules/@topolo/sdk/dist/index.js
 function applyAuthHeaders(headers, credential) {
   if (credential.kind === "api_key") {
     headers.set("X-Api-Key", credential.apiKey);
@@ -86,6 +81,7 @@ var TopoloClient = class {
   requireConfirmForWrites;
   timeoutMs;
   fetchImpl;
+  debug;
   constructor(options) {
     if (!options.credential) throw new TopoloAuthError("credential is required");
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
@@ -95,6 +91,14 @@ var TopoloClient = class {
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? fetch;
+    this.debug = options.debug;
+  }
+  emit(event) {
+    if (!this.debug) return;
+    try {
+      this.debug(event);
+    } catch {
+    }
   }
   /**
    * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
@@ -121,27 +125,56 @@ var TopoloClient = class {
     const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
     if (platformServiceId) headers.set("X-Service-ID", platformServiceId);
     applyAuthHeaders(headers, this.credential);
-    applyAuditHeaders(headers, this.agent, generateRequestId());
+    const requestId = generateRequestId();
+    applyAuditHeaders(headers, this.agent, requestId);
     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;
+    const urlStr = url.toString();
+    const startedAt = Date.now();
+    this.emit({ phase: "request", method, service: opts.service, path: opts.path, url: urlStr, requestId });
     let res;
     try {
-      res = await this.fetchImpl(url.toString(), {
+      res = await this.fetchImpl(urlStr, {
         method,
         headers,
         body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
         signal
       });
+    } catch (err) {
+      this.emit({
+        phase: "error",
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs: Date.now() - startedAt,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
     } 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) {
+      const durationMs = Date.now() - startedAt;
+      const message = describeError(parsed, `HTTP ${res.status}`);
+      this.emit({
+        phase: "error",
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs,
+        error: message,
+        status: res.status
+      });
       if (res.status === 401) throw new TopoloAuthError(describeError(parsed, "Unauthorized"));
       if (res.status === 403) {
         throw new TopoloPermissionError(
@@ -151,6 +184,16 @@ var TopoloClient = class {
       }
       throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
     }
+    this.emit({
+      phase: "response",
+      method,
+      service: opts.service,
+      path: opts.path,
+      url: urlStr,
+      requestId,
+      status: res.status,
+      durationMs: Date.now() - startedAt
+    });
     return parsed;
   }
   /**
@@ -308,6 +351,13 @@ function resolveServiceUrlsFromEnv() {
   return Object.keys(out).length > 0 ? out : void 0;
 }
 
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
 // src/gating.ts
 function hasScope(set, required) {
   if (set.role === "super_admin") return true;
@@ -409,37 +459,12 @@ function filterToolsByScopes(tools, scopes) {
 // 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);
+// src/server.ts
+function buildServer(topolo, scopes, tools = TOOLS) {
+  const availableTools = filterToolsByScopes(tools, scopes);
   const server = new Server(
-    {
-      name: "topolo",
-      version: MCP_VERSION
-    },
-    {
-      capabilities: { tools: {} }
-    }
+    { name: "topolo", version: MCP_VERSION },
+    { capabilities: { tools: {} } }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: availableTools.map((t) => ({
@@ -469,9 +494,7 @@ async function main() {
     try {
       const result = await tool.handler(topolo, params.arguments ?? {});
       return {
-        content: [
-          { type: "text", text: JSON.stringify(result, null, 2) }
-        ]
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
       };
     } catch (err) {
       if (err instanceof TopoloPermissionError) {
@@ -483,10 +506,46 @@ async function main() {
       return toolError(err instanceof Error ? err.message : String(err));
     }
   });
+  return server;
+}
+function advertisedToolNames(scopes, tools = TOOLS) {
+  return filterToolsByScopes(tools, scopes).map((t) => t.name);
+}
+function toolError(message) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }]
+  };
+}
+
+// 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 server = buildServer(topolo, scopes);
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  const toolNames = advertisedToolNames(scopes);
   process.stderr.write(
-    `TopoloMCP v${MCP_VERSION} connected. Tools available: ${availableTools.map((t) => t.name).join(", ") || "(none)"}
+    `TopoloMCP v${MCP_VERSION} connected. Tools available: ${toolNames.join(", ") || "(none)"}
 `
   );
 }
@@ -506,12 +565,6 @@ async function loadScopes(topolo) {
     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)}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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": {
@@ -21,7 +21,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "devDependencies": {
-    "@topolo/sdk": "file:../packages/topolo-sdk",
+    "@topolo/sdk": "latest",
     "@types/node": "^20.12.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",