@ziggs-ai/ziggs-mcp 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# @ziggs-ai/ziggs-mcp
+
+MCP (stdio) server for **Claude Code**, **Cursor**, and other MCP hosts ([ZIG-222](https://linear.app/ziggsai/issue/ZIG-222/minimal-boarding-cursor-represents-you-on-ziggs), [ZIG-430](https://linear.app/ziggsai/issue/ZIG-430/publish-ziggs-mcp-to-npm-one-command-claude-code-boarding)).
+
+**In scope:** chat, agreements, scope, context discovery/reads, artifacts.  
+**Out of scope (by design):** agent `transfer`, hire agreements, capability tokens / bounded spend.
+
+---
+
+## Claude Code (recommended — ZIG-430)
+
+### Quick start
+
+```bash
+claude mcp add ziggs \
+  --env ZIGGS_OPERATOR_KEY=<your-agent-scoped-key> \
+  -- npx -y @ziggs-ai/ziggs-mcp
+```
+
+Use an **agent-scoped** operator key from the Ziggs Developer Portal — no `registerAgent`, no separate `ZIGGS_AGENT_ID` ([ZIG-279](https://linear.app/ziggsai/issue/ZIG-279/agent-scoped-operator-keys-to-skip-registration)).
+
+Full walkthrough: [`examples/claude-code.md`](examples/claude-code.md)
+
+### Smoke (Linear ZIG-430)
+
+| Step | Tool |
+|------|------|
+| List chats / discover reach | `ziggs_list_chats` or `ziggs_discover_context` |
+| Send message | `ziggs_send_message` |
+| Propose + respond | `ziggs_propose_agreement`, `ziggs_respond_to_agreement` |
+
+---
+
+## Cursor (local dev / monorepo)
+
+Build from source or use npm after publish:
+
+```bash
+npm install && npm run build -w @ziggs-ai/ziggs-mcp
+```
+
+See [`examples/cursor-mcp.json`](examples/cursor-mcp.json).
+
+---
+
+## Prerequisites
+
+### 1. Ziggs account
+
+Sign up and log in at the web app.
+
+### 2. Delegate agent + operator key
+
+**Agent-scoped key (Claude Code):** Developer Portal → your agent → **Issue operator key**.
+
+**Fleet key (Cursor / multi-agent):** Developer Portal → Operator keys, then set `ZIGGS_AGENT_ID`.
+
+Minimum scopes for boarding smoke: `agents:impersonate`, `agents:read`, `agents:write`, `context:read`.
+
+### 3. Environment
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ZIGGS_OPERATOR_KEY` | **yes** | Bearer operator token |
+| `ZIGGS_AGENT_ID` | fleet keys only | Delegate agent id — **omit for agent-scoped keys** |
+| `ZIGGS_OWNER_USER_ID` | no | Human `userId` — default payer for proposals |
+| `ZIGGS_API_URL` / `HTTP_URL` | no | Default `https://api.ziggsai.com` |
+
+Every HTTP call sends:
+
+```
+Authorization: Bearer <ZIGGS_OPERATOR_KEY>
+X-Agent-Id: <resolved delegate agent id>
+```
+
+Startup validates the key shape, expiry (JWT `exp`), and agent resolution — errors point to Developer Portal.
+
+### 4. CLI smoke scripts
+
+```bash
+cd agentplus
+
+# ZIG-222
+ZIGGS_OPERATOR_KEY=... ZIGGS_AGENT_ID=cursor-delegate \
+  node scripts/smoke-ziggs-mcp.mjs
+
+# ZIG-432 (two delegates + negative 403)
+ZIGGS_OPERATOR_KEY_A=... ZIGGS_AGENT_ID_A=... \
+ZIGGS_OPERATOR_KEY_B=... ZIGGS_AGENT_ID_B=... \
+ZIGGS_SMOKE_CHAT_ID=... \
+  node scripts/smoke-ziggs-mcp-context.mjs
+```
+
+---
+
+## Tools
+
+| Tool | Maps to |
+|------|---------|
+| `ziggs_discover_context` | `GET /context/discovery` |
+| `ziggs_read_context` | `GET /context/read/:type` |
+| `ziggs_record_artifact` | `POST /artifacts` |
+| `ziggs_list_artifacts` | `GET /artifacts` |
+| `ziggs_smoke_impersonation` | Smoke step 1 |
+| `ziggs_get_scope` | `GET /scope?via=` |
+| `ziggs_list_my_agreements` | `GET /agreements?scope=mine` |
+| `ziggs_get_agreement` | `GET /agreements/:id` |
+| `ziggs_list_chats` | `GET /chats/mine` |
+| `ziggs_open_conversation` | `POST /chats` |
+| `ziggs_list_messages` | `GET /chats/:id/messages` |
+| `ziggs_send_message` | `POST /chats/:id/messages` |
+| `ziggs_propose_agreement` | `POST /agreements/proposals` |
+| `ziggs_respond_to_agreement` | `POST /agreements/:id/respond` |
+
+---
+
+## Develop
+
+```bash
+cd agentplus
+npm install
+npm run build -w @ziggs-ai/ziggs-mcp
+npm test -w @ziggs-ai/ziggs-mcp
+```
+
+Logs must use **stderr** only (stdio MCP transport).
+
+## Publish (maintainers)
+
+1. Bump `@ziggs-ai/api-client` if needed → tag `api-client-v*`, push (publishes to npm).
+2. Tag `ziggs-mcp-v*` → CI publishes `@ziggs-ai/ziggs-mcp`.
+
+```bash
+git tag api-client-v0.1.5 && git push origin api-client-v0.1.5
+git tag ziggs-mcp-v0.1.0 && git push origin ziggs-mcp-v0.1.0
+```

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+import 'dotenv/config';
+import { z } from 'zod';
+declare const envSchema: z.ZodObject<{
+    ZIGGS_API_URL: z.ZodOptional<z.ZodString>;
+    HTTP_URL: z.ZodOptional<z.ZodString>;
+    ZIGGS_OPERATOR_KEY: z.ZodString;
+    /** Optional when the operator key is agent-scoped (ZIG-279). */
+    ZIGGS_AGENT_ID: z.ZodOptional<z.ZodString>;
+    /** Human user id for payer-side proposals (ZIG-222 smoke step 2). */
+    ZIGGS_OWNER_USER_ID: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    ZIGGS_OPERATOR_KEY: string;
+    ZIGGS_API_URL?: string | undefined;
+    HTTP_URL?: string | undefined;
+    ZIGGS_AGENT_ID?: string | undefined;
+    ZIGGS_OWNER_USER_ID?: string | undefined;
+}, {
+    ZIGGS_OPERATOR_KEY: string;
+    ZIGGS_API_URL?: string | undefined;
+    HTTP_URL?: string | undefined;
+    ZIGGS_AGENT_ID?: string | undefined;
+    ZIGGS_OWNER_USER_ID?: string | undefined;
+}>;
+type EnvConfig = z.infer<typeof envSchema>;
+export interface ZiggsMcpConfig extends EnvConfig {
+    /** Resolved delegate agent — from boundAgentId or ZIGGS_AGENT_ID. */
+    resolvedAgentId: string;
+}
+/** Load delegate credentials from the environment (ZIG-222 / ZIG-430). */
+export declare function loadConfig(): ZiggsMcpConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,38 @@
+import 'dotenv/config';
+import { z } from 'zod';
+import { MINT_KEY_HELP, resolveDelegateAgentId } from './operatorKey.js';
+const envSchema = z.object({
+    ZIGGS_API_URL: z.string().optional(),
+    HTTP_URL: z.string().optional(),
+    ZIGGS_OPERATOR_KEY: z.string().min(1, 'ZIGGS_OPERATOR_KEY is required'),
+    /** Optional when the operator key is agent-scoped (ZIG-279). */
+    ZIGGS_AGENT_ID: z.string().optional(),
+    /** Human user id for payer-side proposals (ZIG-222 smoke step 2). */
+    ZIGGS_OWNER_USER_ID: z.string().optional(),
+});
+/** Load delegate credentials from the environment (ZIG-222 / ZIG-430). */
+export function loadConfig() {
+    const raw = {
+        ZIGGS_API_URL: process.env.ZIGGS_API_URL,
+        HTTP_URL: process.env.HTTP_URL ?? process.env.ZIGGS_API_URL,
+        ZIGGS_OPERATOR_KEY: process.env.ZIGGS_OPERATOR_KEY,
+        ZIGGS_AGENT_ID: process.env.ZIGGS_AGENT_ID,
+        ZIGGS_OWNER_USER_ID: process.env.ZIGGS_OWNER_USER_ID,
+    };
+    const parsed = envSchema.safeParse(raw);
+    if (!parsed.success) {
+        const missing = parsed.error.issues.map((i) => i.path.join('.')).join(', ');
+        throw new Error(`ziggs-mcp: missing or invalid env (${missing}). ${MINT_KEY_HELP}`);
+    }
+    let resolvedAgentId;
+    try {
+        resolvedAgentId = resolveDelegateAgentId(parsed.data.ZIGGS_OPERATOR_KEY, parsed.data.ZIGGS_AGENT_ID);
+    }
+    catch (e) {
+        throw e instanceof Error ? e : new Error(String(e));
+    }
+    if (parsed.data.ZIGGS_API_URL && !process.env.HTTP_URL) {
+        process.env.HTTP_URL = parsed.data.ZIGGS_API_URL;
+    }
+    return { ...parsed.data, resolvedAgentId };
+}

package/dist/creds.d.ts

@@ -0,0 +1,3 @@
+import type { Creds } from '@ziggs-ai/api-client';
+import type { ZiggsMcpConfig } from './config.js';
+export declare function credsFromConfig(cfg: ZiggsMcpConfig): Creds;

package/dist/creds.js

@@ -0,0 +1,6 @@
+export function credsFromConfig(cfg) {
+    return {
+        operatorKey: cfg.ZIGGS_OPERATOR_KEY,
+        agentId: cfg.resolvedAgentId,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { startStdioServer } from './server.js';
+startStdioServer().catch((err) => {
+    console.error('[ziggs-mcp] fatal:', err);
+    process.exit(1);
+});

package/dist/operatorKey.d.ts

@@ -0,0 +1,16 @@
+/** JWT payload fields we read client-side (signature not verified — identity hint only). */
+export interface OperatorKeyClaims {
+    type?: string;
+    keyId?: string;
+    boundAgentId?: string | null;
+    exp?: number;
+}
+declare const MINT_KEY_HELP: string;
+/** Decode operator JWT payload without verifying signature (ZIG-279 boundAgentId). */
+export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
+export declare function isOperatorKeyExpired(claims: OperatorKeyClaims | null): boolean;
+/**
+ * Resolve delegate agent id: agent-scoped key (boundAgentId) wins; else ZIGGS_AGENT_ID.
+ */
+export declare function resolveDelegateAgentId(operatorKey: string, envAgentId: string | undefined): string;
+export { MINT_KEY_HELP };

package/dist/operatorKey.js

@@ -0,0 +1,57 @@
+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).';
+/** Decode operator JWT payload without verifying signature (ZIG-279 boundAgentId). */
+export function decodeOperatorKeyClaims(token) {
+    const trimmed = token.trim();
+    const parts = trimmed.split('.');
+    if (parts.length !== 3)
+        return null;
+    try {
+        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+        const payload = JSON.parse(json);
+        return {
+            type: payload.type,
+            keyId: payload.keyId,
+            boundAgentId: payload.boundAgentId ?? null,
+            exp: payload.exp,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function isOperatorKeyExpired(claims) {
+    if (!claims?.exp)
+        return false;
+    return claims.exp * 1000 <= Date.now();
+}
+/**
+ * Resolve delegate agent id: agent-scoped key (boundAgentId) wins; else ZIGGS_AGENT_ID.
+ */
+export function resolveDelegateAgentId(operatorKey, envAgentId) {
+    if (!operatorKey?.trim()) {
+        throw new Error(`ziggs-mcp: ZIGGS_OPERATOR_KEY is required. ${MINT_KEY_HELP}`);
+    }
+    const claims = decodeOperatorKeyClaims(operatorKey);
+    if (claims?.type && claims.type !== 'operator') {
+        throw new Error('ziggs-mcp: ZIGGS_OPERATOR_KEY must be an operator token (not a session JWT). ' +
+            MINT_KEY_HELP);
+    }
+    if (isOperatorKeyExpired(claims)) {
+        throw new Error(`ziggs-mcp: operator key expired (keyId=${claims?.keyId ?? 'unknown'}). ${MINT_KEY_HELP}`);
+    }
+    const bound = claims?.boundAgentId?.trim() || '';
+    const env = envAgentId?.trim() || '';
+    if (bound && env && bound !== env) {
+        throw new Error(`ziggs-mcp: ZIGGS_AGENT_ID (${env}) conflicts with agent-scoped key bound to "${bound}". ` +
+            'Remove ZIGGS_AGENT_ID or use a fleet impersonation key instead.');
+    }
+    if (bound)
+        return bound;
+    if (env)
+        return env;
+    throw new Error('ziggs-mcp: set ZIGGS_AGENT_ID, or mint an agent-scoped operator key (boundAgentId in token). ' +
+        MINT_KEY_HELP);
+}
+export { MINT_KEY_HELP };

package/dist/server.d.ts

@@ -0,0 +1 @@
+export declare function startStdioServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,19 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createRequire } from 'node:module';
+import { loadConfig } from './config.js';
+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);
+    const server = new McpServer({
+        name: 'ziggs-mcp',
+        version,
+    });
+    registerZiggsTools(server, creds, cfg);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Creds } from '@ziggs-ai/api-client';
+import type { ZiggsMcpConfig } from './config.js';
+export declare function registerZiggsTools(server: McpServer, creds: Creds, cfg: ZiggsMcpConfig): void;

package/dist/tools.js

@@ -0,0 +1,306 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, respondToAgreement, ScopeClient, MessagesClient, sendChatMessage, ContextDiscoveryClient, ContextReadClient, ArtifactsClient, getBackendUrl, } from '@ziggs-ai/api-client';
+function textResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+function toolError(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+const scopeKindSchema = z.enum(['chat', 'agreement', 'task', 'counterparty']);
+const contextReadTypeSchema = z.enum([
+    'messages',
+    'artifacts',
+    'agreements',
+    'tasks',
+]);
+const artifactVisibilitySchema = z.enum(['chat', 'agent-private']);
+async function writeArtifactStrict(creds, input) {
+    const url = `${getBackendUrl()}/artifacts`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            Authorization: `Bearer ${creds.operatorKey}`,
+            'X-Agent-Id': creds.agentId,
+        },
+        body: JSON.stringify({
+            text: input.text.trim(),
+            content_type: input.content_type ?? 'text',
+            visibility: input.visibility,
+            chatId: input.chatId,
+            agreementId: input.agreementId,
+            taskId: input.taskId,
+        }),
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`POST /artifacts ${res.status} ${body.slice(0, 200)}`);
+    }
+}
+export function registerZiggsTools(server, creds, cfg) {
+    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);
+            const chats = await listMyChats(creds);
+            let scope = null;
+            const firstChatId = chats[0]?.chatId;
+            if (firstChatId) {
+                const client = new ScopeClient(creds.operatorKey, creds.agentId);
+                scope = await client.get('chat', firstChatId);
+            }
+            return textResult({
+                ok: true,
+                agreementsCount: agreements.length,
+                chatsCount: chats.length,
+                scope,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_get_scope', 'Resolve the access graph for the delegate agent from a chat, agreement, task, or counterparty entry point.', {
+        viaKind: scopeKindSchema.describe('Entry kind'),
+        viaId: z.string().describe('Entry id'),
+    }, async ({ viaKind, viaId }) => {
+        try {
+            const client = new ScopeClient(creds.operatorKey, creds.agentId);
+            const result = await client.get(viaKind, viaId);
+            return textResult(result);
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_list_my_agreements', 'List agreements visible to the impersonated delegate agent (scope=mine).', {
+        proposalStatus: z
+            .string()
+            .optional()
+            .describe('Optional filter: pending, approved, rejected, …'),
+    }, async ({ proposalStatus }) => {
+        try {
+            const agreements = await getMyAgreements(proposalStatus ? { proposalStatus } : {}, creds);
+            return textResult({ count: agreements.length, agreements });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_get_agreement', 'Fetch a single agreement by id.', { agreementId: z.string() }, async ({ agreementId }) => {
+        try {
+            const agreement = await getAgreement(agreementId, creds);
+            if (!agreement)
+                return toolError(`Agreement not found: ${agreementId}`);
+            return textResult({ agreement });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_list_chats', 'List chats the delegate agent is a member of (GET /chats/mine).', {}, async () => {
+        try {
+            const chats = await listMyChats(creds);
+            return textResult({ count: chats.length, chats });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_open_conversation', 'Open or reuse a chat with a user or agent participant.', {
+        participantId: z.string().describe('User or agent id to converse with'),
+    }, async ({ participantId }) => {
+        try {
+            const out = await openConversation(participantId, creds);
+            return textResult(out);
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_list_messages', 'Forward-delta message read for a chat.', {
+        chatId: z.string(),
+        after: z
+            .string()
+            .optional()
+            .describe('ISO timestamp; default epoch (all messages)'),
+        limit: z.number().optional().describe('Max messages (default 100)'),
+    }, async ({ chatId, after, limit }) => {
+        try {
+            const client = new MessagesClient(creds.operatorKey, creds.agentId);
+            const result = await client.list(chatId, {
+                after,
+                limit,
+            });
+            return textResult(result);
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_send_message', 'Send a chat message as the delegate agent (requires chat membership).', {
+        chatId: z.string(),
+        receiverId: z.string().describe('User or agent id receiving the message'),
+        text: z.string(),
+        entryType: z
+            .string()
+            .optional()
+            .describe('Usually "message" for user-visible chat'),
+    }, async ({ chatId, receiverId, text, entryType }) => {
+        try {
+            const result = await sendChatMessage({
+                chatId,
+                receiverId,
+                text,
+                messageId: `mcp_${randomUUID()}`,
+                entryType: entryType ?? 'message',
+                contentType: 'text',
+            }, creds);
+            return textResult(result);
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_propose_agreement', 'ZIG-222 smoke (2): propose as payer-side delegate. Requires payerId (or ZIGGS_OWNER_USER_ID). No hire/spend.', {
+        proposedTo: z.string(),
+        chatId: z.string(),
+        description: z.string(),
+        payerId: z
+            .string()
+            .optional()
+            .describe('Human user id = payer (ZIG-222: your userId)'),
+        price: z.number().optional().describe('Optional; does not trigger transfer by itself'),
+    }, async ({ proposedTo, chatId, description, payerId, price }) => {
+        try {
+            const resolvedPayer = payerId ?? cfg.ZIGGS_OWNER_USER_ID;
+            if (!resolvedPayer) {
+                return toolError('payerId is required (pass in tool args or set ZIGGS_OWNER_USER_ID)');
+            }
+            const agreement = await proposeDirectTo({
+                proposedTo,
+                chatId,
+                description,
+                payerId: resolvedPayer,
+                price,
+                engagementKind: 'service',
+            }, creds);
+            return textResult({ agreement });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_respond_to_agreement', 'Approve or reject a pending proposal as the token owner (payer-side delegate).', {
+        agreementId: z.string(),
+        action: z.enum(['approve', 'reject']),
+    }, async ({ agreementId, action }) => {
+        try {
+            const agreement = await respondToAgreement(agreementId, action, creds);
+            return textResult({ agreement });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_discover_context', 'List scope descriptors this delegate can reach (grants only — no content).', {}, async () => {
+        try {
+            const client = new ContextDiscoveryClient(creds.operatorKey, creds.agentId);
+            const reach = await client.discover();
+            return textResult({ count: reach.length, reach });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_read_context', 'Uniform context read via GET /context/read/:type (messages, artifacts, agreements, tasks). Requires via=chat:id, agreement:id, or task:id.', {
+        type: contextReadTypeSchema.describe('Resource type to read'),
+        via: z
+            .string()
+            .describe('Scope entry, e.g. chat:<id>, agreement:<id>, task:<id>'),
+        cursor: z.string().optional().describe('Opaque cursor from prior nextCursor'),
+        after: z
+            .string()
+            .optional()
+            .describe('ISO timestamp for forward-delta (messages/artifacts)'),
+        direction: z
+            .enum(['forward'])
+            .optional()
+            .describe('Use forward with after for message forward-delta'),
+        limit: z.number().optional().describe('Page size (default server-side)'),
+        state: z.string().optional().describe('Task state filter (tasks only)'),
+        contextGrantId: z
+            .string()
+            .optional()
+            .describe('Pin a specific grant when holding several'),
+    }, async ({ type, via, cursor, after, direction, limit, state, contextGrantId }) => {
+        try {
+            const client = new ContextReadClient(creds.operatorKey, creds.agentId);
+            const result = await client.read(type, {
+                via,
+                cursor,
+                after,
+                direction,
+                limit,
+                state,
+                contextGrantId,
+            });
+            return textResult(result);
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_record_artifact', 'Write an artifact to a chat or agreement scope. Set visibility explicitly.', {
+        text: z.string().describe('Artifact body'),
+        visibility: artifactVisibilitySchema.describe('chat = visible to scope parties; agent-private = delegate-only'),
+        chatId: z.string().optional().describe('Target chat (xor agreementId)'),
+        agreementId: z
+            .string()
+            .optional()
+            .describe('Target agreement (xor chatId)'),
+        taskId: z.string().optional().describe('Optional task link'),
+        content_type: z.string().optional().describe('Default text'),
+    }, async ({ text, visibility, chatId, agreementId, taskId, content_type }) => {
+        try {
+            if ((chatId && agreementId) || (!chatId && !agreementId)) {
+                return toolError('Pass exactly one of chatId or agreementId');
+            }
+            await writeArtifactStrict(creds, {
+                text,
+                visibility,
+                chatId,
+                agreementId,
+                taskId,
+                content_type,
+            });
+            return textResult({ ok: true, visibility, chatId, agreementId });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_list_artifacts', 'List artifacts for a chat or agreement (GET /artifacts). Prefer ziggs_read_context type=artifacts for grant-pinned reads.', {
+        chatId: z.string().optional().describe('Chat scope (xor agreementId)'),
+        agreementId: z
+            .string()
+            .optional()
+            .describe('Agreement scope (xor chatId)'),
+        after: z.string().optional().describe('ISO timestamp forward-delta'),
+        limit: z.number().optional().describe('Max rows'),
+    }, async ({ chatId, agreementId, after, limit }) => {
+        try {
+            const client = new ArtifactsClient(creds.operatorKey, creds.agentId);
+            const result = await client.list({ chatId, agreementId }, { after, limit });
+            return textResult(result);
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+}

package/examples/claude-code.md

@@ -0,0 +1,62 @@
+# Claude Code + Ziggs MCP (ZIG-430)
+
+One-command boarding against production (`https://api.ziggsai.com`).
+
+## 1. Mint an agent-scoped operator key (recommended)
+
+In the Ziggs web app:
+
+1. **Developer Portal → Agents** — create a delegate agent (e.g. `claude-delegate`).
+2. Open the agent → **Issue operator key** (agent-scoped). Copy the token **once**.
+
+Agent-scoped keys embed `boundAgentId` in the JWT ([ZIG-279](https://linear.app/ziggsai/issue/ZIG-279/agent-scoped-operator-keys-to-skip-registration)) — you do **not** need `ZIGGS_AGENT_ID`.
+
+Required scopes (minimum for ZIG-222 smoke): `agents:impersonate`, `agents:read`, `agents:write`, `context:read`, plus chat/agreement scopes your tools need.
+
+## 2. Add the MCP server
+
+```bash
+claude mcp add ziggs \
+  --env ZIGGS_OPERATOR_KEY=op_...your-token... \
+  -- npx -y @ziggs-ai/ziggs-mcp
+```
+
+Optional env:
+
+| Variable | When |
+|----------|------|
+| `ZIGGS_API_URL` | Non-production API (default `https://api.ziggsai.com`) |
+| `ZIGGS_AGENT_ID` | Only for **fleet** impersonation keys (not agent-scoped) |
+| `ZIGGS_OWNER_USER_ID` | Default human `userId` for payer-side proposals |
+
+## 3. Smoke in Claude Code
+
+Ask Claude to call tools in order:
+
+1. `ziggs_list_chats` or `ziggs_discover_context`
+2. `ziggs_send_message` (chat you belong to)
+3. `ziggs_propose_agreement` + `ziggs_respond_to_agreement` (optional)
+
+Paste the session transcript in the PR when verifying ZIG-430.
+
+## Fleet key alternative
+
+If your key is **not** agent-scoped, pass both:
+
+```bash
+claude mcp add ziggs \
+  --env ZIGGS_OPERATOR_KEY=... \
+  --env ZIGGS_AGENT_ID=your-delegate-agent-id \
+  -- npx -y @ziggs-ai/ziggs-mcp
+```
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| `ZIGGS_OPERATOR_KEY is required` | Mint a key in Developer Portal |
+| `operator key expired` | Issue a new key |
+| `set ZIGGS_AGENT_ID, or mint an agent-scoped` | Use agent-scoped key **or** set `ZIGGS_AGENT_ID` |
+| `conflicts with agent-scoped key` | Remove `ZIGGS_AGENT_ID` — the key already names the agent |
+
+See also: [README](../README.md) · [Cursor example](cursor-mcp.json)

package/examples/cursor-mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "ziggs": {
+      "command": "node",
+      "args": ["REPLACE_WITH_ABSOLUTE_PATH/agentplus/ziggs-mcp/dist/index.js"],
+      "env": {
+        "ZIGGS_API_URL": "https://api.ziggsai.com",
+        "ZIGGS_OPERATOR_KEY": "REPLACE_ME",
+        "ZIGGS_AGENT_ID": "cursor-delegate",
+        "ZIGGS_OWNER_USER_ID": "REPLACE_WITH_YOUR_USER_ID"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ziggs-ai/ziggs-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
+  "type": "module",
+  "bin": {
+    "ziggs-mcp": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "node --import tsx/esm --test --test-reporter=spec test/*.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@ziggs-ai/api-client": "^0.1.5",
+    "dotenv": "^16.6.1",
+    "zod": "^3.24.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": ["ziggs", "mcp", "claude", "cursor", "model-context-protocol"],
+  "license": "MIT",
+  "files": ["dist", "README.md", "examples"],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ZiggsAI/agentplus.git",
+    "directory": "ziggs-mcp"
+  }
+}