@ziggs-ai/ziggs-mcp 0.23.1 → 0.24.0

package/dist/server.js

@@ -6,6 +6,7 @@ import { loadConfig } from './config.js';
 import { credsFromConfig } from './creds.js';
 import { registerZiggsTools } from './tools.js';
 import { applySurfacePolicy } from './surface.js';
+import { backendToolPick } from './toolPick.js';
 import { renderInstructions } from './protocol/delegateProtocol.js';
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
@@ -25,7 +26,7 @@ export function createZiggsMcpServer(creds, cfg) {
     registerZiggsTools(server, creds, cfg);
     // Decide what a caller loads natively and what it reaches through
     // the catalog. Runs after registration because the catalog is built by it.
-    applySurfacePolicy(server);
+    applySurfacePolicy(server, { pickTool: backendToolPick(creds) });
     return server;
 }
 /** Drop this process's inbox host. Best-effort — shutdown must not fail on it. */

package/dist/surface.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type PickTool } from './toolPick.js';
 import { type CatalogEntry } from './toolCatalog.js';
 /**
  * The tools a cold session gets natively, with their full schemas.
@@ -23,6 +24,9 @@ import { type CatalogEntry } from './toolCatalog.js';
  * Deliberately NOT native: the agreement verbs, payments, artifacts, grants,
  * links, connections, tasks beyond the result. Every one of them is a real
  * capability an agent reaches for occasionally and pays for constantly.
+ *
+ * The names live in api-client (`EVERYDAY_MCP_TOOLS`) so the hosted brain
+ * loads the same set and the two doors cannot drift.
  */
 export declare const NATIVE_TOOLS: readonly string[];
 /**
@@ -80,4 +84,7 @@ export declare function callLine(entry: CatalogEntry): string;
  * hand-building that response would risk a schema-shape difference on exactly
  * the tools every caller loads. We filter its output and change nothing else.
  */
-export declare function applySurfacePolicy(server: McpServer): void;
+export declare function applySurfacePolicy(server: McpServer, opts?: {
+    /** Answers `ziggs_tools need=`. Absent: `need` falls back to the full list. */
+    pickTool?: PickTool;
+}): void;

package/dist/surface.js

@@ -1,10 +1,12 @@
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { EVERYDAY_DESTRUCTIVE_MCP, EVERYDAY_MCP_TOOLS } from '@ziggs-ai/api-client';
 import { readOnly, write } from './toolAnnotations.js';
 import { registerStrictTool } from './strictParams.js';
 import { toolError } from './toolError.js';
 import { textResult } from './capabilityAdapter.js';
 import { aliasMatches } from './toolAliases.js';
+import { pickLine } from './toolPick.js';
 import { catalogEntry, catalogFor, catalogRow, describeEntry, removeCatalogEntry, } from './toolCatalog.js';
 /**
  * The tools a cold session gets natively, with their full schemas.
@@ -29,25 +31,11 @@ import { catalogEntry, catalogFor, catalogRow, describeEntry, removeCatalogEntry
  * Deliberately NOT native: the agreement verbs, payments, artifacts, grants,
  * links, connections, tasks beyond the result. Every one of them is a real
  * capability an agent reaches for occasionally and pays for constantly.
+ *
+ * The names live in api-client (`EVERYDAY_MCP_TOOLS`) so the hosted brain
+ * loads the same set and the two doors cannot drift.
  */
-export const NATIVE_TOOLS = [
-    'ziggs_inbox',
-    // Count-only orientation: who you are and whether mail is waiting, without
-    // taking the mailbox. The full read below is the one that acquires.
-    'ziggs_inbox_peek',
-    // The ack is native beside the read it follows: a readPlan ends with it, and
-    // a caller that had to go through the catalog to close its loop would pay the
-    // dispatcher on every pass.
-    '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.
-    'ziggs_agreement_revoke',
-    'ziggs_context_revoke_grant',
-];
+export const NATIVE_TOOLS = EVERYDAY_MCP_TOOLS;
 /**
  * Irreversible tools stay natively listed, and the write dispatcher refuses
  * them.
@@ -68,10 +56,7 @@ export const NATIVE_TOOLS = [
  * If a third destructive tool ever appears, it belongs in both lists. The test
  * in `core-only-tier.test.ts` fails if one is added and not listed here.
  */
-export const DESTRUCTIVE_STAY_NATIVE = [
-    'ziggs_agreement_revoke',
-    'ziggs_context_revoke_grant',
-];
+export const DESTRUCTIVE_STAY_NATIVE = EVERYDAY_DESTRUCTIVE_MCP;
 const TOOLS_CATALOG_NAME = 'ziggs_tools';
 const TOOL_READ_NAME = 'ziggs_tool_read';
 const TOOL_WRITE_NAME = 'ziggs_tool_write';
@@ -100,6 +85,7 @@ const ZIGGS_API = 'the Ziggs API (https://api.ziggsai.com, reference at https://
 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, 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 `need` with a plain sentence of what you want done (e.g. "send a message to the customer", "cancel the task I am on") to get the one tool that does it, with its schema and call line, or "nothing fits" — when no single tool clearly fits you get the complete catalog instead. ' +
     '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}. ` +
