@ziggs-ai/ziggs-mcp 0.1.24 → 0.1.25

package/dist/pendingDecisions.d.ts

@@ -1,17 +1,22 @@
 import type { InboxEnvelope, Task } from '@ziggs-ai/api-client';
-export type PendingDecisionKind = 'proposal' | 'link_request';
+export type PendingDecisionKind = 'proposal' | 'link_request' | 'mcp_server_request';
 export interface PendingDecisionItem {
     kind: PendingDecisionKind;
+    /** Agreement id for proposals; requestId for link / MCP server requests. */
     agreementId: string;
     title: string;
     subtitle: string | null;
     proposedAt: string | null;
     proposedAtLabel: string | null;
     appUrl: string;
-    respondApprove: string;
-    respondReject: string;
-    sayApprove: string;
-    sayReject: string;
+    /**
+     * Null for mcp_server_request — connecting a server (OAuth) happens in the
+     * browser at /app/settings/connections; there is no MCP respond tool.
+     */
+    respondApprove: string | null;
+    respondReject: string | null;
+    sayApprove: string | null;
+    sayReject: string | null;
 }
 export interface ActiveWorkItem {
     taskId: string;
@@ -26,11 +31,14 @@ export interface ActiveWorkItem {
 export declare function resolveWebAppOrigin(webUrl?: string | null): string;
 export declare function agreementAppUrl(origin: string, agreementId: string): string;
 export declare function agreementsListAppUrl(origin: string): string;
+/** Where the human connects MCP servers and grants tools (ZIG-686). */
+export declare function connectionsSettingsAppUrl(origin: string): string;
 export declare function buildPendingDecisionItems(inbox: InboxEnvelope, webOrigin: string): PendingDecisionItem[];
 export declare function buildActiveWorkItems(tasks: Task[], webOrigin: string): ActiveWorkItem[];
 export declare function buildDecisionChatCard(items: PendingDecisionItem[], opts: {
     truncatedProposals?: number;
     truncatedConnectionRequests?: number;
+    truncatedMcpServerRequests?: number;
     agreementsListAppUrl?: string;
 }): string;
 export declare function buildWorkChatCard(work: ActiveWorkItem[], listUrl?: string): string;
@@ -38,6 +46,7 @@ export declare function buildWorkChatCard(work: ActiveWorkItem[], listUrl?: stri
 export declare function buildSessionChatCard(decisions: PendingDecisionItem[], work: ActiveWorkItem[], opts: {
     truncatedProposals?: number;
     truncatedConnectionRequests?: number;
+    truncatedMcpServerRequests?: number;
     agreementsListAppUrl?: string;
 }): string;
 /** Structured session payload for MCP tools (ZIG-625 + active work). */

package/dist/pendingDecisions.js

@@ -9,6 +9,10 @@ export function agreementAppUrl(origin, agreementId) {
 export function agreementsListAppUrl(origin) {
     return `${origin}/app/agreements`;
 }
+/** Where the human connects MCP servers and grants tools (ZIG-686). */
+export function connectionsSettingsAppUrl(origin) {
+    return `${origin}/app/settings/connections`;
+}
 function truncateText(text, max = TITLE_MAX) {
     const oneLine = text.replace(/\s+/g, ' ').trim();
     if (oneLine.length <= max)
@@ -75,6 +79,23 @@ function linkToItem(c, origin) {
         sayReject: `reject link ${id}`,
     };
 }
+function mcpServerRequestToItem(r, origin) {
+    const tools = r.tools?.length ? r.tools.join(', ') : 'no tools listed';
+    const reason = r.reason?.trim() || null;
+    return {
+        kind: 'mcp_server_request',
+        agreementId: r.requestId,
+        title: truncateText(`Connect MCP server · ${r.serverUrl}`),
+        subtitle: truncateText(reason ? `${reason} — tools: ${tools}` : `Tools: ${tools}`, 160),
+        proposedAt: r.requestedAt,
+        proposedAtLabel: formatWhen(r.requestedAt),
+        appUrl: connectionsSettingsAppUrl(origin),
+        respondApprove: null,
+        respondReject: null,
+        sayApprove: null,
+        sayReject: null,
+    };
+}
 export function buildPendingDecisionItems(inbox, webOrigin) {
     const items = [];
     for (const p of inbox.proposalsAwaitingMe ?? []) {
@@ -83,6 +104,9 @@ export function buildPendingDecisionItems(inbox, webOrigin) {
     for (const c of inbox.connectionRequestsAwaitingMe ?? []) {
         items.push(linkToItem(c, webOrigin));
     }
+    for (const r of inbox.mcpServerRequestsAwaitingMe ?? []) {
+        items.push(mcpServerRequestToItem(r, webOrigin));
+    }
     return items;
 }
 export function buildActiveWorkItems(tasks, webOrigin) {
@@ -105,17 +129,26 @@ export function buildActiveWorkItems(tasks, webOrigin) {
     });
 }
 function kindLabel(kind) {
-    return kind === 'proposal' ? 'Agreement proposal' : 'Agent link request';
+    if (kind === 'proposal')
+        return 'Agreement proposal';
+    if (kind === 'link_request')
+        return 'Agent link request';
+    return 'MCP server request';
 }
 function kindHint(kind) {
-    return kind === 'proposal'
-        ? 'Someone proposed work or terms — your approval opens or rejects it.'
-        : 'Another agent wants to link — your approval enables cross-org reach.';
+    if (kind === 'proposal') {
+        return 'Someone proposed work or terms — your approval opens or rejects it.';
+    }
+    if (kind === 'link_request') {
+        return 'Another agent wants to link — your approval enables cross-org reach.';
+    }
+    return 'Your agent asks you to connect an MCP server and grant it the listed tools — connect (OAuth) or reject in the browser.';
 }
 function buildDecisionSection(items, opts) {
     const truncatedProposals = opts.truncatedProposals ?? 0;
     const truncatedConnectionRequests = opts.truncatedConnectionRequests ?? 0;
-    const truncated = truncatedProposals + truncatedConnectionRequests;
+    const truncatedMcpServerRequests = opts.truncatedMcpServerRequests ?? 0;
+    const truncated = truncatedProposals + truncatedConnectionRequests + truncatedMcpServerRequests;
     if (!items.length && truncated === 0)
         return [];
     const lines = [];
@@ -136,18 +169,27 @@ function buildDecisionSection(items, opts) {
             lines.push(`> ${item.subtitle}`);
         }
         lines.push('');
-        lines.push(`[Review in Ziggs →](${item.appUrl})`);
-        lines.push('');
-        lines.push('| You say in chat | What the agent runs |');
-        lines.push('|:----------------|:--------------------|');
-        lines.push(`| \`${item.sayApprove}\` | \`${item.respondApprove}\` |`);
-        lines.push(`| \`${item.sayReject}\` | \`${item.respondReject}\` |`);
+        if (item.sayApprove && item.respondApprove && item.sayReject && item.respondReject) {
+            lines.push(`[Review in Ziggs →](${item.appUrl})`);
+            lines.push('');
+            lines.push('| You say in chat | What the agent runs |');
+            lines.push('|:----------------|:--------------------|');
+            lines.push(`| \`${item.sayApprove}\` | \`${item.respondApprove}\` |`);
+            lines.push(`| \`${item.sayReject}\` | \`${item.respondReject}\` |`);
+        }
+        else {
+            // Browser-only decision (mcp_server_request): connecting a server runs
+            // OAuth consent — no MCP tool can approve it from chat.
+            lines.push(`[Connect or reject in Ziggs →](${item.appUrl})`);
+            lines.push('');
+            lines.push('_This one is decided in the browser — nothing to approve from chat._');
+        }
         lines.push('');
     }
     if (truncated > 0) {
         lines.push('---');
         lines.push('');
-        lines.push(`_+${truncated} more pending (${truncatedProposals} proposal(s), ${truncatedConnectionRequests} link(s)) — not listed here._`);
+        lines.push(`_+${truncated} more pending (${truncatedProposals} proposal(s), ${truncatedConnectionRequests} link(s), ${truncatedMcpServerRequests} MCP server request(s)) — not listed here._`);
         lines.push('');
     }
     return lines;
@@ -188,11 +230,13 @@ function buildWorkSection(work, startIndex = 1) {
 export function buildDecisionChatCard(items, opts) {
     const truncatedProposals = opts.truncatedProposals ?? 0;
     const truncatedConnectionRequests = opts.truncatedConnectionRequests ?? 0;
-    const truncated = truncatedProposals + truncatedConnectionRequests;
+    const truncatedMcpServerRequests = opts.truncatedMcpServerRequests ?? 0;
+    const truncated = truncatedProposals + truncatedConnectionRequests + truncatedMcpServerRequests;
     if (!items.length && truncated === 0)
         return '';
     const proposals = items.filter((i) => i.kind === 'proposal').length;
     const links = items.filter((i) => i.kind === 'link_request').length;
+    const mcpRequests = items.filter((i) => i.kind === 'mcp_server_request').length;
     const listedTotal = items.length + truncated;
     const lines = [
         `### 🔔 Ziggs — **${listedTotal}** ${listedTotal === 1 ? 'item needs' : 'items need'} your decision`,
@@ -201,9 +245,12 @@ export function buildDecisionChatCard(items, opts) {
         '|:--|--:|',
         `| Agreement proposals | **${proposals}** |`,
         `| Agent link requests | **${links}** |`,
+        ...(mcpRequests + truncatedMcpServerRequests > 0
+            ? [`| MCP server requests | **${mcpRequests}** |`]
+            : []),
         ...(truncated > 0 ? [`| _Not shown (inbox cap)_ | _+${truncated}_ |`] : []),
         '',
-        '> **Heads-up:** Ziggs MCP is pull-only — nothing pops up in Cursor until inbox is checked. **You** approve or reject in this chat; the agent calls `ziggs_respond_to_agreement` only after you say so.',
+        '> **Heads-up:** Ziggs MCP is pull-only — nothing pops up in Cursor until inbox is checked. **You** approve or reject in this chat; the agent calls `ziggs_respond_to_agreement` only after you say so. MCP server requests are the exception — those are connected or rejected in the browser.',
         '',
         ...buildDecisionSection(items, opts),
     ];
@@ -232,12 +279,15 @@ export function buildWorkChatCard(work, listUrl) {
 export function buildSessionChatCard(decisions, work, opts) {
     const truncatedProposals = opts.truncatedProposals ?? 0;
     const truncatedConnectionRequests = opts.truncatedConnectionRequests ?? 0;
-    const truncated = truncatedProposals + truncatedConnectionRequests;
+    const truncatedMcpServerRequests = opts.truncatedMcpServerRequests ?? 0;
+    const truncated = truncatedProposals + truncatedConnectionRequests + truncatedMcpServerRequests;
     const decisionListed = decisions.length + truncated;
     const workCount = work.length;
     const total = decisionListed + workCount;
     if (total === 0)
         return '';
+    const mcpRequestCount = decisions.filter((d) => d.kind === 'mcp_server_request').length +
+        truncatedMcpServerRequests;
     const lines = [
         `### 🔔 Ziggs — **${total}** ${total === 1 ? 'thing needs' : 'things need'} you`,
         '',
@@ -248,11 +298,16 @@ export function buildSessionChatCard(decisions, work, opts) {
                 `| Approve / reject | **${decisionListed}** |`,
                 `| — proposals | ${decisions.filter((d) => d.kind === 'proposal').length}${truncatedProposals ? ` (+${truncatedProposals} hidden)` : ''} |`,
                 `| — link requests | ${decisions.filter((d) => d.kind === 'link_request').length}${truncatedConnectionRequests ? ` (+${truncatedConnectionRequests} hidden)` : ''} |`,
+                ...(mcpRequestCount > 0
+                    ? [
+                        `| — MCP server requests | ${decisions.filter((d) => d.kind === 'mcp_server_request').length}${truncatedMcpServerRequests ? ` (+${truncatedMcpServerRequests} hidden)` : ''} |`,
+                    ]
+                    : []),
             ]
             : []),
         ...(workCount > 0 ? [`| Active tasks (your work) | **${workCount}** |`] : []),
         '',
-        '> **Heads-up:** MCP is pull-only — check at session start. **Decisions:** you say approve/reject. **Tasks:** say `work on <taskId>` — the agent implements and reports on Ziggs.',
+        '> **Heads-up:** MCP is pull-only — check at session start. **Decisions:** you say approve/reject (MCP server requests are connected in the browser instead). **Tasks:** say `work on <taskId>` — the agent implements and reports on Ziggs.',
         '',
     ];
     let sectionIndex = 1;
@@ -275,13 +330,18 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
     const activeWork = buildActiveWorkItems(opts?.activeTasks ?? [], webOrigin);
     const truncatedProposals = inbox.truncatedProposals ?? 0;
     const truncatedConnectionRequests = inbox.truncatedConnectionRequests ?? 0;
-    const pendingCount = decisions.length + truncatedProposals + truncatedConnectionRequests;
+    const truncatedMcpServerRequests = inbox.truncatedMcpServerRequests ?? 0;
+    const pendingCount = decisions.length +
+        truncatedProposals +
+        truncatedConnectionRequests +
+        truncatedMcpServerRequests;
     const activeWorkCount = activeWork.length;
     const actionCount = pendingCount + activeWorkCount;
     const listUrl = agreementsListAppUrl(webOrigin);
     const cardOpts = {
         truncatedProposals,
         truncatedConnectionRequests,
+        truncatedMcpServerRequests,
         agreementsListAppUrl: listUrl,
     };
     const decisionChatCard = buildDecisionChatCard(decisions, cardOpts);
@@ -289,6 +349,7 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
     const sessionChatCard = buildSessionChatCard(decisions, activeWork, cardOpts);
     const proposalCount = decisions.filter((d) => d.kind === 'proposal').length;
     const linkCount = decisions.filter((d) => d.kind === 'link_request').length;
+    const mcpServerRequestCount = decisions.filter((d) => d.kind === 'mcp_server_request').length;
     const instruction = actionCount > 0
         ? 'Paste sessionChatCard at the top of your reply. Decisions: wait for explicit approve/reject before ziggs_respond_to_agreement. Tasks: when the human says work on <taskId>, read context and implement.'
         : 'No pending decisions or active tasks — continue with ziggs_inbox for scope news.';
@@ -302,15 +363,20 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
         summary: {
             proposals: proposalCount + truncatedProposals,
             linkRequests: linkCount + truncatedConnectionRequests,
+            mcpServerRequests: mcpServerRequestCount + truncatedMcpServerRequests,
             activeTasks: activeWorkCount,
             listed: decisions.length,
-            truncated: truncatedProposals + truncatedConnectionRequests,
+            truncated: truncatedProposals +
+                truncatedConnectionRequests +
+                truncatedMcpServerRequests,
         },
         decisions,
         activeWork,
         truncatedProposals,
         truncatedConnectionRequests,
+        truncatedMcpServerRequests,
         agreementsListAppUrl: listUrl,
+        connectionsSettingsAppUrl: connectionsSettingsAppUrl(webOrigin),
         ...(decisionChatCard ? { decisionChatCard } : {}),
         ...(workChatCard ? { workChatCard } : {}),
         ...(sessionChatCard ? { sessionChatCard } : {}),
@@ -327,7 +393,12 @@ export function buildPendingNextActions(decisions, work = []) {
         actions.push('Wait for the human to say approve/reject (e.g. `approve agr-…`) — do not auto-respond.');
     }
     for (const d of decisions.slice(0, 4)) {
-        actions.push(`${kindLabel(d.kind)} ${d.agreementId}: \`${d.sayApprove}\` or \`${d.sayReject}\``);
+        if (d.sayApprove && d.sayReject) {
+            actions.push(`${kindLabel(d.kind)} ${d.agreementId}: \`${d.sayApprove}\` or \`${d.sayReject}\``);
+        }
+        else {
+            actions.push(`${kindLabel(d.kind)} ${d.agreementId}: connect or reject in the browser → ${d.appUrl}`);
+        }
     }
     for (const w of work.slice(0, 4)) {
         actions.push(`Active task ${w.taskId}: human says \`${w.sayWork}\` to start implementation.`);

package/dist/tools.js

@@ -4,7 +4,7 @@ import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDi
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
-import { formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
+import { connectionsSettingsAppUrl, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
 import { PROTOCOL } from './protocol/delegateProtocol.js';
 import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
 // ZIG-557: the protocol sentences (loop / ack / humanAttention) are sourced
@@ -205,6 +205,50 @@ async function listConnectionsForHolder(creds) {
     }
     return parsed?.['connections'] ?? [];
 }
+/**
+ * ZIG-686 — agent-initiated MCP connection request: ask the principal to
+ * connect a remote MCP server and grant this agent the listed tools. Creates a
+ * pending decision the human resolves in the browser (OAuth consent or a grant
+ * from an existing connection) — never from chat.
+ */
+async function createMcpConnectionRequest(creds, input) {
+    const url = `${getBackendUrl()}/connections/mcp/requests`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            Authorization: `Bearer ${creds.operatorKey}`,
+            'X-Agent-Id': creds.agentId,
+        },
+        body: JSON.stringify({
+            serverUrl: input.serverUrl,
+            tools: input.tools,
+            reason: input.reason,
+        }),
+    });
+    const body = await res.text().catch(() => '');
+    if (!res.ok) {
+        throw new Error(`POST /connections/mcp/requests ${res.status} ${body.slice(0, 200)}`);
+    }
+    return body ? JSON.parse(body) : {};
+}
+/** ZIG-686 — the requests this agent made, each with status / connectionId / grantId. */
+async function listMcpConnectionRequests(creds) {
+    const url = `${getBackendUrl()}/connections/mcp/requests`;
+    const res = await fetch(url, {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${creds.operatorKey}`,
+            'X-Agent-Id': creds.agentId,
+        },
+    });
+    const body = await res.text().catch(() => '');
+    if (!res.ok) {
+        throw new Error(`GET /connections/mcp/requests ${res.status} ${body.slice(0, 200)}`);
+    }
+    const parsed = body ? JSON.parse(body) : null;
+    return parsed?.['requests'] ?? [];
+}
 async function loadSessionActionsPayload(creds, cfg) {
     const webOrigin = resolveWebAppOrigin(cfg.ZIGGS_WEB_URL);
     const client = new InboxClient(creds.operatorKey, creds.agentId);
@@ -287,7 +331,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 : 'Next: ziggs_inbox or ziggs_pending_decisions at session start.',
         });
     });
-    server.tool('ziggs_switch_org', 'ZIG-640 — Switch which org this MCP OAuth session acts in without reconnecting. Existing Bearer unchanged; runtime org flips server-side. Requires confirm=true (party-identity change). Target org must be one you belong to. Call ziggs_auth_status after to verify actingOrgId.', {
+    server.tool('ziggs_switch_org', 'Switch which org this MCP OAuth session acts in without reconnecting. Existing Bearer unchanged; runtime org flips server-side. Requires confirm=true (party-identity change). Target org must be one you belong to. Call ziggs_auth_status after to verify actingOrgId.', {
         orgId: z.string().describe('Organization id to act in'),
         confirm: z
             .literal(true)
@@ -796,5 +840,46 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
+    server.tool('ziggs_request_connection', 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
+        'Creates a pending decision — the human connects (OAuth) or rejects it in the browser under Settings → Connections; there is no MCP tool to approve it, so tell them and link the returned approveUrl. ' +
+        'Check the outcome with ziggs_request_connection_status: a fulfilled request carries the connectionId + grantId to use with ziggs_connection_proxy.', {
+        serverUrl: z.string().describe('Remote MCP server URL (https)'),
+        tools: z
+            .array(z.string())
+            .describe("Tool names you want — become the grant's allowed_actions caveats"),
+        reason: z
+            .string()
+            .optional()
+            .describe('Plain-language reason shown to the human deciding'),
+    }, WRITE, async ({ serverUrl, tools, reason }) => {
+        try {
+            const result = await createMcpConnectionRequest(creds, {
+                serverUrl,
+                tools,
+                reason,
+            });
+            const approveUrl = connectionsSettingsAppUrl(resolveWebAppOrigin(cfg.ZIGGS_WEB_URL));
+            return textResult({
+                ok: true,
+                ...result,
+                approveUrl,
+                note: 'Pending your principal\'s decision. Tell the human now (pull-only MCP has no push) and link the approveUrl — they connect or reject there. ' +
+                    'Poll ziggs_request_connection_status for the outcome; fulfilled requests carry connectionId + grantId for ziggs_connection_proxy.',
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_request_connection_status', 'List the MCP server connection requests this agent made with ziggs_request_connection, each with status pending | fulfilled | rejected. ' +
+        'A fulfilled request carries the connectionId + grantId to feed into ziggs_connection_proxy (it also appears in ziggs_list_my_connections).', {}, READ_ONLY, async () => {
+        try {
+            const requests = await listMcpConnectionRequests(creds);
+            return textResult({ requests });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
     registerTrustTools(server, creds, cfg);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.1.19",
+    "@ziggs-ai/api-client": "^0.1.20",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },