Eino MCP Chat Agent 使用文档

项目简介

这是一个基于 CloudWeGo Eino 框架构建的智能对话 Agent，支持通过 MCP (Model Context Protocol) 协议集成各种工具。项目包含一个自定义的文件统计 MCP Server，可以统计指定目录下的文件数量。

项目结构

eino-mcp-agent/
├── main.go                          # 主程序入口
├── config.yaml                      # 配置文件
├── go.mod                           # Go 模块定义
├── internal/                        # 内部包
│   ├── config/                      # 配置管理
│   │   └── config.go
│   ├── mcp/                         # MCP 客户端管理
│   │   └── manager.go
│   └── agent/                       # Agent 实现
│       └── agent.go
├── mcp-server/                      # 自定义 MCP Server
│   └── filecount-server.js         # 文件统计服务
└── README.md                        # 本文档

功能特性

• ✅ 支持多个 MCP Server 同时连接
• ✅ 基于 ReAct Agent 自动决策工具调用
• ✅ 流式对话输出
• ✅ 配置文件驱动，易于扩展
• ✅ 自定义 MCP Server 示例

环境要求

• Go 1.21+
• Python 3.7+ (用于运行 MCP Server) ⭐ 当前使用
• Node.js 16+ (可选，如果使用 JavaScript 版本的 MCP Server)
• LLM API Key (支持 OpenAI、Volcengine ARK 等)

安装步骤

1. 进入项目目录

cd /Users/wangfangyong/work/mymcp/eino-mcp-agent

2. 安装 Go 依赖

go mod tidy

3. 配置环境变量

# 使用 OpenAI
export OPENAI_API_KEY="your-openai-api-key"

# 或使用 Volcengine ARK (当前配置)
# API Key 已在 config.yaml 中配置
# 如需修改，编辑 config.yaml 中的 llm.api_key

4. 测试 MCP Server

# 测试 Python 版本（当前使用）
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0.0"}}}' | python3 mcp-server/filecount-server.py

# 或使用测试脚本
./test-mcp-python.sh

配置说明

config.yaml 配置文件

llm:
  provider: volcengine     # LLM 提供商 (openai, volcengine, ark)
  api_key: your-api-key    # API Key
  model: ep-xxx            # 模型端点 ID
  base_url: https://ark.cn-beijing.volces.com/api/v3  # API 端点

mcp_servers:
  - name: filecount         # MCP Server 名称
    type: stdio             # 传输类型 (stdio 或 sse)
    command: python3        # 启动命令
    args:                   # 命令参数
      - mcp-server/filecount-server.py
    enabled: true           # 是否启用
    tools:                  # 指定使用的工具（可选）
      - count_files

agent:
  system_prompt: |          # 系统提示词
    你是一个智能助手，可以使用工具来帮助用户完成任务。
    你可以使用 count_files 工具来统计指定目录下的文件数量。
  max_iterations: 10        # 最大工具调用次数

支持的 LLM 提供商

1. Volcengine ARK (当前配置)

llm:
  provider: volcengine
  api_key: your-volcengine-api-key
  model: ep-20251208120114-7csw8
  base_url: https://ark.cn-beijing.volces.com/api/v3

2. OpenAI

llm:
  provider: openai
  api_key: ${OPENAI_API_KEY}
  model: gpt-4
  base_url: https://api.openai.com/v1

3. 其他 OpenAI 兼容的 API

只要 API 兼容 OpenAI 格式，都可以通过配置 base_url 使用：

llm:
  provider: openai
  api_key: your-api-key
  model: your-model
  base_url: https://your-api-endpoint.com/v1

添加更多 MCP Server

在 config.yaml 的 mcp_servers 数组中添加新的配置：

mcp_servers:
  # 现有的 filecount server
  - name: filecount
    type: stdio
    command: node
    args:
      - mcp-server/filecount-server.js
    enabled: true
  
  # 添加文件系统 MCP Server
  - name: filesystem
    type: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/tmp"
    enabled: true
    tools:
      - read_file
      - write_file
      - list_directory
  
  # 添加 GitHub MCP Server
  - name: github
    type: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}
    enabled: false  # 默认禁用，需要时启用

运行程序

启动 Agent

go run main.go

交互命令

启动后，你可以使用以下命令：

• 直接输入问题进行对话
• 输入 tools 查看可用工具列表
• 输入 exit 退出程序