@@ -241,7 +227,7 @@ function registerDispatcher(server, lane) {
  * hand-building that response would risk a schema-shape difference on exactly
  * the tools every caller loads. We filter its output and change nothing else.
  */
-export function applySurfacePolicy(server) {
+export function applySurfacePolicy(server, opts = {}) {
     const native = new Set(NATIVE_TOOLS);
     listOnly(server, native);
     registerStrictTool(server, TOOLS_CATALOG_NAME, TOOLS_DESCRIPTION, {
@@ -253,7 +239,11 @@ export function applySurfacePolicy(server) {
             .string()
             .optional()
             .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 }) => {
+        need: z
+            .string()
+            .optional()
+            .describe('What you want done, in a plain sentence. Answers with the one tool that does it, or "nothing fits"; falls back to the full list when unsure.'),
+    }, readOnly('List every Ziggs tool'), async ({ describe, search, need }) => {
         try {
             if (describe?.length) {
                 // Sorted rows are the listing's business — a describe answers by name
@@ -278,6 +268,26 @@ export function applySurfacePolicy(server) {
                 });
             }
             const all = sortRows(catalogFor(server));
+            const wanted = need?.trim();
+            if (wanted && opts.pickTool && !search?.trim()) {
+                const answer = await opts.pickTool(wanted, all.map((e) => ({ name: e.name, line: pickLine(e.title, e.description) })));
+                const picked = answer?.how === 'pick' && answer.tool ? catalogEntry(server, answer.tool) : undefined;
+                if (picked) {
+                    return textResult({
+                        need: wanted,
+                        tools: [withCall(picked, describeEntry(picked))],
+                        next: `This is the one tool for that need. Call it as its call line says. If it is not what you meant, call ${TOOLS_CATALOG_NAME} with no arguments for every tool.`,
+                    });
+                }
+                if (answer?.how === 'nothing_fits') {
+                    return textResult({
+                        need: wanted,
+                        tools: [],
+                        nothingFits: `No Ziggs tool does this. Call ${TOOLS_CATALOG_NAME} with no arguments to check the full list yourself.`,
+                    });
+                }
+                // Unsure, off or unreachable: the list, exactly as without `need`.
+            }
             const needle = search?.trim().toLowerCase();
             const rows = (needle
                 ? all.filter((e) => e.name.toLowerCase().includes(needle) ||

package/dist/toolPick.d.ts

@@ -0,0 +1,27 @@
+import { type Creds } from '@ziggs-ai/api-client';
+/** One catalog row as the picker reads it. */
+export interface ToolPickOption {
+    name: string;
+    line: string;
+}
+/**
+ * - `pick`         one tool does the need: `tool` names it.
+ * - `nothing_fits` no tool does it.
+ * - `unsure` / `off` no answer worth giving: show the list.
+ */
+export interface ToolPickAnswer {
+    how: 'pick' | 'nothing_fits' | 'unsure' | 'off';
+    tool?: string;
+    confidence?: number;
+}
+/** Null means "no answer": the surface shows the list it always has. */
+export type PickTool = (need: string, options: ToolPickOption[]) => Promise<ToolPickAnswer | null>;
+/**
+ * The backend picker: `POST /internal/tool-pick` with this connection's key.
+ * The model call and its key live on the backend, since this server also runs
+ * on a caller's own machine. Any failure is null, including the 404 from a
+ * backend that predates the route.
+ */
+export declare function backendToolPick(creds: Creds): PickTool;
+/** What the picker is told a tool does: its title and the first sentence it says. */
+export declare function pickLine(title: string, description: string): string;

package/dist/toolPick.js

@@ -0,0 +1,39 @@
+import { buildCredsHeaders, getBackendUrl } from '@ziggs-ai/api-client';
+/** A listing is always the fallback, so waiting long for a pick buys nothing. */
+const TIMEOUT_MS = 6000;
+/**
+ * The backend picker: `POST /internal/tool-pick` with this connection's key.
+ * The model call and its key live on the backend, since this server also runs
+ * on a caller's own machine. Any failure is null, including the 404 from a
+ * backend that predates the route.
+ */
+export function backendToolPick(creds) {
+    return async (need, options) => {
+        if (!creds.operatorKey)
+            return null;
+        try {
+            const res = await fetch(`${getBackendUrl()}/internal/tool-pick`, {
+                method: 'POST',
+                headers: buildCredsHeaders(creds),
+                body: JSON.stringify({ need, options }),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            if (!res.ok) {
+                await res.body?.cancel().catch(() => undefined);
+                return null;
+            }
+            const data = (await res.json().catch(() => null));
+            if (!data || typeof data.how !== 'string')
+                return null;
+            return data;
+        }
+        catch {
+            return null;
+        }
+    };
+}
+/** What the picker is told a tool does: its title and the first sentence it says. */
+export function pickLine(title, description) {
+    const first = description.split(/(?<=\.)\s/)[0] ?? '';
+    return `${title}. ${first}`.slice(0, 300);
+}

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, acknowledgeTaskControl, 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 { getAgreement, getMyAgreements, listMyChats, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, acknowledgeTaskControl, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, LISTING_DOOR_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';
@@ -510,6 +510,9 @@ export function registerZiggsTools(server, creds, cfg) {
     registerCapabilities(server, AGREEMENT_VERB_CAPABILITIES, creds, {
         webUrl: cfg.ZIGGS_WEB_URL,
     });
+    // The publisher's own door on a listing it already holds: pause and resume.
+    // Apart from the verbs above because they form nothing.
+    registerCapabilities(server, LISTING_DOOR_CAPABILITIES, creds);
     registerCapability(server, agreementClaimCapability, creds, {
         webUrl: cfg.ZIGGS_WEB_URL,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "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.23.1",
+    "@ziggs-ai/api-client": "0.24.0",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"