UluVoiMCP

Instructions

Implementation Reference

• tools/protocols.js:87-133 (handler)

  The handler function for get_protocol_summary tool. It retrieves protocol details, contracts, and assets, then formats them into a human-readable markdown summary with sections for type, website, description, contracts (grouped by type), assets, and tags.

    async ({ protocolId }) => {
      const protocol = findProtocol(protocolId);
      if (!protocol) {
        return toolError(`Unknown protocol: ${protocolId}`);
      }
      const contracts = protocolContracts(protocolId);
      const assets = protocolAssets(protocolId);
  
      const lines = [
        `# ${protocol.name}`,
        ``,
        `**Type:** ${protocol.type}`,
        `**Website:** ${protocol.website || "N/A"}`,
        ``,
        protocol.description,
        ``,
        `## Contracts (${contracts.length})`,
      ];
  
      const byType = {};
      for (const c of contracts) {
        const t = c.type || "other";
        if (!byType[t]) byType[t] = [];
        byType[t].push(c);
      }
      for (const [type, items] of Object.entries(byType)) {
        lines.push(`- **${type}**: ${items.length} contract(s)`);
        for (const item of items.slice(0, 5)) {
          lines.push(`  - ${item.appId}: ${item.name}`);
        }
        if (items.length > 5) {
          lines.push(`  - ... and ${items.length - 5} more`);
        }
      }
  
      if (assets.length > 0) {
        lines.push(``, `## Assets (${assets.length})`);
        for (const a of assets) {
          lines.push(`- ${a.symbol} (${a.assetId}): ${a.name} — ${a.category}`);
        }
      }
  
      lines.push(``, `**Tags:** ${(protocol.tags || []).join(", ")}`);
  
      return { content: [{ type: "text", text: lines.join("\n") }] };
    },
  );

• tools/protocols.js:82-86 (schema)

  Zod schema definition for the protocolId input parameter, requiring a string that describes the protocol identifier (e.g. humble-swap, envoi, aramid-bridge).

  {
    protocolId: z
      .string()
      .describe("Protocol identifier (e.g. humble-swap, envoi, aramid-bridge)"),
  },

• tools/protocols.js:79-133 (registration)

  Registration of the get_protocol_summary tool with the MCP server using server.tool(), including the tool name, description, input schema, and handler function.

  server.tool(
    "get_protocol_summary",
    "Get a human-readable summary of a Voi protocol including its purpose, contracts, and assets",
    {
      protocolId: z
        .string()
        .describe("Protocol identifier (e.g. humble-swap, envoi, aramid-bridge)"),
    },
    async ({ protocolId }) => {
      const protocol = findProtocol(protocolId);
      if (!protocol) {
        return toolError(`Unknown protocol: ${protocolId}`);
      }
      const contracts = protocolContracts(protocolId);
      const assets = protocolAssets(protocolId);
  
      const lines = [
        `# ${protocol.name}`,
        ``,
        `**Type:** ${protocol.type}`,
        `**Website:** ${protocol.website || "N/A"}`,
        ``,
        protocol.description,
        ``,
        `## Contracts (${contracts.length})`,
      ];
  
      const byType = {};
      for (const c of contracts) {
        const t = c.type || "other";
        if (!byType[t]) byType[t] = [];
        byType[t].push(c);
      }
      for (const [type, items] of Object.entries(byType)) {
        lines.push(`- **${type}**: ${items.length} contract(s)`);
        for (const item of items.slice(0, 5)) {
          lines.push(`  - ${item.appId}: ${item.name}`);
        }
        if (items.length > 5) {
          lines.push(`  - ... and ${items.length - 5} more`);
        }
      }
  
      if (assets.length > 0) {
        lines.push(``, `## Assets (${assets.length})`);
        for (const a of assets) {
          lines.push(`- ${a.symbol} (${a.assetId}): ${a.name} — ${a.category}`);
        }
      }
  
      lines.push(``, `**Tags:** ${(protocol.tags || []).join(", ")}`);
  
      return { content: [{ type: "text", text: lines.join("\n") }] };
    },
  );

• lib/registry.js:38-40 (helper)

  findProtocol helper function that searches the protocols list to find a protocol by its ID, returning null if not found.

  export function findProtocol(id) {
    return getProtocols().find((p) => p.id === id) || null;
  }

• lib/registry.js:52-72 (helper)

  protocolContracts and protocolAssets helper functions that filter applications and assets by protocol ID, returning arrays with appId/assetId and their associated info.

  export function protocolContracts(protocolId) {
    const apps = getApplications();
    const results = [];
    for (const [appId, info] of Object.entries(apps)) {
      if (info.protocol === protocolId) {
        results.push({ appId: Number(appId), ...info });
      }
    }
    return results;
  }
  
  export function protocolAssets(protocolId) {
    const a = getAssets();
    const results = [];
    for (const [assetId, info] of Object.entries(a)) {
      if (info.protocol === protocolId) {
        results.push({ assetId: Number(assetId), ...info });
      }
    }
    return results;
  }