VeChain MCP Server

Instructions

Implementation Reference

• src/tools.ts:103-184 (handler)

  The handler function that implements the core logic of the 'get_account' tool. It normalizes the address, constructs the Thorest API URL for /accounts/{address} with optional revision query param, fetches the data with timeout handling, and returns the JSON response or error details.

  callback: async ({ address, revision }: { address: string, revision: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<[REVISION.Best, REVISION.Justified, REVISION.Finalized]>, z.ZodNumber, z.ZodString]>>> }) => {
      const normalizedAddress = address.startsWith("0x")
          ? address.toLowerCase()
          : `0x${address.toLowerCase()}`;
  
      const base = isMainnet ? vechainConfig.mainnet.thorestApiBaseUrl : vechainConfig.testnet.thorestApiBaseUrl;
      const path = `/accounts/${encodeURIComponent(normalizedAddress)}`;
      const qs = new URLSearchParams();
  
      if (revision !== undefined && revision !== null) {
          qs.set("revision", String(revision));
      }
  
      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: "Account not found (or revision not available)",
                                  address: normalizedAddress,
                                  revision: revision ?? "best",
                              },
                              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 account",
                              reason: String((err as Error)?.message ?? err),
                              url,
                              address: normalizedAddress,
                              revision: revision ?? "best",
                          },
                          null,
                          2
                      ),
                  },
              ],
          };
      } finally {
          clearTimeout(timeout);
      }
  }

• src/tools.ts:82-102 (schema)

  Zod input schema defining the parameters for the 'get_account' tool: required 'address' (validated VeChain address regex) and optional 'revision' (enum, number, or string with default 'best').

  inputSchema: {
      address: z
          .string()
          .regex(vechainConfig.general.addressRegex, "Invalid address: expected 20-byte hex, optional 0x prefix")
          .describe("Account/contract address (20-byte hex, with or without 0x prefix)"),
      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"),
              ])
              .optional()
              .describe(
                  "Revision: best | justified | finalized | block number | block ID (hex). If omitted, best is used."
              )
              .default("best"),
  },

• src/tools.ts:78-185 (registration)

  Registration of the 'get_account' tool as an object in the vechainTools array export, defining name, title, description, inputSchema, and callback handler.

  {
      name: "get_account",
      title: "Retrieve account details",
      description: "Get information about a VeChain account/contract by address. Optionally specify a revision (best | justified | finalized | block number | block ID).",
      inputSchema: {
          address: z
              .string()
              .regex(vechainConfig.general.addressRegex, "Invalid address: expected 20-byte hex, optional 0x prefix")
              .describe("Account/contract address (20-byte hex, with or without 0x prefix)"),
          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"),
                  ])
                  .optional()
                  .describe(
                      "Revision: best | justified | finalized | block number | block ID (hex). If omitted, best is used."
                  )
                  .default("best"),
      },
      callback: async ({ address, revision }: { address: string, revision: z.ZodDefault<z.ZodOptional<z.ZodUnion<[z.ZodEnum<[REVISION.Best, REVISION.Justified, REVISION.Finalized]>, z.ZodNumber, z.ZodString]>>> }) => {
          const normalizedAddress = address.startsWith("0x")
              ? address.toLowerCase()
              : `0x${address.toLowerCase()}`;
  
          const base = isMainnet ? vechainConfig.mainnet.thorestApiBaseUrl : vechainConfig.testnet.thorestApiBaseUrl;
          const path = `/accounts/${encodeURIComponent(normalizedAddress)}`;
          const qs = new URLSearchParams();
  
          if (revision !== undefined && revision !== null) {
              qs.set("revision", String(revision));
          }
  
          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: "Account not found (or revision not available)",
                                      address: normalizedAddress,
                                      revision: revision ?? "best",
                                  },
                                  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 account",
                                  reason: String((err as Error)?.message ?? err),
                                  url,
                                  address: normalizedAddress,
                                  revision: revision ?? "best",
                              },
                              null,
                              2
                          ),
                      },
                  ],
              };
          } finally {
              clearTimeout(timeout);
          }
      }
  },