Rev Calc

A Model Context Protocol (MCP) server that provides deterministic reverse-engineering, binary-analysis, exploitation, and security-research calculations to Large Language Models (LLMs).

This project is similar in spirit to math-mcp, but focused on calculations that AI assistants often get wrong when reasoning about binaries, patches, addresses, encodings, Windows constants, checksums, and exploit-development primitives.

Features

• Integer packing/unpacking, signedness conversion, and sign extension
• Address alignment and page offset helpers
• PE VA/RVA/file-offset mapping and PE section parsing
• Relative branch displacement calculations
• Patch byte generation for jumps, calls, NOPs, INT3, and RET
• x86/x64 disassembly and inline-hook feasibility checks via iced-x86
• Bitfield extraction and flag decoding
• Windows constants decoding, including PAGE flags, PE section flags, IOCTL, NTSTATUS, HRESULT, and Win32 errors
• Pwn helpers for cyclic patterns, packing/unpacking, base calculations, badchars, glibc safe-linking, chunk sizes, and tcache indexes
• Encoding helpers for hex, base64, URL encoding, UTF-16LE, XOR, and single-byte XOR brute force
• Hashing, entropy, CRC32, and internet checksum helpers

Design Notes for LLMs

This server is intentionally strict and explicit so that AI agents can call tools reliably.

• Large integers should be passed as strings, such as "0x7ff612341000" or "18446744073709551615".
• Byte arrays are represented as hex strings, such as "48 8b 05 18 57 0a 00" or "488b0518570a00".
• Tool names use underscores instead of dots, for example integer_pack_int rather than core.integer.pack_int, for better MCP client compatibility.
• Outputs are JSON-formatted text and usually include both decimal and hexadecimal forms.
• Disassembly tools require explicit bitness where relevant: 16, 32, or 64.

Installation

Clone or place this repository somewhere on your machine, then install dependencies and build:

cd D:\mcp-dev\rev-calc-mcp
npm.cmd install
npm.cmd run build

MCP Configuration

Add the server to your MCP client configuration.

Example TOML configuration:

[mcp_servers.rev_calc]
command = "node"
args = ["D:\\mcp-dev\\rev-calc-mcp\\build\\index.js"]

Example JSON-style configuration:

{
  "rev_calc": {
    "command": "node",
    "args": ["D:\\mcp-dev\\rev-calc-mcp\\build\\index.js"]
  }
}

Replace the path with the actual path to this project on your system.

Development

npm.cmd run build
npm.cmd test
npm.cmd run dev

Available Tools

Integer Tools

Tool	Description	Main Parameters
integer_pack_int	Pack an integer into bytes with selected endian and bit width	value, bits, endian, signed
integer_unpack_int	Unpack bytes into a signed or unsigned integer	bytes, endian, signed
integer_to_signed	Interpret an unsigned value as signed N-bit integer	value, bits
integer_to_unsigned	Convert signed value to N-bit unsigned representation	value, bits
integer_sign_extend	Sign-extend a smaller signed integer to a larger width	value, from_bits, to_bits

Example:

{
  "tool": "integer_pack_int",
  "arguments": {
    "value": "0x12345678",
    "bits": 32,
    "endian": "little"
  }
}

Expected result includes:

{
  "bytes_hex": "78 56 34 12",
  "value_hex": "0x12345678"
}

Alignment Tools

Tool	Description	Main Parameters
align_up	Align a value upward to a boundary	value, alignment
align_down	Align a value downward to a boundary	value, alignment
page_base	Get the base address of the page containing an address	address, page_size
page_offset	Get the offset of an address inside a page	address, page_size

Example: page_offset("0x12345678") returns 0x678.

Address and PE Tools

Tool	Description	Main Parameters
address_va_to_rva	Convert VA to RVA	va, image_base
address_rva_to_va	Convert RVA to VA	rva, image_base
address_rva_to_file_offset	Map PE RVA to file offset using section table	rva, sections, strict, size_of_headers
address_file_offset_to_rva	Map PE file offset to RVA using section table	file_offset, sections, size_of_headers
address_va_to_file_offset	Map VA to file offset using image base and section table	va, image_base, sections, strict, size_of_headers
address_pe_parse_sections	Parse PE headers and section table from file bytes	file

Section objects use this shape:

{
  "name": ".text",
  "virtualAddress": "0x1000",
  "virtualSize": "0x6000",
  "rawDataPtr": "0x400",
  "rawDataSize": "0x6000"
}

Branch Tools

Tool	Description	Main Parameters
branch_rel8	Calculate signed 8-bit relative displacement	src, target, instr_len
branch_rel32	Calculate signed 32-bit relative displacement	src, target, instr_len
branch_check_rel_range	Check whether a target is reachable by rel8 or rel32	src, target, bits, instr_len

For x86/x64 call rel32 and jmp rel32, the default instruction length is 5.

Patch Tools

Tool	Description	Main Parameters
patch_make_jmp_rel32	Generate E9 + rel32 jump bytes	src, target
patch_make_call_rel32	Generate E8 + rel32 call bytes	src, target
patch_make_nop	Generate NOP bytes; supports Intel multi-byte NOPs	length, style
patch_make_int3	Generate 0xCC breakpoint bytes	length
patch_make_ret	Generate C3	none
patch_make_ret_imm16	Generate C2 imm16	imm16
patch_make_jmp_abs64	Generate mov rax, imm64; jmp rax	target
patch_make_call_abs64	Generate mov rax, imm64; call rax	target

Note: patch_make_jmp_abs64 and patch_make_call_abs64 clobber RAX.

Disassembly and Inline Hook Tools

