Python MCP Utils

mcp_utils

Python（Pydantic v2）实现 mcp-utils模式 CUE模式。这个基础库为下游MCP服务器实现所依赖的错误处理、进度跟踪、取消和操作生命周期管理提供了类型安全的数据模型。

特性

• 错误分类 --带代码范围的结构化错误响应（连接、身份验证、查询、数据、系统、操作）
• 进度跟踪 --具有百分比一致性验证和详细程度的指标
• 取消令牌 --合作取消并跟踪原因/来源
• 运行状态 --完整的生命周期管理（创建、运行、暂停、完成、失败、取消），带有经过验证的转换
• MCP通知 --具有可选JSON-RPC包装器的传输无关通知模型
• 不可变模型 --所有类型都是冻结的Pydantic模型，序列化为camelCase以实现线兼容性

安装

pip install mcp_utils

需要Python 3.14+。

快速开始

from mcp_utils import create_operation, transition_operation, LifecycleStatus

# Create and transition an operation
op = create_operation("my_tool")
op = transition_operation(op, LifecycleStatus.RUNNING)
op = transition_operation(op, LifecycleStatus.COMPLETED)

有关详细用法，请参阅 用法.md.

发展

设置

1. 安装uv（如果尚未安装）：

curl -LsSf https://astral.sh/uv/install.sh | sh

1. 创建虚拟环境并安装依赖项：

uv venv
uv sync

开发工具

本项目使用以下开发工具：

• 颈毛：装订和格式化
• 米皮：类型检查（使用pydantic插件）
• pytest：测试
• 左钩：Git钩子用于预提交检查

安装左钩：

# On macOS
brew install lefthook

# On Linux
curl -1sLf 'https://dl.cloudsmith.io/public/evilmartians/lefthook/setup.rpm.sh' | sudo -E bash
sudo yum install lefthook

# Or using go
go install github.com/evilmartians/lefthook@latest

初始化git钩子：

lefthook install

运行测试

pytest

运行Linting和类型检查

# Format code
ruff format .

# Lint code
ruff check .

# Type check
mypy src/mcp_utils

或者一次运行所有检查：

./scripts/build.sh

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试和梳理
5. 提交拉取请求

更新日志

看 更改日志.md 版本历史。