# 基础

## 1 服务器初始化

`server.NewMCPServer` 是创建 MCP 服务核心实例的函数，其定义和配置能力如下：

```go
func NewMCPServer(
    name string, 
    version string, 
    opts ...ServerOption
) *MCPServer
```

| 参数        | 类型                | 必需 | 描述                             |
| --------- | ----------------- | -- | ------------------------------ |
| `name`    | `string`          | ✓  | 服务名称（显示在能力端点/capabilities中）    |
| `version` | `string`          | ✓  | 服务版本号（语义化版本格式如 "1.0.0"）        |
| `opts`    | `...ServerOption` | ✕  | ​**​能力配置选项​**​（可变参数，可添加多个配置函数） |

### 1.1 可配置能力

#### 1.1.1 工具能力配置

```go
server.WithToolCapabilities(enabled bool)
```

* ​**​作用​**​：启用/禁用工具调用功能
* ​**​启用后​**​：
  * 暴露 `/mcp/tools/list` 端点
  * 暴露 `/mcp/tools/call` 端点
  * 允许使用 `AddTool()` 注册工具
* ​**​示例​**​：`server.WithToolCapabilities(true)`

#### 1.1.2 资源能力配置

```go
server.WithResourceCapabilities(read, write bool)
```

* **作用​**​：启用/禁用资源读写能力
* ​**​参数​**​：
  * `read`：启用资源读取（GET 操作）
  * `write`：启用资源修改（PUT/POST/DELETE）
* ​**​启用后​**​：
  * 暴露 `/mcp/resources/list` 端点
  * 暴露 `/mcp/resources/read` 端点
  * 允许使用 `AddResource()` 注册资源
* ​**​示例​**​：`server.WithResourceCapabilities(true, false)` // 启用读，禁用写

#### 1.1.3 提示能力配置

```go
server.WithPromptCapabilities(enabled bool)
```

* **作用​**​：启用/禁用提示功能
* ​**​启用后​**​：
  * 暴露 `/mcp/prompts/list` 端点
  * 暴露 `/mcp/prompts/get` 端点
  * 允许管理 AI 提示模板
* ​**​示例​**​：`server.WithPromptCapabilities(true)`

#### 1.1.4 日志能力配置

```go
server.WithLogging()
```

* **作用​**​：启用请求日志记录
* ​**​记录内容​**​：
  * 所有入站请求信息
  * 处理时长
  * 错误信息
* ​**​示例​**​：`server.WithLogging()`

#### 1.1.5 状态管理配置

```go
server.WithStateManagement()
```

* ​**​作用​**​：启用有状态会话支持
* ​**​功能​**​：
  * 自动生成会话 ID
  * 维护跨请求的上下文
  * 会话过期处理
* ​**​示例​**​：`server.WithStateManagement()`

#### 1.1.6 并发控制配置

```go
server.WithMaxConcurrent(max int)
```

* ​**​作用​**​：设置最大并发请求数
* ​**​参数​**​：`max` - 最大并发数（0 表示无限制）
* ​**​示例​**​：`server.WithMaxConcurrent(100)`

#### 1.1.7 请求超时配置

```go
server.WithRequestTimeout(d time.Duration)
```

* ​**​作用​**​：设置请求处理超时时间
* ​**​参数​**​：`d` - 超时时间（如 `30*time.Second`）
* ​**​示例​**​：`server.WithRequestTimeout(10 * time.Second)`

#### 1.1.8 自定义中间件

```go
server.WithMiddleware(middleware MiddlewareFunc)
```

* **作用​**​：添加全局中间件
* ​**​类型定义​**​：

```go
    type MiddlewareFunc func(next Handler) Handler
```

* ​**​示例​**​：

```go
server.WithMiddleware(func(next server.Handler) server.Handler {
    return func(ctx context.Context, req interface{}) (interface{}, error) {
        // 前置处理
        result, err := next(ctx, req)
        // 后置处理
        return result, err
    }
})
```

