ucon-tools

Hostable interfaces for the ucon dimensional analysis engine.

Documentation · MCP Server Guide · Tool Reference

What is ucon-tools?

ucon is a unit-aware computation library for Python. ucon-tools packages it into interfaces that other systems can consume — MCP servers for AI agents, REST APIs for web services, CLIs for humans at a terminal.

Each interface lives under ucon.tools.<interface> and is installable as an optional extra:

MCP Server

The MCP server gives AI agents (Claude, Cursor, and other MCP clients) dimensionally-verified unit conversion and computation.

Agent: "Convert 5 mcg/kg/min for an 80 kg patient to mL/h. Drug is 400 mg in 250 mL."

  decompose → constraint solver places quantities, auto-bridges mcg→mg and min→h
  compute   → 5 × 80 kg × (60 min/h) × (1 mg/1000 mcg) × (250 mL/400 mg) = 15 mL/h
  validate  → result dimension matches expected unit ✓

Installation

pip install ucon-tools[mcp]

Requires Python 3.10+.

Configuration

Claude Desktop / Claude Code — add to your MCP configuration:

{
  "mcpServers": {
    "ucon": {
      "command": "uvx",
      "args": ["--from", "ucon-tools[mcp]", "ucon-mcp"]
    }
  }
}

Standalone:

ucon-mcp                    # stdio transport (default)
ucon-mcp --transport sse    # SSE transport for remote clients

Tools

Core — conversion and computation:

Discovery — explore the unit system:

Runtime extension — add units and conversions per session:

Kind-of-Quantity (KOQ) — semantic disambiguation:

Unit systems — inspect and scope the active system:

All deprecated tools remain functional until v1.0.0 and return identical payloads to their replacements, leaving a ten-tool surface: convert, compute, decompose, check_dimensions, discover, define, system, call_formula, validate_result, reset_session. See ROADMAP.md for the migration table and what lands before then.

Architecture

The MCP server is embeddable: create_server(ServerConfig(...)) builds an independent server with your own base unit system, per-call instrumentation, and transport settings — see the embedding guide.

ucon-tools is an interface layer. It does not reimplement dimensional analysis — it delegates to ucon for all unit resolution, conversion, and dimensional algebra. What it adds is interface-specific logic: session state, protocol handling, error suggestions, and agent-oriented features like the decompose constraint solver and KOQ disambiguation.

┌───────────────────────────────────────────────────────┐
│                     Clients                           │
│   MCP (Claude, Cursor)  ·  HTTP  ·  Terminal          │
└──────────┬──────────────────┬──────────────┬──────────┘
           │                  │              │
┌──────────▼───┐   ┌──────────▼───┐  ┌───────▼──────┐
│ ucon.tools   │   │ ucon.tools   │  │ ucon.tools   │
│     .mcp     │   │     .rest    │  │     .cli     │
│              │   │              │  │              │
│  sessions    │   │  (planned)   │  │  (planned)   │
│  decompose   │   │              │  │              │
│  KOQ         │   │              │  │              │
│  suggestions │   │              │  │              │
└──────┬───────┘   └──────┬───────┘  └──────┬───────┘
       │                  │                 │
       └──────────────────┼─────────────────┘
                          │ Python imports
               ┌──────────▼──────────┐
               │        ucon         │
               │                     │
               │  Units, Dimensions  │
               │  ConversionGraph    │
               │  Scales, Constants  │
               └─────────────────────┘

UnitSafe Benchmark

UnitSafe is a 500-problem metrological reasoning benchmark for evaluating how well AI models handle unit conversion, dimensional analysis, and kind-of-quantity discrimination. It ships with a runner that can evaluate any model with or without MCP tool augmentation.

pip install ucon-tools[benchmark]

# Bare evaluation (model solves from memory)
python benchmarks/unitsafe/run.py -m claude:claude-haiku-4-5-20251001

# Tool-augmented evaluation (model uses MCP tools)
python benchmarks/unitsafe/run.py -m claude:claude-haiku-4-5-20251001 \
  --tools --mcp-url https://mcp.ucon.dev/mcp/<instance>/mcp

See benchmarks/unitsafe/ for the full dataset, runner, and evaluation protocol.

Development

make venv                               # Create virtual environment
source .ucon-tools-3.12/bin/activate    # Activate
make test                               # Run tests
make test-all                           # Run across all supported Python versions

Running the MCP server locally

make mcp-server                         # Foreground (stdio)
make mcp-server-bg                      # Background
make mcp-server-stop                    # Stop background server

License

AGPL-3.0. See LICENSE.