Blockchain MCP Server

Instructions

Implementation Reference

• src/cast-commands/fourbyte.ts:89-136 (handler)

  The core handler function for the '4byte-decode' tool. It processes ABI-encoded calldata by cleaning it, extracting the function selector, fetching matching signatures from the 4byte.directory API, and formats a response with possible function signatures and remaining parameter data.

     async ({ calldata }) => {
       try {
         const cleanCalldata = calldata.startsWith('0x') ? calldata.slice(2) : calldata;
         
         if (cleanCalldata.length < 8) {
           return {
             content: [{
               type: "text",
               text: "Error: Calldata must have at least 4 bytes for function selector"
             }],
             isError: true
           };
         }
  
         const selector = cleanCalldata.slice(0, 8);
         const signatures = await this.getFunctionSignatures(selector);
         
         if (signatures.length === 0) {
           return {
             content: [{
               type: "text",
               text: `No function signatures found for selector 0x${selector}, cannot decode`
             }]
           };
         }
  
         const decodingInfo = signatures.map((sig, index) => {
           return `${index + 1}. Possible function signature: ${sig.text_signature}
  Selector: 0x${selector}
  Parameter data: 0x${cleanCalldata.slice(8)}`;
         }).join('\n\n');
  
         return {
           content: [{
             type: "text",
             text: `Calldata decode result:\n\noriginal data: 0x${cleanCalldata}\n\n${decodingInfo}\n\nNote: Need specific ABI definition to fully decode parameter values.`
           }]
         };
       } catch (error) {
         return {
           content: [{
             type: "text",
             text: `error: ${error instanceof Error ? error.message : String(error)}`
           }],
           isError: true
         };
       }
     }

• src/cast-commands/fourbyte.ts:82-88 (schema)

  Input schema for the '4byte-decode' tool, specifying the 'calldata' parameter as a hexadecimal string using Zod validation.

  {
    title: "Decode ABI Calldata",
    description: "Decode ABI-encoded calldata using 4byte.directory",
    inputSchema: {
      calldata: z.string().describe("ABI-encoded calldata (hexadecimal string)")
    }
  },

• src/cast-commands/fourbyte.ts:80-137 (registration)

  The server.registerTool call that registers the '4byte-decode' tool with the MCP server, including its name, schema, and handler function.

   server.registerTool(
     "4byte-decode",
     {
       title: "Decode ABI Calldata",
       description: "Decode ABI-encoded calldata using 4byte.directory",
       inputSchema: {
         calldata: z.string().describe("ABI-encoded calldata (hexadecimal string)")
       }
     },
     async ({ calldata }) => {
       try {
         const cleanCalldata = calldata.startsWith('0x') ? calldata.slice(2) : calldata;
         
         if (cleanCalldata.length < 8) {
           return {
             content: [{
               type: "text",
               text: "Error: Calldata must have at least 4 bytes for function selector"
             }],
             isError: true
           };
         }
  
         const selector = cleanCalldata.slice(0, 8);
         const signatures = await this.getFunctionSignatures(selector);
         
         if (signatures.length === 0) {
           return {
             content: [{
               type: "text",
               text: `No function signatures found for selector 0x${selector}, cannot decode`
             }]
           };
         }
  
         const decodingInfo = signatures.map((sig, index) => {
           return `${index + 1}. Possible function signature: ${sig.text_signature}
  Selector: 0x${selector}
  Parameter data: 0x${cleanCalldata.slice(8)}`;
         }).join('\n\n');
  
         return {
           content: [{
             type: "text",
             text: `Calldata decode result:\n\noriginal data: 0x${cleanCalldata}\n\n${decodingInfo}\n\nNote: Need specific ABI definition to fully decode parameter values.`
           }]
         };
       } catch (error) {
         return {
           content: [{
             type: "text",
             text: `error: ${error instanceof Error ? error.message : String(error)}`
           }],
           isError: true
         };
       }
     }
   );

• src/cast-commands/fourbyte.ts:140-152 (helper)

  Helper method used by the '4byte-decode' (and '4byte') tool to query the 4byte.directory API for function signatures matching the given selector.

    private async getFunctionSignatures(selector: string): Promise<FourByteResult[]> {
      const response = await fetch(
        `${this.baseUrl}/signatures/?hex_signature=0x${selector}&format=json`
      );
  
      if (!response.ok) {
        throw new Error(`4byte API request failed: ${response.status} ${response.statusText}`);
      }
  
      const data = await response.json() as FourByteResponse;
      return data.results || [];
    }
  } 

• src/cast-commands/fourbyte.ts:5-18 (schema)

  TypeScript interfaces defining the structure of responses from the 4byte.directory API, used for type safety in the tool implementation.

  interface FourByteResult {
    id: number;
    created_at: string;
    text_signature: string;
    hex_signature: string;
    bytes_signature: string;
  }
  
  interface FourByteResponse {
    count: number;
    next: string | null;
    previous: string | null;
    results: FourByteResult[];
  }