Arbitrum MCP Server

Instructions

Implementation Reference

• src/index.ts:523-540 (handler)

  MCP tool handler for 'arbtrace_replayTransaction': resolves RPC URL or chain name to RPC, creates NitroNodeClient instance, calls its replayTransaction method with txHash and traceTypes (defaulting to ['trace']), and returns the result as JSON-formatted text content.

  case "arbtrace_replayTransaction": {
    const rpcUrl = await this.resolveRpcUrl(
      (args.rpcUrl as string) || (args.chainName as string)
    );
    const nodeClient = new NitroNodeClient(rpcUrl);
    const result = await nodeClient.replayTransaction(
      args.txHash as string,
      (args.traceTypes as string[]) || ["trace"]
    );
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/index.ts:1267-1296 (schema)

  Input schema definition for the arbtrace_replayTransaction MCP tool, specifying properties for rpcUrl (optional), chainName (optional), txHash (required), and traceTypes (optional array).

    name: "arbtrace_replayTransaction",
    description:
      "Replay and trace a specific transaction (requires trace API)",
    inputSchema: {
      type: "object" as const,
      properties: {
        rpcUrl: {
          type: "string",
          description:
            "The RPC URL of the Arbitrum node (optional if default is set)",
        },
        chainName: {
          type: "string",
          description:
            "Chain name (e.g., 'Xai', 'Arbitrum One') - will auto-resolve to RPC URL",
        },
        txHash: {
          type: "string",
          description: "Transaction hash to replay",
        },
        traceTypes: {
          type: "array",
          description:
            "Array of trace types (e.g., ['trace', 'stateDiff'])",
          items: { type: "string" },
        },
      },
      required: ["txHash"],
    },
  },

• src/clients/nitro-node-client.ts:277-295 (handler)

  NitroNodeClient.replayTransaction method: core implementation that performs the actual RPC call to the Nitro node's 'arbtrace_replayTransaction' method with txHash and traceTypes parameters, returning traces or error.

  async replayTransaction(
    txHash: string,
    traceTypes: string[]
  ): Promise<TraceResult> {
    try {
      const traces = await this.makeRpcCall("arbtrace_replayTransaction", [
        txHash,
        traceTypes,
      ]);
      return { traces };
    } catch (error) {
      return {
        traces: null,
        error: `Trace replayTransaction not supported on this RPC endpoint: ${
          (error as Error).message
        }`,
      };
    }
  }

• src/clients/nitro-node-client.ts:488-527 (helper)

  Utility method makeRpcCall used by all client methods to perform HTTP POST RPC requests to the Nitro node RPC endpoint.

    private async makeRpcCall(method: string, params: any[]): Promise<any> {
      try {
        const requestBody = {
          jsonrpc: "2.0",
          id: Date.now(),
          method,
          params,
        };
  
        console.error(`Making RPC call to ${this.rpcUrl}: ${method}`);
        
        const response = await fetch(this.rpcUrl, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify(requestBody),
        });
  
        if (!response.ok) {
          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
  
        const data = await response.json();
  
        if (data.error) {
          throw new Error(`RPC Error: ${data.error.message}`);
        }
  
        return data.result;
      } catch (error) {
        console.error(`RPC call failed for ${method} on ${this.rpcUrl}:`, error);
        if (error instanceof Error) {
          throw error;
        } else {
          throw new Error(`Unknown error during RPC call: ${String(error)}`);
        }
      }
    }
  }