@ziggs-ai/ziggs-mcp 0.22.0 → 0.22.2

package/dist/protocol/delegateProtocol.d.ts

@@ -21,7 +21,7 @@ export declare const PROTOCOL: {
      * because a client that never calls ziggs_tools would otherwise conclude the
      * everyday set is all there is.
      */
-    readonly surface: "Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=[\"<name>\"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.";
+    readonly surface: "Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=[\"<name>\"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.";
     /** The working loop, as the `ziggs_inbox` description phrases it. */
     readonly loop: "Flow: inbox → read → act → ack.";
     /**

package/dist/protocol/delegateProtocol.js

@@ -21,7 +21,7 @@ export const PROTOCOL = {
      * because a client that never calls ziggs_tools would otherwise conclude the
      * everyday set is all there is.
      */
-    surface: 'Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.',
+    surface: 'Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.',
     /** The working loop, as the `ziggs_inbox` description phrases it. */
     loop: 'Flow: inbox → read → act → ack.',
     /**

package/dist/surface.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type CatalogEntry } from './toolCatalog.js';
 /**
  * The tools a cold session gets natively, with their full schemas.
  *
@@ -56,6 +57,8 @@ export declare const DESTRUCTIVE_STAY_NATIVE: readonly string[];
  * when it refuses.
  */
 export declare const CATALOG_TOOLS: readonly string[];
+/** Per-tool how-to-call, derived from NATIVE_TOOLS and the annotations. */
+export declare function callLine(entry: CatalogEntry): string;
 /**
  * Narrow `tools/list` to the native set, then register the tools that make the
  * rest reachable: the catalog, and one dispatcher per annotation lane.

package/dist/surface.js

@@ -96,18 +96,39 @@ const CATALOG_TOOL_NAMES = new Set(CATALOG_TOOLS);
  */
 const ZIGGS_API = 'the Ziggs API (https://api.ziggsai.com, reference at https://ziggsai.com/docs)';
 const TOOLS_DESCRIPTION = 'Every Ziggs tool that exists: name plus one line, for the whole surface. ' +
-    'A handful of everyday tools are already loaded natively; the rest live here. Each row says whether the tool is read-only: call read-only tools with ziggs_tool_read and the others with ziggs_tool_write. ' +
-    'Pass `describe` with one or more tool names to get their full descriptions and input schemas — do that before calling a tool you have not used in this session, so you pass the right arguments. ' +
+    'A handful of everyday tools are already loaded natively; the rest live here. Each row says whether the tool is read-only, whether the host already holds it (`native`), and how to call it (`call`). ' +
+    'Pass `describe` with one or more tool names to get their full descriptions, input schemas, and the same `call` line — do that before calling a tool you have not used in this session, so you pass the right arguments. ' +
     'Pass `search` to filter the listing by a word in the name or title (e.g. "agreement", "artifact"). ' +
     'Nothing is hidden: if a capability exists, its name is in this list.';
 const TOOL_READ_DESCRIPTION = `Call a read-only Ziggs tool by name, against ${ZIGGS_API}. ` +
-    'This reaches every read-only tool ziggs_tools lists that is not natively loaded, and it never changes anything: a tool that writes is refused here and pointed at ziggs_tool_write. ' +
+    'This reaches every read-only tool ziggs_tools lists, native or not. It never changes anything: a tool that writes is refused here and pointed at ziggs_tool_write. ' +
     'Look the tool up with ziggs_tools describe=[<name>] first when you do not already know its parameters: `args` is validated against the real schema and a wrong key is refused, not silently dropped. ' +
     'The result is exactly what the tool itself returns.';
 const TOOL_WRITE_DESCRIPTION = `Call a Ziggs tool that creates or changes something, by name, against ${ZIGGS_API}. ` +
-    'This reaches every writing tool ziggs_tools lists that is not natively loaded. Read-only tools are refused here and pointed at ziggs_tool_read; irreversible tools are loaded natively and are called by their own name. ' +
+    'This reaches every reversible writing tool ziggs_tools lists, native or not. Read-only tools are refused here and pointed at ziggs_tool_read; irreversible tools are called by their own name only — the dispatchers refuse them. ' +
     'Look the tool up with ziggs_tools describe=[<name>] first when you do not already know its parameters: `args` is validated against the real schema and a wrong key is refused, not silently dropped. ' +
     'The result is exactly what the tool itself returns.';
+function isNative(name) {
+    return NATIVE_TOOLS.includes(name);
+}
+/** Per-tool how-to-call, derived from NATIVE_TOOLS and the annotations. */
+export function callLine(entry) {
+    if (entry.annotations.destructiveHint) {
+        return `call it by name only: ${entry.name}; the dispatchers refuse it`;
+    }
+    const dispatcher = laneOf(entry);
+    if (isNative(entry.name)) {
+        return `call it by name: ${entry.name}; ${dispatcher} { tool: "${entry.name}", args } also works`;
+    }
+    return `call via ${dispatcher} { tool, args }`;
+}
+function withCall(entry, base) {
+    return {
+        ...base,
+        ...(isNative(entry.name) ? { native: true } : {}),
+        call: callLine(entry),
+    };
+}
 function sortRows(entries) {
     return [...entries].sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -115,15 +136,6 @@ function sortRows(entries) {
 function laneOf(entry) {
     return entry.annotations.readOnlyHint ? TOOL_READ_NAME : TOOL_WRITE_NAME;
 }
-/** The hint under a describe: the dispatcher to call next, named when one fits all. */
-function nextCall(entries) {
-    const lanes = new Set(entries.map(laneOf));
-    if (lanes.size === 1) {
-        for (const lane of lanes)
-            return `Call it with ${lane} { tool, args }.`;
-    }
-    return `Call read-only tools with ${TOOL_READ_NAME} { tool, args } and the rest with ${TOOL_WRITE_NAME} { tool, args }.`;
-}
 /**
  * Keep `tools/list` to `listed` (plus the catalog tools, registered after this
  * runs) by filtering the response the SDK's own handler builds.
@@ -259,9 +271,8 @@ export function applySurfacePolicy(server) {
                     return toolError(`No such tool: ${unknown.join(', ')}. Call ${TOOLS_CATALOG_NAME} with no arguments for the full list of names.`);
                 }
                 return textResult({
-                    tools: found.map(describeEntry),
+                    tools: found.map((entry) => withCall(entry, describeEntry(entry))),
                     ...(unknown.length ? { unknown } : {}),
-                    next: nextCall(found),
                 });
             }
             const all = sortRows(catalogFor(server));
@@ -270,7 +281,7 @@ export function applySurfacePolicy(server) {
                 ? all.filter((e) => e.name.toLowerCase().includes(needle) ||
                     e.title.toLowerCase().includes(needle) ||
                     aliasMatches(e.name, needle))
-                : all).map(catalogRow);
+                : all).map((entry) => withCall(entry, catalogRow(entry)));
             return textResult({
                 count: rows.length,
                 ...(needle ? { search: needle, total: all.length } : {}),

package/dist/tools.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, openCapability, accessExplainCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, agreementSubcontractCapability, listTasksCapability, cancelTaskCapability, marketplaceViewCapability, parseListFields, pickListedRows, sessionOrientation, presentSendResult, presentTaskOutcome, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, openCapability, accessExplainCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, agreementSubcontractCapability, listTasksCapability, cancelTaskCapability, marketplaceViewCapability, parseListFields, pickListedRows, projectChatListRows, sessionOrientation, presentSendResult, presentTaskOutcome, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
@@ -411,10 +411,18 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
-    registerStrictTool(server, 'ziggs_chat_list', 'List chats the acting agent holds a grant on (GET /chats/mine).', {}, readOnly('List your chats'), async () => {
+    registerStrictTool(server, 'ziggs_chat_list', 'List rooms the acting agent holds a grant on. Default rows are chatId, name, updatedAt, lastMessage, unreadCount, and participantSummary — the people who actually receive in the room, each named once with one face. The web app also builds members (flat viewer list) and rosterSummary (display roster including agreement overlays); those come only when fields asks for them.', {
+        fields: z
+            .array(z.string())
+            .optional()
+            .describe('Return only these keys on each row. Omit for the default (chatId, name, updatedAt, lastMessage, unreadCount, participantSummary). Pass members and/or rosterSummary to include the other web-app rosters. Keep chatId if you will open or send next.'),
+    }, readOnly('List your chats'), async ({ fields }) => {
         try {
             const chats = await listMyChats(creds);
-            return textResult({ count: chats.length, chats });
+            return textResult({
+                count: chats.length,
+                chats: projectChatListRows(chats, fields),
+            });
         }
         catch (e) {
             return toolError(e);

package/package.json

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

package/skills/ziggs/.cursorrules

@@ -3,7 +3,7 @@
 
 You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol.
 
-- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
+- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).

package/skills/ziggs/SKILL.md

@@ -22,7 +22,7 @@ You represent a **delegate agent** on Ziggs. MCP tools are the connection; this
 <!-- BEGIN GENERATED: delegate-protocol — generated file, do not edit by hand -->
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
-- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
+- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).

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

@@ -5,7 +5,7 @@
 <!-- BEGIN GENERATED: delegate-protocol — generated file, do not edit by hand -->
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
-- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
+- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).

package/skills/ziggs/references/reporting-convention.md

@@ -5,7 +5,7 @@
 <!-- BEGIN GENERATED: delegate-protocol — generated file, do not edit by hand -->
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
-- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
+- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).