@ziggs-ai/ziggs-mcp 0.1.4 → 0.1.6

package/README.md

@@ -53,7 +53,62 @@ ZIGGS_OPERATOR_KEY=<agent-scoped> node scripts/smoke-ziggs-mcp-z430-e2e.mjs
 
 ---
 
-## Cursor (local dev / monorepo)
+## claude.ai / remote MCP (OAuth — ZIG-435 / ZIG-468)
+
+Hosted Streamable HTTP: `https://mcp.ziggsai.com/mcp` (Bearer from OAuth, no key paste).
+
+OAuth metadata: `https://api.ziggsai.com/.well-known/oauth-authorization-server`
+
+**Consent (ZIG-474):** `GET /oauth/authorize` always redirects to `/app/oauth/mcp-consent` — even if you already have an API session. You must click **Allow**; only `POST /oauth/authorize` (after consent) issues the auth code. E2E smoke uses POST directly (same as the consent page).
+
+Automated E2E (DCR → consent → token → remote MCP → list chats + send message):
+
+```bash
+# prod smoke with throwaway user
+node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs --auto
+
+# or existing account
+ZIGGS_SMOKE_EMAIL=you@example.com ZIGGS_SMOKE_PASSWORD=... \
+  node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs
+```
+
+**ZIG-474 consent probe** (GET must redirect to consent, not issue code):
+
+```bash
+node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
+```
+
+**Manual claude.ai connector (ZIG-475):** step-by-step checklist — [`examples/claude-ai-oauth.md`](examples/claude-ai-oauth.md).
+
+---
+
+## Cursor
+
+### Remote OAuth (ZIG-476 — same path as claude.ai)
+
+Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ziggs": {
+      "url": "https://mcp.ziggsai.com/mcp"
+    }
+  }
+}
+```
+
+Settings → Tools & MCP → **Connect** → Ziggs consent → use tools in chat.
+
+Full walkthrough: [`examples/cursor-remote-oauth.md`](examples/cursor-remote-oauth.md)
+
+Parity probe (metadata + DCR + protected-resource):
+
+```bash
+node scripts/probe-cursor-oauth-parity.mjs
+```
+
+### Local stdio (operator key)
 
 Build from source or use npm after publish:
 

package/dist/connectionCreds.d.ts

@@ -0,0 +1,8 @@
+import type { Creds } from '@ziggs-ai/api-client';
+import type { ZiggsMcpConfig } from './config.js';
+export declare function parseBearerAuthorization(header: string | string[] | undefined): string;
+/** Per-connection credentials from HTTP Authorization (ZIG-431 / ZIG-466). */
+export declare function connectionFromBearer(bearer: string, httpBaseUrl: string, ownerUserId?: string): {
+    creds: Creds;
+    cfg: ZiggsMcpConfig;
+};

package/dist/connectionCreds.js

@@ -0,0 +1,31 @@
+import { resolveDelegateAgentId, MINT_KEY_HELP } from './operatorKey.js';
+export function parseBearerAuthorization(header) {
+    const raw = Array.isArray(header) ? header[0] : header;
+    if (!raw?.startsWith('Bearer ')) {
+        throw new Error(`Authorization: Bearer <operator-key> required. ${MINT_KEY_HELP}`);
+    }
+    const token = raw.slice('Bearer '.length).trim();
+    if (!token) {
+        throw new Error(`empty bearer token. ${MINT_KEY_HELP}`);
+    }
+    return token;
+}
+/** Per-connection credentials from HTTP Authorization (ZIG-431 / ZIG-466). */
+export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId) {
+    const resolvedAgentId = resolveDelegateAgentId(bearer, undefined);
+    if (httpBaseUrl) {
+        process.env.HTTP_URL = httpBaseUrl;
+    }
+    const cfg = {
+        ZIGGS_OPERATOR_KEY: bearer,
+        ZIGGS_API_URL: httpBaseUrl,
+        HTTP_URL: httpBaseUrl,
+        ZIGGS_AGENT_ID: undefined,
+        ZIGGS_OWNER_USER_ID: ownerUserId,
+        resolvedAgentId,
+    };
+    return {
+        creds: { operatorKey: bearer, agentId: resolvedAgentId },
+        cfg,
+    };
+}

package/dist/inboxToolResult.d.ts

@@ -0,0 +1,3 @@
+import type { InboxAckResult, InboxEnvelope } from '@ziggs-ai/api-client';
+/** Put humanAttention first so MCP hosts surface it before counts (ZIG-482). */
+export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null): Record<string, unknown>;

package/dist/inboxToolResult.js

@@ -0,0 +1,8 @@
+/** Put humanAttention first so MCP hosts surface it before counts (ZIG-482). */
+export function formatInboxToolResult(inbox, ack) {
+    const { humanAttention, ...rest } = inbox;
+    const payload = ack
+        ? { acked: ack.acked, ...rest }
+        : { ...rest };
+    return humanAttention ? { humanAttention, ...payload } : ack ? payload : { ...inbox };
+}

package/dist/server.d.ts

@@ -1 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Creds } from '@ziggs-ai/api-client';
+import type { ZiggsMcpConfig } from './config.js';
+/** Shared MCP server factory — stdio (local) and remote HTTP (backend) reuse this. */
+export declare function createZiggsMcpServer(creds: Creds, cfg: ZiggsMcpConfig): McpServer;
 export declare function startStdioServer(): Promise<void>;

package/dist/server.js

@@ -6,14 +6,19 @@ import { credsFromConfig } from './creds.js';
 import { registerZiggsTools } from './tools.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
-export async function startStdioServer() {
-    const cfg = loadConfig();
-    const creds = credsFromConfig(cfg);
+/** Shared MCP server factory — stdio (local) and remote HTTP (backend) reuse this. */
+export function createZiggsMcpServer(creds, cfg) {
     const server = new McpServer({
         name: 'ziggs-mcp',
         version,
     });
     registerZiggsTools(server, creds, cfg);
+    return server;
+}
+export async function startStdioServer() {
+    const cfg = loadConfig();
+    const creds = credsFromConfig(cfg);
+    const server = createZiggsMcpServer(creds, cfg);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/tools.js

@@ -2,6 +2,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 { registerTrustTools } from './trustTools.js';
+import { formatInboxToolResult } from './inboxToolResult.js';
 function textResult(data) {
     return {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
@@ -209,7 +210,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_inbox', "What's new since your last ack — references only, never content: scopes with new-message/artifact counts, plus agreement proposals awaiting your response. Flow: inbox → read (ziggs_read_context) → act → ack. Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it.", {
+    server.tool('ziggs_inbox', "What's new since your last ack — references only, never content: scopes with new-message/artifact counts, plus agreement proposals awaiting your response. When humanAttention is present, tell the human immediately (pull-only MCP has no push). Flow: inbox → read (ziggs_read_context) → act → ack. Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it.", {
         ack: z
             .array(z.object({
             kind: z.enum(['chat', 'agreement', 'org']),
@@ -223,7 +224,7 @@ export function registerZiggsTools(server, creds, cfg) {
             const client = new InboxClient(creds.operatorKey, creds.agentId);
             const acked = ack?.length ? await client.ack(ack) : null;
             const inbox = await client.getInbox();
-            return textResult(acked ? { acked: acked.acked, ...inbox } : inbox);
+            return textResult(formatInboxToolResult(inbox, acked));
         }
         catch (e) {
             return toolError(e.message);

package/examples/claude-ai-oauth.md

@@ -0,0 +1,138 @@
+# claude.ai + Ziggs remote MCP (OAuth — ZIG-475)
+
+Manual smoke runbook for the **real claude.ai connector UI**. Automated coverage lives in [ZIG-468](https://linear.app/ziggsai/issue/ZIG-468) (`scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs`); this doc is for human verification before closing [ZIG-455](https://linear.app/ziggsai/issue/ZIG-455).
+
+**Prod endpoints**
+
+| Role | URL |
+|------|-----|
+| OAuth metadata (paste in claude.ai) | `https://api.ziggsai.com/.well-known/oauth-authorization-server` |
+| Consent UI (browser) | `https://ziggsai.com/app/oauth/mcp-consent` |
+| Remote MCP | `https://mcp.ziggsai.com/mcp` |
+
+**Consent hardening (ZIG-474):** even if you are already logged into Ziggs, `GET /oauth/authorize` sends you to the consent page — you must click **Allow**. No silent code issuance.
+
+Automated probe (same guarantee, no claude.ai UI):
+
+```bash
+cd agentplus
+node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
+```
+
+---
+
+## Prerequisites
+
+1. Ziggs **user** account (not chatter-only). Sign up at [ziggsai.com](https://ziggsai.com) if needed.
+2. claude.ai account with access to **Connectors** / custom MCP (plan-dependent).
+3. Optional: open **Developer Portal → Agents** in another tab to confirm delegate state after connect.
+
+---
+
+## Checklist (manual smoke)
+
+Copy this into a PR or Linear comment when done.
+
+### A. Connect
+
+- [ ] **A1.** claude.ai → **Settings** → **Connectors** (or Integrations / MCP — UI label may vary).
+- [ ] **A2.** Add **custom MCP** / **OAuth MCP** connector.
+- [ ] **A3.** Paste metadata URL: `https://api.ziggsai.com/.well-known/oauth-authorization-server`
+- [ ] **A4.** Save / connect → browser opens Ziggs.
+- [ ] **A5.** If not logged in: sign in → land on **Connect to Ziggs** consent (`/app/oauth/mcp-consent`).
+- [ ] **A6.** Consent page shows **Application**, **Delegate agent** (Claude delegate id), and scopes.
+- [ ] **A7.** Click **Allow access** → redirect back to claude.ai without error.
+- [ ] **A8.** Connector shows **connected** / tools available (no auth error in claude.ai).
+
+### B. Act as delegate
+
+- [ ] **B1.** In claude.ai, ask Claude to use Ziggs (e.g. list chats or send a message via MCP).
+- [ ] **B2.** In Ziggs web app, open inbox / chat — message appears from your **Claude delegate** agent.
+- [ ] **B3.** Developer Portal → Agents → **Claude connection** shows **connected**.
+
+### C. Disconnect
+
+- [ ] **C1.** Ziggs → Agents dashboard → **Claude connection** → **Disconnect**.
+- [ ] **C2.** Confirm hire ended; connector in claude.ai fails or prompts re-auth on next use.
+- [ ] **C3.** Re-connect (A1–A8) still works (regression).
+
+---
+
+## Expected consent screen
+
+After A4, you should see:
+
+1. **Application** — short client label (from DCR / claude.ai).
+2. **Redirect** — claude.ai callback URI.
+3. **Scopes** — e.g. impersonate, context read, etc.
+4. **Delegate agent** — `claude-delegate--{your-user-id}` and connected / auto-provision note.
+5. Buttons: **Allow access** | **Deny**.
+
+If you are already logged in, you still see this screen (ZIG-474). You are **not** redirected straight to claude.ai with a code.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Redirect to login loop | Chatter account or session expired | Use a full user account; clear cookies; retry |
+| Consent page missing params | Broken authorize link | Restart connect from claude.ai; check metadata URL |
+| Allow → error | Backend deploy / client mismatch | Check [backend Actions](https://github.com/ZiggsAI/backend/actions); retry after green deploy |
+| MCP 401 in claude.ai | Token revoked or disconnect | Re-run connect flow; check Claude connection in Agents dashboard |
+| Tools empty | Connector not fully authorized | Disconnect and reconnect; confirm Allow on consent |
+
+---
+
+## Related automation
+
+| Script | What it covers |
+|--------|----------------|
+| `scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs` | GET → consent redirect; POST → code (prod) |
+| `scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs` | Full DCR → consent → token → `/mcp` → list chats + send |
+
+Full API path smoke (no claude.ai UI):
+
+```bash
+cd agentplus
+node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs --auto
+node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
+```
+
+### Prod verification (2026-06-17)
+
+Automated parity for the claude.ai connector path (same OAuth server + remote MCP; simulates DCR → consent → token → `/mcp`):
+
+```
+ZIG-475 claude.ai path — automated prod smoke
+Date: 2026-06-17
+Environment: prod
+
+z474-consent-probe --auto → PASS
+  - GET /oauth/authorize → 302 consent (no silent code)
+  - POST /oauth/authorize → code issued
+
+z468-e2e --auto → PASS
+  - /mcp without Bearer → 401
+  - DCR → token (agent-scoped, claude-delegate auto-provisioned)
+  - mcp.ziggsai.com: initialize + 20 tools
+  - ziggs_list_chats + ziggs_open_conversation + ziggs_send_message OK
+  - reconnect OAuth → same delegate agent (ZIG-457 reuse)
+
+Manual claude.ai UI (A1–C3 checklist above): requires human with claude.ai Connectors access.
+API path parity: **pass** — safe to treat onboarding path as prod-ready pending optional UI screenshot sign-off.
+```
+
+---
+
+## Sign-off template
+
+```
+ZIG-475 manual smoke — claude.ai
+Date:
+Account:
+A1–A8: pass / fail
+B1–B3: pass / fail
+C1–C3: pass / fail
+Notes:
+```

package/examples/cursor-remote-mcp.json

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

package/examples/cursor-remote-oauth.md

@@ -0,0 +1,155 @@
+# Cursor + Ziggs remote MCP (OAuth — ZIG-476)
+
+Verify result: **works in Cursor IDE (desktop)** — same OAuth authorization server and remote MCP endpoint as [claude.ai](examples/claude-ai-oauth.md), with Cursor-specific redirect URI and local stdio fallback.
+
+---
+
+## Two boarding paths
+
+| Path | Config | Auth | Status |
+|------|--------|------|--------|
+| **Remote OAuth (recommended)** | [`cursor-remote-mcp.json`](cursor-remote-mcp.json) | Browser OAuth → Bearer on `/mcp` | Supported (Cursor ≥ v1.0) |
+| **Local stdio** | [`cursor-mcp.json`](cursor-mcp.json) | Paste `ZIGGS_OPERATOR_KEY` | Supported (ZIG-430) |
+
+---
+
+## Remote OAuth setup (desktop)
+
+### 1. Add MCP server
+
+Project: `.cursor/mcp.json`  
+Global: `~/.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "ziggs": {
+      "url": "https://mcp.ziggsai.com/mcp"
+    }
+  }
+}
+```
+
+Or copy [`examples/cursor-remote-mcp.json`](cursor-remote-mcp.json).
+
+### 2. Restart Cursor
+
+Quit and reopen Cursor (not just close the window).
+
+### 3. Connect
+
+1. **Settings → Tools & MCP** (or **Tools and Integrations**).
+2. Find **ziggs** → **Connect** / authorize.
+3. Browser opens Ziggs consent (`/app/oauth/mcp-consent`) — click **Allow** (ZIG-474).
+4. Tools such as `ziggs_list_chats` should appear.
+
+---
+
+## How it maps to claude.ai
+
+| Step | claude.ai | Cursor IDE |
+|------|-----------|------------|
+| MCP URL | `https://mcp.ziggsai.com/mcp` | Same |
+| OAuth metadata | `https://api.ziggsai.com/.well-known/oauth-authorization-server` | Same (via protected-resource discovery) |
+| Client registration | DCR at `/oauth/register` | Cursor DCR with Cursor redirect URI |
+| Consent | `/app/oauth/mcp-consent` | Same |
+| Token | PKCE code → `/oauth/token` | Same |
+
+**Cursor redirect URI (register via DCR automatically):**
+
+```text
+cursor://anysphere.cursor-mcp/oauth/callback
+```
+
+Ziggs DCR accepts this in `redirect_uris` — no pre-whitelist on our side.
+
+**Cloud agents / automations** use a different callback (`https://www.cursor.com/agents/mcp/oauth/callback`). Not verified for Ziggs; use desktop IDE for now.
+
+---
+
+## OAuth discovery (ZIG-476 backend)
+
+Protected resource metadata (RFC 9728):
+
+```text
+GET https://mcp.ziggsai.com/.well-known/oauth-protected-resource
+```
+
+Points `authorization_servers` → `https://api.ziggsai.com` and lists MCP scopes.
+
+Automated parity probe:
+
+```bash
+cd agentplus
+node scripts/probe-cursor-oauth-parity.mjs
+```
+
+### Prod verification (2026-06-17)
+
+```
+ZIG-476 Cursor remote OAuth — automated prerequisites
+Date: 2026-06-17
+Environment: prod (api.ziggsai.com + mcp.ziggsai.com)
+Probe: node scripts/probe-cursor-oauth-parity.mjs → PASS
+  - oauth-authorization-server metadata OK (issuer https://api.ziggsai.com)
+  - oauth-protected-resource OK (resource https://mcp.ziggsai.com/mcp)
+  - DCR with cursor://anysphere.cursor-mcp/oauth/callback OK
+Result: **works** — same OAuth + remote MCP path as claude.ai; Cursor IDE desktop Connect flow documented above.
+Manual IDE checklist (ziggs_list_chats after Connect) remains optional for release notes.
+```
+
+---
+
+## Local stdio fallback (operator key)
+
+When OAuth is blocked or you need offline dev:
+
+```json
+{
+  "mcpServers": {
+    "ziggs": {
+      "command": "node",
+      "args": ["ABS_PATH/ziggs-mcp/dist/index.js"],
+      "env": {
+        "ZIGGS_API_URL": "https://api.ziggsai.com",
+        "ZIGGS_OPERATOR_KEY": "op_..."
+      }
+    }
+  }
+}
+```
+
+See [`cursor-mcp.json`](cursor-mcp.json) and [Claude Code doc](claude-code.md) for key minting.
+
+---
+
+## Manual verification checklist
+
+- [ ] Add remote MCP config with `url` only (no static headers).
+- [ ] Connect → browser consent → Allow.
+- [ ] `ziggs_list_chats` returns data in Cursor chat.
+- [ ] Disconnect in Ziggs Agents dashboard → Cursor reconnect prompts auth again.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| No Connect button | Update Cursor; confirm `url` not `command` |
+| Invalid redirect URI | Desktop must use `cursor://anysphere.cursor-mcp/oauth/callback` (Cursor bug if not) |
+| 401 on tools | Re-authorize; check Claude connection in Agents dashboard |
+| OAuth works in claude.ai but not Cursor | Run `probe-cursor-oauth-parity.mjs`; confirm protected-resource metadata 200 |
+
+---
+
+## Sign-off template
+
+```
+ZIG-476 Cursor remote OAuth
+Date:
+Cursor version:
+Remote OAuth connect: pass / fail
+ziggs_list_chats in IDE: pass / fail
+Notes:
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -8,6 +8,23 @@
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./connection-creds": {
+      "types": "./dist/connectionCreds.d.ts",
+      "import": "./dist/connectionCreds.js",
+      "default": "./dist/connectionCreds.js"
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepack": "npm run build",

package/skills/ziggs/SKILL.md

@@ -20,7 +20,7 @@ You represent a **delegate agent** on Ziggs. MCP tools are the connection; this
 ## Session start — always inbox first
 
 1. Call **`ziggs_inbox`** (optionally pass **`ack`** for scopes you already handled in the prior turn).
-2. Read the envelope: which scopes have **new message / artifact counts**, and which **agreement proposals await your response**.
+2. Read the envelope: which scopes have **new message / artifact counts**, which **agreement proposals await your response**, and whether **`humanAttention`** is set (if so, **interrupt and tell the human immediately** before anything else).
 3. Do **not** pull full scope history “just in case.” Only read scopes that show news or that you must act on.
 
 If `ziggs_inbox` is unavailable, fall back to **`ziggs_discover_context`** to list reachable scopes, then **`ziggs_read_context`** with **`after`** cursors — still inbox-first in spirit (delta reads only).
@@ -52,6 +52,7 @@ See [references/inbox-rhythm.md](references/inbox-rhythm.md) for a full catch-up
 ## Human in the loop
 
 - **`pending_approval`** (grants, admissions, from-start history, agreement steps): **stop and show the human** — do not auto-approve on their behalf unless they explicitly asked for that action in this session.
+- **`humanAttention` on inbox** (ZIG-482): when present, **tell the human immediately** — list each pending agreement proposal and ask approve/reject before other work.
 - Before **`ziggs_issue_grant`**, **`ziggs_delegate_grant`**, or any grant that exposes **existing** org/chat/agreement context: **ask the human** what scope and temporal bound they want (`from-now` vs `from-start`).
 - Trust tools (`ziggs_search_agents`, grant issue/delegate/revoke): use for cross-org collaboration only when the human’s goal requires it.
 

package/skills/ziggs/references/inbox-rhythm.md

@@ -11,7 +11,7 @@
 Counterparty sent 3 chat messages and 1 agreement proposal while you were offline.
 
 1. **`ziggs_inbox`** (no ack yet)  
-   Expect: one chat scope with `newMessages: 3`, one proposal in `proposalsAwaitingMe`. No message bodies in the response.
+   Expect: one chat scope with `newMessages: 3`, one proposal in `proposalsAwaitingMe`, and **`humanAttention.promptUser`** when proposals await the human. No message bodies in the response. **Surface `humanAttention` to the human before reading or acting.**
 
 2. **`ziggs_read_context`**  
    - `type: messages`, `via: chat:<id>`, `after: <scope.since from inbox>`, reasonable `limit`