VeChain MCP Server

Instructions

Implementation Reference

• src/tools.ts:326-399 (handler)

  The handler function executes the tool logic by constructing the Thorest API URL for the block endpoint, handling query parameters for expanded transactions and raw format, performing the fetch request with timeout and abort control, parsing the JSON response, and returning formatted content or error messages.

  callback: async ({ revision, expanded = false, raw = false }: { revision: z.ZodDefault<z.ZodUnion<[z.ZodEnum<[REVISION.Best, REVISION.Justified, REVISION.Finalized]>, z.ZodNumber, z.ZodString]>>, expanded?: boolean, raw?: boolean }) => {
      const base = isMainnet ? vechainConfig.mainnet.thorestApiBaseUrl : vechainConfig.testnet.thorestApiBaseUrl;
      const path = `/blocks/${encodeURIComponent(String(revision))}`;
      const qs = new URLSearchParams();
  
      if (typeof expanded === "boolean") qs.set("expanded", String(expanded));
      if (typeof raw === "boolean") qs.set("raw", String(raw));
      const url = `${base}${path}${qs.toString() ? `?${qs.toString()}` : ""}`;
  
      const controller = new AbortController();
      const timeout = setTimeout(() => controller.abort(), isMainnet ? vechainConfig.mainnet.controllerAbortTimeout : vechainConfig.testnet.controllerAbortTimeout);
  
      try {
          const res = await fetch(url, { signal: controller.signal });
  
          if (!res.ok) {
              const bodyText = await res.text().catch(() => "");
              throw new Error(
                  `VeChain node responded ${res.status} ${res.statusText}${bodyText ? `: ${bodyText}` : ""
                  }`
              );
          }
  
          const data = await res.json();
  
          if (data == null) {
              return {
                  content: [
                      {
                          type: "text",
                          text: JSON.stringify(
                              {
                                  message: "Block not found",
                                  revision: String(revision),
                                  expanded,
                                  raw,
                              },
                              null,
                              2
                          ),
                      },
                  ],
              };
          }
  
          return {
              content: [
                  {
                      type: "text",
                      text: JSON.stringify(data, null, 2),
                  },
              ],
          };
      } catch (err) {
          const isAbort = (err as Error)?.name === "AbortError";
          return {
              content: [
                  {
                      type: "text",
                      text: JSON.stringify(
                          {
                              error: isAbort ? "Request timed out" : "Failed to fetch VeChain block",
                              reason: String((err as Error)?.message ?? err),
                              url,
                          },
                          null,
                          2
                      ),
                  },
              ],
          };
      } finally {
          clearTimeout(timeout);
      }

• src/tools.ts:301-325 (schema)

  Zod input schema defining parameters: revision (best/justified/finalized, block number, or ID), optional expanded (boolean for full tx objects), optional raw (boolean for RLP hex).

  inputSchema: {
      revision: z
          .union([
              z.enum([REVISION.Best, REVISION.Justified, REVISION.Finalized]),
              z.number().int().nonnegative(),
              z
                  .string()
                  .min(1)
                  .describe("Block ID (hex) or block number as string"),
          ])
          .describe(
              "Block revision: hex ID, block number, or keywords: best | justified | finalized"
          )
          .default("best"),
      expanded: z
          .boolean()
          .optional()
          .describe(
              "Return transactions expanded (objects) instead of just IDs (default: false)"
          ),
      raw: z
          .boolean()
          .optional()
          .describe("Return RLP-encoded block instead of structured JSON (default: false)"),
  },

• src/server.ts:74-92 (registration)

  Registers the 'get_block' tool (and all vechainTools) with the MCP server using server.registerTool, passing the tool's name, title, description, inputSchema, and a wrapper async handler that calls the tool's callback and standardizes the response content type.

  for (const t of vechainTools) {
    server.registerTool(
      t.name,
      {
        title: t.name,
        description: t.description,
        inputSchema: t.inputSchema
      },
      async (args) => {
        const result = await t.callback(args);
        return {
          content: result.content.map(item => ({
            ...item,
            type: "text" as const
          }))
        };
      }
    );
  }