fp-conv

fp-conv-mcp

[npm]

A Model Context Protocol (MCP) server that gives AI agents direct, local tools for floating-point conversions. It is the server-side companion to the fp-conv web app and reuses the same conversion library.

Encode, decode, and convert numbers across FP32, FP64, FP16, BF16, TF32, FP8, FP6, FP4, MX scale/element types, signed/unsigned ints, and custom formats. Supports rounding modes, overflow (saturation) behavior, and calculates precision loss.

Tools

For convert_format, the source is either a value, constructed using the input format's standard defaults, or bits, a binary or hex bit pattern in the input format used exactly as given; exactly one of the two is required. Its roundingMode and overflowMode parameters apply only when encoding the output format. encode_number applies those parameters to its sole format.

convert_format also takes nanMode, which decides what a NaN source becomes: canonical (default) gives the output format's canonical quiet NaN, and preserve keeps the sign and as many high-order payload bits as fit, quieted (IEEE 754-2019 §6.2.3). A NaN's sign and payload exist only in its bit pattern, so give it as bits: { "bits": "0xFFC00000", "inputFormat": "fp32", "outputFormat": "fp16", "nanMode": "preserve" } returns 0xFE00, where canonical returns 0x7E00. See NaN behavior.

Formats

All tools accept either a preset key (string) or a custom format object.

Preset keys

Custom formats

For floating-point:

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

For integers:

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

Precision note: encoding, decoding and conversion are exact at every width. A value a JSON number could not name exactly (a 64-bit integer's maximum, a mantissa wider than 53 bits, a magnitude outside fp64's range) is returned as a decimal digit string rather than a rounded number. Every flag in a custom format, when given, must be a JSON boolean.

Client configuration

Refer to the following examples with details on how to configure the MCP server:

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 (local only)

Alternatively, the server can run a local Streamable HTTP endpoint:

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

Security: The HTTP transport has no authentication and binds to 127.0.0.1 by default. Do not bind it to a non-loopback interface unless you add your own authentication and understand the implications.

To block DNS-rebinding and cross-site requests from web pages, the server refuses (403) a request whose Host is not a loopback name or the --host address, and one whose Origin names any other host. A wildcard bind (--host 0.0.0.0) cannot know its own names, so it skips the Host check and only accepts an Origin that is loopback or matches the Host. Request bodies are capped at 1 MiB, and a session idle for 30 minutes is closed.

Usage

Once connected, you can ask an agent things like:

• "Encode 3.14159 as bf16 and show the binary."
• "What does the fp16 bit-pattern 0x3E00 decode to?"
• "Convert 0.1 from fp32 to fp8 e4m3 and tell me the precision loss."
• "List all supported formats."

Debugging

Use the MCP Inspector:

npx @modelcontextprotocol/inspector npx fp-conv-mcp

Then open the Tools tab, click List Tools, and try any tool.

Development

This package lives in the fp-conv repository as an npm workspace. The published bundle (dist/index.js) inlines the shared conversion engine (lib/floating-point.js) and tool definitions (src/webmcp.js) from the repo root via esbuild, keeping a single source of truth.

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

License

MIT © Spencer Williams