feat: Add get_cmc_metadata_v2 tool for enhanced cryptocurrency metadata retrieval (#67)

- Introduced CMCMetadataV2Schema for detailed validation of cryptocurrency metadata.
- Implemented GetMetadataV2ToolSchema to fetch comprehensive metadata including logos, descriptions, and social links.
- Updated CMCBaseTool to register the new metadata retrieval tool.
- Expanded unit tests to validate functionality and ensure robust error handling for the new tool.

Author: nicky-ru

src/tools/__tests__/cmc.test.ts

@@ -104,7 +104,7 @@ describe("CMCBaseTool", () => {
     expect(cmcTool.description).toContain(
       "Fetches token mapping data from CoinMarketCap"
     );
-    expect(cmcTool.schema).toHaveLength(1);
+    expect(cmcTool.schema).toHaveLength(2);
     expect(cmcTool.schema[0].name).toBe("get_cmc_token_map");
   });
 
@@ -305,4 +305,94 @@ describe("CMCBaseTool", () => {
       expect(result.tokens[0].platform).toBeNull();
     });
   });
+
+  describe("getMetadataV2", () => {
+    const executionOptions = {
+      toolCallId: "test-call-id",
+      messages: [],
+      llm: new LLMService(llmServiceParams),
+    };
+    const mockMetadataResponse = {
+      status: {
+        timestamp: "2024-03-20T12:00:00.000Z",
+        error_code: 0,
+        error_message: null,
+        elapsed: 10,
+        credit_count: 1,
+        notice: null,
+      },
+      data: {
+        BTC: {
+          id: 1,
+          name: "Bitcoin",
+          symbol: "BTC",
+          category: "coin",
+          description: "Bitcoin description",
+          slug: "bitcoin",
+          logo: "https://example.com/btc.png",
+          subreddit: "bitcoin",
+          notice: "",
+          tags: ["store-of-value"],
+          "tag-names": ["Store of Value"],
+          "tag-groups": ["CATEGORY"],
+          urls: {
+            website: ["https://bitcoin.org"],
+            twitter: ["https://twitter.com/bitcoin"],
+          },
+          platform: null,
+          date_added: "2013-04-28T00:00:00.000Z",
+          twitter_username: "bitcoin",
+          is_hidden: 0,
+        },
+      },
+    };
+
+    it("should fetch and validate metadata v2 data", async () => {
+      vi.mocked(fetch).mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(mockMetadataResponse),
+      } as Response);
+
+      const result = await cmcTool.schema[1].tool.execute(
+        { id: "1" },
+        executionOptions
+      );
+
+      if (typeof result === "string") {
+        throw new Error("Expected result to be an object");
+      }
+
+      expect(result.metadata).toEqual({
+        timestamp: "2024-03-20T12:00:00.000Z",
+        errorCode: 0,
+        errorMessage: null,
+        elapsed: 10,
+        creditCount: 1,
+        notice: null,
+      });
+
+      expect(result.tokens.BTC).toEqual({
+        id: 1,
+        name: "Bitcoin",
+        symbol: "BTC",
+        category: "coin",
+        description: "Bitcoin description",
+        slug: "bitcoin",
+        logo: "https://example.com/btc.png",
+        subreddit: "bitcoin",
+        notice: "",
+        tags: ["store-of-value"],
+        "tag-names": ["Store of Value"],
+        "tag-groups": ["CATEGORY"],
+        urls: {
+          website: ["https://bitcoin.org"],
+          twitter: ["https://twitter.com/bitcoin"],
+        },
+        platform: null,
+        date_added: "2013-04-28T00:00:00.000Z",
+        twitter_username: "bitcoin",
+        is_hidden: 0,
+      });
+    });
+  });
 });

src/tools/cmc.ts

@@ -7,7 +7,7 @@ import { logger } from "../logger/winston";
 export const CMC_BASE_URL = "https://pro-api.coinmarketcap.com/v1";
 
 const CMCPlatformSchema = z.object({
-  id: z.number().describe("Platform ID"),
+  id: z.union([z.number(), z.string()]).describe("Platform ID"),
   name: z.string().describe("Platform name"),
   symbol: z.string().describe("Platform symbol"),
   slug: z.string().describe("Platform slug"),
@@ -47,6 +47,51 @@ const CMCResponseSchema = z.object({
   }),
 });
 
