fp-conv

fp-conv-mcp

一个 Model Context Protocol（MCP）服务，为 AI Agent 提供用于浮点数转换的本地工具。它是 fp-conv 网页应用的服务端配套工具，并复用了相同的转换库。

可对 FP32、FP64、FP16、BF16、TF32、FP8、FP6、FP4、MX 缩放／元素类型、有符号／无符号整数和自定义格式进行编码、解码和转换。支持舍入模式、溢出（饱和）行为，并可计算精度损失。

工具

工具	描述
list_formats	列出所有可用的格式预设（键、名称、类别、参数）。
get_format_info	获取格式的详细信息（偏置、范围、特殊值支持情况）。
encode_number	将十进制值（或 Infinity／NaN）编码为指定格式。返回二进制、十六进制和各组成部分。
decode_bits	将二进制或十六进制位模式解码为指定格式。返回十进制值和各组成部分。
convert_format	将值从一种格式转换为另一种格式。

对于 convert_format，输入可以是 value（使用输入格式的标准默认值构造），也可以是 bits（按原样使用的输入格式二进制或十六进制位模式）；两者必须且只能提供一个。roundingMode 和 overflowMode 参数仅在对输出格式进行编码时生效。encode_number 会将这些参数应用于其唯一的格式。

convert_format 还接受 nanMode，用于决定 NaN 输入如何转换：canonical（默认值）使用输出格式的规范静默 NaN；preserve 则保留符号和尽可能多的高位有效载荷位，并将其置为静默 NaN（IEEE 754-2019 §6.2.3）。NaN 的符号和有效载荷仅存在于其位模式中，因此请通过 bits 传入： { "bits": "0xFFC00000", "inputFormat": "fp32", "outputFormat": "fp16", "nanMode": "preserve" } 会返回 0xFE00；若使用 canonical，则会返回 0x7E00。请参阅 NaN 行为。

格式

所有工具都接受预设键（字符串）或自定义格式对象。

预设键

类别	键
IEEE 754	"fp64"、"fp32"、"fp16"
ML	"bf16"、"tf32"
OCP	"fp8_e5m2"、"fp8_e4m3"、"fp6_e3m2"、"fp6_e2m3"、"fp4_e2m1"、"e8m0"、"mxint8"
整数	"int32"、"uint32"、"int16"、"uint16"、"int8"、"uint8"、"int4"、"uint4"

自定义格式

对于浮点数：

{ "signBits": 1, "exponentBits": 5, "mantissaBits": 10, "bias": 15, "hasInfinity": true, "hasNaN": true }

字段	必需	描述
signBits	否	符号位数，0 或 1（默认为 1）
exponentBits	是	指数位数
mantissaBits	是	尾数（小数）位数
bias	否	指数偏置；默认为 2^(exponentBits-1) - 1
hasInfinity	否	格式是否可以表示 ±Infinity（默认为 true）
hasNaN	否	格式是否可以表示 NaN（默认为 true）。当设置 hasInfinity 时，由布局决定：带有尾数字段时为 true（此处传入 false 会报错），不带尾数字段时为 false
hasSubnormals	否	指数字段为 0 时是否表示次正规数/零区域（默认为 true）。对于 E8M0 这类缩放类型，请设为 false。

对于整数：

{ "bits": 16, "signed": true }

字段	必需	描述
bits	是	总位宽（1–64）
signed	否	有符号二进制补码为 true，无符号为 false（默认为 true）
fractionBits	否	隐式 2^-fractionBits 缩放（默认为 0；MXINT8 使用 6）
symmetric	否	不使用最小负数编码，使取值范围对称（默认为 false）

精度说明： 编码、解码和转换在任何位宽下都是精确的。JSON 数字无法精确表示的值（例如 64 位整数的最大值、宽于 53 位的尾数、超出 fp64 范围的数值）会以十进制数字字符串的形式返回，而不是经过舍入的数字。自定义格式中的每个标志（如果提供）都必须是 JSON 布尔值。

客户端配置

请参考以下示例，了解如何配置 MCP 服务：

VS Code（.vscode/mcp.json）

{
  "servers": {
    "fp-conv": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "fp-conv-mcp"]
    }
  }
}

Claude Code

claude mcp add fp-conv -- npx -y fp-conv-mcp

GitHub Copilot CLI

copilot mcp add fp-conv -- npx -y fp-conv-mcp

Cursor（.cursor/mcp.json）/ Windsurf / Claude Desktop

{
  "mcpServers": {
    "fp-conv": {
      "command": "npx",
      "args": ["-y", "fp-conv-mcp"]
    }
  }
}

Antigravity（~/.gemini/config/mcp_config.json）

{
  "mcpServers": {
    "fp-conv": {
      "command": "npx",
      "args": ["-y", "fp-conv-mcp"]
    }
  }
}

Streamable HTTP（仅限本地）

此外，服务也可以运行本地 Streamable HTTP 端点：

npm install -g fp-conv-mcp
fp-conv-mcp --http --host 127.0.0.1 --port 3001
# endpoint: http://127.0.0.1:3001/mcp

安全性： HTTP 传输没有身份验证，默认绑定到 127.0.0.1。除非添加自己的身份验证并了解其影响，否则不要将其绑定到非环回接口。

为阻止 DNS 重绑定和来自网页的跨站请求，服务会拒绝（403）Host 不是环回名称或 --host 地址的请求，以及 Origin 指向其他任何主机的请求。通配符绑定（--host 0.0.0.0）无法得知自身名称，因此会跳过 Host 检查，且仅接受 Origin 为环回地址或与 Host 匹配的请求。请求正文上限为 1 MiB，空闲 30 分钟的会话将被关闭。

使用方法

连接后，你可以向 Agent 提出如下问题：

• “将 3.14159 编码为 bf16，并显示二进制表示。”
• “位模式 0x3E00 解码为 fp16 后是什么值？”
• “将 0.1 从 fp32 转换为 fp8 e4m3，并告诉我精度损失。”
• “列出所有受支持的格式。”

调试

使用 MCP Inspector：

npx @modelcontextprotocol/inspector npx fp-conv-mcp

然后打开 Tools 选项卡，点击 List Tools，再试用任意工具。

开发

此软件包位于 fp-conv 仓库中，是一个 npm 工作区。发布的 bundle（dist/index.js）会通过 esbuild 内联仓库根目录中的共享转换引擎（lib/floating-point.js）和工具定义（src/webmcp.js），以确保只有一个真实来源。

npm install                         # from the repo root
npm run build --workspace fp-conv-mcp
npm test  --workspace fp-conv-mcp

许可证

MIT © Spencer Williams