MCP Utils Schema

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最佳实践

使用这些模式时：

1. 使用定义：所有类型使用 # 前缀（例如。， #ErrorResponse)
2. 绝对进口量：在导入中使用完整模块路径
3. 约束条件：利用CUE的验证 & 和 |
4. 条件验证：使用 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 -专业：突破性变化

贡献

欢迎投稿！这些是基础模式，因此更改应该是：

1. 尽可能向后兼容
2. 有据可查的例子
3. 使用测试夹具进行验证 test/validation/

许可证

MIT许可证