@ziggs-ai/ziggs-mcp 0.3.1 → 0.4.0

package/README.md

@@ -208,7 +208,7 @@ OP_KEY_A=... AGENT_A=... USER_B=... OP_KEY_B=... AGENT_B=... \
 | `ziggs_revoke_agreement` | `DELETE /agreements/:id` — any agreement (hire/service/quest/link) |
 | `ziggs_smoke_impersonation` | [Internal/debug] connectivity check — only when `ZIGGS_MCP_DEBUG=1`; not part of normal delegate workflow |
 | `ziggs_context_snapshot` | `GET /context/snapshot?via=chat:` — one-shot chat orientation (history + agreements + roster), grant-fenced |
-| `ziggs_list_my_agreements` | `GET /agreements?scope=mine` |
+| `ziggs_list_my_agreements` | `GET /agreements?scope=mine&partyOnly=true` — agreements you are a party to; `scope: "reachable"` drops `partyOnly` for every agreement your grant can read |
 | `ziggs_get_agreement` | `GET /agreements/:id` |
 | `ziggs_list_chats` | `GET /chats/mine` |
 | `ziggs_open_conversation` | `POST /chats` |

package/dist/capabilityAdapter.d.ts

@@ -0,0 +1,25 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ZodRawShape } from 'zod';
+import type { CapabilityDefinition, CapabilityParam, Creds } from '@ziggs-ai/api-client';
+/** One JSON text-content result shape for every MCP tool (was copied 3×). */
+export declare function textResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function toZodShape(params: Record<string, CapabilityParam>): ZodRawShape;
+export interface RegisterCapabilityOptions {
+    /** Web-app origin for human-facing URLs (claim links etc.). */
+    webUrl?: string;
+    /**
+     * Description override for wording assembled from MCP-local shared consts
+     * (e.g. the delegate-protocol reporting rule, ZIG-557) — schema and handler
+     * still come from the shared definition.
+     */
+    description?: string;
+    /** Surface-local response decoration (e.g. the read-plan on ziggs_read_context). */
+    transformResult?: (result: unknown, args: Record<string, unknown>) => unknown;
+}
+export declare function registerCapability(server: McpServer, cap: CapabilityDefinition, creds: Creds, opts?: RegisterCapabilityOptions): void;
+export declare function registerCapabilities(server: McpServer, caps: CapabilityDefinition[], creds: Creds, opts?: RegisterCapabilityOptions): void;

