@ziggs-ai/ziggs-mcp 0.3.2 → 0.5.0

package/dist/trustTools.js

@@ -1,227 +1,18 @@
 import { z } from 'zod';
-import { AgentSearchClient, ContextGrantsClient, createAgreement, listAgreements, revokeAgreement, claimAgreement, addChatMember, grantCaveat, } from '@ziggs-ai/api-client';
-import { fetchMyOrgs, resolveOrgSelector } from './orgs.js';
-import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { ContextGrantsClient, addChatMember, contextBounds, resolveOrgScopeId, LINK_CAPABILITIES, DISCOVERY_CAPABILITIES, contextDelegateCapability, } from '@ziggs-ai/api-client';
+import { WRITE, DESTRUCTIVE } from './toolAnnotations.js';
 import { toolError } from './toolError.js';
-function textResult(data) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-    };
-}
-/**
- * Human/LLM-readable bounds for a context grant. ZIG-646 folded a context
- * grant's temporal mode + read watermark into the canonical `caveats` array,
- * so pull them back out here to keep this tool's `bounds` summary stable.
- */
-function contextBounds(grant) {
-    return {
-        temporal: grantCaveat(grant, 'temporal'),
-        watermarkAt: grantCaveat(grant, 'watermark_at'),
-        expiresAt: grant.expiresAt,
-    };
-}
+import { registerCapabilities, registerCapability, textResult } from './capabilityAdapter.js';
 const grantScopeKindSchema = z.enum(['chat', 'agreement', 'org']);
 const contextTemporalSchema = z.enum(['from-now', 'from-start']);
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
-/**
- * ZIG-941 #6 — org-scoped grants may name the org instead of pasting its opaque
- * org_... id. Resolve the selector against the operator's memberships via the
- * (previously unused) resolveOrgSelector: exact id or case-insensitive name.
- * Ambiguous names return the candidate list rather than guessing; a name that
- * matched nothing errors with a pointer to ziggs_list_my_orgs. An org_... id
- * that is not a membership passes through unchanged — you may hold a grant on
- * an org you do not belong to, so the server stays the authority on the id.
- */
-async function resolveOrgScope(creds, scopeId) {
-    const resolution = resolveOrgSelector(await fetchMyOrgs(creds), scopeId);
-    if (resolution.status === 'ok')
-        return { scopeId: resolution.orgId };
-    if (resolution.status === 'ambiguous') {
-        return {
-            error: toolError(`Org name "${scopeId}" matches ${resolution.matches.length} of your orgs — pass the org id: ` +
-                resolution.matches.map((m) => `${m.name} (${m.orgId})`).join(', ')),
-        };
-    }
-    if (scopeId.startsWith('org_'))
-        return { scopeId };
-    return {
-        error: toolError(`No org named "${scopeId}" in your memberships — use ziggs_list_my_orgs to see them, or pass the org id.`),
-    };
-}
-// ZIG-941 #7 — the link tool group, pulled out so the lean session-start
-// tier (ZIGGS_MCP_CORE_ONLY) can skip it. Registration is unchanged.
-function registerLinkTools(server, creds, webUrl) {
-    server.tool('ziggs_request_link', 'Request a bilateral trust link with another agent before cross-org reach (party-to-party, NOT a third-party service connection — see ziggs_list_my_connections for that). A link is just an agreement (POST /agreements {engagementKind:"link"}). The target OWNER must approve it (via ziggs_respond_to_agreement) before unpublished delegates can message each other.', {
-        providerId: z
-            .string()
-            .describe('Bare agent id to link with (the target delegate). Use ziggs_search_agents or a known delegate id — do not guess.'),
-        message: z
-            .string()
-            .optional()
-            .describe('Optional note shown to the counterparty human on approval (agreement description)'),
-    }, WRITE, async ({ providerId, message }) => {
-        try {
-            const { agreement } = await createAgreement({ engagementKind: 'link', providerId, description: message }, creds);
-            return textResult({
-                status: 'pending',
-                message: 'Link agreement created — the counterparty owner must approve (ziggs_respond_to_agreement) before cross-org reach. Surface pending state to the human.',
-                agreement,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_create_link_invite', 'Create a shareable OPEN link invite (bilateral agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) when you do NOT have the counterparty\'s agent id (e.g. connecting across orgs). Creates an open link agreement (POST /agreements {engagementKind:"link"}, proposedTo:"everyone"). Share the returned inviteId (agreementId) out-of-band; the recipient forms the link by calling ziggs_claim_link_invite — neither side pastes an agent id. Revoke via ziggs_revoke_link to disable.', {
-        message: z
-            .string()
-            .optional()
-            .describe('Optional note shown to whoever opens the invite (agreement description)'),
-    }, WRITE, async ({ message }) => {
-        try {
-            const { agreement } = await createAgreement({ engagementKind: 'link', description: message }, creds);
-            return textResult({
-                status: 'open',
-                inviteId: agreement.agreementId,
-                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,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_claim_link_invite', 'Claim an open link invite by its id to form a bilateral link (agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) (POST /agreements/:id/claim). You become the counterparty and the link activates immediately (cross-org reach + bilateral context grants). You cannot claim your own invite.', {
-        agreementId: z
-            .string()
-            .describe('The invite id (agreementId) shared by the issuer'),
-    }, WRITE, async ({ agreementId }) => {
-        try {
-            const { agreement } = await claimAgreement(agreementId, creds);
-            return textResult({
-                status: 'linked',
-                message: 'Link invite claimed — you are now linked. A link is reach-only: open a chat with the peer (ziggs_open_conversation) and grant it chat access with ziggs_issue_grant, or share a slice of a grant you already hold with ziggs_delegate_grant, before reading context.',
-                agreement,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_list_links', 'List link agreements for this delegate — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_list_my_connections for those) (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner). Approve pending links via ziggs_respond_to_agreement.', {
-        status: z
-            .enum(['active', 'open', 'cancelled', 'all'])
-            .optional()
-            .describe('active (default) = established links; open = pending proposals/invites awaiting approval or claim; cancelled = revoked; all = every link regardless of status'),
-    }, READ_ONLY, async ({ status }) => {
-        try {
-            const resolvedStatus = status ?? 'active';
-            const links = await listAgreements({
-                engagementKind: 'link',
-                ...(resolvedStatus === 'all' ? {} : { status: resolvedStatus }),
-            }, creds);
-            // ZIG-670: link-shaped summaries, not raw agreement documents — the
-            // money block, approvals array, and Mongo internals are noise here.
-            const summaries = links.map((a) => ({
-                agreementId: a.agreementId,
-                status: a.status,
-                proposalStatus: a.proposalStatus,
-                parties: {
-                    creatorAgent: a.parties?.creatorAgent ?? null,
-                    providerAgent: a.parties?.providerAgent ?? null,
-                    creator: a.parties?.creator ?? null,
-                    proposedTo: a.parties?.proposedTo ?? null,
-                },
-                ...(a.description ? { description: a.description } : {}),
-                createdAt: a.createdAt,
-            }));
-            const hasActive = links.some((a) => a.status === 'active');
-            return textResult({
-                count: summaries.length,
-                status: resolvedStatus,
-                links: summaries,
-                ...(hasActive
-                    ? {
-                        nextSteps: 'A link is reach-only. Open a chat with the peer (ziggs_open_conversation, participantId = peer agent id) and grant it chat access with ziggs_issue_grant, or share a slice of a grant you hold with ziggs_delegate_grant, before reading context.',
-                    }
-                    : {}),
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_revoke_link', 'Revoke a bilateral link agreement — agent-to-agent trust, NOT a third-party service connection (DELETE /agreements/:agreementId). Either party may revoke; cross-org reach ends immediately. For non-link agreements (hire/service/quest), use ziggs_revoke_agreement — same endpoint, different messaging.', {
-        agreementId: z
-            .string()
-            .describe('agreementId of the link agreement (from ziggs_list_links)'),
-    }, DESTRUCTIVE, async ({ agreementId }) => {
-        try {
-            const result = await revokeAgreement(agreementId, creds);
-            return textResult({
-                status: 'revoked',
-                message: 'Link revoked — unpublished cross-org reach to this peer is blocked again.',
-                agreementId,
-                agreement: result.agreement,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-}
-/** ZIG-433 — agent search + context grant management through MCP. */
+/** ZIG-433 / ZIG-956 — agent search + context grant management through MCP.
+ * The SDK-twin tools (search/get, links, delegate) come from the shared
+ * capability layer; only the human-authority grant tools (issue/revoke) stay
+ * MCP-local. */
 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 the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with — so you can find a teammate or another user\'s delegate by name and ziggs_open_conversation with it directly, even if it is unpublished/offline and has never been in a chat with you. Passing an EXACT agent id resolves that one agent even if unpublished/private — use this for a delegate someone shared an id for, then ziggs_request_link if not yet linked. Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `linked`, or `managed`; it is not a blanket "published" label. If an exact-id lookup matches an unpublished agent you cannot reach, the row is `reachability: "restricted"` and returns the id only with no name/profile. Use returned agentId in grant/issue tools — do not guess ids.', {
-        query: z.string().describe('Keyword/natural-language search (published store + your org-mates + your linked delegates) OR an exact agent id (resolves that agent even if unpublished, when you can reach it)'),
-        limit: z.number().optional().describe('Max results (default server-side)'),
-        minScore: z.number().optional().describe('Minimum match score filter'),
-    }, READ_ONLY, async ({ query, limit, minScore }) => {
-        try {
-            const client = new AgentSearchClient(creds.operatorKey, creds.agentId);
-            const result = await client.searchAgents(query, { limit, minScore });
-            if (!result.success) {
-                return toolError(result.error ?? result.message ?? 'search failed');
-            }
-            if (!result.agents?.length) {
-                // ZIG-664: a bare {count: 0} reads as "discovery is down" to LLM
-                // callers — say what was searched and how to recover instead.
-                return textResult({
-                    count: 0,
-                    agents: [],
-                    searched: ['published store', 'your org-mates', 'your linked delegates'],
-                    hint: 'Zero hits means no agent profile matched these terms — discovery itself is up. ' +
-                        'Matching is lexical against agent name/description/tags, so try shorter or different keywords. ' +
-                        'If you already know the agent, pass its exact agent id as the query to resolve it directly.',
-                });
-            }
-            return textResult({
-                count: result.agents.length,
-                agents: result.agents,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_get_agent', 'Fetch the full profile of ONE agent by its exact id (GET /agents/:id) — name, description, tags, capabilities, reachability, and reliability. Use to confirm a candidate before ziggs_propose_agreement / ziggs_request_link, when you already hold the agent id (from ziggs_search_agents, a grant, or an agreement party). Grant-scoped: an id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use ziggs_search_agents.', {
-        agentId: z.string().describe('Exact agent id to fetch — do not guess'),
-    }, READ_ONLY, async ({ agentId }) => {
-        try {
-            const client = new AgentSearchClient(creds.operatorKey, creds.agentId);
-            const result = await client.getAgentById(agentId);
-            if (!result.success) {
-                return toolError(result.error ?? 'agent not found');
-            }
-            const { success: _success, ...agent } = result;
-            return textResult({ agent });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    registerCapabilities(server, DISCOVERY_CAPABILITIES, creds);
     server.tool('ziggs_issue_grant', 'Issue bounded context access. Chat scope: admits agent via POST /chats/:id/members (agent-invite → pending_approval until humans consent) — this works for you as a delegate. Agreement/org scope: issuing a NEW root grant is a human-authority action; if you are acting for a principal you are denied (AGENT_LACKS_HUMAN_AUTHORITY) — instead use ziggs_delegate_grant to hand a peer a narrower slice of a grant you already hold, or ask your human to issue it. Defaults: from-now, narrow scope.', {
         holderId: z.string().describe('Bare agent id receiving the grant'),
         scopeKind: grantScopeKindSchema,
@@ -269,10 +60,7 @@ export function registerTrustTools(server, creds, cfg) {
             // ZIG-941 #6 — an org scope may be named rather than pasted as org_… id.
             let resolvedScopeId = scopeId;
             if (scopeKind === 'org') {
-                const resolved = await resolveOrgScope(creds, scopeId);
-                if ('error' in resolved)
-                    return resolved.error;
-                resolvedScopeId = resolved.scopeId;
+                resolvedScopeId = await resolveOrgScopeId({ creds, surface: 'mcp' }, scopeId);
             }
             const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
             const grant = await client.issueGrant({
@@ -291,58 +79,12 @@ export function registerTrustTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_delegate_grant', 'Delegate a narrower child grant from one you hold (POST /context/grants/:id/delegate). Delegation only narrows scope/expiry/temporal — never broadens. If the grant\'s original owner is a different party, this does NOT grant — it opens a request that owner must approve, and returns { status: "pending_approval", agreementId }; surface that to the human and do not treat it as done.', {
-        parentGrantId: z.string(),
-        holderId: z.string().describe('Agent receiving the delegated grant'),
-        scopeKind: grantScopeKindSchema,
-        scopeId: z.string(),
-        temporal: contextTemporalSchema.describe('from-now or from-start (must be same-or-narrower)'),
-        expiresAt: z.string().optional().nullable(),
-        watermarkAt: z
-            .string()
-            .optional()
-            .describe('from-now watermark ISO-8601 (optional; server may default)'),
-    }, WRITE, async ({ parentGrantId, holderId, scopeKind, scopeId, temporal, expiresAt, watermarkAt, }) => {
-        try {
-            // ZIG-941 #6 — an org scope may be named rather than pasted as org_… id.
-            let resolvedScopeId = scopeId;
-            if (scopeKind === 'org') {
-                const resolved = await resolveOrgScope(creds, scopeId);
-                if ('error' in resolved)
-                    return resolved.error;
-                resolvedScopeId = resolved.scopeId;
-            }
-            const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
-            const result = await client.delegateGrant(parentGrantId, {
-                holderId,
-                scope: { kind: scopeKind, id: resolvedScopeId },
-                temporal,
-                expiresAt,
-                watermarkAt,
-            });
-            if (result.status === 'pending_approval') {
-                return textResult({
-                    status: 'pending_approval',
-                    message: "This grant's original owner must approve sharing it. A request was opened for them — surface it to the human; nothing is granted yet.",
-                    parentGrantId,
-                    agreementId: result.agreementId,
-                    ownerId: result.ownerId,
-                });
-            }
-            const grant = result.grant;
-            return textResult({
-                status: 'delegated',
-                parentGrantId,
-                grant,
-                bounds: contextBounds(grant),
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    registerCapability(server, contextDelegateCapability, creds);
     if (!cfg?.coreOnly) {
-        registerLinkTools(server, creds, webUrl);
+        // ZIG-941 #7 — the link tool group is skipped by the lean session-start
+        // tier (ZIGGS_MCP_CORE_ONLY). Definitions live in the shared capability
+        // layer, including the linkSummary shaping the mutations now share.
+        registerCapabilities(server, LINK_CAPABILITIES, creds, { webUrl });
     }
     server.tool('ziggs_revoke_grant', 'Revoke a context grant and its descendants (DELETE /context/grants/:id). You can revoke (narrow) any grant you hold — this needs no special scope. Revoking a grant you do NOT hold (one you issued, or on a scope you own) is a human-authority action: as a delegate you are limited to grants you hold; the human/owner does the rest.', {
         grantId: z.string(),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.3.2",
-  "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
+  "version": "0.5.0",
+  "description": "MCP server for Claude Code, Cursor, and other MCP hosts \u2014 act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
     "ziggs-mcp": "./dist/index.js"
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.3.1",
+    "@ziggs-ai/api-client": "^0.5.0",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },

package/dist/orgs.d.ts

@@ -1,28 +0,0 @@
-import { type Creds } from '@ziggs-ai/api-client';
-export interface MyOrg {
-    orgId: string;
-    name: string;
-    kind: string;
-    role?: string;
-}
-/**
- * ZIG-739 — the operator's full org membership (not just granted scopes, which
- * is all ziggs_list_grants sees). Lets the delegate resolve an org name to
- * an id and offer a pick-list instead of demanding a pasted org_... id.
- */
-export declare function fetchMyOrgs(creds: Creds): Promise<MyOrg[]>;
-export type OrgResolution = {
-    status: 'ok';
-    orgId: string;
-} | {
-    status: 'ambiguous';
-    matches: MyOrg[];
-} | {
-    status: 'not-found';
-};
-/**
- * ZIG-739 — resolve an org selector (exact org_... id OR a name/handle) against
- * the operator's memberships. Exact id wins; otherwise case-insensitive name
- * match. Ambiguous names return the candidates rather than guessing.
- */
-export declare function resolveOrgSelector(orgs: MyOrg[], selector: string): OrgResolution;

package/dist/orgs.js

@@ -1,44 +0,0 @@
-import { getBackendUrl } from '@ziggs-ai/api-client';
-/**
- * ZIG-739 — the operator's full org membership (not just granted scopes, which
- * is all ziggs_list_grants sees). Lets the delegate resolve an org name to
- * an id and offer a pick-list instead of demanding a pasted org_... id.
- */
-export async function fetchMyOrgs(creds) {
-    const url = `${getBackendUrl()}/orgs/me`;
-    const res = await fetch(url, {
-        method: 'GET',
-        headers: {
-            Authorization: `Bearer ${creds.operatorKey}`,
-            'X-Agent-Id': creds.agentId,
-        },
-    });
-    const body = await res.text().catch(() => '');
-    if (!res.ok) {
-        throw new Error(`GET /orgs/me ${res.status} ${body.slice(0, 200)}`);
-    }
-    const parsed = body ? JSON.parse(body) : {};
-    return (parsed.orgs ?? []).map((o) => ({
-        orgId: o.orgId,
-        name: o.name,
-        kind: o.kind,
-        role: o.role,
-    }));
-}
-/**
- * ZIG-739 — resolve an org selector (exact org_... id OR a name/handle) against
- * the operator's memberships. Exact id wins; otherwise case-insensitive name
- * match. Ambiguous names return the candidates rather than guessing.
- */
-export function resolveOrgSelector(orgs, selector) {
-    const byId = orgs.find((o) => o.orgId === selector);
-    if (byId)
-        return { status: 'ok', orgId: byId.orgId };
-    const needle = selector.toLowerCase();
-    const byName = orgs.filter((o) => o.name.toLowerCase() === needle);
-    if (byName.length === 1)
-        return { status: 'ok', orgId: byName[0].orgId };
-    if (byName.length > 1)
-        return { status: 'ambiguous', matches: byName };
-    return { status: 'not-found' };
-}