@topolo/mcp 0.1.0 → 0.1.1

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

@@ -8,7 +8,7 @@ import {
   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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",