package/dist/capabilityAdapter.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { toolError } from './toolError.js';
+/** One JSON text-content result shape for every MCP tool (was copied 3×). */
+export function textResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * ZIG-956 — the MCP surface adapter for shared capability definitions
+ * (api-client `capabilities/`). Lowers the neutral param DSL to zod v3 (the
+ * MCP SDK's ZodRawShape; api-client itself carries no zod, and agent-sdk is on
+ * zod v4, so the schema is defined once and lowered per surface).
+ */
+function zodParam(param) {
+    let t;
+    switch (param.type) {
+        case 'string':
+            t = param.enum ? z.enum(param.enum) : z.string();
+            break;
+        case 'number':
+            t = z.number();
+            break;
+        case 'boolean':
+            t = z.boolean();
+            break;
+        case 'object':
+            t = z.record(z.unknown());
+            break;
+        case 'array': {
+            const items = param.items;
+            const inner = items?.type === 'string'
+                ? items.enum
+                    ? z.enum(items.enum)
+                    : z.string()
+                : z.record(z.unknown());
+            t = z.array(inner);
+            break;
+        }
+    }
+    if (param.description)
+        t = t.describe(param.description);
+    if (!param.required)
+        t = t.optional();
+    return t;
+}
+export function toZodShape(params) {
+    const shape = {};
+    for (const [name, param] of Object.entries(params)) {
+        shape[name] = zodParam(param);
+    }
+    return shape;
+}
+export function registerCapability(server, cap, creds, opts = {}) {
+    const annotations = cap.annotation === 'read-only'
+        ? READ_ONLY
+        : cap.annotation === 'destructive'
+            ? DESTRUCTIVE
+            : WRITE;
+    server.tool(cap.names.mcp, opts.description ?? cap.descriptions.mcp, toZodShape(cap.params), annotations, async (args) => {
+        try {
+            const env = { creds, webUrl: opts.webUrl, surface: 'mcp' };
+            const result = await cap.handler(args, env);
+            return textResult(opts.transformResult ? opts.transformResult(result, args) : result);
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+}
+export function registerCapabilities(server, caps, creds, opts = {}) {
+    for (const cap of caps)
+        registerCapability(server, cap, creds, opts);
+}

package/dist/config.d.ts

@@ -12,6 +12,12 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_OWNER_USER_ID: z.ZodOptional<z.ZodString>;
     /** Set to 1/true/yes to register internal/debug-only MCP tools (ZIG-672). */
     ZIGGS_MCP_DEBUG: z.ZodOptional<z.ZodString>;
+    /**
+     * Set to 1/true/yes to register only the core everyday/session-start tools,
+     * skipping the heavy groups (payments, links, marketplace, connections) to
+     * cut cold-start deferred-loading (ZIG-941 #7). Unset = all tools register.
+     */
+    ZIGGS_MCP_CORE_ONLY: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     ZIGGS_OPERATOR_KEY: string;
     ZIGGS_API_URL?: string | undefined;
@@ -20,6 +26,7 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_AGENT_ID?: string | undefined;
     ZIGGS_OWNER_USER_ID?: string | undefined;
     ZIGGS_MCP_DEBUG?: string | undefined;
+    ZIGGS_MCP_CORE_ONLY?: string | undefined;
 }, {
     ZIGGS_OPERATOR_KEY: string;
     ZIGGS_API_URL?: string | undefined;
@@ -28,6 +35,7 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_AGENT_ID?: string | undefined;
     ZIGGS_OWNER_USER_ID?: string | undefined;
     ZIGGS_MCP_DEBUG?: string | undefined;
+    ZIGGS_MCP_CORE_ONLY?: string | undefined;
 }>;
 type EnvConfig = z.infer<typeof envSchema>;
 export interface ZiggsMcpConfig extends EnvConfig {
@@ -35,6 +43,11 @@ export interface ZiggsMcpConfig extends EnvConfig {
     resolvedAgentId: string;
     /** When true, register internal/debug-only tools such as ziggs_smoke_impersonation. */
     debugTools: boolean;
+    /**
+     * When true, register only the core everyday/session-start tool tier and skip
+     * the heavy groups (payments, links, marketplace, connections) — ZIG-941 #7.
+     */
+    coreOnly: boolean;
 }
 /** Load delegate credentials from the environment (ZIG-222 / ZIG-430). */
 export declare function loadConfig(): ZiggsMcpConfig;

package/dist/config.js

@@ -13,8 +13,15 @@ const envSchema = z.object({
     ZIGGS_OWNER_USER_ID: z.string().optional(),
     /** Set to 1/true/yes to register internal/debug-only MCP tools (ZIG-672). */
     ZIGGS_MCP_DEBUG: z.string().optional(),
+    /**
+     * Set to 1/true/yes to register only the core everyday/session-start tools,
+     * skipping the heavy groups (payments, links, marketplace, connections) to
+     * cut cold-start deferred-loading (ZIG-941 #7). Unset = all tools register.
+     */
+    ZIGGS_MCP_CORE_ONLY: z.string().optional(),
 });
-function parseDebugToolsFlag(raw) {
+/** Parse a truthy env flag (1/true/yes) — shared by ZIGGS_MCP_DEBUG and ZIGGS_MCP_CORE_ONLY. */
+function parseBoolFlag(raw) {
     if (!raw)
         return false;
     const v = raw.trim().toLowerCase();
@@ -30,6 +37,7 @@ export function loadConfig() {
         ZIGGS_AGENT_ID: process.env.ZIGGS_AGENT_ID,
         ZIGGS_OWNER_USER_ID: process.env.ZIGGS_OWNER_USER_ID,
         ZIGGS_MCP_DEBUG: process.env.ZIGGS_MCP_DEBUG,
+        ZIGGS_MCP_CORE_ONLY: process.env.ZIGGS_MCP_CORE_ONLY,
     };
     const parsed = envSchema.safeParse(raw);
     if (!parsed.success) {
@@ -49,6 +57,7 @@ export function loadConfig() {
     return {
         ...parsed.data,
         resolvedAgentId,
-        debugTools: parseDebugToolsFlag(parsed.data.ZIGGS_MCP_DEBUG),
+        debugTools: parseBoolFlag(parsed.data.ZIGGS_MCP_DEBUG),
+        coreOnly: parseBoolFlag(parsed.data.ZIGGS_MCP_CORE_ONLY),
     };
 }

package/dist/connectionCreds.js

@@ -24,6 +24,7 @@ export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId) {
         ZIGGS_OWNER_USER_ID: ownerUserId,
         resolvedAgentId,
         debugTools: false,
+        coreOnly: false,
     };
     return {
         creds: { operatorKey: bearer, agentId: resolvedAgentId },

package/dist/paymentTools.d.ts

@@ -1,13 +1,14 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Creds } from '@ziggs-ai/api-client';
 /**
- * ZIG-896 — the wallet toolset on the MCP surface, same base names as the SDK's
- * PAYMENT_TOOLS (payment_* → ziggs_payment_*), riding the shared PaymentsClient
- * (ZIG-894). Safety is unchanged: money-moving calls are policy-gated
- * server-side (transfers above threshold return `approval_required`; the human
- * decides on the wallet page — surfaced by ziggs_pending_decisions), and rails
- * stay gated by the operator key's payments scopes. There is deliberately NO
- * approve/decide tool on either agent surface — an agent must not approve its
- * own spend.
+ * ZIG-896 / ZIG-956 — the wallet toolset on the MCP surface, same base names
+ * as the SDK's PAYMENT_TOOLS (payment_* → ziggs_payment_*), now registered
+ * from the shared capability definitions in api-client (one schema + handler,
+ * two thin surface adapters). Safety is unchanged: money-moving calls are
+ * policy-gated server-side (transfers above threshold return
+ * `approval_required`; the human decides on the wallet page — surfaced by
+ * ziggs_pending_decisions), and rails stay gated by the operator key's
+ * payments scopes. There is deliberately NO approve/decide tool on either
+ * agent surface — an agent must not approve its own spend.
  */
 export declare function registerPaymentTools(server: McpServer, creds: Creds): void;

package/dist/paymentTools.js

@@ -1,252 +1,16 @@
-import { z } from 'zod';
-import { PaymentsClient } from '@ziggs-ai/api-client';
-import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
-import { toolError } from './toolError.js';
-function textResult(data) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-    };
-}
-function buildCaveats(args) {
-    const caveats = [];
-    if (args.maxAmount != null)
-        caveats.push({ type: 'max_amount', value: args.maxAmount });
-    if (args.dailyBudget != null)
-        caveats.push({ type: 'daily_budget', value: args.dailyBudget });
-    if (args.allowedRecipients != null)
-        caveats.push({ type: 'allowed_recipients', value: args.allowedRecipients });
-    if (args.expiresInSeconds != null)
-        caveats.push({ type: 'expires_at', value: Date.now() + args.expiresInSeconds * 1000 });
-    return caveats;
-}
+import { PAYMENT_CAPABILITIES } from '@ziggs-ai/api-client';
+import { registerCapabilities } from './capabilityAdapter.js';
 /**
- * ZIG-896 — the wallet toolset on the MCP surface, same base names as the SDK's
- * PAYMENT_TOOLS (payment_* → ziggs_payment_*), riding the shared PaymentsClient
- * (ZIG-894). Safety is unchanged: money-moving calls are policy-gated
- * server-side (transfers above threshold return `approval_required`; the human
- * decides on the wallet page — surfaced by ziggs_pending_decisions), and rails
- * stay gated by the operator key's payments scopes. There is deliberately NO
- * approve/decide tool on either agent surface — an agent must not approve its
- * own spend.
+ * ZIG-896 / ZIG-956 — the wallet toolset on the MCP surface, same base names
+ * as the SDK's PAYMENT_TOOLS (payment_* → ziggs_payment_*), now registered
+ * from the shared capability definitions in api-client (one schema + handler,
+ * two thin surface adapters). Safety is unchanged: money-moving calls are
+ * policy-gated server-side (transfers above threshold return
+ * `approval_required`; the human decides on the wallet page — surfaced by
+ * ziggs_pending_decisions), and rails stay gated by the operator key's
+ * payments scopes. There is deliberately NO approve/decide tool on either
+ * agent surface — an agent must not approve its own spend.
  */
 export function registerPaymentTools(server, creds) {
-    const client = () => new PaymentsClient(creds.operatorKey, creds.agentId);
-    server.tool('ziggs_payment_balance', "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds.", {}, READ_ONLY, async () => {
-        try {
-            return textResult(await client().balance());
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_resolve_wallet', 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.', {
-        userId: z.string().optional().describe('User to resolve'),
-        agentId: z.string().optional().describe('Agent to resolve'),
-    }, READ_ONLY, async ({ userId, agentId }) => {
-        if (!userId && !agentId) {
-            return toolError('Provide userId or agentId to resolve a wallet');
-        }
-        try {
-            const wallet = (await client().resolve({ userId, agentId }));
-            return textResult({
-                walletId: wallet?.['walletId'] || null,
-                ownerId: wallet?.['ownerId'] || null,
-                currency: wallet?.['currency'] || 'pez',
-                status: wallet?.['status'] || null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_transfer', 'Transfer funds to another wallet. Amounts are integer cents. As a delegate you spend under a payment grant the wallet owner issued (paymentGrantId — find yours via ziggs_list_grants scopeKind=wallet). Transfers above the owner\'s policy pause with status "approval_required": the human approves on the wallet page (it also shows in ziggs_pending_decisions) — you can wait inline with ziggs_payment_wait_for_approval, and you must NEVER approve your own transfer.', {
-        toWalletId: z
-            .string()
-            .describe('Destination wal_... id — or a userId/agentId to auto-resolve'),
-        amount: z.number().describe('Amount in integer cents, > 0'),
-        description: z.string().optional().describe('Human-readable transfer memo'),
-        idempotencyKey: z
-            .string()
-            .optional()
-            .describe('Client-supplied key to make retries safe (auto-generated when omitted)'),
-        paymentGrantId: z
-            .string()
-            .optional()
-            .describe('Payment grant to spend under (required for agent-impersonated transfers)'),
-    }, WRITE, async ({ toWalletId, amount, description, idempotencyKey, paymentGrantId }) => {
-        if (!amount || amount <= 0)
-            return toolError('amount must be positive');
-        try {
-            const result = (await client().transfer({
-                to: toWalletId,
-                amount: Math.round(amount),
-                description: description || 'Agent-initiated transfer',
-                idempotencyKey,
-                paymentGrantId,
-            }));
-            if (result['status'] === 'approval_required') {
-                return textResult({
-                    status: 'approval_required',
-                    approvalId: result['approvalId'] || null,
-                    expiresAt: result['expiresAt'] || null,
-                    reason: result['reason'] || null,
-                    amount,
-                    toWalletId: result['toWalletId'],
-                    note: 'Transfer paused: the wallet owner must approve this amount on the wallet page (also listed by ziggs_pending_decisions). Tell the human now (pull-only MCP has no push). ' +
-                        'Wait inline with ziggs_payment_wait_for_approval when you expect a quick decision (≤2 min).',
-                });
-            }
-            return textResult({
-                status: 'transferred',
-                transactionId: result['transactionId'] || null,
-                amount,
-                toWalletId: result['toWalletId'],
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_wait_for_approval', 'Poll a paused transfer (status "approval_required") until the human decides or the timeout passes. Returns executed | rejected | expired | timeout | gone. Use for quick decisions (≤2 min); for longer waits, stop and check again next session.', {
-        approvalId: z.string().describe('Approval to wait on (from ziggs_payment_transfer)'),
-        timeoutMs: z.number().optional().describe('Max wait, default 120000'),
-        pollMs: z.number().optional().describe('Poll interval, default 3000 (min 500)'),
-    }, READ_ONLY, async ({ approvalId, timeoutMs, pollMs }) => {
-        try {
-            const result = (await client().waitForApproval(approvalId, {
-                timeoutMs,
-                pollMs,
-            }));
-            return textResult({
-                status: result['status'],
-                approvalId,
-                transactionId: result['transactionId'] || null,
-                approval: result['approval'] || null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_hold', "Pre-authorize (escrow) funds without moving them. Use to reserve payment at agreement formation; release with ziggs_payment_release once work is complete, or refund if it's cancelled.", {
-        amount: z.number().describe('Amount in integer cents, > 0'),
-        description: z.string().optional().describe('Human-readable hold memo'),
-        idempotencyKey: z.string().optional().describe('Client-supplied retry-safety key'),
-    }, WRITE, async ({ amount, description, idempotencyKey }) => {
-        if (!amount || amount <= 0)
-            return toolError('amount must be positive');
-        try {
-            const result = (await client().hold({
-                amount: Math.round(amount),
-                description: description || 'Agent escrow hold',
-                idempotencyKey,
-            }));
-            return textResult({
-                status: 'held',
-                transactionId: result['transaction']?.['transactionId'] || null,
-                amount,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_release', "Settle or refund an escrow hold. action='complete' transfers held funds to toWalletId (work done); action='refund' returns funds to the sender (work cancelled).", {
-        holdId: z.string().describe('Hold to settle (transactionId from ziggs_payment_hold)'),
-        action: z.enum(['complete', 'refund']).describe('complete = pay out, refund = return'),
-        toWalletId: z
-            .string()
-            .optional()
-            .describe('Destination wallet — required when action=complete'),
-        idempotencyKey: z.string().optional().describe('Client-supplied retry-safety key'),
-    }, WRITE, async ({ holdId, action, toWalletId, idempotencyKey }) => {
-        if (action === 'complete' && !toWalletId) {
-            return toolError('toWalletId is required when action=complete');
-        }
-        try {
-            const result = (await client().release({
-                holdId,
-                action,
-                toWalletId,
-                idempotencyKey,
-            }));
-            return textResult({
-                status: action === 'complete' ? 'settled' : 'refunded',
-                transactionId: result['transaction']?.['transactionId'] || null,
-                holdId,
-                action,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    const grantCaveatArgs = {
-        maxAmount: z.number().optional().describe('Per-transfer ceiling in cents'),
-        dailyBudget: z.number().optional().describe('Rolling daily budget in cents'),
-        allowedRecipients: z
-            .array(z.string())
-            .optional()
-            .describe('Wallet ids the holder may pay'),
-        expiresInSeconds: z.number().optional().describe('Grant lifetime from now'),
-    };
-    server.tool('ziggs_payment_issue_grant', "Issue a payment grant delegating bounded spend from the operator's wallet to an agent holder. Caveats bound what the holder can do (max_amount, daily_budget, allowed_recipients, expiry). The holder spends by passing the grantId as paymentGrantId on transfers.", {
-        holderId: z.string().describe('Agent that will hold the grant'),
-        ...grantCaveatArgs,
-    }, WRITE, async ({ holderId, ...caveatArgs }) => {
-        try {
-            const caveats = buildCaveats(caveatArgs);
-            const result = (await client().issueGrant({ holderId, caveats }));
-            const grant = result['grant'];
-            return textResult({
-                grantId: grant?.['grantId'] || null,
-                holderId: grant?.['holderId'] || holderId,
-                caveats: grant?.['caveats'] || caveats,
-                expiresAt: grant?.['expiresAt'] || null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_attenuate_grant', 'Re-delegate a payment grant you hold to another agent with TIGHTER caveats (narrowing only — the child can never exceed the parent). Use to pass a bounded spend slice to a sub-agent.', {
-        grantId: z.string().describe('Parent grant to attenuate'),
-        holderId: z.string().describe('Agent that will hold the narrowed grant'),
-        ...grantCaveatArgs,
-    }, WRITE, async ({ grantId, holderId, ...caveatArgs }) => {
-        try {
-            const caveats = buildCaveats(caveatArgs);
-            const result = (await client().attenuateGrant({
-                grantId,
-                holderId,
-                caveats,
-            }));
-            const grant = result['grant'];
-            return textResult({
-                grantId: grant?.['grantId'] || null,
-                parentGrantId: grant?.['parentGrantId'] || grantId,
-                holderId: grant?.['holderId'] || holderId,
-                caveats: grant?.['caveats'] || caveats,
-                expiresAt: grant?.['expiresAt'] || null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_revoke_grant', 'Revoke a payment grant (and its attenuated children). The holder can no longer spend under it.', {
-        grantId: z.string().describe('Grant to revoke'),
-    }, DESTRUCTIVE, async ({ grantId }) => {
-        try {
-            const result = (await client().revokeGrant(grantId));
-            return textResult({
-                status: 'revoked',
-                grantId,
-                revoked: result?.['revoked'] ?? null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    registerCapabilities(server, PAYMENT_CAPABILITIES, creds);
 }