+const CMCMetadataV2Schema = z.object({
+  data: z.record(
+    z.object({
+      id: z.number().describe("CoinMarketCap ID"),
+      name: z.string().describe("Token name"),
+      symbol: z.string().describe("Token symbol"),
+      category: z.string().describe("Token category"),
+      description: z.string().describe("Token description"),
+      slug: z.string().describe("Token slug"),
+      logo: z.string().optional().describe("Token logo URL"),
+      subreddit: z.string().optional().describe("Token subreddit"),
+      notice: z.string().optional().describe("Token notice"),
+      tags: z.array(z.string()).optional().describe("Token tags"),
+      "tag-names": z.array(z.string()).optional().describe("Token tag names"),
+      "tag-groups": z.array(z.string()).optional().describe("Token tag groups"),
+      urls: z
+        .object({
+          website: z.array(z.string()).optional(),
+          twitter: z.array(z.string()).optional(),
+          message_board: z.array(z.string()).optional(),
+          chat: z.array(z.string()).optional(),
+          facebook: z.array(z.string()).optional(),
+          explorer: z.array(z.string()).optional(),
+          reddit: z.array(z.string()).optional(),
+          technical_doc: z.array(z.string()).optional(),
+          source_code: z.array(z.string()).optional(),
+          announcement: z.array(z.string()).optional(),
+        })
+        .optional(),
+      platform: CMCPlatformSchema.nullable().optional(),
+      date_added: z.string().optional(),
+      twitter_username: z.string().optional(),
+      is_hidden: z.number().optional(),
+    })
+  ),
+  status: z.object({
+    timestamp: z.string(),
+    error_code: z.number(),
+    error_message: z.string().nullable(),
+    elapsed: z.number(),
+    credit_count: z.number(),
+    notice: z.string().nullable(),
+  }),
+});
+
 const GetTokenMapToolSchema = {
   name: "get_cmc_token_map",
   description:
@@ -150,6 +195,62 @@ const GetTokenMapToolSchema = {
   },
 };
 
+const GetMetadataV2ToolSchema = {
+  name: "get_cmc_metadata_v2",
+  description:
+    "Fetches detailed metadata for cryptocurrencies including logo, description, website URLs, and social links.\n" +
+    "If you don't know the token id, use get_cmc_token_map tool to get the token id first.",
+  parameters: z.object({
+    id: z
+      .string()
+      .optional()
+      .describe("Comma-separated CoinMarketCap cryptocurrency IDs"),
+    address: z.string().optional().describe("Contract address"),
+    skip_invalid: z.boolean().optional().default(false),
+    aux: z
+      .string()
+      .optional()
+      .default("urls,logo,description,tags,platform,date_added,notice")
+      .describe(
+        "Only include necessary fields to reduce response size. Can be a single value or comma-separated list"
+      ),
+  }),
+  execute: async (args: {
+    id?: string;
+    slug?: string;
+    symbol?: string;
+    address?: string;
+    skip_invalid?: boolean;
+    aux?: string;
+  }) => {
+    try {
+      const tool = new CMCBaseTool();
+      const response = await tool.getMetadataV2(args);
+      const parsedResponse = CMCMetadataV2Schema.parse(response);
+
+      return {
+        tokens: Object.fromEntries(
+          Object.entries(parsedResponse.data).map(([symbol, tokens]) => [
+            symbol,
+            tokens,
+          ])
+        ),
+        metadata: {
+          timestamp: parsedResponse.status.timestamp,
+          errorCode: parsedResponse.status.error_code,
+          errorMessage: parsedResponse.status.error_message,
+          elapsed: parsedResponse.status.elapsed,
+          creditCount: parsedResponse.status.credit_count,
+          notice: parsedResponse.status.notice,
+        },
+      };
+    } catch (error) {
+      logger.error("Error executing get_cmc_metadata_v2 tool", error);
+      return `Error executing get_cmc_metadata_v2 tool`;
+    }
+  },
+};
+
 type CMCBaseParams = {
   start?: number;
   limit?: number;
@@ -162,6 +263,7 @@ type CMCBaseParams = {
 export class CMCBaseTool extends APITool<CMCBaseParams> {
   schema = [
     { name: GetTokenMapToolSchema.name, tool: tool(GetTokenMapToolSchema) },
+    { name: GetMetadataV2ToolSchema.name, tool: tool(GetMetadataV2ToolSchema) },
   ];
 
   constructor() {
@@ -207,4 +309,37 @@ export class CMCBaseTool extends APITool<CMCBaseParams> {
 
     return await res.json();
   }
+
+  async getMetadataV2(params: {
+    id?: string;
+    slug?: string;
+    symbol?: string;
+    address?: string;
+    skip_invalid?: boolean;
+    aux?: string;
+  }) {
+    const queryParams = new URLSearchParams();
+
+    if (params.id) queryParams.set("id", params.id);
+    if (params.slug) queryParams.set("slug", params.slug);
+    if (params.symbol) queryParams.set("symbol", params.symbol);
+    if (params.address) queryParams.set("address", params.address);
+    if (params.skip_invalid) queryParams.set("skip_invalid", "true");
+    if (params.aux) queryParams.set("aux", params.aux);
+
+    const res = await fetch(
+      `${CMC_BASE_URL}/cryptocurrency/info?${queryParams.toString()}`,
+      {
+        headers: {
+          "X-CMC_PRO_API_KEY": process.env.CMC_API_KEY || "",
+        },
+      }
+    );
+
+    if (!res.ok) {
+      throw new Error(`API request failed with status: ${res.status}`);
+    }
+
+    return await res.json();
+  }
 }