@ziggs-ai/ziggs-mcp 0.41.7 → 0.41.9

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.41.9
+
+## 0.41.8
+
+- Calling a tool Ziggs removed now answers with an error the assistant can act on, not the SDK's bare "not found". It says the tool was removed and the assistant's tool list is out of date, names the tool (or tools, with when to use each) that does the job now, and says what to do next: on the compact door, call the replacement through `ziggs_tool_read` or `ziggs_tool_write` and give the person the refresh steps; on the directory door, ask the person once to refresh Ziggs, with steps for ChatGPT, Claude, Cursor and Claude Code. The same message answers a call through either dispatcher and `ziggs_tools` describe, and the server sends the tool-list-changed signal on a session that has a stream. `ziggs_tools` search finds the replacement for a retired word. 87 removed tools are covered, and a test fails when a tool leaves the registered set without a row in `src/retiredTools.ts`.
+- Bucket tools no longer take `agreement` items: an agreement brings its people into a bucket rather than going into one. `bucketId` on the hire tools is the bucket the other side joins once the hire starts.
+
 ## 0.41.7
 
 - `ziggs_artifact_share` is removed from every surface, the directory included: an artifact reaches people only by being added to a bucket.

package/dist/retiredCalls.d.ts

@@ -0,0 +1,12 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Door } from './retiredTools.js';
+/**
+ * Answer a direct call to a removed tool with the removed-tool message, before
+ * the MCP SDK can say only that the tool was not found. Wraps whatever
+ * `tools/call` handler is installed, so call it after every other one.
+ *
+ * On a session that keeps an open stream, the tool-list-changed signal goes out
+ * as well, so an app that acts on it reloads its list without its person doing
+ * anything. A session with no stream has nobody to tell; that is not an error.
+ */
+export declare function answerRetiredCalls(server: McpServer, door: Door): void;

package/dist/retiredCalls.js

@@ -0,0 +1,29 @@
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { doorContext, retiredTool, retiredToolResult } from './retiredTools.js';
+/**
+ * Answer a direct call to a removed tool with the removed-tool message, before
+ * the MCP SDK can say only that the tool was not found. Wraps whatever
+ * `tools/call` handler is installed, so call it after every other one.
+ *
+ * On a session that keeps an open stream, the tool-list-changed signal goes out
+ * as well, so an app that acts on it reloads its list without its person doing
+ * anything. A session with no stream has nobody to tell; that is not an error.
+ */
+export function answerRetiredCalls(server, door) {
+    const inner = server.server;
+    const built = inner._requestHandlers?.get('tools/call');
+    if (!built)
+        return;
+    server.server.setRequestHandler(CallToolRequestSchema, (async (req, extra) => {
+        const retired = retiredTool(req.params.name);
+        if (!retired)
+            return built(req, extra);
+        try {
+            server.sendToolListChanged();
+        }
+        catch {
+            // No open stream on this session.
+        }
+        return retiredToolResult(req.params.name, retired, doorContext(server, door));
+    }));
+}

package/dist/retiredTools.d.ts

