ucon-tools

tests codecov publish

Hostbare Schnittstellen für die ucon Dimensionsanalyse-Engine.

Dokumentation · MCP-Server-Handbuch · Tool-Referenz

Was ist ucon-tools?

ucon ist eine einheitenbewusste Berechnungsbibliothek für Python. ucon-tools verpackt diese in Schnittstellen, die von anderen Systemen genutzt werden können – MCP-Server für KI-Agenten, REST-APIs für Webdienste, CLIs für Menschen am Terminal.

Jede Schnittstelle befindet sich unter ucon.tools.<interface> und ist als optionales Extra installierbar:

Schnittstelle	Paket	Extra	Status
MCP-Server	`ucon.tools.mcp`	`ucon-tools[mcp]`	Verfügbar
REST-API	`ucon.tools.rest`	`ucon-tools[rest]`	Geplant
CLI	`ucon.tools.cli`	`ucon-tools[cli]`	Geplant

MCP-Server

Der MCP-Server bietet KI-Agenten (Claude, Cursor und anderen MCP-Clients) eine dimensionsgeprüfte Einheitenumrechnung und Berechnung.

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]

Erfordert Python 3.10+.

Konfiguration

Claude Desktop / Claude Code — zur MCP-Konfiguration hinzufügen:

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

Eigenständig:

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

Tools

Kern — Umrechnung und Berechnung:

Tool	Beschreibung
`convert`	Wert zwischen kompatiblen Einheiten umrechnen
`compute`	Mehrstufige Faktor-Label-Berechnung mit Dimensionsverfolgung
`decompose`	Erstellen einer Faktorenkette aus natürlichsprachlicher oder strukturierter Eingabe
`check_dimensions`	Prüfen, ob zwei Einheiten dieselbe Dimension haben

Entdeckung — das Einheitensystem erkunden:

Tool	Beschreibung
`list_units`	Verfügbare Einheiten auflisten, optional nach Dimension gefiltert
`list_scales`	SI-Dezimal- und Binärpräfixe auflisten
`list_dimensions`	Verfügbare physikalische Dimensionen auflisten
`list_constants`	Physikalische Konstanten auflisten (CODATA 2022)
`list_formulas`	Registrierte Fachformeln auflisten

Laufzeiterweiterung — Einheiten und Umrechnungen pro Sitzung hinzufügen:

Tool	Beschreibung
`define_unit`	Benutzerdefinierte Einheit für die Sitzung registrieren
`define_conversion`	Umrechnungskante hinzufügen (linear oder affin)
`define_constant`	Benutzerdefinierte physikalische Konstante definieren
`call_formula`	Registrierte, dimensionsgebundene Formel aufrufen
`reset_session`	Alle sitzungsdefinierten Einheiten, Umrechnungen und Konstanten löschen

Art der Größe (Kind-of-Quantity, KOQ) — semantische Disambiguierung:

Tool	Beschreibung
`define_quantity_kind`	Größenart zur Disambiguierung registrieren
`declare_computation`	Erwartete Größenart vor der Berechnung deklarieren
`validate_result`	Validieren, ob ein Ergebnis der deklarierten Art entspricht
`list_quantity_kinds`	Registrierte Größenarten auflisten
`extend_basis`	Erweiterte Dimensionsbasis erstellen
`list_extended_bases`	Sitzungsdefinierte erweiterte Basen auflisten

Architektur

ucon-tools ist eine Schnittstellenschicht. Es implementiert die Dimensionsanalyse nicht neu – es delegiert an ucon für die gesamte Einheitenauflösung, Umrechnung und Dimensionsalgebra. Was es hinzufügt, ist schnittstellenspezifische Logik: Sitzungsstatus, Protokollbehandlung, Fehlervorschläge und agentenorientierte Funktionen wie den decompose-Constraint-Solver und die KOQ-Disambiguierung.

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

Entwicklung

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

Lokales Ausführen des MCP-Servers

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

Lizenz

AGPL-3.0. Siehe LICENSE.

ucon-mcp