Bitcoin MCP Server

Instructions

Implementation Reference

• src/server/tools.ts:107-128 (handler)

  MCP handler function for the decode_tx tool. Validates input schema and delegates to BitcoinService.decodeTx, then formats the response.

  export async function handleDecodeTx(
    bitcoinService: BitcoinService,
    args: unknown
  ) {
    const result = DecodeTxSchema.safeParse(args);
    if (!result.success) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Invalid parameters: ${result.error.message}`
      );
    }
  
    const tx = bitcoinService.decodeTx(result.data.rawHex);
    return {
      content: [
        {
          type: "text",
          text: `Decoded transaction:\nTXID: ${tx.txid}\nVersion: ${tx.version}\nInputs: ${tx.inputs.length}\nOutputs: ${tx.outputs.length}\nLocktime: ${tx.locktime}`,
        },
      ] as TextContent[],
    };
  }

• src/types.ts:122-124 (schema)

  Zod schema for validating input to decode_tx tool: requires rawHex string.

  export const DecodeTxSchema = z.object({
    rawHex: z.string().min(1, "Raw transaction hex is required"),
  });

• src/server/base.ts:136-145 (registration)

  Tool registration in listToolsRequestHandler: defines name, description, and inputSchema for decode_tx.

    name: "decode_tx",
    description: "Decode a Bitcoin transaction",
    inputSchema: {
      type: "object",
      properties: {
        rawHex: { type: "string", description: "Transaction hex" },
      },
      required: ["rawHex"],
    },
  } as Tool,

• src/server/base.ts:206-207 (registration)

  Tool call handler registration: switch case dispatches decode_tx calls to handleDecodeTx.

  case "decode_tx": {
    return handleDecodeTx(this.bitcoinService, args);

• src/services/bitcoin.ts:137-163 (helper)

  Core implementation of transaction decoding using bitcoinjs-lib Transaction.fromHex, extracts txid, inputs, outputs, etc.

  decodeTx(rawHex: string): DecodedTx {
    try {
      const tx = bitcoin.Transaction.fromHex(rawHex);
  
      return {
        txid: tx.getId(),
        version: tx.version,
        inputs: tx.ins.map((input) => ({
          txid: Buffer.from(input.hash).reverse().toString("hex"),
          vout: input.index,
          sequence: input.sequence,
        })),
        outputs: tx.outs.map((output) => ({
          value: output.value,
          scriptPubKey: output.script.toString("hex"),
          address: this.tryGetAddress(output.script),
        })),
        locktime: tx.locktime,
      };
    } catch (error) {
      logger.error({ error, rawHex }, "Failed to decode transaction");
      throw new BitcoinError(
        "Failed to decode transaction",
        BitcoinErrorCode.DECODE_ERROR
      );
    }
  }