使用示例

示例 1: 查看可用工具

=== Eino MCP Chat Agent ===
Type 'exit' to quit, 'tools' to list available tools

You: tools

=== Available Tools ===
1. count_files: 统计指定目录下的文件数量（不包括子目录）

You: 

示例 2: 统计文件数量

You: 帮我统计一下 /Users/wangfangyong/work 目录下有多少个文件

Agent: 我来帮你统计 /Users/wangfangyong/work 目录下的文件数量...

[Agent 调用 count_files 工具]

根据统计结果：
- 目录: /Users/wangfangyong/work
- 文件数: 15
- 子目录数: 8
- 总计: 23

该目录下共有 15 个文件和 8 个子目录。

You: 

示例 3: 统计当前目录

You: 统计当前目录的文件数

Agent: 我来统计当前目录的文件...

[Agent 调用 count_files 工具，参数为 "."]

当前目录统计结果：
- 文件数: 5
- 子目录数: 3
- 总计: 8

You: 

示例 4: 处理错误情况

You: 统计 /nonexistent 目录的文件数

Agent: 让我检查一下这个目录...

[Agent 调用 count_files 工具]

抱歉，该目录不存在。错误信息：目录不存在: /nonexistent

请确认目录路径是否正确。

You: 

自定义 MCP Server 说明

filecount-server 功能

项目提供了两个版本的 MCP Server：

1. Python 版本 (当前使用): mcp-server/filecount-server.py
2. JavaScript 版本 (备用): mcp-server/filecount-server.js

详细说明请查看 PYTHON_MCP.md

工具名称: count_files

功能: 统计指定目录下的文件和子目录数量

输入参数:

• directory (string): 要统计的目录路径

输出:

• 文件数量
• 子目录数量
• 总计数量

实现特点:

• Python 版本：使用 pathlib，纯标准库，约 150 行
• JavaScript 版本：使用 fs/path，纯标准库，约 180 行
• 支持 MCP Stdio 传输协议
• 完整的错误处理
• 符合 MCP 2024-11-05 规范

版本切换

查看 PYTHON_MCP.md 了解如何在 Python 和 JavaScript 版本之间切换。

创建自己的 MCP Server

参考 filecount-server.js 的实现，你可以创建自己的 MCP Server：

1. 实现 initialize 方法返回服务器信息
2. 实现 tools/list 方法返回工具列表
3. 实现 tools/call 方法处理工具调用
4. 使用 Stdio 传输层进行通信

故障排查

问题 1: MCP Server 启动失败

症状: 程序启动时报错 "failed to initialize MCP client"

解决方法:

1. 检查 Python 是否已安装: python3 --version (需要 3.7+)
2. 检查 MCP Server 脚本路径是否正确
3. 手动测试 MCP Server: python3 mcp-server/filecount-server.py
4. 如果使用 JavaScript 版本，检查 Node.js: node --version

问题 2: OpenAI API 调用失败

症状: 对话时报错 "failed to create chat model"

解决方法:

1. 检查环境变量是否设置: echo $OPENAI_API_KEY
2. 检查 API Key 是否有效
3. 检查网络连接
4. 如果在国内，可能需要配置代理或使用国内镜像

问题 3: 工具调用失败

症状: Agent 无法正确调用工具

解决方法:

1. 使用 tools 命令检查工具是否加载
2. 检查 MCP Server 日志输出
3. 确认目录路径是否正确（使用绝对路径）

扩展开发

添加新的 LLM Provider

在 internal/agent/agent.go 的 createChatModel 函数中添加新的 case：

case "qwen":
    return qwen.NewChatModel(ctx, &qwen.ChatModelConfig{
        APIKey: cfg.APIKey,
        Model:  cfg.Model,
    })

添加更多工具到 filecount-server

在 filecount-server.js 中添加新的工具定义和处理逻辑：

this.tools = [
  {
    name: 'count_files',
    // ... 现有工具
  },
  {
    name: 'get_file_size',
    description: '获取文件大小',
    inputSchema: {
      type: 'object',
      properties: {
        filepath: {
          type: 'string',
          description: '文件路径'
        }
      },
      required: ['filepath']
    }
  }
];

参考资料

• Eino 官方文档
• MCP 协议规范
• MCP Go SDK

许可证

MIT License

联系方式

如有问题，请提交 Issue 或 Pull Request。