@ziggs-ai/ziggs-mcp 0.1.6 → 0.1.8

package/dist/operatorKey.d.ts

@@ -2,7 +2,9 @@
 export interface OperatorKeyClaims {
     type?: string;
     keyId?: string;
+    ownerId?: string;
     boundAgentId?: string | null;
+    boundOrgId?: string | null;
     exp?: number;
 }
 declare const MINT_KEY_HELP: string;

package/dist/operatorKey.js

@@ -1,6 +1,6 @@
 const MINT_KEY_HELP = 'Mint a key in the Ziggs app: Developer Portal → Operator keys (fleet key + set ZIGGS_AGENT_ID), ' +
     'or open your delegate agent → Issue operator key (agent-scoped — no ZIGGS_AGENT_ID needed). ' +
-    'Docs: https://app.ziggsai.com/docs (Claude Code MCP tier).';
+    'Docs: https://ziggsai.com/docs (Claude Code MCP tier).';
 /** Decode operator JWT payload without verifying signature (ZIG-279 boundAgentId). */
 export function decodeOperatorKeyClaims(token) {
     const trimmed = token.trim();
@@ -13,7 +13,9 @@ export function decodeOperatorKeyClaims(token) {
         return {
             type: payload.type,
             keyId: payload.keyId,
+            ownerId: payload.ownerId,
             boundAgentId: payload.boundAgentId ?? null,
+            boundOrgId: payload.boundOrgId ?? null,
             exp: payload.exp,
         };
     }

package/dist/tools.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, respondToAgreement, ScopeClient, MessagesClient, sendChatMessage, ContextDiscoveryClient, ContextReadClient, InboxClient, ArtifactsClient, getBackendUrl, } from '@ziggs-ai/api-client';
+import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { formatInboxToolResult } from './inboxToolResult.js';
 function textResult(data) {
@@ -46,6 +47,24 @@ async function writeArtifactStrict(creds, input) {
     }
 }
 export function registerZiggsTools(server, creds, cfg) {
+    server.tool('ziggs_connection_status', 'ZIG-503 — Verify MCP OAuth binding: delegate agent id, owner user id, and org scope. Call after connect before inbox/chats.', {}, async () => {
+        const claims = decodeOperatorKeyClaims(creds.operatorKey);
+        const boundOrgId = claims?.boundOrgId?.trim() || null;
+        return textResult({
+            ok: true,
+            agentId: creds.agentId,
+            ownerId: claims?.ownerId ?? cfg.ZIGGS_OWNER_USER_ID ?? null,
+            keyId: claims?.keyId ?? null,
+            tokenType: claims?.type ?? 'operator',
+            orgId: boundOrgId,
+            orgBinding: boundOrgId ? 'selected' : 'personal',
+            orgBindingNote: boundOrgId
+                ? 'MCP OAuth is bound to the organization you chose at consent (ZIG-504).'
+                : 'MCP OAuth binds to your personal org when no org was specified at consent.',
+            apiBase: getBackendUrl(),
+            docs: 'https://ziggsai.com/docs',
+        });
+    });
     server.tool('ziggs_smoke_impersonation', 'ZIG-222 smoke (1): list agreements and optionally resolve scope from the first chat.', {}, async () => {
         try {
             const agreements = await getMyAgreements({}, creds);

package/examples/claude-code-remote-mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "ziggs": {
+      "url": "https://mcp.ziggsai.com/mcp"
+    }
+  }
+}

package/examples/claude-code-remote-oauth.md

@@ -0,0 +1,114 @@
+# Claude Code + Ziggs remote MCP (OAuth — ZIG-500 V4)
+
+Verify the **fresh Claude Code** journey: empty repo, `.mcp.json` only (no operator key), OAuth → real Ziggs tools.
+
+Automated prerequisites + Path A parity (no UI):
+
+```bash
+cd agentplus
+node scripts/smoke-zig-500-v4-path.mjs --discovery-only
+node scripts/smoke-zig-500-v4-path.mjs --auto
+```
+
+---
+
+## What V4 proves
+
+| Layer | Automated script | Manual Claude Code |
+|-------|------------------|-------------------|
+| ZIG-496 discovery (well-known, 401 docs) | `--discovery-only` | Client uses same URLs |
+| OAuth → Bearer → full tool surface | `--auto` or smoke creds | Connect in IDE |
+| No stub-only tools | fails if only `authenticate` / `complete_authentication` | Tool picker shows `ziggs_*` |
+| Restart not required | N/A | Tools visible right after OAuth |
+
+**Path A (pass):** Native MCP OAuth — client discovers metadata, gets Bearer, `tools/list` returns ≥12 `ziggs_*` tools.
+
+**Path B (fail → epic children 501–502):** OAuth succeeds but only stub auth tools appear — needs unauth MCP + `tools/list_changed` design in backend.
+
+---
+
+## Manual setup (empty repo)
+
+### 1. Create `.mcp.json` at repo root
+
+Copy [`claude-code-remote-mcp.json`](claude-code-remote-mcp.json):
+
+```json
+{
+  "mcpServers": {
+    "ziggs": {
+      "url": "https://mcp.ziggsai.com/mcp"
+    }
+  }
+}
+```
+
+No `ZIGGS_OPERATOR_KEY`, no `command` / `npx` — URL + OAuth only.
+
+### 2. Open in Claude Code
+
+Use a **throwaway directory** (no existing Ziggs plugin or stdio MCP).
+
+### 3. Connect / authorize
+
+1. Claude Code should prompt for MCP OAuth (or open MCP settings).
+2. Browser → Ziggs consent (`/app/oauth/mcp-consent`) → **Allow**.
+3. Return to Claude Code — check tool list.
+
+### 4. Smoke tools (no restart)
+
+Ask Claude to call in order:
+
+1. `ziggs_list_chats` or `ziggs_inbox`
+2. `ziggs_send_message` (chat you belong to)
+
+**Pass:** both succeed; tool picker shows many `ziggs_*` tools (not just 2 auth stubs).
+
+**Fail:** only `authenticate` / `complete_authentication`; or OAuth OK but tools empty until restart → comment on [ZIG-500](https://linear.app/ziggsai/issue/ZIG-500) with Path B.
+
+---
+
+## Discovery URLs (same as Cursor / claude.ai)
+
+| Resource | URL |
+|----------|-----|
+| MCP endpoint | `https://mcp.ziggsai.com/mcp` |
+| Protected resource (RFC 9728) | `https://mcp.ziggsai.com/.well-known/oauth-protected-resource/mcp` |
+| Authorization server | `https://api.ziggsai.com/.well-known/oauth-authorization-server` |
+| Docs (401 hint) | `https://ziggsai.com/docs` |
+
+Localhost redirect (Claude Code default): `https://localhost/oauth/callback`
+
+---
+
+## Operator-key fallback (not V4)
+
+For dev or when OAuth is blocked, use [claude-code.md](claude-code.md) Option B (`ZIGGS_OPERATOR_KEY` + `npx @ziggs-ai/ziggs-mcp`). That path is **not** the ZIG-500 epic acceptance target.
+
+---
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|--------|
+| OAuth loop / 401 on tools | Re-run `smoke-zig-500-v4-path.mjs --auto`; revoke MCP in Agents dashboard → reconnect |
+| Only 2 stub tools | Path B — epic needs 501/502; paste tool list in Linear |
+| `app.ziggsai.com` in 401 `error` text | ZIG-496 fixed `docs` field; `error` string comes from pinned `@ziggs-ai/ziggs-mcp` npm — bump backend dep after publish |
+| Tools after restart only | ZIG-502 `tools/list_changed` candidate |
+
+---
+
+## Sign-off template (paste in ZIG-500)
+
+```
+ZIG-500 V4 — fresh Claude Code
+Date:
+Claude Code version:
+Repo: empty + .mcp.json only (Y/N)
+Automated: smoke-zig-500-v4-path.mjs --discovery-only → pass/fail
+Automated: smoke-zig-500-v4-path.mjs --auto → Path A/B, N tools
+Manual OAuth connect: pass/fail
+Tool count after OAuth (no restart): __
+ziggs_inbox or ziggs_list_chats: pass/fail
+Notes:
+```

package/examples/claude-code.md

@@ -1,6 +1,8 @@
-# Claude Code + Ziggs MCP (ZIG-430 / ZIG-437)
+# Claude Code + Ziggs MCP (ZIG-430 / ZIG-437 / ZIG-500)
 
-One-command boarding against production (`https://api.ziggsai.com`).
+**Recommended:** [Remote OAuth](claude-code-remote-oauth.md) — `.mcp.json` with `https://mcp.ziggsai.com/mcp` only, no operator key.
+
+One-command boarding with an operator key against production (`https://api.ziggsai.com`).
 
 ## Option A — Plugin (ZIG-437, recommended)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {