nofx/mcp/intro

MCP - Model Context Protocol Client

一个灵活、可扩展的 AI 模型客户端库，支持 DeepSeek、Qwen 等多种 AI 提供商。

✨ 特性

• 🔌 多 Provider 支持 - DeepSeek、Qwen、OpenAI 兼容 API
• 🎯 模板方法模式 - 固定流程，可扩展步骤
• 🏗️ 构建器模式 - 支持多轮对话、Function Calling、精细参数控制
• 📦 零外部依赖 - 仅使用 Go 标准库
• 🔧 高度可配置 - 支持 Functional Options 模式
• 🧪 易于测试 - 支持依赖注入和 Mock
• ⚡ 向前兼容 - 现有代码无需修改
• 📝 丰富的日志 - 可替换的日志接口

🚀 快速开始

基础用法

import "nofx/mcp"

// 创建客户端
client := mcp.NewClient(
    mcp.WithDeepSeekConfig("sk-xxx"),
)

// 调用 AI
result, err := client.CallWithMessages("system prompt", "user prompt")
if err != nil {
    log.Fatal(err)
}

fmt.Println(result)

DeepSeek 客户端

client := mcp.NewDeepSeekClientWithOptions(
    mcp.WithAPIKey("sk-xxx"),
    mcp.WithTimeout(60 * time.Second),
)

Qwen 客户端

client := mcp.NewQwenClientWithOptions(
    mcp.WithAPIKey("sk-xxx"),
    mcp.WithMaxTokens(4000),
)

🏗️ 构建器模式（高级功能）

构建器模式支持多轮对话、精细参数控制、Function Calling 等高级功能。

简单用法

// 使用构建器创建请求
request := mcp.NewRequestBuilder().
    WithSystemPrompt("You are helpful").
    WithUserPrompt("What is Go?").
    WithTemperature(0.8).
    Build()

result, err := client.CallWithRequest(request)

多轮对话

// 构建包含历史的多轮对话
request := mcp.NewRequestBuilder().
    AddSystemMessage("You are a trading advisor").
    AddUserMessage("Analyze BTC").
    AddAssistantMessage("BTC is bullish...").
    AddUserMessage("What about entry point?").  // 继续对话
    WithTemperature(0.3).
    Build()

result, err := client.CallWithRequest(request)

预设场景

// 代码生成（低温度、精确）
request := mcp.ForCodeGeneration().
    WithUserPrompt("Generate a HTTP server").
    Build()

// 创意写作（高温度、随机）
request := mcp.ForCreativeWriting().
    WithUserPrompt("Write a story").
    Build()

// 聊天（平衡参数）
request := mcp.ForChat().
    WithUserPrompt("Hello").
    Build()

Function Calling

// 定义工具
weatherParams := map[string]any{
    "type": "object",
    "properties": map[string]any{
        "location": map[string]any{"type": "string"},
    },
}

request := mcp.NewRequestBuilder().
    WithUserPrompt("北京天气怎么样？").
    AddFunction("get_weather", "Get weather", weatherParams).
    WithToolChoice("auto").
    Build()

result, err := client.CallWithRequest(request)

📖 详细文档

• 构建器模式完整示例 - 多轮对话、Function Calling、参数控制
• 构建器模式价值分析 - 为什么引入构建器模式
• 迁移指南 - 从旧 API 迁移到新 API
• Logrus 集成 - 日志框架集成示例
• 代码审查报告 - 问题分析和修复记录

🎛️ 配置选项

依赖注入

// 自定义日志器
mcp.WithLogger(customLogger)

// 自定义 HTTP 客户端
mcp.WithHTTPClient(customHTTP)

超时和重试

mcp.WithTimeout(60 * time.Second)
mcp.WithMaxRetries(5)
mcp.WithRetryWaitBase(3 * time.Second)

AI 参数

mcp.WithMaxTokens(4000)
mcp.WithTemperature(0.7)

Provider 配置

// 快速配置 DeepSeek
mcp.WithDeepSeekConfig("sk-xxx")

// 快速配置 Qwen
mcp.WithQwenConfig("sk-xxx")

// 自定义配置
mcp.WithAPIKey("sk-xxx")
mcp.WithBaseURL("https://api.custom.com")
mcp.WithModel("gpt-4")

