@ziggs-ai/ziggs-mcp 0.22.1 → 0.22.3

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.
  *
@@ -13,6 +14,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * - `ziggs_open` is how it opens a returned artifact/chat/task/agreement id.
  *   The inbox returns references, never content; `readPlan` names this tool
  *   with the ordinary id. `ziggs_context_read` remains the paged/via listing.
+ * - `ziggs_chat_open` starts or reuses contact; an absent room is not a refusal.
  * - `ziggs_chat_send` and `ziggs_task_set_result` are the two ways to answer:
  *   conversation, and finished work. An agent that can read its mail and
  *   cannot reply is worse off than one that pays for a schema it never used.
@@ -56,6 +58,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

@@ -20,6 +20,7 @@ import { catalogEntry, catalogFor, catalogRow, describeEntry, removeCatalogEntry
  * - `ziggs_open` is how it opens a returned artifact/chat/task/agreement id.
  *   The inbox returns references, never content; `readPlan` names this tool
  *   with the ordinary id. `ziggs_context_read` remains the paged/via listing.
+ * - `ziggs_chat_open` starts or reuses contact; an absent room is not a refusal.
  * - `ziggs_chat_send` and `ziggs_task_set_result` are the two ways to answer:
  *   conversation, and finished work. An agent that can read its mail and
  *   cannot reply is worse off than one that pays for a schema it never used.
@@ -40,6 +41,7 @@ export const NATIVE_TOOLS = [
     'ziggs_inbox_ack',
     'ziggs_open',
     'ziggs_context_read',
+    'ziggs_chat_open',
     'ziggs_chat_send',
     'ziggs_task_set_result',
     // And every irreversible tool — see DESTRUCTIVE_STAY_NATIVE below.
@@ -96,18 +98,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. ' +
-    'Pass `search` to filter the listing by a word in the name or title (e.g. "agreement", "artifact"). ' +
+    '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 by name, title, or common intent (e.g. "contact", "permission", "grant", "artifact"). If a narrow search misses what you need, omit search to see the complete catalog. ' +
     '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 +138,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.
@@ -238,7 +252,7 @@ export function applySurfacePolicy(server) {
         search: z
             .string()
             .optional()
-            .describe('Only list tools whose name or title contains this word.'),
+            .describe('Filter tools by name, title, or common intent such as contact, teammate, permission, or grant. Omit to list every tool.'),
     }, readOnly('List every Ziggs tool'), async ({ describe, search }) => {
         try {
             if (describe?.length) {
@@ -259,9 +273,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 +283,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/toolAliases.js

@@ -23,6 +23,9 @@
  *    nothing.
  */
 export const SEARCH_ALIASES = {
+    ziggs_chat_open: ['contact', 'teammate', 'colleague', 'start conversation', 'create chat', 'message someone'],
+    ziggs_agent_search: ['teammate', 'colleague', 'directory', 'find person'],
+    ziggs_context_request: ['grant', 'permission', 'restricted', 'request access', 'unlock document'],
     ziggs_agreement_buy: [
         'hire',
         'commission', // retired name

package/dist/tools.js

@@ -422,6 +422,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({
                 count: chats.length,
                 chats: projectChatListRows(chats, fields),
+                note: 'These are existing rooms, not everyone you can contact. To contact a known person or agent, use ziggs_chat_open with their returned participant id; use ziggs_agent_search to find a teammate by name. The server checks whether contact is allowed. No existing room does not mean contact is forbidden.',
             });
         }
         catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "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.1",
+    "@ziggs-ai/api-client": "0.22.3",
     "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).