# ieee754-toolbox

一个面向**逆向工程 / 二进制分析**场景的 IEEE 754 浮点工具箱 MCP 服务器。

让支持 MCP 的 AI 助手（WorkBuddy、Claude Desktop、Cursor 等）能够精确完成浮点常量的编码、解码与逐位拆解——patch 二进制浮点常量时不再靠手算。

## 工具一览

| 工具 | 功能 | 典型场景 |
|------|------|----------|
| `float_to_hex` | 十进制数 → float / double 十六进制编码 | patch 前计算目标值的机器码（如 10.2 → `0x41233333` / `0x4024666666666666`） |
| `hex_to_float` | 十六进制 → 十进制浮点值 | 确认反汇编中立即数对应的浮点值 |
| `float_bit_breakdown` | 逐位拆解符号位 / 指数 / 尾数字段 | 深入理解 IEEE 754 编码结构（指数偏移、隐含前导位） |

## 环境要求

- Python >= 3.10
- `mcp` >= 2.0（注意：mcp 2.x 中 `FastMCP` 已改名为 `MCPServer`，本项目使用 2.x API）

## 安装

```bash
pip install -r requirements.txt
```

## 配置 MCP 客户端

在客户端的 MCP 配置文件中添加（WorkBuddy 为 `~/.workbuddy/mcp.json`，Claude Desktop 为 `claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "ieee754-toolbox": {
      "command": "python",
      "args": ["C:/path/to/ieee754-toolbox/server.py"]
    }
  }
}
```

将 `command` 换成你的 Python 解释器绝对路径（建议使用虚拟环境），`args` 换成 `server.py` 的实际路径。配置后重启客户端，并在连接器管理页面信任该服务器。

## 冒烟测试（不依赖客户端）

直接用管道向服务器发送 JSON-RPC 消息验证：

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoketest","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"float_to_hex","arguments":{"value":10.2}}}' \
  | python server.py
```

预期输出：initialize 响应（含 serverInfo）、3 个工具的清单、`float_to_hex` 返回 `0x41233333` 与 `0x4024666666666666`。

## 使用示例

配置完成后，直接对 AI 助手说自然语言即可：

- "把 3.14 编成 double 的机器码" → 调用 `float_to_hex`
- "0x4024666666666666 是多少" → 调用 `hex_to_float`
- "拆解一下 0x41233333 这个 float 的字段" → 调用 `float_bit_breakdown`

## 背景知识

IEEE 754 浮点数由符号位、指数（带偏移量：float=127，double=1023）、尾数（含隐含前导 1）组成。同一个十进制数在 float（32位）与 double（64位）中编码完全不同——本工具箱帮你免手算处理两种格式。

## License

MIT