VeChain MCP Server

Instructions

Implementation Reference

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

  The handler function for the 'get_account' tool. Normalizes the address, constructs the Thorest API URL with optional revision, fetches the account data, handles errors and timeouts, 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 validating the address (regex for 20-byte hex) 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)

  Full tool registration object in the vechainTools array, including name, title, description, inputSchema, and inline 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); } } },