feat: integrate jsonschema output

Author: voocel

README.md

@@ -36,6 +36,42 @@ MCP Go SDK 是模型上下文协议（Model Context Protocol）的 Go 语言实
 - **高性能** - 并发安全，优化的消息处理
 - **安全防护** - 内置输入验证、路径遍历保护、资源限制
 
+## MCP协议版本支持
+
+本SDK跟踪并支持MCP协议的最新发展，确保与生态系统的兼容性：
+
+### 支持的版本
+
+| 版本 | 发布时间 | 主要特性 | 支持状态 |
+|------|----------|----------|----------|
+| **2025-06-18** | 2025年6月 | 结构化工具输出、工具注解、用户交互请求 | **完全支持** |
+| **2025-03-26** | 2025年3月 | OAuth 2.1授权、Streamable HTTP、JSON-RPC批处理 | **完全支持** |
+| **2024-11-05** | 2024年11月 | HTTP+SSE传输、基础工具和资源 | **完全支持** |
+
+### 最新特性 (2025-06-18)
+
+- **结构化工具输出**：工具可返回类型化JSON数据，便于程序化处理
+- **工具注解**：描述工具行为特征（只读、破坏性、缓存策略等）
+- **用户交互请求**：工具可主动请求用户输入或确认
+- **资源链接**：支持资源间的关联和引用
+- **协议版本头**：HTTP传输需要`MCP-Protocol-Version`头
+
+### 主要变更历史
+
+**2025-03-26 → 2025-06-18**：
+
+- 新增结构化工具输出支持
+- 增强工具注解系统
+- 添加用户交互请求机制
+- 支持资源链接功能
+
+**2024-11-05 → 2025-03-26**：
+
+- 引入OAuth 2.1授权框架
+- 用Streamable HTTP替代HTTP+SSE
+- 添加JSON-RPC批处理支持
+- 增加音频内容类型支持
+
 ## 安装
 
 ```bash
@@ -253,16 +289,16 @@ result, err := client.CallTool(ctx, "tool_name", map[string]interface{}{"param":
 ## 协议支持
 
 ### MCP 标准合规性
-✅ **完全符合 MCP 2025-06-18 规范**，向后兼容 MCP 2025-03-26, 2024-11-05
+**完全符合 MCP 2025-06-18 规范**，向后兼容 MCP 2025-03-26, 2024-11-05
 
 ### 传输协议
 | 协议 | 使用场景 | 官方支持 | 协议版本 |
-|------|----------|----------|----------|
-| **STDIO** | 子进程通信 | ✅ 官方标准 | 2024-11-05+ |
-| **SSE** | Web 应用 | ✅ 官方标准 | 2024-11-05+ |
-| **Streamable HTTP** | 现代 Web 应用 | ✅ 官方标准 | 2025-06-18 |
-| ~~**WebSocket**~~ | ~~实时应用~~ | ❌ 非官方标准 | - |
-| ~~**gRPC**~~ | ~~微服务~~ | ❌ 非官方标准 | - |
+|------|----------|------|----------|
+| **STDIO** | 子进程通信 | 官方标准 | 2024-11-05+ |
+| **SSE** | Web 应用 | 官方标准 | 2024-11-05+ |
+| **Streamable HTTP** | 现代 Web 应用 | 官方标准 | 2025-06-18 |
+| ~~**WebSocket**~~ | ~~实时应用~~ | 非官方标准 | - |
+| ~~**gRPC**~~ | ~~微服务~~ | 非官方标准 | - |
 
 **支持的协议版本**: 2025-06-18, 2025-03-26, 2024-11-05
 
@@ -301,6 +337,15 @@ if result.IsError {
 
 MIT License - 详见 [LICENSE](LICENSE) 文件
 
+## Roadmap
+
+- [x] **结构化工具输出** - 支持类型化、验证的工具结果 (MCP 2025-06-18)
+- [ ] **基础会话管理** - 支持每客户端独立状态管理
+- [ ] **简单中间件系统** - 提供基本的请求/响应拦截能力
+- [ ] **用户交互请求 (Elicitation)** - 服务器可在交互过程中请求用户输入 (MCP 2025-06-18)
+- [ ] **OAuth 2.1授权支持** - 企业级安全认证机制
+- [ ] **高级工具过滤** - 基于用户角色的工具访问控制
+
 ## 相关项目
 
 - [MCP 官方规范](https://github.com/anthropics/model-context-protocol) - 协议规范定义

examples/streamable-demo/server/main.go

@@ -7,17 +7,47 @@ import (
 	"os"
 	"os/signal"
 	"syscall"
+	"time"
 
 	"github.com/voocel/mcp-sdk-go/protocol"
 	"github.com/voocel/mcp-sdk-go/server"
 	"github.com/voocel/mcp-sdk-go/transport/streamable"
 )
 
+// CalculationResult 计算结果
+type CalculationResult struct {
+	Expression string  `json:"expression" description:"原始表达式"`
+	Result     float64 `json:"result" description:"计算结果"`
+	Operation  string  `json:"operation" description:"执行的运算"`
+	Timestamp  string  `json:"timestamp" description:"计算时间"`
+}
+
+// WeatherInfo 天气信息
+type WeatherInfo struct {
+	Location    string  `json:"location" description:"地点"`
+	Temperature float64 `json:"temperature" description:"温度(摄氏度)"`
+	Humidity    int     `json:"humidity" description:"湿度百分比"`
+	Condition   string  `json:"condition" description:"天气状况"`
+	UpdateTime  string  `json:"update_time" description:"更新时间"`
+}
+
+// ServerStats 服务器统计信息
+type ServerStats struct {
+	Uptime       string `json:"uptime" description:"运行时间"`
+	RequestCount int    `json:"request_count" description:"请求总数"`
+	ActiveTools  int    `json:"active_tools" description:"活跃工具数"`
+	Protocol     string `json:"protocol" description:"协议版本"`
+}
+
+var (
+	serverStartTime = time.Now()
+	requestCounter  = 0
+)
+
 func main() {
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
-	// 处理优雅关闭
 	signalCh := make(chan os.Signal, 1)
 	signal.Notify(signalCh, os.Interrupt, syscall.SIGTERM)
 	go func() {
@@ -26,10 +56,7 @@ func main() {
 		cancel()
 	}()
 
-	// 创建FastMCP服务器
 	mcp := server.NewFastMCP("Streamable HTTP 演示服务", "1.0.0")
-
-	// 注册一个简单的问候工具
 	mcp.Tool("greet", "问候用户").
 		WithStringParam("name", "用户名称", true).
 		WithStringParam("language", "语言（可选）", false).
@@ -54,26 +81,125 @@ func main() {
 			return protocol.NewToolResultText(greeting), nil
 		})
 
-	// 注册一个数学计算工具
-	mcp.Tool("calculate", "执行数学计算").
-		WithStringParam("expression", "数学表达式", true).
-		Handle(func(ctx context.Context, args map[string]any) (*protocol.CallToolResult, error) {
-			expr, ok := args["expression"].(string)
+	// 注册一个数学计算工具 - 结构化输出 (MCP 2025-06-18)
+	err := mcp.Tool("calculate", "执行数学计算，返回结构化结果").
+		WithStringParam("operation", "运算类型 (add, subtract, multiply, divide)", true).
+		WithNumberParam("a", "第一个数字", true).
+		WithNumberParam("b", "第二个数字", true).
+		WithStructOutputSchema(CalculationResult{}). // 使用结构体自动生成输出模式
+		HandleWithValidation(func(ctx context.Context, args map[string]any) (*protocol.CallToolResult, error) {
+			requestCounter++
+
+			operation, _ := args["operation"].(string)
+			a, _ := args["a"].(float64)
+			b, _ := args["b"].(float64)
+
+			var result float64
+			var opSymbol string
+
+			switch operation {
+			case "add":
+				result = a + b
+				opSymbol = "+"
+			case "subtract":
+				result = a - b
+				opSymbol = "-"
+			case "multiply":
+				result = a * b
+				opSymbol = "×"
+			case "divide":
+				if b == 0 {
+					return protocol.NewToolResultError("除数不能为零"), nil
+				}
+				result = a / b
+				opSymbol = "÷"
+			default:
+				return protocol.NewToolResultError("不支持的运算类型"), nil
+			}
+
+			calcResult := CalculationResult{
+				Expression: fmt.Sprintf("%.2f %s %.2f", a, opSymbol, b),
+				Result:     result,
+				Operation:  operation,
+				Timestamp:  time.Now().Format(time.RFC3339),
+			}
+
+			return protocol.NewToolResultTextWithStructured(
+				fmt.Sprintf("计算完成：%.2f %s %.2f = %.2f", a, opSymbol, b, result),
+				calcResult,
+			), nil
+		})
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	err = mcp.SimpleStructuredTool(
+		"get_weather",
+		"获取指定城市的天气信息",
+		protocol.JSONSchema{
+			"type": "object",
+			"properties": map[string]any{
+				"location":    map[string]any{"type": "string", "description": "地点"},
+				"temperature": map[string]any{"type": "number", "description": "温度(摄氏度)"},
+				"humidity":    map[string]any{"type": "integer", "description": "湿度百分比"},
+				"condition":   map[string]any{"type": "string", "description": "天气状况"},
+				"update_time": map[string]any{"type": "string", "description": "更新时间"},
+			},
+			"required": []string{"location", "temperature", "humidity", "condition", "update_time"},
+		},
+		func(ctx context.Context, args map[string]any) (any, error) {
+			requestCounter++
+
+			location, ok := args["location"].(string)
 			if !ok {
-				return protocol.NewToolResultError("参数 'expression' 必须是字符串"), nil
+				return nil, fmt.Errorf("location参数是必需的")
 			}
 
-			// 简单的计算示例（实际应用中应该使用安全的表达式解析器）
-			result := fmt.Sprintf("计算结果：%s = [此处应该是计算结果]", expr)
-			return protocol.NewToolResultText(result), nil
+			conditions := []string{"晴天", "多云", "小雨", "阴天"}
+			weather := WeatherInfo{
+				Location:    location,
+				Temperature: 15 + float64(len(location)%20),
+				Humidity:    50 + len(location)%40,
+				Condition:   conditions[len(location)%len(conditions)],
+				UpdateTime:  time.Now().Format("2006-01-02 15:04:05"),
+			}
+
+			return weather, nil
+		},
+	)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// 注册服务器状态工具 - 演示动态结构化数据
+	err = mcp.Tool("server_stats", "获取服务器运行状态").
+		WithStructOutputSchema(ServerStats{}).
+		HandleWithValidation(func(ctx context.Context, args map[string]any) (*protocol.CallToolResult, error) {
+			requestCounter++
+
+			uptime := time.Since(serverStartTime)
+			stats := ServerStats{
+				Uptime:       uptime.Round(time.Second).String(),
+				RequestCount: requestCounter,
+				ActiveTools:  4, // greet, calculate, get_weather, server_stats
+				Protocol:     "Streamable HTTP (MCP 2025-06-18)",
+			}
+
+			return protocol.NewToolResultTextWithStructured(
+				fmt.Sprintf("服务器已运行 %s，处理了 %d 个请求", stats.Uptime, stats.RequestCount),
+				stats,
+			), nil
 		})
+	if err != nil {
+		log.Fatal(err)
+	}
 
 	// 注册一个资源
 	mcp.Resource("info://server", "服务器信息", "获取服务器基本信息").
 		Handle(func(ctx context.Context) (*protocol.ReadResourceResult, error) {
 			info := `# Streamable HTTP MCP 服务器
 
