gomcptest: 使用自定义主机进行MCP概念验证

该项目是一个概念验证（POC），演示如何使用自定义构建的主机实现模型上下文协议（MCP）以与代理系统交互。代码主要从零开始编写，以便清晰地理解底层机制。

参见实验网站上的文档（自动生成）：https://owulveryck.github.io/gomcptest/

目标

该项目的主要目标是通过模型上下文协议（MCP）轻松测试代理系统。例如：

• dispatch_agent 可以专门用于扫描代码库中的安全漏洞
• 创建代码审查代理，可以分析拉取请求中的潜在问题
• 构建数据分析代理，处理并可视化复杂的数据集
• 开发自动化文档生成代理，可以从代码中生成全面的文档

这些专用代理可以使用本仓库提供的工具轻松测试和迭代。

预备条件

• Go >= 1.21
• 访问Google Cloud Platform上的Vertex AI API
• github.com/mark3labs/mcp-go

工具使用由gcloud auth login配置的默认GCP登录凭证。

项目结构

• host/openaiserver：实现一个模仿OpenAI API的自定义主机，使用Google Gemini和函数调用。这是POC的核心部分，并包括现代的AgentFlow网页界面。
• host/cliGCP：类似于Claude Code的CLI工具，用于测试代理交互。⚠️ 注意：此组件已被弃用，推荐使用AgentFlow网页界面。
• tools：包含各种与MCP兼容的工具，可用于主机：
  • Bash：执行Bash命令
  • Edit：编辑文件内容
  • GlobTool：查找匹配通配符模式的文件
  • GrepTool：使用正则表达式搜索文件内容
  • LS：列出目录内容
  • Replace：替换整个文件内容
  • View：查看文件内容
  • dispatch_agent：用于各种自动化任务的专用代理调度器
  • imagen：使用Google Imagen生成和操作图像
  • duckdbserver：用于数据处理的DuckDB服务器

组件

关键特性

• OpenAI兼容性：API设计为与OpenAI v1聊天完成格式兼容。
• Google Gemini集成：它利用VertexAI API与Google Gemini模型互动。
• 流支持：服务器支持流响应。
• 函数调用：允许Gemini调用外部函数并将结果整合到聊天回复中。
• MCP服务器交互：演示与MCP（模型上下文协议）服务器交互以执行工具。
• AgentFlow网页界面：现代、移动优化的网页界面，用于使用自然语言测试代理系统。
• Vertex AI内置工具：支持Google的原生工具，包括代码执行、Google搜索和Google搜索检索。
• 模板引擎：灵活的模板系统支持多种部署模式。

构建工具

您可以使用根Makefile构建所有工具和服务器：

# 构建所有工具和服务器
make all

# 仅构建工具
make tools

# 仅构建服务器
make servers

# 运行特定工具进行测试
make run TOOL=Bash

# 将二进制文件安装到指定目录
make install INSTALL_DIR=/path/to/install

# 清理构建工件
make clean

配置

设置主机应用程序所需的环境变量：

export GCP_PROJECT=your-project-id
export GCP_REGION=your-region
export GEMINI_MODELS=gemini-2.0-flash

# 可选：启用Vertex AI内置工具
export VERTEX_AI_CODE_EXECUTION=true
export VERTEX_AI_GOOGLE_SEARCH=true
export VERTEX_AI_GOOGLE_SEARCH_RETRIEVAL=true

注意：由于图像功能现在由独立的MCP工具tools/imagen提供，因此主机不再需要IMAGEN_MODELS和IMAGE_DIR。

AgentFlow网页界面

AgentFlow 是与代理系统交互的现代基于Web的界面。它直接嵌入到openaiserver二进制文件中，提供了专业、移动优化的实时流式响应聊天体验。

特性

• 移动优先设计：针对iPhone和移动设备进行了优化，支持Apple触摸图标
• 实时流式传输：服务器发送事件，立即显示响应
• 专业风格：干净、现代的界面，带有渐变背景
• 对话管理：持久的对话历史记录，易于导航
• 附件支持：上传和管理文件，包括PDF
• 嵌入式架构：构建到主openaiserver中，便于部署

如何访问AgentFlow

只需启动openaiserver并在/ui端点访问UI：

./bin/openaiserver
# AgentFlow UI可用地址：http://localhost:8080/ui

就是这样！无需单独的UI服务器——AgentFlow已嵌入到主二进制文件中。

开发说明

simpleui目录包含一个仅用于开发和测试目的的独立UI服务器。常规用户应通过/ui端点使用嵌入式UI。

测试CLI（已弃用）

⚠️ 注意：CLI工具已被弃用，推荐使用AgentFlow网页界面。

您仍然可以通过bin目录中的旧CLI进行测试：

./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./dispatch_agent -glob-path ./GlobTool -grep-path ./GrepTool -ls-path ./LS -view-path ./View;./Bash;./Replace;./imagen"

警告

⚠️ 警告：这些工具具有在您的系统上执行命令和修改文件的能力。建议在chroot或容器环境中使用它们，以防对系统造成潜在损害。

快速入门

本指南将帮助您快速运行位于host/openaiserver目录下的openaiserver。

预备条件

• 已安装并配置了Go。
• 正确设置了环境变量。

运行服务器

1. 导航到host/openaiserver目录：

   cd host/openaiserver
   

2. 设置所需环境变量。有关环境变量的详细信息，请参阅配置部分。最小示例：

   export GCP_PROJECT=your-gcp-project-id
   export GCP_REGION=us-central1
   

3. 运行服务器：

   go run .
   

   或

   go run main.go
   

   若要进行全事件流测试（推荐用于开发）：

   go run . -withAllEvents
   

服务器将启动并监听配置的端口（默认：8080）。

配置

openaiserver应用程序使用环境变量进行配置。支持以下变量：

全局配置

变量	描述	默认值	是否必需
PORT	服务器监听的端口	8080	否
LOG_LEVEL	日志级别（DEBUG, INFO, WARN, ERROR）	INFO	否

GCP配置

变量	描述	默认值	是否必需
GCP_PROJECT	Google Cloud项目ID		是
GEMINI_MODELS	逗号分隔的Gemini模型列表	gemini-1.5-pro,gemini-2.0-flash	否
GCP_REGION	Google Cloud区域	us-central1	否

Vertex AI内置工具

变量	描述	默认值	是否必需
VERTEX_AI_CODE_EXECUTION	启用Vertex AI代码执行工具	false	否
VERTEX_AI_GOOGLE_SEARCH	启用Vertex AI Google搜索工具	false	否
VERTEX_AI_GOOGLE_SEARCH_RETRIEVAL	启用Vertex AI Google搜索检索工具	false	否

OpenAI服务器命令行选项

标志	描述	默认值	是否必需
-mcpservers	输入字符串形式的MCP服务器		否
-withAllEvents	在流输出中包含所有事件（工具调用、工具响应），而不仅仅是内容块	false	否

⚠️ 重要提示：对于开发中的工具事件流测试，-withAllEvents标志是必须的。它使所有工具执行事件（包括工具调用和响应）的流式传输成为可能，这对于调试和开发至关重要。如果没有这个标志，只有标准的聊天完成响应会被流式传输。

注意：由于图像生成现在由独立的tools/imagen MCP服务器处理，因此主机不再需要IMAGEN_MODELS和IMAGE_DIR环境变量。

备注

• 这是一个POC，存在局限性。
• 提供代码是为了教育目的，了解如何使用自定义主机实现MCP。