ucon-tools tests codecov publish

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:

Interface	Package	Extra	Status
MCP server	ucon.tools.mcp	ucon-tools[mcp]	Available
REST API	ucon.tools.rest	ucon-tools[rest]	Planned
CLI	ucon.tools.cli	ucon-tools[cli]	Planned

---

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:

Tool	Description
convert	Convert a value between compatible units
compute	Multi-step factor-label calculation with dimensional tracking
decompose	Build a factor chain from natural-language or structured input
check_dimensions	Check if two units share the same dimension

Discovery — explore the unit system:

Tool	Description
list_units	List available units, optionally filtered by dimension
list_scales	List SI decimal and binary prefixes
list_dimensions	List available physical dimensions
list_constants	List physical constants (CODATA 2022)
list_formulas	List registered domain formulas

Runtime extension — add units and conversions per session:

Tool	Description
define_unit	Register a custom unit for the session
define_conversion	Add a conversion edge (linear or affine)
define_constant	Define a custom physical constant
call_formula	Call a registered dimensionally-typed formula
reset_session	Clear all session-defined units, conversions, and constants

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

Tool	Description
define_quantity_kind	Register a quantity kind for disambiguation
declare_computation	Declare expected quantity kind before computing
validate_result	Validate that a result matches the declared kind
list_quantity_kinds	List registered quantity kinds
extend_basis	Create an extended dimensional basis
list_extended_bases	List session-defined extended bases

---

Architecture

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.