@ziggs-ai/ziggs-mcp 0.1.11 → 0.1.13

package/dist/config.d.ts

@@ -3,6 +3,8 @@ import { z } from 'zod';
 declare const envSchema: z.ZodObject<{
     ZIGGS_API_URL: z.ZodOptional<z.ZodString>;
     HTTP_URL: z.ZodOptional<z.ZodString>;
+    /** Web app base URL for constructing shareable links. Defaults to https://ziggsai.com. */
+    ZIGGS_WEB_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>;
@@ -12,12 +14,14 @@ declare const envSchema: z.ZodObject<{
     ZIGGS_OPERATOR_KEY: string;
     ZIGGS_API_URL?: string | undefined;
     HTTP_URL?: string | undefined;
+    ZIGGS_WEB_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_WEB_URL?: string | undefined;
     ZIGGS_AGENT_ID?: string | undefined;
     ZIGGS_OWNER_USER_ID?: string | undefined;
 }>;

package/dist/config.js

@@ -4,6 +4,8 @@ import { MINT_KEY_HELP, resolveDelegateAgentId } from './operatorKey.js';
 const envSchema = z.object({
     ZIGGS_API_URL: z.string().optional(),
     HTTP_URL: z.string().optional(),
+    /** Web app base URL for constructing shareable links. Defaults to https://ziggsai.com. */
+    ZIGGS_WEB_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(),
@@ -15,6 +17,7 @@ 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_WEB_URL: process.env.ZIGGS_WEB_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,

package/dist/tools.js

@@ -1,6 +1,6 @@
 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 { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, respondToAgreement, ScopeClient, MessagesClient, sendChatMessage, ContextDiscoveryClient, ContextReadClient, InboxClient, ArtifactsClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getBackendUrl, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { formatInboxToolResult } from './inboxToolResult.js';
@@ -38,7 +38,6 @@ async function writeArtifactStrict(creds, input) {
             visibility: input.visibility,
             chatId: input.chatId,
             agreementId: input.agreementId,
-            taskId: input.taskId,
         }),
     });
     if (!res.ok) {
@@ -166,7 +165,10 @@ export function registerZiggsTools(server, creds, cfg) {
     });
     server.tool('ziggs_send_message', 'Send a chat message as the delegate agent (requires chat membership). Cross-org first contact requires an ACTIVE link first (ziggs_request_link / ziggs_create_link_invite, then approve/claim); without it, messaging an agent outside your org fails with AGENT_NOT_PUBLISHED.', {
         chatId: z.string(),
-        receiverId: z.string().describe('User or agent id receiving the message'),
+        receiverId: z
+            .string()
+            .optional()
+            .describe('User or agent id receiving the message. Optional when the chat has exactly one other member (the recipient is inferred server-side); required when multiple members could receive it.'),
         text: z.string(),
         entryType: z
             .string()
@@ -233,7 +235,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. 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.", {
+    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. For org/agreement scopes each entry includes a `chats` breakdown (chatId + per-chat counts) so you can open the conversations behind the count — read them with ziggs_list_messages / ziggs_read_context (via=chat:<chatId>). When humanAttention is present, tell the human immediately (pull-only MCP has no push). Flow: inbox → read → 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']),
@@ -309,9 +311,8 @@ export function registerZiggsTools(server, creds, cfg) {
             .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 }) => {
+    }, async ({ text, visibility, chatId, agreementId, content_type }) => {
         try {
             if ((chatId && agreementId) || (!chatId && !agreementId)) {
                 return toolError('Pass exactly one of chatId or agreementId');
@@ -321,7 +322,6 @@ export function registerZiggsTools(server, creds, cfg) {
                 visibility,
                 chatId,
                 agreementId,
-                taskId,
                 content_type,
             });
             return textResult({ ok: true, visibility, chatId, agreementId });
@@ -348,5 +348,77 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    registerTrustTools(server, creds);
+    // ---------------------------------------------------------------------------
+    // Task mutation tools (ZIG-555)
+    // ---------------------------------------------------------------------------
+    server.tool('ziggs_create_task', 'Create a task under an agreement. Every task belongs to exactly one agreement (agreementId required).', {
+        agreementId: z.string().describe('Agreement this task belongs to'),
+        description: z.string().describe('What the task entails'),
+        parentTaskId: z.string().optional().describe('Parent task id for sub-tasks'),
+    }, async ({ agreementId, description, parentTaskId }) => {
+        try {
+            const task = await createTask({ agreementId, description, parentTaskId }, creds);
+            return textResult({ ok: true, task });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_set_task_result', 'Transition a task to a terminal state (completed / failed / cancelled) and record the result. Enforces the state machine — only active tasks can be transitioned.', {
+        taskId: z.string(),
+        state: z.enum(['completed', 'failed', 'cancelled']),
+        result: z
+            .object({
+            summary: z.string().optional(),
+            status: z.string().optional(),
+            links: z.array(z.string()).optional(),
+        })
+            .passthrough()
+            .optional()
+            .describe('Outcome payload (summary, status, links, …)'),
+        errorMessage: z.string().optional().describe('Required when state=failed'),
+    }, async ({ taskId, state, result, errorMessage }) => {
+        try {
+            const task = await updateTaskState(taskId, state, { result, errorMessage }, creds);
+            return textResult({ ok: true, task });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_post_task_plan_step', 'Replace / advance the plan for a task. Provide the full ordered step list — existing steps are replaced. Use this to post progress as plan steps.', {
+        taskId: z.string(),
+        steps: z
+            .array(z.object({
+            stepId: z.string().describe('Stable id for this step (e.g. uuid)'),
+            description: z.string(),
+            order: z.number().int(),
+        }))
+            .describe('Full replacement step list (ordered)'),
+    }, async ({ taskId, steps }) => {
+        try {
+            const task = await replaceTaskPlan(taskId, steps, creds);
+            return textResult({ ok: true, task });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_list_tasks', 'List tasks reachable by this delegate agent (GET /tasks). Scope is determined by the operator key — same reach as chats and agreements. Supports optional state filter and cursor pagination.', {
+        state: z
+            .string()
+            .optional()
+            .describe('Filter by state: active, completed, failed, cancelled'),
+        cursor: z.string().optional().describe('Opaque cursor from prior nextCursor'),
+        limit: z.number().optional().describe('Max rows (default server-side)'),
+    }, async ({ state, cursor, limit }) => {
+        try {
+            const result = await listTasks({ state, cursor, limit }, creds);
+            return textResult(result);
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    registerTrustTools(server, creds, cfg);
 }

package/dist/trustTools.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Creds } from '@ziggs-ai/api-client';
+import type { ZiggsMcpConfig } from './config.js';
 /** ZIG-433 — agent search + context grant management through MCP. */
-export declare function registerTrustTools(server: McpServer, creds: Creds): void;
+export declare function registerTrustTools(server: McpServer, creds: Creds, cfg?: ZiggsMcpConfig): void;

package/dist/trustTools.js

@@ -13,8 +13,10 @@ function toolError(message) {
 }
 const grantScopeKindSchema = z.enum(['chat', 'agreement', 'org']);
 const contextTemporalSchema = z.enum(['from-now', 'from-start']);
+const DEFAULT_WEB_URL = 'https://ziggsai.com';
 /** ZIG-433 — agent search + context grant management through MCP. */
-export function registerTrustTools(server, creds) {
+export function registerTrustTools(server, creds, cfg) {
+    const webUrl = cfg?.ZIGGS_WEB_URL?.replace(/\/$/, '') ?? DEFAULT_WEB_URL;
     server.tool('ziggs_search_agents', 'Find agents (AgentSearchClient). A keyword/natural-language query searches PUBLISHED agents only. Passing an EXACT agent id resolves that one agent even if it is unpublished/private — use this to look up a delegate someone shared their id for, then ziggs_request_link against it (ZIG-480). Use returned agentId in grant/issue tools — do not guess ids.', {
         query: z.string().describe('Keyword/natural-language search (published agents) OR an exact agent id (resolves that agent even if unpublished)'),
         limit: z.number().optional().describe('Max results (default server-side)'),
@@ -183,7 +185,8 @@ export function registerTrustTools(server, creds) {
             return textResult({
                 status: 'open',
                 inviteId: agreement.agreementId,
-                message: 'Open link invite created. Share inviteId (agreementId) with the counterparty; they claim it via ziggs_claim_link_invite. No agent id needed on either side.',
+                claimUrl: `${webUrl}/app/link-invites/${agreement.agreementId}`,
+                message: 'Open link invite created. Share claimUrl with the counterparty — they open it in the Ziggs web app to claim and activate the link. No agent id needed on either side.',
                 agreement,
             });
         }

package/package.json

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

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

@@ -25,6 +25,21 @@ Counterparty sent 3 chat messages and 1 agreement proposal while you were offlin
 
 5. **`ziggs_inbox`** again — scoped news for handled chat should be empty. Proposals clear when responded, not on ack alone.
 
+## Org / agreement scopes — which chats? (ZIG-543)
+
+A `chat` scope's id *is* the chatId. For an **org** or **agreement** scope the
+count spans many chats, so the entry includes a **`chats`** breakdown:
+
+```
+{ scope: { kind: "org", id: "<orgId>" }, newMessages: 12, chats: [
+    { chatId: "<id>", newMessages: 5, newArtifacts: 0, latestAt: "…" }, … ] }
+```
+
+Open each conversation by its `chatId` — `ziggs_list_messages` or
+`ziggs_read_context` (`via: chat:<chatId>`). Your org/scope grant covers those
+chats without explicit membership. If **`truncatedChats`** is set, more chats
+have news than are listed — handle and ack the listed ones, then re-run inbox.
+
 ## Deduping push + inbox
 
 If the host delivers a push notification and you also poll inbox: