MCP Agents Go

mcp特工走了

一个Go库，用于构建可以使用大型语言模型（LLM）与多模型上下文协议（MCP）服务器交互的智能代理。

概述

mcp-agents-go提供了一个创建AI代理的框架，可以：

• 连接到多个MCP服务器以访问各种工具和资源
• 使用不同的LLM提供程序（目前支持Azure OpenAI）
• 根据自然语言提示执行工具调用
• 管理具有不同功能和工具访问权限的多个代理

本项目使用：

• 朗肯走 用于LLM集成
• mark3labs/mcp go 用于MCP客户端和服务器功能

特性

• 多提供商LLM支持：目前支持具有可扩展架构的Azure OpenAI
• 灵活的MCP服务器连接：支持stdio和SSE传输类型
• 基于代理的体系结构：创建具有不同工具访问权限的多个代理
• 配置驱动的设置：基于YAML的配置，便于部署
• 工具访问控制：对每个代理可以使用的工具进行细粒度控制
• 流媒体响应：实时响应流 GenerateContentAsStreaming
• 增强对话流：支持与工具交互的复杂多回合对话

安装

go get github.com/carlossantin/mcp-agents-go

快速开始

1.配置文件

创建一个 config.yaml 向您的提供商、服务器和代理提交文件：

providers:
  - name: my-azure-provider
    type: AZURE
    token: 
    baseUrl: 
    model: gpt-4o-mini
    version: 2025-01-01-preview

servers:
  - name: my-mcp-server
    type: sse
    url: http://localhost:8080/mcp/events
    # For stdio servers:
    # type: stdio
    # command: 
    #   - /path/to/your/mcp-server

agents:
  - name: my-agent
    servers:
      - name: my-mcp-server
        allowed_tools:
          - tool001
          - tool002
    provider: my-azure-provider

2.基本用法

package main

import (
    "context"
    "fmt"
    "github.com/carlossantin/mcp-agents-go/config"
    "github.com/tmc/langchaingo/llms"
)

func main() {
    ctx := context.Background()
    
    // Setup from configuration file
    err := config.SetupFromFile(ctx, "config.yaml")
    if err != nil {
        panic(err)
    }
    
    // Get an agent and generate content
    agent, ok := config.SysConfig.Agents["my-agent"]
    if !ok {
        panic("Agent not found")
    }
    
    // Create message content
    msgs := []llms.MessageContent{
        {Role: llms.ChatMessageTypeHuman, Parts: []llms.ContentPart{llms.TextContent{Text: "What tools are available?"}}},
    }
    
    response, _ := agent.GenerateContent(ctx, msgs, false)
    fmt.Println(response)
}

2.1.流媒体使用情况

对于实时流媒体响应：

package main

import (
    "context"
    "fmt"
    "github.com/carlossantin/mcp-agents-go/config"
    "github.com/tmc/langchaingo/llms"
)

func main() {
    ctx := context.Background()
    
    // Setup from configuration file
    err := config.SetupFromFile(ctx, "config.yaml")
    if err != nil {
        panic(err)
    }
    
    // Get an agent
    agent, ok := config.SysConfig.Agents["my-agent"]
    if !ok {
        panic("Agent not found")
    }
    
    // Create message content
    msgs := []llms.MessageContent{
        {Role: llms.ChatMessageTypeHuman, Parts: []llms.ContentPart{llms.TextContent{Text: "Give me the current dollar to real exchange rate in BRL."}}},
    }
    
    // Stream responses
    var textResp <-chan string
    var msgsResp <-chan llms.MessageContent
    textResp, msgsResp = agent.GenerateContentAsStreaming(ctx, msgs, true)

    // Process both channels concurrently
    go func() {
        for resp := range msgsResp {
            msgs = append(msgs, resp)
        }
    }()

    for resp := range textResp {
        fmt.Print(resp)
    }
}

3.程序设置

您可以通过编程方式设置系统，而不是使用配置文件：

package main

