Bankless Onchain MCP Server

Instructions

Implementation Reference

• src/operations/contracts.ts:319-365 (handler)

  The main handler function 'getSource' that performs the API call to retrieve contract source code from the Bankless API.

  export async function getSource(
      network: string,
      contract: string
  ): Promise<ContractSourceResponse> {
      const token = process.env.BANKLESS_API_TOKEN;
  
      if (!token) {
          throw new BanklessAuthenticationError('BANKLESS_API_TOKEN environment variable is not set');
      }
  
      const endpoint = `${BASE_URL}/chains/${network}/get_source/${contract}`;
  
      try {
          const response = await axios.get(
              endpoint,
              {
                  headers: {
                      'Content-Type': 'application/json',
                      'X-BANKLESS-TOKEN': `${token}`
                  }
              }
          );
  
          return response.data;
      } catch (error) {
          if (axios.isAxiosError(error)) {
              const statusCode = error.response?.status || 'unknown';
              const errorMessage = error.response?.data?.message || error.message;
  
              if (statusCode === 401 || statusCode === 403) {
                  throw new BanklessAuthenticationError(`Authentication Failed: ${errorMessage}`);
              } else if (statusCode === 404) {
                  throw new BanklessResourceNotFoundError(`Not Found: ${errorMessage}`);
              } else if (statusCode === 422) {
                  throw new BanklessValidationError(`Validation Error: ${errorMessage}`, error.response?.data);
              } else if (statusCode === 429) {
                  // Extract reset timestamp or default to 60 seconds from now
                  const resetAt = new Date();
                  resetAt.setSeconds(resetAt.getSeconds() + 60);
                  throw new BanklessRateLimitError(`Rate Limit Exceeded: ${errorMessage}`, resetAt);
              }
  
              throw new Error(`Bankless API Error (${statusCode}): ${errorMessage}`);
          }
          throw new Error(`Failed to get contract source: ${error instanceof Error ? error.message : String(error)}`);
      }
  }

• src/operations/contracts.ts:81-84 (schema)

  Zod schema defining the input parameters for the 'get_source' tool: network and contract address.

  export const GetSourceSchema = z.object({
      network: z.string().describe('The blockchain network (e.g., "ethereum", "base")'),
      contract: z.string().describe('The contract address'),
  });

• src/index.ts:92-96 (registration)

  Registration of the 'get_source' tool in the list of available tools, specifying name, description, and input schema.

  {
      name: "get_source",
      description: "Gets the source code for a given contract on a specific network",
      inputSchema: zodToJsonSchema(contracts.GetSourceSchema),
  },

• src/index.ts:180-189 (registration)

  Dispatch logic in the MCP server request handler that routes 'get_source' calls to the contracts.getSource function.

  case "get_source": {
      const args = contracts.GetSourceSchema.parse(request.params.arguments);
      const result = await contracts.getSource(
          args.network,
          args.contract
      );
      return {
          content: [{type: "text", text: JSON.stringify(result, null, 2)}],
      };
  }