@oobe-protocol-labs/sap-mcp-server 0.9.7 → 0.9.9

package/dist/tools/sap-sdk-tools.js

@@ -147,6 +147,40 @@ function summarizeProtocolIndexes(protocolIndexes) {
     }))
         .sort((left, right) => left.protocolId.localeCompare(right.protocolId));
 }
+function normalizeDirectoryToken(value) {
+    return value.trim().toLowerCase();
+}
+function matchesNormalizedValue(values, expected) {
+    const normalizedExpected = normalizeDirectoryToken(expected);
+    return values.some((value) => normalizeDirectoryToken(value) === normalizedExpected);
+}
+function matchesNormalizedSubstring(values, query) {
+    return values.some((value) => normalizeDirectoryToken(value).includes(query));
+}
+function encodeDirectoryCursor(offset) {
+    return encodeDirectoryCursorPayload(offset);
+}
+function decodeDirectoryCursor(cursor) {
+    if (!cursor) {
+        return undefined;
+    }
+    try {
+        const parsed = decodeDirectoryCursorPayload(cursor);
+        const offset = parsed.offset;
+        return typeof offset === 'number' && Number.isInteger(offset) && offset >= 0 ? offset : undefined;
+    }
+    catch {
+        throw new Error('cursor must be a nextCursor value returned by sap_list_all_agents or sap_discover_agents');
+    }
+}
+function encodeDirectoryCursorPayload(offset) {
+    const base64 = Buffer.from(JSON.stringify({ offset }), 'utf-8').toString('base64');
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/u, '');
+}
+function decodeDirectoryCursorPayload(cursor) {
+    const padded = cursor.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(cursor.length / 4) * 4, '=');
+    return JSON.parse(Buffer.from(padded, 'base64').toString('utf-8'));
+}
 /**
  * @name buildAgentDirectoryEntry
  * @description Converts an AgentAccount into a compact directory row with optional stats and protocol-index membership.
@@ -185,14 +219,257 @@ function matchesAgentDirectoryFilters(entry, filters) {
     if (!filters.includeInactive && !entry.isActive) {
         return false;
     }
-    if (filters.protocol && !entry.protocols.includes(filters.protocol) && !entry.indexedProtocols.includes(filters.protocol)) {
+    if (filters.wallet && normalizeDirectoryToken(entry.wallet) !== normalizeDirectoryToken(filters.wallet)) {
+        return false;
+    }
+    if (filters.agentPda && normalizeDirectoryToken(entry.agentPda) !== normalizeDirectoryToken(filters.agentPda)) {
+        return false;
+    }
+    if (filters.hasX402Endpoint !== undefined && Boolean(entry.x402Endpoint) !== filters.hasX402Endpoint) {
         return false;
     }
-    if (filters.capability && !entry.capabilities.includes(filters.capability)) {
+    if (filters.protocol
+        && !matchesNormalizedValue(entry.protocols, filters.protocol)
+        && !matchesNormalizedValue(entry.indexedProtocols, filters.protocol)) {
         return false;
     }
+    const requiredCapabilities = [
+        ...(filters.capability ? [filters.capability] : []),
+        ...(filters.capabilities ?? []),
+    ];
+    if (requiredCapabilities.length > 0) {
+        const mode = filters.capabilityMode ?? 'any';
+        const predicate = (capability) => matchesNormalizedValue(entry.capabilities, capability);
+        if (mode === 'all' ? !requiredCapabilities.every(predicate) : !requiredCapabilities.some(predicate)) {
+            return false;
+        }
+    }
+    const query = filters.query ? normalizeDirectoryToken(filters.query) : undefined;
+    if (query) {
+        const searchableValues = [
+            entry.agentPda,
+            entry.wallet,
+            entry.name,
+            entry.description,
+            entry.agentId,
+            entry.agentUri,
+            entry.x402Endpoint,
+            ...entry.protocols,
+            ...entry.indexedProtocols,
+            ...entry.capabilities,
+            ...entry.activePlugins,
+        ].filter((value) => typeof value === 'string');
+        if (!matchesNormalizedSubstring(searchableValues, query)) {
+            return false;
+        }
+    }
     return true;
 }
+function compactAgentDirectoryEntry(entry) {
+    return {
+        agentPda: entry.agentPda,
+        wallet: entry.wallet,
+        name: entry.name,
+        description: entry.description,
+        agentId: entry.agentId,
+        x402Endpoint: entry.x402Endpoint,
+        isActive: entry.isActive,
+        protocols: entry.protocols,
+        indexedProtocols: entry.indexedProtocols,
+        capabilities: entry.capabilities,
+        reputationScore: entry.reputationScore,
+        totalCallsServed: entry.totalCallsServed,
+        uptimePercent: entry.uptimePercent,
+        createdAt: entry.createdAt,
+    };
+}
+function directoryAgentGuidance(page) {
+    return {
+        paidHostedRead: true,
+        useThisWhen: [
+            'The user asks to find SAP agents, list the ecosystem, inspect available on-chain agents, or discover x402-enabled agents.',
+            'Use query/protocol/capability/capabilities filters first; avoid repeated broad scans.',
+        ],
+        pagination: page.hasMore
+            ? `Call the same tool with cursor="${page.nextCursor}" to fetch the next page.`
+            : 'No further page is available for the current filters.',
+        nextTools: [
+            'sap_get_agent_profile with wallet for one hydrated owner profile.',
+            'sap_fetch_protocol_index with protocolId when the user wants protocol membership.',
+            'sap_fetch_capability_index with capabilityId when the user wants a capability-specific index.',
+            'sap_x402_estimate_cost before calling a paid x402 endpoint exposed by a discovered agent.',
+        ],
+        matchingNotes: {
+            query: 'Matches name, description, agentId, wallet, PDA, endpoint, protocols, capabilities, and active plugin labels.',
+            capability: 'Capability matching is case-insensitive and exact after trimming. For multiple capabilities set capabilityMode to any or all.',
+            x402: 'Set hasX402Endpoint=true to find agents that advertise paid HTTP/x402 resources.',
+        },
+    };
+}
+async function buildAgentDirectoryPage(client, options) {
+    const accounts = getSapAnchorAccounts(client);
+    const [agentAccounts, statsAccounts, protocolIndexes, overview] = await Promise.all([
+        accounts.agentAccount.all(),
+        accounts.agentStats.all(),
+        accounts.protocolIndex.all(),
+        client.discovery.getNetworkOverview(),
+    ]);
+    const statsByAgent = new Map(statsAccounts.map(({ account }) => [account.agent.toBase58(), account]));
+    const indexedProtocolsByAgent = buildProtocolMembership(protocolIndexes);
+    const filteredAgents = agentAccounts
+        .map((account) => buildAgentDirectoryEntry(account, statsByAgent, indexedProtocolsByAgent))
+        .filter((entry) => matchesAgentDirectoryFilters(entry, options))
+        .sort((left, right) => Number(right.createdAt) - Number(left.createdAt));
+    const page = filteredAgents.slice(options.offset, options.offset + options.limit);
+    const hasMore = options.offset + page.length < filteredAgents.length;
+    const nextOffset = hasMore ? options.offset + page.length : null;
+    const nextCursor = nextOffset === null ? null : encodeDirectoryCursor(nextOffset);
+    const agents = options.view === 'compact' ? page.map(compactAgentDirectoryEntry) : page;
+    return {
+        source: 'program.account.agentAccount.all + program.account.protocolIndex.all',
+        overview,
+        filters: {
+            includeInactive: options.includeInactive,
+            protocol: options.protocol ?? null,
+            capability: options.capability ?? null,
+            capabilities: options.capabilities ?? [],
+            capabilityMode: options.capabilityMode ?? 'any',
+            query: options.query ?? null,
+            wallet: options.wallet ?? null,
+            agentPda: options.agentPda ?? null,
+            hasX402Endpoint: options.hasX402Endpoint ?? null,
+            view: options.view,
+        },
+        count: page.length,
+        totalEnumerated: filteredAgents.length,
+        returned: page.length,
+        offset: options.offset,
+        limit: options.limit,
+        truncated: hasMore,
+        pagination: {
+            total: filteredAgents.length,
+            returned: page.length,
+            offset: options.offset,
+            limit: options.limit,
+            hasMore,
+            nextOffset,
+            nextCursor,
+        },
+        totalAgentAccounts: agentAccounts.length,
+        activeAgentAccounts: agentAccounts.filter(({ account }) => account.isActive).length,
+        protocolIndexes: options.includeProtocolIndexes ? summarizeProtocolIndexes(protocolIndexes) : undefined,
+        agents,
+        agentGuidance: directoryAgentGuidance({ hasMore, nextCursor, filters: options }),
+    };
+}
+function parseCapabilityMode(input) {
+    const mode = optionalString(input, 'capabilityMode')?.trim().toLowerCase();
+    if (!mode) {
+        return 'any';
+    }
+    if (mode === 'any' || mode === 'all') {
+        return mode;
+    }
+    throw new Error('capabilityMode must be "any" or "all"');
+}
+function parseOptionalStringArray(input, field) {
+    const value = input[field];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${field} must be an array of strings`);
+    }
+    return value
+        .filter((item) => typeof item === 'string' && item.trim().length > 0)
+        .map((item) => item.trim());
+}
+function parseDirectoryOffset(input) {
+    return Math.max(0, decodeDirectoryCursor(optionalString(input, 'cursor')) ?? optionalNumber(input, 'offset') ?? 0);
+}
+function parseDirectoryView(input) {
+    const view = optionalString(input, 'view');
+    if (!view && input.hydrate === true) {
+        return 'full';
+    }
+    if (!view || view === 'compact') {
+        return 'compact';
+    }
+    if (view === 'full') {
+        return 'full';
+    }
+    throw new Error('view must be "compact" or "full"');
+}
+function parseHasX402Endpoint(input) {
+    return optionalBoolean(input, 'hasX402Endpoint');
+}
+function makeAgentDirectoryInputSchema(defaultLimit) {
+    return {
+        query: {
+            type: 'string',
+            description: 'Optional text search across name, description, agentId, wallet, PDA, x402 endpoint, protocols, capabilities, and active plugins. Example: "XONA" or "creative".',
+        },
+        wallet: {
+            type: 'string',
+            description: 'Optional exact owner wallet public key filter. Use this when a wallet is known; it is the most reliable lookup path.',
+        },
+        agentPda: {
+            type: 'string',
+            description: 'Optional exact SAP agent PDA filter.',
+        },
+        protocol: {
+            type: 'string',
+            description: 'Optional protocol filter matched case-insensitively against agent protocols and protocol-index membership. Example: "jupiter", "creative", "payments".',
+        },
+        capability: {
+            type: 'string',
+            description: 'Optional single capability ID filter matched case-insensitively. Example: "creative:imageGeneration" or "jupiter:swap".',
+        },
+        capabilities: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Optional list of capability IDs. Use capabilityMode="all" when the agent must have every capability.',
+        },
+        capabilityMode: {
+            type: 'string',
+            enum: ['any', 'all'],
+            description: 'How to match the capability/capabilities filters. Defaults to "any".',
+        },
+        hasX402Endpoint: {
+            type: 'boolean',
+            description: 'Optional filter for agents that advertise a paid HTTP/x402 endpoint.',
+        },
+        includeInactive: {
+            type: 'boolean',
+            description: 'Include inactive agents. Defaults to false.',
+        },
+        limit: {
+            type: 'number',
+            description: `Maximum rows to return. Defaults to ${defaultLimit}; hard-capped at 500.`,
+        },
+        offset: {
+            type: 'number',
+            description: 'Zero-based pagination offset. Defaults to 0. Prefer cursor after the first page when nextCursor is returned.',
+        },
+        cursor: {
+            type: 'string',
+            description: 'Opaque pagination cursor returned as pagination.nextCursor by a previous sap_list_all_agents or sap_discover_agents call.',
+        },
+        view: {
+            type: 'string',
+            enum: ['compact', 'full'],
+            description: 'Result shape. Use compact for broad discovery and full for detailed rows. Defaults to compact.',
+        },
+        hydrate: {
+            type: 'boolean',
+            description: 'Deprecated compatibility alias. Use view="full" for full rows or view="compact" for directory rows.',
+        },
+        includeProtocolIndexes: {
+            type: 'boolean',
+            description: 'Include compact protocol index summaries. Defaults to false for sap_discover_agents and true for sap_list_all_agents.',
+        },
+    };
+}
 /**
  * @name asRecord
  * @description Normalizes MCP tool input into an object.
@@ -723,7 +1000,7 @@ function buildSapSdkToolDescription(definition) {
 }
 function getSapSdkToolContext(name) {
     if (name === 'sap_register_agent') {
-        return 'SAP MCP context: This is the primary on-chain SAP agent registration tool for the connected profile signer. Use agentUri or metadataUri for off-chain metadata, including a Metaplex or DAS-backed identity document when the agent also has NFT/collection metadata. After registration, use sap_publish_tool_by_name for advertised MCP capabilities and AgentKit metaplex-nft_* tools for NFT collection, badge, or metadata workflows.';
+        return 'SAP MCP context: This is the primary on-chain SAP agent registration tool for a local profile signer or external signer. Hosted accountless SAP MCP rejects direct registration before x402 payment because OOBE never custodies user wallet keys. Use agentUri or metadataUri for off-chain metadata, including a Metaplex or DAS-backed identity document when the agent also has NFT/collection metadata. After registration, use sap_publish_tool_by_name for advertised MCP capabilities and AgentKit metaplex-nft_* tools for NFT collection, badge, or metadata workflows.';
     }
     if (name === 'sap_update_agent') {
         return 'SAP MCP context: Use this after sap_register_agent to refresh name, description, capabilities, pricing, supported protocols, x402 endpoint, or metadataUri. For NFT-backed identity changes, update the Metaplex asset first when needed, then point the SAP agent metadataUri at the current metadata document.';
@@ -752,7 +1029,7 @@ const agentTools = [
     {
         name: 'sap_register_agent',
         title: 'Register SAP Agent',
-        description: 'Register the connected wallet as a SAP agent using SDK AgentModule.register.',
+        description: 'Local-signer-only: register the connected wallet as a SAP agent using SDK AgentModule.register. Hosted accountless SAP MCP rejects this direct write before x402 payment; run it through a local SAP MCP profile or external signer.',
         inputSchema: {
             name: { type: 'string', description: 'Human-readable name for the SAP agent' },
             description: { type: 'string', description: 'Detailed description of the agent\'s purpose and capabilities' },
@@ -864,107 +1141,59 @@ const discoveryTools = [
     {
         name: 'sap_discover_agents',
         title: 'Discover SAP Agents',
-        description: 'Discover agents by protocol, capability, or capability list. For unfiltered global listing, use sap_list_all_agents.',
-        inputSchema: {
-            protocol: { type: 'string', description: 'Protocol identifier to filter agents by (e.g. "jupiter", "drift")' },
-            capability: { type: 'string', description: 'Single capability ID to filter agents by (e.g. "jupiter:swap")' },
-            capabilities: { type: 'array', items: { type: 'string' }, description: 'Array of capability IDs to filter agents by (requires at least one)' },
-            hydrate: { type: 'boolean', description: 'Whether to include full hydrated agent profiles in results (default: true)' },
-            limit: { type: 'number', description: 'Maximum number of agents to return (default: 50)' },
-        },
+        description: 'Paid hosted discovery for SAP agents. Search and filter the current on-chain AgentAccount directory by query, wallet, protocol, capability, x402 endpoint presence, and cursor pagination. Use this for targeted agent discovery before calling per-agent fetch tools.',
+        inputSchema: makeAgentDirectoryInputSchema(50),
         handler: async (input, client) => {
-            const hydrate = input.hydrate !== false;
-            const limit = optionalNumber(input, 'limit') ?? 50;
-            const capabilities = Array.isArray(input.capabilities)
-                ? input.capabilities.filter((item) => typeof item === 'string' && item.length > 0)
-                : [];
-            const protocol = optionalString(input, 'protocol');
+            const limit = Math.max(1, Math.min(optionalNumber(input, 'limit') ?? 50, 500));
             const capability = optionalString(input, 'capability');
-            if (protocol) {
-                const agents = await client.discovery.findAgentsByProtocol(protocol, { hydrate });
-                return { count: Math.min(agents.length, limit), agents: agents.slice(0, limit) };
-            }
-            if (capability) {
-                const agents = await client.discovery.findAgentsByCapability(capability, { hydrate });
-                return { count: Math.min(agents.length, limit), agents: agents.slice(0, limit) };
-            }
-            if (capabilities.length > 0) {
-                const agents = await client.discovery.findAgentsByCapabilities(capabilities, { hydrate });
-                return { count: Math.min(agents.length, limit), agents: agents.slice(0, limit) };
-            }
-            return {
-                count: 0,
-                agents: [],
-                overview: await client.discovery.getNetworkOverview(),
-                note: 'SDK filtered discovery requires a protocol or capability. For global on-chain directory snapshots, call sap_list_all_agents.',
-            };
+            const capabilities = parseOptionalStringArray(input, 'capabilities');
+            return buildAgentDirectoryPage(client, {
+                includeInactive: input.includeInactive === true,
+                protocol: optionalString(input, 'protocol'),
+                capability,
+                capabilities,
+                capabilityMode: parseCapabilityMode(input),
+                query: optionalString(input, 'query'),
+                wallet: optionalString(input, 'wallet'),
+                agentPda: optionalString(input, 'agentPda'),
+                hasX402Endpoint: parseHasX402Endpoint(input),
+                limit,
+                offset: parseDirectoryOffset(input),
+                view: parseDirectoryView(input),
+                includeProtocolIndexes: input.includeProtocolIndexes === true,
+            });
         },
     },
     {
         name: 'sap_list_agents',
         title: 'List SAP Agents',
-        description: 'Compatibility alias for filtered SAP agent discovery. Requires protocol or capability. Use sap_list_all_agents for a global on-chain directory snapshot.',
-        inputSchema: {
-            protocol: { type: 'string', description: 'Protocol identifier to filter agents by (e.g. "jupiter", "drift")' },
-            capability: { type: 'string', description: 'Single capability ID to filter agents by (e.g. "jupiter:swap")' },
-            capabilities: { type: 'array', items: { type: 'string' }, description: 'Array of capability IDs to filter agents by (requires at least one)' },
-            hydrate: { type: 'boolean', description: 'Whether to include full hydrated agent profiles in results (default: true)' },
-            limit: { type: 'number', description: 'Maximum number of agents to return (default: 50)' },
-        },
+        description: 'Compatibility alias for sap_discover_agents. Supports query, wallet, protocol, capability, x402 endpoint filtering, and cursor pagination.',
+        inputSchema: makeAgentDirectoryInputSchema(50),
         handler: async (input, client) => discoveryTools[3].handler(input, client),
     },
     {
         name: 'sap_list_all_agents',
         title: 'List All SAP Agents',
-        description: 'Enumerate SAP AgentAccount PDAs directly from the on-chain program account set. Use this for current global directory requests such as "list all agents in the SAP ecosystem rn".',
-        inputSchema: {
-            limit: { type: 'number', description: 'Maximum rows to return. Defaults to 100; hard-capped at 500.' },
-            offset: { type: 'number', description: 'Zero-based pagination offset. Defaults to 0.' },
-            includeInactive: { type: 'boolean', description: 'Include inactive agents. Defaults to false.' },
-            protocol: { type: 'string', description: 'Optional protocol filter matched against agent profile protocols and protocol-index membership.' },
-            capability: { type: 'string', description: 'Optional capability ID filter such as jupiter:swap.' },
-            includeProtocolIndexes: { type: 'boolean', description: 'Include compact protocol index summaries. Defaults to true.' },
-        },
+        description: 'Paid hosted global SAP agent directory read. Enumerates current on-chain AgentAccount PDAs and supports query, wallet, protocol, capability, x402 endpoint filtering, compact/full views, and cursor pagination.',
+        inputSchema: makeAgentDirectoryInputSchema(100),
         handler: async (input, client) => {
             const limit = Math.max(1, Math.min(optionalNumber(input, 'limit') ?? 100, 500));
-            const offset = Math.max(0, optionalNumber(input, 'offset') ?? 0);
-            const includeInactive = input.includeInactive === true;
-            const includeProtocolIndexes = input.includeProtocolIndexes !== false;
-            const protocol = optionalString(input, 'protocol');
             const capability = optionalString(input, 'capability');
-            const accounts = getSapAnchorAccounts(client);
-            const [agentAccounts, statsAccounts, protocolIndexes, overview] = await Promise.all([
-                accounts.agentAccount.all(),
-                accounts.agentStats.all(),
-                accounts.protocolIndex.all(),
-                client.discovery.getNetworkOverview(),
-            ]);
-            const statsByAgent = new Map(statsAccounts.map(({ account }) => [account.agent.toBase58(), account]));
-            const indexedProtocolsByAgent = buildProtocolMembership(protocolIndexes);
-            const filteredAgents = agentAccounts
-                .map((account) => buildAgentDirectoryEntry(account, statsByAgent, indexedProtocolsByAgent))
-                .filter((entry) => matchesAgentDirectoryFilters(entry, { includeInactive, protocol, capability }))
-                .sort((left, right) => Number(right.createdAt) - Number(left.createdAt));
-            const page = filteredAgents.slice(offset, offset + limit);
-            return {
-                source: 'program.account.agentAccount.all + program.account.protocolIndex.all',
-                overview,
-                filters: {
-                    includeInactive,
-                    protocol: protocol ?? null,
-                    capability: capability ?? null,
-                },
-                totalEnumerated: filteredAgents.length,
-                totalAgentAccounts: agentAccounts.length,
-                activeAgentAccounts: agentAccounts.filter(({ account }) => account.isActive).length,
-                returned: page.length,
-                offset,
+            return buildAgentDirectoryPage(client, {
+                includeInactive: input.includeInactive === true,
+                protocol: optionalString(input, 'protocol'),
+                capability,
+                capabilities: parseOptionalStringArray(input, 'capabilities'),
+                capabilityMode: parseCapabilityMode(input),
+                query: optionalString(input, 'query'),
+                wallet: optionalString(input, 'wallet'),
+                agentPda: optionalString(input, 'agentPda'),
+                hasX402Endpoint: parseHasX402Endpoint(input),
                 limit,
-                truncated: offset + page.length < filteredAgents.length,
-                protocolIndexes: includeProtocolIndexes ? summarizeProtocolIndexes(protocolIndexes) : undefined,
-                agents: page,
-                note: 'This is global account enumeration, not filtered DiscoveryRegistry lookup. Use sap_discover_agents for protocol/capability search and sap_fetch_protocol_index when you already know a protocol ID.',
-            };
+                offset: parseDirectoryOffset(input),
+                view: parseDirectoryView(input),
+                includeProtocolIndexes: input.includeProtocolIndexes !== false,
+            });
         },
     },
     {