import (
    "context"
    "github.com/carlossantin/mcp-agents-go/config"
    "github.com/carlossantin/mcp-agents-go/agent"
    "github.com/tmc/langchaingo/llms"
)

func main() {
    ctx := context.Background()
    
    providers := []config.LLMProvider{
        {
            Name:    "my-provider",
            Type:    "AZURE",
            Token:   "your-token",
            BaseURL: "your-base-url",
            Model:   "gpt-4o-mini",
            Version: "2025-01-01-preview",
        },
    }
    
    servers := []config.MCPServer{
        {
            Name: "my-server",
            Type: "sse",
            URL:  "http://localhost:8080/mcp/events",
        },
    }
    
    agents := []config.MCPAgent{
        {
            Name: "my-agent",
            MCPAgentServers: []agent.MCPAgentServer{
                {
                    Name:         "my-server",
                    AllowedTools: []string{"tool1", "tool2"},
                },
            },
            Provider: "my-provider",
        },
    }
    
    err := config.Setup(ctx, providers, servers, agents)
    if err != nil {
        panic(err)
    }
}

配置参考

LLM提供商

providers:
  - name: string          # Unique identifier for the provider
    type: string          # Currently supports "AZURE"
    token: string         # API token/key
    baseUrl: string       # Base URL for the API
    model: string         # Model name (e.g., "gpt-4o-mini")
    version: string       # API version (for Azure)

MCP服务器

servers:
  - name: string          # Unique identifier for the server
    type: string          # "stdio" or "sse"
    # For stdio servers:
    command: []string     # Command to start the server
    # For SSE servers:
    url: string           # Server URL
    headers: []string     # Optional HTTP headers

代理

agents:
  - name: string          # Unique identifier for the agent
    servers:              # List of MCP servers this agent can use
      - name: string      # Server name (must match a server definition)
        allowed_tools:    # Optional: restrict which tools can be used
          - string
    provider: string      # Provider name (must match a provider definition)

建筑

该库由几个主要组件组成：

• 配置：管理系统配置和初始化
• 服务器：处理MCP服务器连接（stdio和SSE）
• 代理：通过LLM集成实现代理逻辑
• 例子：演示使用模式

代理工作流

1. 代理收到自然语言提示，如下所示 MessageContent
2. LLM分析提示并确定是否需要工具
3. 如果需要工具，代理将通过MCP服务器执行这些工具
4. 工具响应被反馈给LLM，以生成最终响应
5. 对于流模式，响应在生成时实时传递

api参考

代理方法

GenerateContent(ctx context.Context, msgs []llms.MessageContent, addNotFinalResponses bool) (string, []llms.MessageContent)

从消息序列同步生成内容。

参数：

• ctx：请求的上下文
• msgs：表示对话的消息内容数组
• addNotFinalResponses：是否在响应中包含中间工具执行详细信息

退货：

• string：生成的响应文本
• []llms.MessageContent：完整的对话背景，包括新的回应

GenerateContentAsStreaming(ctx context.Context, msgs []llms.MessageContent, addNotFinalResponses bool) (chan string, chan llms.MessageContent)

生成具有实时流媒体响应的内容。

参数：

• ctx：请求的上下文
• msgs：表示对话的消息内容数组
• addNotFinalResponses：是否在流中包含中间工具执行详细信息

退货：

• chan string：用于流式传输响应块的通道
• chan llms.MessageContent：完整消息上下文通道

消息内容结构

消息使用 llms.MessageContent 结构：

type MessageContent struct {
    Role  ChatMessageType  // Human, AI, Tool, etc.
    Parts []ContentPart    // Text, images, tool calls, etc.
}

示例用法：

msgs := []llms.MessageContent{
    {
        Role: llms.ChatMessageTypeHuman, 
        Parts: []llms.ContentPart{
            llms.TextContent{Text: "Your question here"}
        }
    },
}

环境变量

您可以在配置文件中使用环境变量：

