ucon-tools

tests codecov publish

Хостируемые интерфейсы для движка размерного анализа ucon.

Документация · Руководство по MCP-серверу · Справочник инструментов

Что такое ucon-tools?

ucon — это библиотека вычислений с учетом единиц измерения для Python. ucon-tools упаковывает её в интерфейсы, которые могут использовать другие системы — MCP-серверы для ИИ-агентов, 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-сервер предоставляет ИИ-агентам (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`	Проверка того, имеют ли две единицы одинаковую размерность

Обнаружение — исследование системы единиц:

Инструмент	Описание
`list_units`	Список доступных единиц, опционально с фильтрацией по размерности
`list_scales`	Список десятичных и двоичных приставок СИ
`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