# 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` 中加入:

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

### Kimi Code / 其他 MCP 客户端

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

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

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

## 开发与测试

```bash
# 单元测试(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