-这是一个演示 Streamable HTTP 传输协议的 MCP 服务器。
+这是一个演示 Streamable HTTP 传输协议和结构化工具输出的 MCP 服务器。
 
 ## 特性
 
@@ -82,16 +208,35 @@ func main() {
 - **会话管理**：支持有状态的会话
 - **可恢复连接**：支持连接中断后的恢复
 - **安全防护**：内置 DNS rebinding 攻击防护
+- **结构化输出**：支持类型化的工具结果 (MCP 2025-06-18)
 
 ## 协议版本
 
-- MCP 版本：2025-03-26
+- MCP 版本：2025-06-18
 - 传输协议：Streamable HTTP
+- 新特性：结构化工具输出
 
 ## 可用工具
 
-1. **greet** - 多语言问候工具
-2. **calculate** - 数学计算工具（演示用）
+1. **greet** - 多语言问候工具（传统文本输出）
+2. **calculate** - 数学计算工具（结构化输出演示）
+3. **get_weather** - 天气查询工具（简化API演示）
+4. **server_stats** - 服务器状态工具（动态数据演示）
+
+## 结构化输出示例
+
+工具现在可以返回类型化的JSON数据：
+
+` + "```" + `json
+{
+  "content": [{"type": "text", "text": "人类可读的描述"}],
+  "structuredContent": {
+    "result": 42,
+    "timestamp": "2025-01-15T10:30:00Z",
+    "operation": "multiply"
+  }
+}
+` + "```" + `
 
 ## 可用资源
 
@@ -113,13 +258,17 @@ func main() {
 			var content string
 			switch topic {
 			case "transport":
-				content = "Streamable HTTP 是 MCP 2025-03-26 规范中的新传输协议，它统一了 HTTP 和 SSE 的优势。"
+				content = "Streamable HTTP 是 MCP 2025-06-18 规范中的传输协议，它统一了 HTTP 和 SSE 的优势。"
 			case "session":
 				content = "会话管理允许服务器在多个请求之间保持状态，提供更好的用户体验。"
 			case "security":
 				content = "Streamable HTTP 包含多种安全机制，包括 Origin 验证和会话管理。"
+			case "structured":
+				content = "结构化工具输出是 MCP 2025-06-18 的新特性，允许工具返回类型化的JSON数据，同时保持文本描述的可读性。"
+			case "tools":
+				content = "本服务器演示了多种工具类型：传统文本输出(greet)、结构化输出(calculate)、简化API(get_weather)和动态数据(server_stats)。"
 			default:
-				content = "Streamable HTTP 是一个现代化的 MCP 传输协议，提供了灵活的通信方式。"
+				content = "Streamable HTTP 是一个现代化的 MCP 传输协议，现在支持结构化工具输出功能。"
 			}
 
 			messages := []protocol.PromptMessage{
@@ -138,6 +287,8 @@ func main() {
 	log.Println("启动 Streamable HTTP MCP 服务器")
 	log.Println("监听地址: http://localhost:8081")
 	log.Println("传输协议: Streamable HTTP")
+	log.Println("MCP版本: 2025-06-18 (支持结构化工具输出)")
+	log.Println("可用工具: greet, calculate, get_weather, server_stats")
 
 	if err := streamableServer.Serve(ctx); err != nil && err != context.Canceled {
 		log.Fatalf("服务器错误: %v", err)

go.mod

@@ -10,6 +10,7 @@ require (
 )
 
 require (
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
 	golang.org/x/net v0.34.0 // indirect
 	golang.org/x/sys v0.29.0 // indirect
 	golang.org/x/text v0.21.0 // indirect

go.sum

@@ -10,6 +10,8 @@ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
+github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
 go.opentelemetry.io/auto/sdk v1.1.0 h1:cH53jehLUN6UFLY71z+NDOiNJqDdPRaXzTel0sJySYA=
 go.opentelemetry.io/auto/sdk v1.1.0/go.mod h1:3wSPjt5PWp2RhlCcmmOial7AvC4DQqZb7a7wCow3W8A=
 go.opentelemetry.io/otel v1.34.0 h1:zRLXxLCgL1WyKsPVrgbSdMN4c0FMkDAskSTQP+0hdUY=