servers:
  - name: my-server
    type: sse
    url: ${MY_SERVER_URL|http://localhost:8080/mcp/events}

高级功能

工具执行跟踪

当 addNotFinalResponses 设置为 true，代理提供有关工具执行的详细信息：

• [tool_usage] tool_name：指示正在执行的工具
• [tool_response] tool_name: response：显示工具的响应（如果长度超过1000个字符，则截断）

这对于调试和理解代理的决策过程特别有用。

对话上下文管理

两者 GenerateContent 和 GenerateContentAsStreaming 方法返回完整的对话上下文，允许您：

• 维护多个交互中的对话历史记录
• 实现对话持久化
• 构建复杂的多回合对话

例子：

// Initial conversation
msgs := []llms.MessageContent{
    {Role: llms.ChatMessageTypeHuman, Parts: []llms.ContentPart{llms.TextContent{Text: "Hello!"}}},
}

response, conversationContext := agent.GenerateContent(ctx, msgs, false)

// Continue conversation with context
conversationContext = append(conversationContext, llms.MessageContent{
    Role: llms.ChatMessageTypeHuman, 
    Parts: []llms.ContentPart{llms.TextContent{Text: "What was my previous question?"}},
})

response2, updatedContext := agent.GenerateContent(ctx, conversationContext, false)

实时流媒体

流媒体功能允许实时响应传递：

var textResp <-chan string
var msgsResp <-chan llms.MessageContent
textResp, msgsResp = agent.GenerateContentAsStreaming(ctx, msgs, true)

// Process both channels concurrently
go func() {
    for msg := range msgsResp {
        // Handle conversation context updates
        msgs = append(msgs, msg)
    }
}()

for chunk := range textResp {
    fmt.Print(chunk) // Print each chunk as it arrives
}

错误处理

该库包括全面的错误处理：

• 初始化过程中会报告服务器连接失败
• 工具执行错误将传递给LLM进行适当处理
• 配置验证确保所有必填字段都存在
• 流操作包括通过通道传播错误

最佳实践

1. 始终检查代理是否存在 使用前：

   agent, ok := config.SysConfig.Agents["my-agent"]
   if !ok {
       return fmt.Errorf("agent not found")
   }

1. 正确处理流媒体频道:

   var textResp <-chan string
   var msgsResp <-chan llms.MessageContent
   textResp, msgsResp = agent.GenerateContentAsStreaming(ctx, msgs, true)

   // Handle both channels concurrently
   go func() {
       for msg := range msgsResp {
           // Process conversation context
       }
   }()

   for chunk := range textResp {
       fmt.Print(chunk)
   }

1. 使用上下文取消:

   ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
   defer cancel()

   response, _ := agent.GenerateContent(ctx, msgs, false)

1. 管理对话上下文 对于多回合对话：

   var conversationHistory []llms.MessageContent

   // Add user message
   conversationHistory = append(conversationHistory, llms.MessageContent{
       Role: llms.ChatMessageTypeHuman,
       Parts: []llms.ContentPart{llms.TextContent{Text: userInput}},
   })

   // Get response and update context
   response, updatedContext := agent.GenerateContent(ctx, conversationHistory, false)
   conversationHistory = updatedContext

依赖项

此项目使用几个关键依赖项：

• tmc/langchaingo：LLM集成和会话管理
• mark3labs/mcp go：MCP客户端和服务器功能
• 字节/声波：高性能JSON序列化
• gookit/config：支持环境变量的配置管理
• 生命4/起源：切片和集合的实用函数

贡献

欢迎投稿！请随时提交拉取请求。

在捐款时，请确保：

• 您的代码遵循Go最佳实践
• 包括新功能的测试
• 更新API变更文档
• 适当处理错误
• 考虑向后兼容性

许可证

此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。

支持

如有疑问和支持，请 创建问题 在GitHub上。

常见问题

1. 未找到代理：确保您的 config.yaml 文件格式正确，代理名称匹配
2. 工具执行失败：检查您的MCP服务器是否正在运行且可访问
3. 流媒体问题：确保您正确处理了返回的两个频道 GenerateContentAsStreaming
4. 配置错误：验证所有必填字段是否存在，环境变量是否已设置