hexforge-mcp

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

特性

• 机器字语义:所有运算按 2^bits 取模回绕,模拟真实 CPU 寄存器溢出

• 双解释输出:每个结果同时给出 hex / 无符号十进制 / 有符号十进制 / 二进制

• 输入宽容:接受 0x41、4142、41 42、\x41\x42 等常见格式

• 安全求值:表达式基于 AST 白名单解析,杜绝代码注入

• 零依赖启动:只需 Python ≥ 3.10 和 mcp 包

Related MCP server: mcp-capstone

工具一览

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