ucon-mcp
Verified unit conversion and dimensional analysis for AI agents. 190+ units, 31 domain formulas (clinical, physics, aerospace, SRE), physical constants with uncertainty propagation. Refuses invalid conversions structurally: the tool that won't convert mg to mL and knows the difference between torque and energy.
Ask AI about ucon-mcp
Powered by Claude Β· Grounded in docs
I know everything about ucon-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
|
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:
| 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.
