fp-conv

fp-conv-mcp

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

Tool	Description
list_formats	List all available format presets (keys, names, categories, parameters).
get_format_info	Get detailed information about a format (bias, range, special-value support).
encode_number	Encode a decimal value (or Infinity/NaN) into a format. Returns binary, hex, and components.
decode_bits	Decode a binary or hex bit-pattern into a format. Returns the decimal value and components.
convert_format	Convert a value from one format to another.

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

Category	Keys
IEEE 754	"fp64", "fp32", "fp16"
ML	"bf16", "tf32"
OCP	"fp8_e5m2", "fp8_e4m3", "fp6_e3m2", "fp6_e2m3", "fp4_e2m1", "e8m0", "mxint8"
Integer	"int32", "uint32", "int16", "uint16", "int8", "uint8", "int4", "uint4"

Custom formats

For floating-point:

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

Field	Required	Description
signBits	no	Number of sign bits, 0 or 1 (default 1)
exponentBits	yes	Number of exponent bits
mantissaBits	yes	Number of mantissa (fraction) bits
bias	no	Exponent bias; defaults to 2^(exponentBits-1) - 1
hasInfinity	no	Whether the format can represent ±Infinity (default true)
hasNaN	no	Whether the format can represent NaN (default true). Decided by the layout when hasInfinity is set: true with a mantissa field (passing false there is an error), false without one
hasSubnormals	no	Whether exponent field 0 is a subnormal/zero region (default true). Set false for a scale type such as E8M0.

For integers:

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

Field	Required	Description
bits	yes	Total bit width (1–64)
signed	no	true for signed two's-complement, false for unsigned (default true)
fractionBits	no	Implicit 2^-fractionBits scale (default 0; MXINT8 uses 6)
symmetric	no	Leave the most-negative encoding unused so the range is symmetric (default false)

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-mcp
fp-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 root
npm run build --workspace fp-conv-mcp
npm test  --workspace fp-conv-mcp

License

MIT © Spencer Williams