mcp-azeth

Instructions

Implementation Reference

• src/tools/registry.ts:257-405 (handler)

  The handler for `azeth_discover_services`, which queries the Azeth API with fallback to on-chain registry discovery, including metadata overlay and reputation enrichment.

  server.registerTool(
    'azeth_discover_services',
    {
      description: [
        'Find services, agents, and infrastructure on the trust registry by capability, entity type, and reputation.',
        '',
        'Use this when: You need to find a participant that offers a specific capability (e.g., "swap", "price-feed"),',
        'or you want to browse available services filtered by type and minimum reputation score.',
        '',
        'Returns: Array of registry entries with token ID, owner, entity type, name, capabilities, endpoint, and status.',
        '',
        'Note: This queries the Azeth server API. Set AZETH_SERVER_URL env var if the server is not at the default location.',
        'Results are ranked by reputation score. No private key is required for read-only discovery.',
        '',
        'Example: { "capability": "price-feed" } or { "entityType": "service", "minReputation": 50, "limit": 5 }',
      ].join('\n'),
      inputSchema: z.object({
        chain: z.string().optional().describe('Target chain. Defaults to AZETH_CHAIN env var or "baseSepolia". Accepts "base", "baseSepolia", "ethereumSepolia", "ethereum" (and aliases like "base-sepolia", "eth-sepolia", "sepolia", "eth", "mainnet").'),
        capability: z.string().max(128).optional().describe('Filter by capability (e.g., "swap", "price-feed", "translation").'),
        entityType: z.enum(['agent', 'service', 'infrastructure']).optional().describe('Filter by participant type.'),
        minReputation: z.coerce.number().min(0).max(100).optional().describe('Minimum reputation score (0-100). Higher means more trusted.'),
        limit: z.coerce.number().int().min(1).max(100).optional().describe('Maximum number of results. Defaults to 10.'),
        offset: z.coerce.number().int().min(0).optional().describe('Number of results to skip for pagination. Defaults to 0.'),
      }),
    },
    async (args) => {
      try {
        const serverUrl = process.env['AZETH_SERVER_URL'] ?? 'https://api.azeth.ai';
        const chainName = resolveChain(args.chain);
  
        // Create a public client for the on-chain fallback
        const { createPublicClient, http } = await import('viem');
        const chain = resolveViemChain(chainName);
        const rpcUrl = process.env[RPC_ENV_KEYS[chainName]] ?? SUPPORTED_CHAINS[chainName].rpcDefault;
        const publicClient = createPublicClient({ chain, transport: http(rpcUrl) });
  
        const result = await discoverServicesWithFallback(
          serverUrl,
          {
            capability: args.capability,
            entityType: args.entityType as 'agent' | 'service' | 'infrastructure' | undefined,
            minReputation: args.minReputation,
            limit: args.limit ?? 10,
            offset: args.offset,
          },
          // Cast needed: viem's chain-specific PublicClient has extra tx types
          // that are a superset of the generic Chain type the SDK expects
          publicClient as any,
          chainName,
        );
  
        // Deduplicate entries: when the same entity appears multiple times
        // (e.g., registered from both EOA and smart account), keep the entry
        // with the highest tokenId (most recent) per owner+name pair.
        const deduped = new Map<string, typeof result.entries[number]>();
        for (const entry of result.entries) {
          const key = `${entry.owner?.toLowerCase() ?? ''}:${entry.name?.toLowerCase() ?? ''}`;
          const existing = deduped.get(key);
          if (!existing || BigInt(entry.tokenId) > BigInt(existing.tokenId)) {
            deduped.set(key, entry);
          }
        }
        const uniqueEntries = [...deduped.values()];
  
        // ── Overlay per-key metadata updates for on-chain fallback results ──
        if (result.source === 'on-chain' && uniqueEntries.length <= 10) {
          const overlayRegistryAddr = ERC8004_REGISTRY[chainName] as `0x${string}`;
          await Promise.all(
            uniqueEntries.map(async (entry) => {
              try {
                await overlayMetadataUpdates(publicClient as any, overlayRegistryAddr, BigInt(entry.tokenId), entry as unknown as Record<string, unknown>);
              } catch { /* non-fatal */ }
            }),
          );
        }
  
        // ── Optional reputation enrichment ──
        // For small result sets (≤10), fetch weighted reputation for each entry.
        // Non-fatal: if reputation is unavailable for any entry, it's set to null.
        const reputationModuleAddr = AZETH_CONTRACTS[chainName].reputationModule;
        const shouldEnrich = uniqueEntries.length <= 10
          && !!reputationModuleAddr
          && reputationModuleAddr !== ('' as `0x${string}`);
        const DEFAULT_REPUTATION = { weightedValue: '0', weightedValueFormatted: '0', totalWeight: '0', totalWeightFormatted: '0', opinionCount: '0' };
        const reputationMap = new Map<string, { weightedValue: string; weightedValueFormatted: string; totalWeight: string; totalWeightFormatted: string; opinionCount: string }>();
  
        if (shouldEnrich) {
          await Promise.all(
            uniqueEntries.map(async (entry) => {
              try {
                const tid = BigInt(entry.tokenId);
                if (tid === 0n) return;
                const rep = await publicClient.readContract({
                  address: reputationModuleAddr,
                  abi: ReputationModuleAbi,
                  functionName: 'getWeightedReputationAll',
                  args: [tid],
                }) as readonly [bigint, bigint, bigint];
                const [weightedValue, totalWeight, opinionCount] = rep;
                // Format weighted value using same heuristic as reputation.ts
                const absValue = weightedValue < 0n ? -weightedValue : weightedValue;
                const isHighPrecision = absValue > 10n ** 15n;
                const weightedValueFormatted = isHighPrecision
                  ? formatTokenAmount(weightedValue, 18, 4)
                  : weightedValue.toString();
                // Format totalWeight as USD with adaptive precision
                const totalWeightFormatted = formatTokenAmount(totalWeight, 12, 2);
                reputationMap.set(String(entry.tokenId), {
                  weightedValue: weightedValue.toString(),
                  weightedValueFormatted,
                  totalWeight: totalWeight.toString(),
                  totalWeightFormatted,
                  opinionCount: opinionCount.toString(),
                });
              } catch { /* reputation not available for this entry */ }
            }),
          );
        }
  
        const requestedLimit = args.limit ?? 10;
        // hasMore: true if the API returned a full page (before dedup), suggesting more results exist
        const hasMore = result.entries.length >= requestedLimit;
  
        return success({
          count: uniqueEntries.length,
          hasMore,
          source: result.source,
          offset: args.offset ?? 0,
          limit: requestedLimit,
          ...(result.minReputationIgnored ? { warning: 'minReputation filter is not supported in on-chain fallback mode and was ignored.' } : {}),
          services: uniqueEntries.map((s) => ({
            tokenId: String(s.tokenId),
            owner: s.owner,
            entityType: s.entityType,
            name: s.name,
            description: s.description ?? '',
            capabilities: s.capabilities,
            endpoint: s.endpoint,
            pricing: s.pricing,
            catalog: s.catalog ?? null,
            active: s.active,
            reputation: reputationMap.get(String(s.tokenId)) ?? (s.reputation ?? DEFAULT_REPUTATION),
          })),
        });
      } catch (err) {
        return handleError(err);
      }
    },
  );