🧪 测试

// 使用 Mock HTTP 客户端
mockHTTP := &MockHTTPClient{
    Response: `{"choices":[{"message":{"content":"test"}}]}`,
}

client := mcp.NewClient(
    mcp.WithHTTPClient(mockHTTP),
    mcp.WithLogger(mcp.NewNoopLogger()), // 禁用日志
)

🏗️ 架构设计

模板方法模式

CallWithMessages (固定重试流程)
    ↓
call (固定调用流程)
    ↓
hooks (可重写的步骤)
    ├─ buildMCPRequestBody
    ├─ marshalRequestBody
    ├─ buildUrl
    ├─ setAuthHeader
    ├─ parseMCPResponse
    └─ isRetryableError

接口分离

// 公开接口（给外部使用）
type AIClient interface {
    SetAPIKey(...)
    SetTimeout(...)
    CallWithMessages(...) (string, error)
}

// 内部钩子接口（供子类重写）
type clientHooks interface {
    buildMCPRequestBody(...) map[string]any
    buildUrl() string
    setAuthHeader(...)
    marshalRequestBody(...) ([]byte, error)
    parseMCPResponse(...) (string, error)
    isRetryableError(...) bool
}

🔄 向前兼容

所有旧 API 继续工作：

// ✅ 旧代码无需修改
client := mcp.New()
client.SetAPIKey("sk-xxx", "https://api.custom.com", "gpt-4")

dsClient := mcp.NewDeepSeekClient()
dsClient.SetAPIKey("sk-xxx", "", "")

📦 作为独立模块使用

// go.mod
module github.com/yourorg/yourproject

require github.com/yourorg/mcp v1.0.0

// main.go
import "github.com/yourorg/mcp"

client := mcp.NewClient(
    mcp.WithDeepSeekConfig("sk-xxx"),
)

🤝 扩展自定义 Provider

type CustomProvider struct {
    *mcp.Client
}

// 重写特定钩子
func (c *CustomProvider) buildUrl() string {
    return c.BaseURL + "/custom/endpoint"
}

func (c *CustomProvider) setAuthHeader(headers http.Header) {
    headers.Set("X-Custom-Auth", c.APIKey)
}

📝 日志器适配示例

Zap 日志器

type ZapLogger struct {
    logger *zap.Logger
}

func (l *ZapLogger) Infof(format string, args ...any) {
    l.logger.Sugar().Infof(format, args...)
}

func (l *ZapLogger) Debugf(format string, args ...any) {
    l.logger.Sugar().Debugf(format, args...)
}

// 使用
client := mcp.NewClient(
    mcp.WithLogger(&ZapLogger{zapLogger}),
)

Logrus 日志器

type LogrusLogger struct {
    logger *logrus.Logger
}

func (l *LogrusLogger) Infof(format string, args ...any) {
    l.logger.Infof(format, args...)
}

func (l *LogrusLogger) Debugf(format string, args ...any) {
    l.logger.Debugf(format, args...)
}

🎯 使用场景

开发环境

devClient := mcp.NewClient(
    mcp.WithDeepSeekConfig("sk-xxx"),
    mcp.WithLogger(&customLogger{}), // 详细日志
)

生产环境

prodClient := mcp.NewClient(
    mcp.WithDeepSeekConfig("sk-xxx"),
    mcp.WithLogger(&zapLogger{}),     // 结构化日志
    mcp.WithTimeout(30*time.Second),  // 超时保护
    mcp.WithMaxRetries(3),            // 重试保护
)

测试环境

testClient := mcp.NewClient(
    mcp.WithHTTPClient(mockHTTP),
    mcp.WithLogger(mcp.NewNoopLogger()),
)

📊 性能特性

• ✅ HTTP 连接复用
• ✅ 智能重试机制
• ✅ 可配置超时
• ✅ 零分配日志（使用 NoopLogger）

🛡️ 安全性

• ✅ API Key 部分脱敏日志
• ✅ HTTPS 默认启用
• ✅ 支持自定义 TLS 配置
• ✅ 请求超时保护

📈 版本兼容性

• Go 1.18+
• 向前兼容保证
• 语义化版本管理

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🔗 相关链接

• DeepSeek API 文档
• Qwen API 文档
• OpenAI API 文档