@@ -0,0 +1,62 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Tools we removed, and what replaced them.
+ *
+ * An assistant that loaded its Ziggs tool list before a removal still holds the
+ * old name. Without this table the call dies on the MCP SDK's bare "not found",
+ * and the assistant tells its person Ziggs is broken. Every way of reaching a
+ * tool by name reads this table: a direct call, both dispatchers, and describe.
+ *
+ * Retired names are never registered, so they never appear in `tools/list`.
+ * Removing a tool adds its row in the same change; retiredTools.test.ts fails
+ * when a name leaves the registered set without one.
+ */
+export interface Replacement {
+    tool: string;
+    /** When to use this one, for a job that was split across several tools. */
+    when?: string;
+}
+export interface RetiredTool {
+    /** The tools that do the job now. Empty when nothing replaces it. */
+    use: Replacement[];
+    /** What changed, in one line. */
+    note?: string;
+}
+export declare const RETIRED_TOOLS: Readonly<Record<string, RetiredTool>>;
+export declare function retiredTool(name: string): RetiredTool | undefined;
+/** The replacement tools for a search word such as `commission` or `ziggs_quest`. */
+export declare function retiredReplacementsFor(needle: string): string[];
+export type Door = 'compact' | 'directory';
+/** How a person refreshes Ziggs in the app the connection came from. */
+export declare function refreshSteps(clientName: string | undefined): string;
+/**
+ * The tool result for a call to a removed tool: an ordinary error the assistant
+ * can act on. The compact door can call the replacement through its dispatcher
+ * at once; the directory door cannot call a tool that is not in its list, so
+ * its message asks the person to refresh, once.
+ */
+export declare function retiredToolResult(name: string, retired: RetiredTool, ctx: {
+    door: Door;
+    clientName?: string;
+}): {
+    structuredContent: {
+        error: {
+            code: string;
+            message: string;
+            retired: {
+                name: string;
+                replacements: Replacement[];
+            };
+        };
+    };
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/** Which door this server was built for, and the client's name once it has connected. */
+export declare function doorContext(server: McpServer, door: Door): {
+    door: Door;
+    clientName: string | undefined;
+};

package/dist/retiredTools.js

@@ -0,0 +1,174 @@
+import { toolError } from './toolError.js';
+const same = (tool, note) => ({ use: [{ tool }], ...(note ? { note } : {}) });
+const gone = (note) => ({ use: [], note });
+const split = (...use) => ({
+    use: use.map(([tool, when]) => ({ tool, when })),
+});
+/** One tool does the same job under a new name. */
+const RENAMED = [
+    ['ziggs_agreement_commission', 'ziggs_agreement_buy'],
+    ['ziggs_agreement_quest', 'ziggs_agreement_request'],
+    ['ziggs_cancel_task', 'ziggs_task_cancel'],
+    ['ziggs_chat_open', 'ziggs_message_send', 'There is no room to open; send the message.'],
+    ['ziggs_chat_send', 'ziggs_message_send'],
+    ['ziggs_claim_link_invite', 'ziggs_agreement_claim'],
+    ['ziggs_claim_offer', 'ziggs_agreement_claim'],
+    ['ziggs_connection_status', 'ziggs_auth_status'],
+    ['ziggs_context_request', 'ziggs_access_request'],
+    ['ziggs_conversation_send', 'ziggs_message_send'],
+    ['ziggs_counter_agreement', 'ziggs_agreement_counter'],
+    ['ziggs_create_link_invite', 'ziggs_link_propose'],
+    ['ziggs_create_party_connection_invite', 'ziggs_link_propose'],
+    ['ziggs_create_task', 'ziggs_task_create'],
+    ['ziggs_delegate_grant', 'ziggs_context_delegate'],
+    ['ziggs_discover_grantable', 'ziggs_context_discover_grantable'],
+    ['ziggs_expand_context', 'ziggs_context_expand_reach'],
+    ['ziggs_fulfill_agreement', 'ziggs_agreement_fulfill'],
+    ['ziggs_get_active_tasks', 'ziggs_task_list'],
+    ['ziggs_get_agent', 'ziggs_agent_get'],
+    ['ziggs_get_agreement', 'ziggs_agreement_get'],
+    ['ziggs_get_scope', 'ziggs_context_snapshot'],
+    ['ziggs_get_task', 'ziggs_task_get'],
+    ['ziggs_inbox_park', 'ziggs_inbox_defer'],
+    ['ziggs_issue_grant', 'ziggs_context_delegate'],
+    ['ziggs_link_create_invite', 'ziggs_link_propose'],
+    ['ziggs_list_connections', 'ziggs_connection_list'],
+    ['ziggs_list_grants', 'ziggs_grant_list'],
+    ['ziggs_list_links', 'ziggs_link_list'],
+    ['ziggs_list_messages', 'ziggs_message_list'],
+    ['ziggs_list_my_agreements', 'ziggs_agreement_list'],
+    ['ziggs_list_my_connections', 'ziggs_connection_list'],
+    ['ziggs_list_my_grants', 'ziggs_grant_list'],
+    ['ziggs_list_my_orgs', 'ziggs_org_list'],
+    ['ziggs_list_party_connections', 'ziggs_link_list'],
+    ['ziggs_list_tasks', 'ziggs_task_list'],
+    ['ziggs_open_conversation', 'ziggs_message_send'],
+    ['ziggs_pending_decisions', 'ziggs_inbox', 'A fresh inbox read carries the decisions.'],
+    ['ziggs_publish_quest', 'ziggs_agreement_request'],
+    ['ziggs_read_context', 'ziggs_context_read'],
+    ['ziggs_record_artifact', 'ziggs_artifact_record'],
+    ['ziggs_redeem_party_connection_invite', 'ziggs_agreement_claim'],
+    ['ziggs_request_connection_status', 'ziggs_connection_list'],
+    ['ziggs_request_link', 'ziggs_link_propose'],
+    ['ziggs_request_party_connection', 'ziggs_link_propose'],
+    ['ziggs_respond_to_agreement', 'ziggs_agreement_respond'],
+    ['ziggs_respond_to_party_connection', 'ziggs_agreement_respond'],
+    ['ziggs_revoke_agreement', 'ziggs_agreement_revoke'],
+    ['ziggs_revoke_grant', 'ziggs_context_revoke_grant'],
+    ['ziggs_revoke_link', 'ziggs_agreement_revoke'],
+    ['ziggs_revoke_party_connection', 'ziggs_agreement_revoke'],
+    ['ziggs_search_agents', 'ziggs_agent_search'],
+    ['ziggs_send_message', 'ziggs_message_send'],
+    ['ziggs_set_task_result', 'ziggs_task_set_result'],
+];
+const PROPOSE = split(['ziggs_agreement_buy', 'you pay a named party'], ['ziggs_agreement_bid', 'you offer your work to a named party'], ['ziggs_agreement_request', 'an open call for anyone'], ['ziggs_agreement_broker', 'you arrange a deal between others'], ['ziggs_agreement_handoff', 'you pass your work on to someone else'], ['ziggs_link_propose', 'you want a link']);
+const LISTING = gone("Posting and pausing a listing is the person's job in the web app. Claim someone's listing with ziggs_agreement_claim; browse with ziggs_marketplace_view.");
+const ROOMS = gone('Rooms are gone. Read with ziggs_inbox or ziggs_message_list.');
+const ANSWERS = gone('Messages are fyi or request now; there are no answer requests. Read replies with ziggs_message_replies.');
+const PAYMENT = gone('Agents do not move points. ziggs_payment_balance is the only payment tool.');
+const OTHER = [
+    ['ziggs_agreement_propose', PROPOSE],
+    ['ziggs_propose_agreement', PROPOSE],
+    ['ziggs_context_issue_grant', split(['ziggs_context_delegate', 'a slice of a grant you hold'], ['ziggs_bucket_insert', 'one file: add it to a bucket'])],
+    ['ziggs_conversation_read', split(['ziggs_message_read', 'one message'], ['ziggs_message_list', 'the whole thread, with conversationOf'])],
+    ['ziggs_discover_context', split(['ziggs_grant_list', 'what you hold'], ['ziggs_context_discover_grantable', 'what exists that you cannot read yet'])],
+    ['ziggs_list_artifacts', split(['ziggs_artifact_list', 'what you wrote'], ['ziggs_context_read', 'what is in a scope, with type artifacts'])],
+    ['ziggs_post_task_plan_step', split(['ziggs_task_replace_plan', 'the whole plan'], ['ziggs_task_update_steps', 'progress only'])],
+    ['ziggs_tool', split(['ziggs_tool_read', 'reads'], ['ziggs_tool_write', 'writes'])],
+    ['ziggs_agreement_offer', LISTING],
+    ['ziggs_publish_offer', LISTING],
+    ['ziggs_listing_pause', LISTING],
+    ['ziggs_listing_resume', LISTING],
+    ['ziggs_chat_list', ROOMS],
+    ['ziggs_list_chats', ROOMS],
+    ['ziggs_message_answers', ANSWERS],
+    ['ziggs_message_answer_cancel', ANSWERS],
+    ['ziggs_payment_attenuate_grant', PAYMENT],
+    ['ziggs_payment_hold', PAYMENT],
+    ['ziggs_payment_issue_grant', PAYMENT],
+    ['ziggs_payment_release', PAYMENT],
+    ['ziggs_payment_resolve_wallet', PAYMENT],
+    ['ziggs_payment_revoke_grant', PAYMENT],
+    ['ziggs_payment_transfer', PAYMENT],
+    ['ziggs_payment_wait_for_approval', PAYMENT],
+    ['ziggs_context_record_message', gone('Send messages with ziggs_message_send.')],
+    ['ziggs_context_record_thought', gone('Nothing replaces it. Save finished work with ziggs_artifact_record.')],
+    ['ziggs_get_subtasks', gone('Nothing replaces it. Nearest: ziggs_task_list, ziggs_task_get.')],
+    ['ziggs_mark_task_processing', gone('Nothing replaces it. Nearest: ziggs_inbox_claim.')],
+    ['ziggs_update_task_state', gone('Nothing replaces it. Finish with ziggs_task_set_result or stop with ziggs_task_cancel.')],
+    ['ziggs_switch_org', gone('The workspace is chosen when Ziggs is connected. See them with ziggs_org_list.')],
+    ['ziggs_request_connection', gone('Requesting a connection is not a Ziggs MCP tool any more. See yours with ziggs_connection_list.')],
+    ['ziggs_artifact_reextract', gone('Not an agent tool any more.')],
+    ['ziggs_provision_relay_workers', gone('Not an agent tool any more. Engage agents with the agreement tools and ziggs_task_create.')],
+];
+export const RETIRED_TOOLS = Object.freeze({
+    ...Object.fromEntries(RENAMED.map(([name, tool, note]) => [name, same(tool, note)])),
+    ...Object.fromEntries(OTHER),
+});
+export function retiredTool(name) {
+    return Object.hasOwn(RETIRED_TOOLS, name) ? RETIRED_TOOLS[name] : undefined;
+}
+/** The replacement tools for a search word such as `commission` or `ziggs_quest`. */
+export function retiredReplacementsFor(needle) {
+    const hits = new Set();
+    for (const candidate of [needle, `ziggs_${needle}`, `ziggs_agreement_${needle}`]) {
+        for (const entry of retiredTool(candidate)?.use ?? [])
+            hits.add(entry.tool);
+    }
+    return [...hits];
+}
+/** How a person refreshes Ziggs in the app the connection came from. */
+export function refreshSteps(clientName) {
+    const name = (clientName ?? '').toLowerCase();
+    if (name.includes('chatgpt') || name.includes('openai'))
+        return 'In ChatGPT: Settings → Apps & Connectors → Ziggs → Refresh. ChatGPT never refreshes by itself. On Business and Enterprise plans a workspace admin refreshes or republishes it.';
+    if (name.includes('cursor'))
+        return 'In Cursor: turn Ziggs off and on in MCP settings, or restart Cursor. Cursor ignores the list-changed signal.';
+    if (name.includes('claude-code') || name.includes('claude code'))
+        return 'In Claude Code: run /mcp and reconnect Ziggs, or start a new session.';
+    if (name.includes('claude'))
+        return 'In Claude: Settings → Connectors → Ziggs → ⋯ → refresh the tool list, or remove Ziggs and add it again.';
+    return "Reconnect Ziggs in the app's connector settings, or start a new conversation.";
+}
+/**
+ * The tool result for a call to a removed tool: an ordinary error the assistant
+ * can act on. The compact door can call the replacement through its dispatcher
+ * at once; the directory door cannot call a tool that is not in its list, so
+ * its message asks the person to refresh, once.
+ */
+export function retiredToolResult(name, retired, ctx) {
+    const lines = [`${name} was removed from Ziggs, so your list of Ziggs tools is out of date.`];
+    if (retired.note)
+        lines.push(retired.note);
+    if (retired.use.length === 1) {
+        lines.push(`Use ${retired.use[0].tool} for this now.`);
+    }
+    else if (retired.use.length > 1) {
+        lines.push(`This job is now done by more than one tool: ${retired.use.map((u) => `${u.tool} (${u.when})`).join('; ')}.`);
+    }
+    if (ctx.door === 'compact') {
+        lines.push(retired.use.length
+            ? 'Call the replacement now through ziggs_tool_read (read-only tools) or ziggs_tool_write (tools that change something), and also give your person these steps so your tool list is current:'
+            : 'Give your person these steps so your tool list is current:');
+    }
+    else {
+        lines.push('You cannot call a tool that is not in your list. Ask your person, once per conversation, to refresh Ziggs:');
+    }
+    lines.push(refreshSteps(ctx.clientName));
+    const result = toolError(lines.join(' '));
+    const error = {
+        ...result.structuredContent.error,
+        code: 'TOOL_RETIRED',
+        message: lines.join(' '),
+        retired: { name, replacements: retired.use },
+    };
+    return {
+        structuredContent: { error },
+        content: [{ type: 'text', text: JSON.stringify({ error }, null, 2) }],
+        isError: true,
+    };
+}
+/** Which door this server was built for, and the client's name once it has connected. */
+export function doorContext(server, door) {
+    return { door, clientName: server.server.getClientVersion()?.name };
+}

package/dist/server.js

@@ -10,6 +10,7 @@ import { loadConfig } from './config.js';
 import { credsFromConfig } from './creds.js';
 import { registerZiggsTools } from './tools.js';
 import { applySurfacePolicy, listWithoutSchemaDialect } from './surface.js';
+import { answerRetiredCalls } from './retiredCalls.js';
 import { backendToolPick } from './toolPick.js';
 import { renderConnectText } from './protocol/connectText.js';
 import { CHANNEL_CAPABILITY, observeFor, startInboxChannel } from './inboxChannel.js';
@@ -44,6 +45,7 @@ export function createZiggsMcpServer(creds, cfg) {
     if (cfg.directConnection !== false)
         applySurfacePolicy(server, { pickTool: backendToolPick(creds) });
     listWithoutSchemaDialect(server);
+    answerRetiredCalls(server, cfg.directConnection === false ? 'directory' : 'compact');
     return server;
 }
 /** Drop this process's inbox host. Best-effort — shutdown must not fail on it. */

package/dist/surface.js

@@ -6,6 +6,7 @@ import { registerStrictTool } from './strictParams.js';
 import { toolError } from './toolError.js';
 import { textResult } from './capabilityAdapter.js';
 import { aliasMatches } from './toolAliases.js';
+import { doorContext, retiredReplacementsFor, retiredTool, retiredToolResult } from './retiredTools.js';
 import { pickLine } from './toolPick.js';
 import { catalogEntry, catalogFor, catalogRow, describeEntry, removeCatalogEntry, } from './toolCatalog.js';
 /**
@@ -141,6 +142,9 @@ function registerDispatcher(server, lane) {
     }, lane.annotations, async ({ tool, args }) => {
         const entry = catalogEntry(server, tool);
         if (!entry) {
+            const retired = retiredTool(tool);
+            if (retired)
+                return retiredToolResult(tool, retired, doorContext(server, 'compact'));
             return toolError(`No such tool: ${tool}. Call ${TOOLS_CATALOG_NAME} for the full list of names.`);
         }
         // Each lane carries one kind of tool, so its annotation is true of every
@@ -218,6 +222,9 @@ export function applySurfacePolicy(server, opts = {}) {
                         unknown.push(name);
                 }
                 if (!found.length) {
+                    const retired = unknown.map((name) => [name, retiredTool(name)]).find(([, r]) => r);
+                    if (retired?.[1])
+                        return retiredToolResult(retired[0], retired[1], doorContext(server, 'compact'));
                     return toolError(`No such tool: ${unknown.join(', ')}. Call ${TOOLS_CATALOG_NAME} with no arguments for the full list of names.`);
                 }
                 return textResult({
@@ -250,7 +257,8 @@ export function applySurfacePolicy(server, opts = {}) {
             const rows = (needle
                 ? all.filter((e) => e.name.toLowerCase().includes(needle) ||
                     e.title.toLowerCase().includes(needle) ||
-                    aliasMatches(e.name, needle))
+                    aliasMatches(e.name, needle) ||
+                    retiredReplacementsFor(needle).includes(e.name))
                 : all).map((entry) => withCall(entry, catalogRow(entry)));
             return textResult({
                 count: rows.length,

package/dist/toolAliases.d.ts

@@ -13,15 +13,12 @@
  * appear in a catalog row, and cost nothing at connect time because the search
  * runs server-side.
  *
- * Two kinds of word belong here:
+ * The word belonging here is the plain-English word for the intent, when our
+ * name is a term of art: "hire" for claim (the default) and for buy (a direct
+ * proposal), "subcontract" for the parent-rail verb.
  *
- * 1. The plain-English word for the intent, when our name is a term of art.
- *    "hire" for claim (the default) and for buy (a direct proposal),
- *    "subcontract" for the parent-rail verb.
- * 2. A name we retired. `agreement_commission` and `agreement_quest` were
- *    renamed before the surface went public; anything still holding the old
- *    word searches it and lands on the tool that replaced it, rather than on
- *    nothing.
+ * A retired name is not an alias: retiredTools.ts holds those, and search
+ * reads it, so anything still holding an old name lands on its replacement.
  */
 export declare const SEARCH_ALIASES: Readonly<Record<string, readonly string[]>>;
 /** Does `needle` match one of this tool's aliases? Substring, both ways. */

package/dist/toolAliases.js

@@ -13,15 +13,12 @@
  * appear in a catalog row, and cost nothing at connect time because the search
  * runs server-side.
  *
- * Two kinds of word belong here:
+ * The word belonging here is the plain-English word for the intent, when our
+ * name is a term of art: "hire" for claim (the default) and for buy (a direct
+ * proposal), "subcontract" for the parent-rail verb.
  *
- * 1. The plain-English word for the intent, when our name is a term of art.
- *    "hire" for claim (the default) and for buy (a direct proposal),
- *    "subcontract" for the parent-rail verb.
- * 2. A name we retired. `agreement_commission` and `agreement_quest` were
- *    renamed before the surface went public; anything still holding the old
- *    word searches it and lands on the tool that replaced it, rather than on
- *    nothing.
+ * A retired name is not an alias: retiredTools.ts holds those, and search
+ * reads it, so anything still holding an old name lands on its replacement.
  */
 export const SEARCH_ALIASES = {
     ziggs_message_send: ['contact', 'message someone', 'teammate', 'group'],
@@ -30,14 +27,12 @@ export const SEARCH_ALIASES = {
     ziggs_agreement_claim: ['hire'],
     ziggs_agreement_buy: [
         'hire',
-        'commission', // retired name
         'procure',
         'outsource',
         'engage',
     ],
     ziggs_agreement_bid: ['sell', 'pitch', 'apply', 'tender', 'quote'],
     ziggs_agreement_request: [
-        'quest', // retired name
         'wanted',
         'open call',
         'rfp',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.41.7",
+  "version": "0.41.9",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {
@@ -51,13 +51,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.40.6",
+    "@ziggs-ai/api-client": "0.40.7",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"
   },
   "devDependencies": {
-    "@ziggs-ai/agent-sdk": "0.46.4"
+    "@ziggs-ai/agent-sdk": "0.46.5"
   },
   "engines": {
     "node": ">=20"