AI导哈

类型安全数据模型库

一个基于Python Pydantic v2实现的类型安全数据模型库，提供错误处理、进度跟踪、取消操作和生命周期管理等功能，适用于MCP服务器实现。

  • by thomasbellio
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 thomasbellio/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 版本历史。

相关 MCP