### 1.2 返回值

| 返回值          | 类型    | 描述                                          |
| ------------ | ----- | ------------------------------------------- |
| `*MCPServer` | 结构体指针 | 初始化完成的 MCP 服务器实例，包含以下核心字段：                  |
|              |       | - `name`：服务名称                               |
|              |       | - `version`：版本号                             |
|              |       | - `tools`：注册的工具映射（map\[string]Tool）         |
|              |       | - `resources`：注册的资源映射（map\[string]Resource） |
|              |       | - `prompts`：提示词集合                           |
|              |       | - `middlewares`：中间件链                        |
|              |       | - `capabilities`：启用的能力配置                    |

### 1.3 示例

```go
s := server.NewMCPServer(
    "User Management API",  // 服务名称
    "1.5.0",                 // 版本号
    
    // 能力配置
    server.WithToolCapabilities(true),
    server.WithResourceCapabilities(true, false), // 启用读，禁用写
    server.WithPromptCapabilities(true),
    server.WithLogging(),
    server.WithStateManagement(),
    server.WithMaxConcurrent(50),
    server.WithRequestTimeout(15 * time.Second),
    
    // 自定义中间件
    server.WithMiddleware(func(next server.Handler) server.Handler {
        return func(ctx context.Context, req interface{}) (interface{}, error) {
            start := time.Now()
            log.Printf("Processing request: %T", req)
            res, err := next(ctx, req)
            log.Printf("Request processed in %v", time.Since(start))
            return res, err
        }
    }),
    
    // 另一个中间件（认证）
    server.WithMiddleware(authMiddleware),
)
```

### 1.4 注意

1.  ​**​能力依赖​**​：

    ```
     - 未启用 `WithToolCapabilities` 时调用 `AddTool()` 会 panic
     - 未启用 `WithResourceCapabilities` 时添加资源无效
    ```
2. ​**​配置顺序​**​：

```go
// ✅ 正确：先配置能力再添加内容
s := NewMCPServer("svc", "1.0", WithToolCapabilities(true))
s.AddTool(...)

// ❌ 错误：未启用能力就添加工具
s := NewMCPServer("svc", "1.0")
s.AddTool(...) // 将导致运行时错误        
```

3. ​**​默认行为​**​：
   * 所有能力默认 ​**​禁用​**​
   * 未配置超时/并发限制时无约束
   * 未启用日志时不记录请求
4. ​**​中间件执行顺序​**​：

