MCP实用程序架构
模型上下文协议（MCP）服务器实用程序的可重用CUE模式。
仓库: https://github.com/thomasbellio/mcp-utils-schema
概述
该模块为MCP服务器中的跨领域问题提供了标准化的、类型安全的模式：
- 错误处理 -带分类的结构化错误响应（1xxx-6xxx）
- 进度跟踪 -带有指标的进度通知
- 取消 -合作取消代币
- 操作状态 -长时间运行操作的生命周期管理
- MCP通知 -标准MCP协议通知
这些模式旨在由任何MCP服务器实现导入，为常见的操作模式提供一致的基础。
先决条件
- CUE v0.9.0或更高版本：https://cuelang.org/docs/install/
- Node.js（用于TypeScript生成）
安装
安装Node.js依赖项：
npm install快速开始
# Validate all schemas
npm run validate
# Generate TypeScript types and JSON Schemas
npm run generate
# Clean generated files
npm run clean在您的项目中使用
将这些模式导入CUE文件：
import (
"github.com/thomasbellio/mcp-utils-schema/base"
"github.com/thomasbellio/mcp-utils-schema/core"
)
#MyTool: {
input: {
cancellationToken: core.#CancellationToken
}
output: {
result: {...}
error?: core.#ErrorResponse
}
}架构组织
基地(base/)
所有模式中使用的基础类型：
- primitives.cue -UUID、时间戳、操作ID、ProgressToken
- system_types.cue -VerbosityMode枚举
核心(core/)
常见MCP服务器模式的核心实用程序模式：
- error_response.cue -使用结构化错误代码进行错误处理（1xxx-6xxx分类法）
- progress_metrics.cue -使用指标和通知进行进度跟踪
- cancelation_token.cue -合作取消模式
- 操作_状态.cue -运营生命周期管理
MCP(mcp/)
MCP协议特定的通知模式：
- 通知.cue -标准MCP通知（进度、取消、错误、状态更改）
错误代码分类
错误遵循具有特定范围的结构化分类：
- 1000-1999：连接错误
- 2000-2999：身份验证错误
- 3000-3999：查询错误
- 4000-4999：数据错误
- 5000-5999：系统错误
- 6000-6999：操作错误
例子：
errorResponse: core.#ErrorResponse & {
code: 1001
message: "Failed to connect to database"
context: {
operation: "connect"
retriesAttempted: 3
}
suggestion: "Check that the database server is running and accessible"
timestamp: "2025-01-15T10:30:00Z"
}进度跟踪
进度通知支持多种详细程度：
- 粗糙的：只有重大阶段变化
- 正常：阶段+百分比更新
- 好：详细指标+信息
- 调试：包括元数据在内的所有内容
例子：
progress: core.#ProgressNotification & {
operationId: "op-550e8400-e29b-41d4-a716-446655440000"
progressToken: "pt-550e8400-e29b-41d4-a716-446655440001"
stage: "processing"
progress: {
current: 42
total: 100
unit: "records"
percentage: 42.0
}
message: "Processing records"
timestamp: "2025-01-15T10:30:00Z"
}取消
合作取消，原因和来源明确：
cancellationToken: core.#CancellationToken & {
isCancellationRequested: true
reason: "user_requested"
source: "client"
timestamp: "2025-01-15T10:30:00Z"
}生成的输出
跑步 npm run generate 生产：
generated/typescript/types/-TypeScript类型定义generated/json-schema/-JSON模式文件
这些可以由TypeScript/JavaScript项目导入。
例子
看 test/validation/ 完整示例：
error_response.cue-错误处理示例progress_notification.cue-进度跟踪示例
建筑
看 docs/architecture/ 有关详细的架构图：
error-handling-system.mermaid-错误响应结构error-code-taxonomy.mermaid-错误代码范围progress-notification-system.mermaid-进度跟踪cancellation-system.mermaid-取消模式operation-state-management.mermaid-操作生命周期
CUE最佳实践
使用这些模式时：
- 使用定义：所有类型使用
#前缀（例如。，#ErrorResponse) - 绝对进口量：在导入中使用完整模块路径
- 约束条件：利用CUE的验证
&和| - 条件验证：使用
if上下文相关需求的声明
例子：
import "github.com/thomasbellio/mcp-utils-schema/core"
myError: core.#AuthError & {
code: 2001
message: "Invalid credentials"
suggestion: "Check your username and password"
timestamp: "2025-01-15T10:30:00Z"
}版本控制
此项目遵循语义版本控制：
- v1.0.x -补丁：Bug修复、文档
- v1.x.0 -次要：新功能，向后兼容
- vx.0.0 -专业：突破性变化
贡献
欢迎投稿！这些是基础模式，因此更改应该是：
- 尽可能向后兼容
- 有据可查的例子
- 使用测试夹具进行验证
test/validation/
许可证
MIT许可证