Tool	Description	Main Parameters
disasm_disasm_bytes	Disassemble x86/x64 bytes using iced-x86	bytes, bitness, ip, syntax
disasm_instruction_lengths	Decode instruction lengths	bytes, bitness, ip
disasm_calc_overwrite_len	Calculate how many full instructions are needed for a patch length	instruction_lengths, patch_length
disasm_check_patch_boundary	Check whether a patch cuts an instruction	instruction_lengths, patch_length
disasm_analyze_inline_hook_basic	Analyze rel32 reachability, overwrite length, instruction boundary, RIP-relative risk, and branch/call relocation risk	src, target, bytes, instruction_lengths, bitness, patch_length

Example:

{
  "tool": "disasm_analyze_inline_hook_basic",
  "arguments": {
    "src": "0x1000",
    "target": "0x2000",
    "bytes": "48 8b 05 18 57 0a 00 90",
    "bitness": 64,
    "patch_length": 5
  }
}

This can detect that the overwritten instruction is RIP-relative and may require trampoline relocation.

Bit Tools

Tool	Description	Main Parameters
bits_bit_test	Check whether a bit is set	value, bit
bits_extract_bits	Extract a bit range from an integer	value, start, length
bits_decode_flags	Decode a bitmask using a caller-provided flag table	value, flags

Windows Tools

Tool	Description	Main Parameters
windows_decode_page_protection	Decode Windows PAGE_* memory protection constants	value
windows_decode_section_characteristics	Decode PE section characteristics	value
windows_decode_ioctl	Decode Windows IOCTL / CTL_CODE values	code
windows_encode_ioctl	Encode Windows IOCTL / CTL_CODE values	device_type, function, method, access
windows_decode_memory_allocation_type	Decode Windows MEM_* allocation/type constants	value
windows_decode_file_access	Decode file access and generic access mask flags	value
windows_decode_ntstatus	Decode NTSTATUS severity, facility, code, and common names	value
windows_decode_hresult	Decode HRESULT severity, facility, code, and common names	value
windows_decode_win32_error	Decode common Win32 error codes	value

Example: windows_decode_ioctl("0x222003") decodes DeviceType, Function, Method, and Access.

Pwn Tools

Tool	Description	Main Parameters
pwn_cyclic_create	Create Metasploit-style cyclic pattern	length
pwn_cyclic_find	Find offset in Metasploit-style cyclic pattern	needle, max_length, endian
pwn_cyclic_create_de_bruijn	Create De Bruijn cyclic pattern	length, alphabet, n
pwn_cyclic_find_de_bruijn	Find offset in De Bruijn cyclic pattern	needle, max_length, alphabet, n, endian
pwn_calc_base	Calculate module base from leak and symbol offset	leak_addr, symbol_offset
pwn_calc_symbol_addr	Calculate symbol address from base and offset	base, symbol_offset
pwn_badchar_check	Check payload for bad characters	payload, badchars
pwn_safe_linking_encode	Encode glibc safe-linking pointer	ptr, pos
pwn_safe_linking_decode	Decode glibc safe-linking pointer	encoded, pos
pwn_p32	Pack integer as little-endian uint32	value
pwn_p64	Pack integer as little-endian uint64	value
pwn_u32	Unpack little-endian uint32	bytes, signed
pwn_u64	Unpack little-endian uint64	bytes, signed
pwn_glibc_chunk_size	Calculate glibc malloc chunk size for a request size	request, ptr_size
pwn_glibc_tcache_index	Calculate glibc tcache bin index	size, input_kind, ptr_size
pwn_one_gadget_constraint_helper	Checklist helper for one_gadget constraints	constraints, known_facts

Encoding Tools

Tool	Description	Main Parameters
encoding_hex_encode	Convert text, hex, or base64 input to hex	input, input_format, text_encoding
encoding_hex_decode	Convert hex input to text, hex, or base64	hex, output_format, text_encoding
encoding_base64_encode	Convert text, hex, or base64 input to base64	input, input_format, text_encoding
encoding_base64_decode	Convert base64 input to text, hex, or base64	base64, output_format, text_encoding
encoding_url_encode	URL-encode text	text
encoding_url_decode	URL-decode text	text
encoding_utf16le_decode	Decode UTF-16LE bytes from hex	hex
encoding_xor_with_key	XOR data with a repeating key	data, key
encoding_xor_single_byte_bruteforce	Brute-force single-byte XOR and rank candidates	data, top

Example:

{
  "tool": "encoding_base64_encode",
  "arguments": {
    "input": "6869",
    "input_format": "hex"
  }
}

Expected output includes "base64": "aGk=".

Data Tools

Tool	Description	Main Parameters
data_hash_data	Hash input bytes with MD5, SHA1, or SHA256	data, algorithm
data_hash_file	Hash a local file with MD5, SHA1, or SHA256	path, algorithm
data_entropy	Calculate Shannon entropy for bytes	data
data_crc32	Calculate CRC32	data
data_internet_checksum	Calculate one's-complement internet checksum	data

Safety Note

data_hash_file reads the path supplied by the caller. This is useful for local reverse-engineering workflows, but if you expose this server to untrusted clients, consider restricting file reads to an allowed workspace.

Current Scope

This MCP server is meant to provide calculation and analysis primitives. It does not attempt to exploit targets, modify binaries on disk, or attach to processes by itself.

Current disassembly support is focused on x86/x64 through iced-x86. Other architectures such as ARM, MIPS, and RISC-V would require an additional backend such as Capstone.

Acknowledgements

• iced-x86 / iced-x86 on npm: used as the x86/x64 disassembly backend for disasm_disasm_bytes, disasm_instruction_lengths, and inline-hook analysis helpers.
• math-mcp: inspiration for building small, deterministic MCP calculation tools for AI assistants.