![](https://1266245412-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLRcKCR7yPLRstW52M5Uq%2Fuploads%2Fgit-blob-2ee907424ea77f8ade727b1c00d1682200553a39%2F%E5%9F%BA%E7%A1%80_time_1.png?alt=media)

## 2 工具注册

在 `mcp-go` 包中，工具注册是构建 MCP 服务的核心环节，主要涉及两个关键函数：`NewTool()` 和 `AddTool()`。

### 2.1 工具创建函数：NewTool

```go
func NewTool(
    name string, 
    opts ...ToolOption,
) *Tool
```

| 参数     | 类型              | 必需 | 描述                                    |
| ------ | --------------- | -- | ------------------------------------- |
| `name` | `string`        | ✓  | ​**​工具名称​**​（唯一标识符，如 "search\_users"） |
| `opts` | `...ToolOption` | ✕  | ​**​工具配置选项​**​（可变参数，可添加多个配置函数）        |

#### 2.1.1 参数定义函数

```go
// 添加字符串参数
func WithString(
    name string, 
    opts ...ParamOption,
) ToolOption

// 添加数值参数
func WithNumber(
    name string, 
    opts ...ParamOption,
) ToolOption

// 添加布尔参数
func WithBoolean(
    name string, 
    opts ...ParamOption,
) ToolOption

// 添加对象参数（JSON对象）
func WithObject(
    name string, 
    opts ...ParamOption,
) ToolOption

// 添加数组参数
func WithArray(
    name string, 
    opts ...ParamOption,
) ToolOption
```

#### 2.1.2 参数选项

```go
// 标记参数为必需
func Required() ParamOption

// 设置默认值（字符串）
func DefaultString(value string) ParamOption

// 设置默认值（数字）
func DefaultNumber(value float64) ParamOption

// 设置默认值（布尔）
func DefaultBoolean(value bool) ParamOption

// 设置最小值（数值参数）
func Min(value float64) ParamOption

// 设置最大值（数值参数）
func Max(value float64) ParamOption

// 设置参数描述
func Description(desc string) ParamOption

// 设置允许值枚举
func AllowedValues(values ...interface{}) ParamOption
```

#### 2.1.3 元数据配置

```go
// 设置工具描述
func WithDescription(desc string) ToolOption

// 设置工具分类
func WithCategory(category string) ToolOption

// 设置工具图标（URL或base64）
func WithIcon(icon string) ToolOption
```

#### 2.1.4 返回值

| 返回值     | 类型    | 描述                                |
| ------- | ----- | --------------------------------- |
| `*Tool` | 结构体指针 | 初始化完成的工具对象，包含以下核心字段：              |
|         |       | - `Name`: 工具名称                    |
|         |       | - `Description`: 工具描述             |
|         |       | - `Parameters`: 参数列表（包含名称、类型、约束等） |
|         |       | - `Category`: 工具分类                |

#### 2.1.5 示例

```go
searchTool := mcp.NewTool(
    "search_users",
    mcp.WithDescription("Search users with filters"),
    mcp.WithString("query", 
        mcp.Description("Search keywords"),
        mcp.DefaultString(""),
    ),
    mcp.WithNumber("limit",
        mcp.DefaultNumber(10),
        mcp.Min(1),
        mcp.Max(100),
        mcp.Description("Maximum results per page"),
    ),
    mcp.WithNumber("offset",
        mcp.DefaultNumber(0),
        mcp.Min(0),
        mcp.Description("Pagination offset"),
    ),
    mcp.WithArray("filters",
        mcp.Description("Additional filter criteria"),
    ),
    mcp.WithCategory("User Management"),
    mcp.WithIcon("https://example.com/search-icon.png"),
)
```

### 2.2 工具注册函数：AddTool

```go
func (s *MCPServer) AddTool(
    tool *Tool, 
    handler ToolHandler,
) error
```

| 参数        | 类型            | 必需 | 描述                  |
| --------- | ------------- | -- | ------------------- |
| `tool`    | `*Tool`       | ✓  | 由 `NewTool` 创建的工具对象 |
| `handler` | `ToolHandler` | ✓  | 工具调用的处理函数           |

#### 2.2.1 处理函数签名

```go
type ToolHandler func(
    ctx context.Context, 
    req CallToolRequest,
) (*CallToolResult, error)
```

* ​**​`ctx context.Context`​**​\
  包含请求上下文，可用于：
  * 获取请求超时信息
  * 传递中间件设置的值（如用户身份）
  * 访问 HTTP 原始请求头（通过 `req.Header`）
* ​**​`req CallToolRequest`​**​\
  工具调用请求结构：

```go
type CallToolRequest struct {
    Params ToolCallParams
    Header http.Header // 原始HTTP头
}

type ToolCallParams struct {
    Name      string                 // 工具名
    Arguments map[string]interface{} // 参数字典
    SessionID string                 // 会话ID（有状态时）
}
```

​**​`*CallToolResult`​**​\
成功时返回的结果对象，使用以下构造器创建：

```go
// 创建文本结果
func NewToolResultText(text string) *CallToolResult

// 创建JSON结果
func NewToolResultJSON(data interface{}) *CallToolResult

// 创建多内容结果（文本+JSON）
func NewToolResult(contents ...ToolResultContent) *CallToolResult
```

其中 `ToolResultContent` 可以是：

```go
type TextResultContent struct {
    Type string `json:"type"` // "text"
    Text string `json:"text"`
}

type JSONResultContent struct {
    Type string      `json:"type"` // "json"
    Data interface{} `json:"data"`
}
```

* ​**​`error`​**​\
  错误时返回，会触发 JSON-RPC 错误响应；注册成功返回 nil，工具名重复时返回 ErrToolExists

**2.2.1.1 处理函数示例**

```go
func handleSearchUsers(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
    // 安全获取参数（带默认值）
    query := req.GetString("query", "")
    limit := req.GetInt("limit", 10)
    offset := req.GetInt("offset", 0)
    
    // 获取原始HTTP头
    authToken := req.Header.Get("Authorization")
    requestID := req.Header.Get("X-Request-ID")
    
    // 业务逻辑
    users, total, err := searchUsers(query, limit, offset)
    if err != nil {
        return nil, fmt.Errorf("search failed: %w", err)
    }
    
    // 构造复合结果（文本摘要+JSON数据）
    return mcp.NewToolResult(
        mcp.TextContent(fmt.Sprintf("Found %d users", total)),
        mcp.JSONContent(map[string]interface{}{
            "results": users,
            "pagination": map[string]int{
                "total":  total,
                "limit":  limit,
                "offset": offset,
            }
        }),
    ), nil
}
```

## 3 资源注册

### 3.1 资源创建函数：NewResource

在 `mcp-go` 中，资源注册是构建 MCP 服务的核心能力之一，它允许你定义可通过统一资源标识符（URI）访问的数据实体。

```go
func NewResource(
    uriPattern string, 
    displayName string, 
    opts ...ResourceOption,
) *Resource
```

| 参数            | 类型                  | 必需 | 描述                                             |
| ------------- | ------------------- | -- | ---------------------------------------------- |
| `uriPattern`  | `string`            | ✓  | ​**​URI模式​**​（支持参数化路径，如 `"users://{user_id}"`） |
| `displayName` | `string`            | ✓  | ​**​显示名称​**​（用于文档和发现）                          |
| `opts`        | `...ResourceOption` | ✕  | 资源配置选项（可变参数）                                   |

#### 3.1.1 资源配置

**3.1.1.1 元数据配置**

```go
// 设置详细描述
WithResourceDescription(desc string)

// 设置MIME类型
WithMIMEType(mimeType string)

// 设置资源图标（URL或base64）
WithIcon(icon string)

// 设置资源分类
WithCategory(category string)
```

**3.1.1.2 访问控制配置**

```go
// 设置读写权限（true=可读，true=可写）
WithAccessControl(readable, writable bool)

// 设置所需权限列表
WithRequiredPermissions(perms []string)
```

**3.1.1.3 缓存控制配置**

```go
// 设置最大缓存时间
WithMaxAge(maxAge time.Duration)

// 启用ETag验证
WithETagSupport()

// 启用最后修改时间验证
WithLastModifiedSupport()
```

**3.1.1.4 分页支持配置**

```go
// 启用分页支持
WithPaginationSupport()

// 设置默认分页大小
WithDefaultPageSize(size int)
```

**3.1.1.5 内容协商配置**

```go
// 设置支持的表示格式（如JSON/XML）
WithRepresentations(reps ...Representation)
```

#### 3.1.2 返回值

| 返回值         | 类型    | 描述                                    |
| ----------- | ----- | ------------------------------------- |
| `*Resource` | 结构体指针 | 资源对象，包含以下核心字段：                        |
|             |       | - `URIPattern`: 原始URI模式               |
|             |       | - `DisplayName`: 显示名称                 |
|             |       | - `Description`: 详细描述                 |
|             |       | - `MIMEType`: 默认MIME类型                |
|             |       | - `CompiledPattern`: 编译后的正则模式（用于参数提取） |

#### 3.1.3 示例

```go
userRes := mcp.NewResource(
    "users://{user_id}",
    "User Profile",
    mcp.WithResourceDescription("Complete user profile information"),
    mcp.WithMIMEType("application/json"),
    mcp.WithIcon("https://example.com/user-icon.png"),
    mcp.WithAccessControl(true, false), // 可读不可写
    mcp.WithRequiredPermissions([]string{"user.read"}),
    mcp.WithMaxAge(5*time.Minute),
    mcp.WithETagSupport(),
    mcp.WithPaginationSupport(),
)
```

### 3.2 资源注册函数：AddResource

```go
func (s *MCPServer) AddResource(
    res *Resource, 
    handler ResourceHandler,
) error
```

| 参数        | 类型                | 必需 | 描述                      |
| --------- | ----------------- | -- | ----------------------- |
| `res`     | `*Resource`       | ✓  | 由 `NewResource` 创建的资源对象 |
| `handler` | `ResourceHandler` | ✓  | 资源访问处理函数                |

#### 3.2.1 处理函数签名

```go
type ResourceHandler func(
    ctx context.Context, 
    req ReadResourceRequest,
) ([]ResourceContents, error)
```

* ​**​`ctx context.Context`​**​\
  请求上下文，包含：
  * 请求超时信息
  * 中间件传递的值（如用户身份）
  * 访问控制信息
* ​**​`req ReadResourceRequest`​**​\
  资源请求结构：

```go
type ReadResourceRequest struct {
    Params ReadResourceParams
    Header http.Header // 原始HTTP头
}

type ReadResourceParams struct {
    URI         string                 // 请求的完整URI
    Parameters  map[string]string       // 从URI模式提取的参数
    Query       map[string][]string     // URL查询参数
    IfNoneMatch string                 // If-None-Match头
    IfModifiedSince time.Time          // If-Modified-Since头
    RangeHeader string                 // Range头（支持部分内容）
    SessionID   string                 // 会话ID（有状态时）
}
```

​- **​`[]ResourceContents`​**​\
资源内容列表，支持多种内容类型：

```go
// 文本内容
type TextResourceContents struct {
    URI      string `json:"uri"`      // 实际资源URI
    MIMEType string `json:"mimeType"` // MIME类型
    Text     string `json:"text"`     // 文本内容
}

// 二进制内容
type BinaryResourceContents struct {
    URI      string `json:"uri"`      
    MIMEType string `json:"mimeType"`
    Data     []byte `json:"data"`     // 二进制数据
}

// 流内容
type StreamResourceContents struct {
    URI        string `json:"uri"`
    MIMEType   string `json:"mimeType"`
    Stream     io.Reader `json:"-"`   // 流数据（不序列化）
}
```

* 构造函数

```go
// 创建文本内容
func TextContents(uri, mimeType, text string) ResourceContents

// 创建JSON内容（自动设置MIME类型）
func JSONContents(uri string, data interface{}) ResourceContents

// 创建二进制内容
func BinaryContents(uri, mimeType string, data []byte) ResourceContents
```

* **`error`​**​\
  错误时返回，会转换为HTTP错误状态码；注册成功返回 nil，URI模式冲突时返回 ErrResourceExists

#### 3.2.2 示例

```go
func handleUserResource(ctx context.Context, req mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
    // 从URI参数获取user_id
    userID := req.Params.Parameters["user_id"]
    
    // 获取查询参数（如扩展字段）
    fields := req.Params.Query["fields"]
    
    // 条件请求处理
    if etag := req.Params.IfNoneMatch; etag != "" {
        if currentETag := getETag(userID); currentETag == etag {
            return nil, mcp.StatusError(http.StatusNotModified)
        }
    }
    
    // 获取用户数据
    user, err := getUser(userID)
    if err != nil {
        if errors.Is(err, ErrNotFound) {
            return nil, mcp.StatusError(http.StatusNotFound)
        }
        return nil, err
    }
    
    // 构建响应
    return []mcp.ResourceContents{
        mcp.JSONContents(
            fmt.Sprintf("users://%s", userID), // 实际URI
            map[string]interface{}{
                "id":    user.ID,
                "name":  user.Name,
                "email": user.Email,
                // 根据fields参数过滤字段
            },
        ),
    }, nil
}
```

## 4 中间件系统

MCP 的中间件系统提供了强大的请求处理管道能力，允许开发者在核心业务逻辑前后插入自定义处理逻辑。

### 4.1 工具中间件

```go
func (s *MCPServer) AddToolMiddleware(
    middleware func(next ToolHandler) ToolHandler
)
```

* `middleware`：中间件函数，签名如下：

```go
func(next ToolHandler) ToolHandler
```

* `next`：下一个中间件或最终处理函数
* 返回：包装后的处理函数

```go
type ToolMiddlewareFunc func(
    next ToolHandler, // 下一层处理器
) ToolHandler // 返回包装后的处理器

type ToolHandler func(
    ctx context.Context, 
    req CallToolRequest,
) (*CallToolResult, error)
```

### 4.2 资源中间件

```go
func (s *MCPServer) AddResourceMiddleware(
    middleware func(next ResourceHandler) ResourceHandler
)
```

* `middleware`：中间件函数，签名如下：

```go
func(next ResourceHandler) ResourceHandler
```

* `next`：下一个中间件或最终处理函数
* 返回：包装后的处理函数

```go
type ResourceMiddlewareFunc func(
    next ResourceHandler, // 下一层处理器
) ResourceHandler // 返回包装后的处理器

type ResourceHandler func(
    ctx context.Context, 
    req ReadResourceRequest,
) ([]ResourceContents, error)
```

### 4.3 示例

* 认证与鉴权

```go
func authMiddleware(next server.ToolHandler) server.ToolHandler {
    return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        token := req.Header.Get("Authorization")
        if !validateToken(token) {
            return nil, fmt.Errorf("unauthorized")
        }
        return next(ctx, req)
    }
}
```

* 缓存处理

```go
func cacheMiddleware(next server.ResourceHandler) server.ResourceHandler {
    return func(ctx context.Context, req mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) {
        // 检查缓存
        if cached, ok := cache.Get(req.Params.URI); ok {
            return cached, nil
        }
        
        // 调用实际处理器
        res, err := next(ctx, req)
        
        // 缓存结果
        if err == nil {
            cache.Set(req.Params.URI, res, 5*time.Minute)
        }
        
        return res, err
    }
}
```

## 5 服务启动

在 `mcp-go` 包中，服务启动是构建 MCP 服务的最后环节，提供了多种配置选项来优化服务行为和性能。

### 5.1 创建HTTP服务器

`NewStreamableHTTPServer` 函数是创建 MCP HTTP 服务器的核心入口，它提供了丰富的配置选项来定制 HTTP 服务的行为和特性。

```go
func NewStreamableHTTPServer(
    s *MCPServer, 
    opts ...HTTPOption,
) *StreamableHTTPServer
```

| 参数     | 类型              | 必需 | 描述                                   |
| ------ | --------------- | -- | ------------------------------------ |
| `s`    | `*MCPServer`    | ✓  | ​**​MCP 服务器实例​**​（包含工具、资源等注册信息）      |
| `opts` | `...HTTPOption` | ✕  | ​**​HTTP 服务器配置选项​**​（可变参数，可添加多个配置函数） |

#### 5.1.1 端点路径配置

```go
// 设置 MCP 端点的基本路径
WithEndpointPath(basePath string)

// 设置健康检查端点路径
WithHealthCheckPath(path string)

// 设置能力端点路径
WithCapabilitiesPath(path string)
```

#### 5.1.2 会话管理配置

```go
// 启用/禁用有状态会话
WithStateLess(stateless bool)

// 设置会话超时时间
WithSessionTimeout(timeout time.Duration)

// 设置会话存储后端（默认为内存）
WithSessionStore(store SessionStore)
```

#### 5.1.3 心跳机制

```go
// 设置心跳间隔（0 表示禁用）
WithHeartbeatInterval(interval time.Duration)

// 设置心跳响应内容
WithHeartbeatResponse(content string)
```

#### 5.1.4 请求处理配置

```go
// 设置最大请求体大小（字节）
WithMaxBodySize(bytes int64)

// 设置请求头大小限制（字节）
WithMaxHeaderBytes(bytes int)

// 启用请求ID生成
WithRequestIDGeneration(enabled bool)
```

#### 5.1.5 内容编码

```go
// 启用Gzip压缩
WithGzipCompression(level int) // level: gzip.BestSpeed 到 gzip.BestCompression

// 启用Brotli压缩
WithBrotliCompression()
```

#### 5.1.6 CORS配置

```go
// 设置CORS策略
WithCORS(config *CORSOptions)

// CORSOptions 结构
type CORSOptions struct {
    AllowedOrigins   []string
    AllowedMethods   []string
    AllowedHeaders   []string
    AllowCredentials bool
    MaxAge           time.Duration
}
```

#### 5.1.7 安全头配置

```go
// 添加安全头（如XSS保护）
WithSecureHeaders(headers map[string]string)

// 启用默认安全头集
WithDefaultSecureHeaders()
```

| 返回值                     | 类型    | 描述                           |
| ----------------------- | ----- | ---------------------------- |
| `*StreamableHTTPServer` | 结构体指针 | HTTP 服务器实例，包含以下核心字段：         |
|                         |       | - `mcpserver`: 关联的 MCP 服务器实例 |
|                         |       | - `router`: HTTP 路由器         |
|                         |       | - `sessionManager`: 会话管理器    |
|                         |       | - `heartbeatInterval`: 心跳间隔  |
|                         |       | - `corsConfig`: CORS 配置      |
|                         |       | - `gzipLevel`: Gzip 压缩级别     |

#### 5.1.8 示例

```go
func main() {
    // 创建MCP服务器
    s := server.NewMCPServer(
        "User API", 
        "1.0.0",
        server.WithToolCapabilities(true),
        server.WithResourceCapabilities(true, false),
    )
    
    // 注册工具和资源...
    
    // 创建HTTP服务器
    httpServer := server.NewStreamableHTTPServer(
        s,
        // 端点配置
        server.WithEndpointPath("/api/v1/mcp"),
        server.WithHealthCheckPath("/healthz"),
        server.WithCapabilitiesPath("/capabilities"),
        
        // 会话管理
        server.WithStateLess(false),
        server.WithSessionTimeout(30*time.Minute),
        
        // 心跳机制
        server.WithHeartbeatInterval(15*time.Second),
        server.WithHeartbeatResponse("OK"),
        
        // 请求处理
        server.WithMaxBodySize(10 * 1024 * 1024), // 10MB
        server.WithMaxHeaderBytes(1 * 1024 * 1024), // 1MB
        server.WithRequestIDGeneration(true),
        
        // 内容编码
        server.WithGzipCompression(gzip.BestSpeed),
        
        // CORS配置
        server.WithCORS(&server.CORSOptions{
            AllowedOrigins:   []string{"https://example.com", "https://app.example.com"},
            AllowedMethods:   []string{"GET", "POST", "PUT", "DELETE", "OPTIONS"},
            AllowedHeaders:   []string{"Authorization", "Content-Type", "X-Request-ID"},
            AllowCredentials: true,
            MaxAge:           24 * time.Hour,
        }),
        
        // 安全头
        server.WithSecureHeaders(map[string]string{
            "X-Content-Type-Options": "nosniff",
            "X-Frame-Options":        "DENY",
            "Content-Security-Policy": "default-src 'self'",
        }),
    )
    
    // 启动服务器
    if err := httpServer.Start(":8080"); err != nil {
        log.Fatal(err)
    }
}
```

### 5.2 HTTP传输

```go
func (s *StreamableHTTPServer) Start(
    addr string, 
    opts ...StartOption,
) error
```

| 参数     | 类型               | 必需 | 描述                                               |
| ------ | ---------------- | -- | ------------------------------------------------ |
| `addr` | `string`         | ✓  | ​**​服务监听地址​**​（格式："ip:port" 或 ":port"，如 ":8080"） |
| `opts` | `...StartOption` | ✕  | ​**​启动配置选项​**​（可变参数，可添加多个配置函数）                   |

#### 5.2.1 连接管理选项

```go
// 设置读取超时
WithReadTimeout(timeout time.Duration)

// 设置写入超时
WithWriteTimeout(timeout time.Duration)

// 设置空闲连接超时
WithIdleTimeout(timeout time.Duration)

// 设置最大并发连接数
WithMaxConnections(max int)

// 启用 Keep-Alive
WithKeepAlive(enabled bool)
```

#### 5.2.2 TLS/SSL 安全配置

```go
// 启用 HTTPS
WithTLS(certFile, keyFile string)

// 自动重定向 HTTP 到 HTTPS
WithAutoRedirectHTTP(redirectPort int)

// 设置 TLS 配置
WithTLSConfig(config *tls.Config)
```

#### 5.2.3 高级性能选项

```go
// 设置读取缓冲区大小
WithReadBufferSize(bytes int)

// 设置写入缓冲区大小
WithWriteBufferSize(bytes int)

// 禁用 HTTP/2
WithDisableHTTP2()

// 启用连接复用
WithConnStateHandler(func(net.Conn, http.ConnState))
```

#### 5.2.4 调试与诊断

```go
// 启用性能分析端点
WithPProf(path string) // 默认 /debug/pprof

// 设置请求日志格式
WithRequestLogger(logger *log.Logger)

// 设置服务名称（用于日志）
WithServiceName(name string)

// 设置指标收集器
WithMetricsCollector(collector metrics.Collector)
```

#### 5.2.5 优雅关闭

```go
// 设置优雅关闭超时
WithGracefulShutdownTimeout(timeout time.Duration)

// 添加关闭钩子
WithShutdownHook(func())
```

* error：
  * 启动成功返回 nil，失败返回具体错误（如端口冲突）

#### 5.2.6 示例

```go
func main() {
    // 1. 初始化服务器
    s := server.NewMCPServer(
        "User API", 
        "1.0.0",
        server.WithToolCapabilities(true),
        server.WithResourceCapabilities(true, false),
    )
    
    // 2. 注册工具和资源
    s.AddTool(createUserTool, handleCreateUser)
    s.AddResource(userResource, handleUserResource)
    
    // 3. 添加中间件
    s.AddToolMiddleware(authMiddleware)
    s.AddToolMiddleware(loggingMiddleware)
    
    // 4. 创建 HTTP 服务器
    httpServer := server.NewStreamableHTTPServer(s,
        server.WithEndpointPath("/api/v1"),
        server.WithHeartbeatInterval(30*time.Second),
    )
    
    // 5. 启动服务
    if err := httpServer.Start(
        ":8443", // 监听端口
        server.WithTLS("cert.pem", "key.pem"),
        server.WithAutoRedirectHTTP(8080),
        server.WithReadTimeout(15*time.Second),
        server.WithWriteTimeout(30*time.Second),
        server.WithIdleTimeout(120*time.Second),
        server.WithPProf("/debug"),
        server.WithMetricsCollector(prometheusCollector),
        server.WithGracefulShutdownTimeout(30*time.Second),
        server.WithShutdownHook(func() {
            log.Println("Running cleanup tasks...")
            db.Close()
        }),
    ); err != nil {
        log.Fatalf("Failed to start server: %v", err)
    }
}
```
