hexforge-mcp

专为二进制安全 / 逆向工程场景打造的十六进制计算 MCP 服务器。让 AI 大模型把精确计算交给工具完成,不再靠"心算"做地址运算、进制转换和位操作。

特性

• 机器字语义:所有运算按 2^bits 取模回绕,模拟真实 CPU 寄存器溢出
• 双解释输出:每个结果同时给出 hex / 无符号十进制 / 有符号十进制 / 二进制
• 输入宽容:接受 0x41、4142、41 42、\x41\x42 等常见格式
• 安全求值:表达式基于 AST 白名单解析,杜绝代码注入
• 零依赖启动:只需 Python ≥ 3.10 和 mcp 包

工具一览

工具	用途	示例
evaluate	算术/位运算表达式(+ - * / % ** & | ^ ~ << >>、括号),按位宽回绕	(0x400000 + 0x1234) & ~0xfff → 0x401000
convert	进制转换(hex/dec/bin/oct),可选位宽有符号解释	0xff @8位 → 有符号 -1
bit_rotate	循环移位 ROL / ROR	rol(0x12345678, 8) → 0x34567812
bytes_swap	字节序翻转(大小端互换)	0x11223344 → 0x44332211
pack_value	数值打包为字节(u8~u64 / i8~i64 / f32 / f64,大小端)	0x11223344 as u32 LE → 44332211
unpack_value	字节解包为数值(pack 的逆操作)	44332211 as u32 LE → 0x11223344
xor_data	循环密钥 XOR(Shellcode 解码、混淆字符串还原)	68656c6c6f ⊕ 00 → hello
align	地址对齐(向上/向下/检查)	0x1234 @ 0x1000 向上 → 0x2000

evaluate 语义说明

• / 与 // 均为无符号整除(操作数按无符号机器字处理)
• >> 为逻辑右移;<< 移位超位宽时结果为 0(回绕语义)
• 一元 -x 等价于 (-x) & mask,~x 等价于 mask ^ x
• bits 参数 1~4096,默认 64

安装与配置

依赖:Python ≥ 3.10,pip install mcp(本项目仅用此一个依赖)。

Claude Desktop

在 claude_desktop_config.json 中加入:

{
  "mcpServers": {
    "hexforge": {
      "command": "python",
      "args": ["path/to/hexforge-mcp/hexforge_mcp/server.py"]
    }
  }
}

Kimi Code / 其他 MCP 客户端

同上,command 为 python,args 指向 hexforge_mcp/server.py 的绝对路径即可。也可以在仓库根目录使用模块方式启动:

{
  "mcpServers": {
    "hexforge": {
      "command": "python",
      "args": ["-m", "hexforge_mcp.server"],
      "cwd": "path/to/hexforge-mcp"
    }
  }
}

安装为命令后也可以使用:pip install . 然后 command 填 hexforge-mcp。

开发与测试

# 单元测试(66 个用例)
python -m pytest -q

# 端到端冒烟测试:通过 stdio 真实启动 server 并调用工具
python tests/smoke_client.py

项目结构

hexforge-mcp/
├── hexforge_mcp/
│   ├── core.py      # 纯计算逻辑(不依赖 mcp,可独立测试)
│   └── server.py    # FastMCP 入口,将 core 包装为 8 个 MCP 工具
├── pyproject.toml
└── README.md

License

MIT