ucon-tools

tests codecov publish

ucon 次元解析エンジンのためのホスト可能なインターフェース。

ucon-toolsとは？

ucon は、Python向けの単位認識計算ライブラリです。ucon-tools は、AIエージェント用のMCPサーバー、Webサービス用のREST API、ターミナルユーザー用のCLIなど、他のシステムが利用できるインターフェースとしてパッケージ化します。

各インターフェースは ucon.tools.<interface> 配下にあり、オプションの追加機能としてインストール可能です：

インターフェース	パッケージ	追加機能	ステータス
MCPサーバー	`ucon.tools.mcp`	`ucon-tools[mcp]`	利用可能
REST API	`ucon.tools.rest`	`ucon-tools[rest]`	計画中
CLI	`ucon.tools.cli`	`ucon-tools[cli]`	計画中

MCPサーバー

MCPサーバーは、AIエージェント（Claude、Cursor、およびその他の MCP クライアント）に対して、次元的に検証された単位変換と計算機能を提供します。

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 ✓

インストール

pip install ucon-tools[mcp]

Python 3.10以上が必要です。

設定

Claude Desktop / Claude Code — MCP設定に追加してください：

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

スタンドアロン:

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

ツール

コア — 変換と計算：

ツール	説明
`convert`	互換性のある単位間で値を変換
`compute`	次元追跡を伴う多段階の因子ラベル計算
`decompose`	自然言語または構造化入力から因子チェーンを構築
`check_dimensions`	2つの単位が同じ次元を共有しているか確認

探索 — 単位システムを探索：

ツール	説明
`list_units`	利用可能な単位を一覧表示（次元によるフィルタリング可）
`list_scales`	SI接頭辞およびバイナリ接頭辞を一覧表示
`list_dimensions`	利用可能な物理次元を一覧表示
`list_constants`	物理定数を一覧表示 (CODATA 2022)
`list_formulas`	登録済みのドメイン数式を一覧表示

ランタイム拡張 — セッションごとに単位と変換を追加：

ツール	説明
`define_unit`	セッション用のカスタム単位を登録
`define_conversion`	変換エッジ（線形またはアフィン）を追加
`define_constant`	カスタム物理定数を定義
`call_formula`	登録済みの次元型数式を呼び出し
`reset_session`	セッションで定義されたすべての単位、変換、定数をクリア

量種別 (KOQ) — 意味的な曖昧さの解消：

ツール	説明
`define_quantity_kind`	曖昧さ解消のための量種別を登録
`declare_computation`	計算前に期待される量種別を宣言
`validate_result`	結果が宣言された種別と一致するか検証
`list_quantity_kinds`	登録済みの量種別を一覧表示
`extend_basis`	拡張次元基底を作成
`list_extended_bases`	セッションで定義された拡張基底を一覧表示

アーキテクチャ

ucon-tools はインターフェース層です。次元解析を再実装するのではなく、単位の解決、変換、次元代数のすべてを ucon に委譲します。追加されるのは、セッション状態、プロトコル処理、エラーの提案、decompose 制約ソルバーや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  │
               └─────────────────────┘

開発

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

MCPサーバーをローカルで実行する

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

ライセンス

AGPL-3.0。 LICENSE を参照してください。

ucon-mcp