ucon-tools

tests codecov publish

Interfaces alojables para el motor de análisis dimensional ucon.

Documentación · Guía del servidor MCP · Referencia de herramientas

¿Qué es ucon-tools?

ucon es una biblioteca de computación consciente de las unidades para Python. ucon-tools la empaqueta en interfaces que otros sistemas pueden consumir: servidores MCP para agentes de IA, API REST para servicios web, CLI para humanos en una terminal.

Cada interfaz reside en ucon.tools.<interface> y se puede instalar como un extra opcional:

Interfaz	Paquete	Extra	Estado
Servidor MCP	`ucon.tools.mcp`	`ucon-tools[mcp]`	Disponible
API REST	`ucon.tools.rest`	`ucon-tools[rest]`	Planificado
CLI	`ucon.tools.cli`	`ucon-tools[cli]`	Planificado

Servidor MCP

El servidor MCP proporciona a los agentes de IA (Claude, Cursor y otros clientes MCP) conversión de unidades y computación verificadas dimensionalmente.

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 ✓

Instalación

pip install ucon-tools[mcp]

Requiere Python 3.10+.

Configuración

Claude Desktop / Claude Code — añadir a su configuración de MCP:

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

Independiente:

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

Herramientas

Núcleo — conversión y computación:

Herramienta	Descripción
`convert`	Convierte un valor entre unidades compatibles
`compute`	Cálculo de factor-etiqueta de varios pasos con seguimiento dimensional
`decompose`	Construye una cadena de factores a partir de lenguaje natural o entrada estructurada
`check_dimensions`	Comprueba si dos unidades comparten la misma dimensión

Descubrimiento — explora el sistema de unidades:

Herramienta	Descripción
`list_units`	Lista las unidades disponibles, opcionalmente filtradas por dimensión
`list_scales`	Lista los prefijos decimales y binarios del SI
`list_dimensions`	Lista las dimensiones físicas disponibles
`list_constants`	Lista las constantes físicas (CODATA 2022)
`list_formulas`	Lista las fórmulas de dominio registradas

Extensión en tiempo de ejecución — añade unidades y conversiones por sesión:

Herramienta	Descripción
`define_unit`	Registra una unidad personalizada para la sesión
`define_conversion`	Añade un borde de conversión (lineal o afín)
`define_constant`	Define una constante física personalizada
`call_formula`	Llama a una fórmula registrada con tipo dimensional
`reset_session`	Borra todas las unidades, conversiones y constantes definidas en la sesión

Tipo de Cantidad (KOQ) — desambiguación semántica:

Herramienta	Descripción
`define_quantity_kind`	Registra un tipo de cantidad para la desambiguación
`declare_computation`	Declara el tipo de cantidad esperado antes de calcular
`validate_result`	Valida que un resultado coincida con el tipo declarado
`list_quantity_kinds`	Lista los tipos de cantidad registrados
`extend_basis`	Crea una base dimensional extendida
`list_extended_bases`	Lista las bases extendidas definidas en la sesión

Arquitectura

ucon-tools es una capa de interfaz. No reimplementa el análisis dimensional; delega en ucon para toda la resolución de unidades, conversión y álgebra dimensional. Lo que añade es lógica específica de la interfaz: estado de la sesión, manejo de protocolos, sugerencias de error y características orientadas al agente como el solucionador de restricciones decompose y la desambiguación KOQ.

┌───────────────────────────────────────────────────────┐
│                     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  │
               └─────────────────────┘

Desarrollo

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

Ejecución del servidor MCP localmente

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

Licencia

AGPL-3.0. Ver LICENSE.

ucon-mcp