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`	检查两个单位是否具有相同的量纲

发现 — 探索单位系统：

工具	描述
`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

ucon-tools

什么是 ucon-tools？

MCP 服务器

安装

配置

工具

架构

开发

在本地运行 MCP 服务器

许可证

Resources

Latest Blog Posts

MCP directory API