集成Google Forms与CamelAIOrg代理的MCP服务器

一个集成Google Forms API和CamelAIOrg代理的模型上下文协议（MCP）服务器，用于通过自然语言指令创建、修改和检索表单。

概述

该项目允许通过自然语言请求创建和管理Google表单。它由两个主要组件组成：

1. MCP服务器：基于Flask的服务器，实现模型上下文协议（MCP），以暴露Google表单操作作为工具。
2. CamelAIOrg代理：一个处理自然语言请求并将其转换为MCP工具调用的人工智能代理框架。

系统具有深色主题用户界面，并带有动画化的请求流程可视化，展示前端、代理、MCP服务器和Google API之间的交互。

特性

• 从自然语言请求创建Google表单
• 添加不同类型的问题（文本、段落、多项选择、复选框）
• 检索表单响应
• 可视化请求和响应的流程
• 带有动画的深色主题用户界面
• 完全符合MCP（模型上下文协议）
• 使用Docker容器化，便于部署

架构

┌─────────────┐    ┌─────────────┐    ┌────────────┐    ┌────────────┐
│             │    │             │    │            │    │            │
│   前端      │◄──►│ CamelAIOrg  │◄──►│ MCP 服务器 │◄──►│  Google    │
│    (UI)     │    │   代理      │    │            │    │ Forms API  │
│             │    │             │    │            │    │            │
└─────────────┘    └─────────────┘    └────────────┘    └────────────┘

流程图

此图表说明了用户请求如何流经系统：

graph TD
    subgraph "用户界面"
        A[前端UI]
    end
    
    subgraph "处理逻辑"
        B((CamelAIOrg代理))
        C((MCP服务器))
    end
    
    subgraph "外部服务"
        D{{Google Forms API}}
    end
    
    A -->|"1. 用户输入：创建反馈表单"| B
    B -->|"2. 解释请求，发送工具调用"| C
    C -->|"3. 转换为API请求"| D
    D -->|"4. 返回表单ID和URL"| C
    C -->|"5. 处理API响应"| B
    B -->|"6. 格式化最终结果到UI"| A
    
    style B fill:#f9d423,stroke:#333,stroke-width:2px,color:#333
    style C fill:#8ecae6,stroke:#333,stroke-width:2px,color:#333

组件角色

• 前端UI：提供用户界面，用于输入自然语言请求以及可视化过程和结果。
• CamelAIOrg代理（高亮黄色）：
  • 职责：解释和规划。
  • 接收原始自然语言请求。
  • 解析请求以理解用户的意图并提取关键细节（表单标题、问题、类型等）。
  • 确定完成请求所需的行动序列（MCP工具调用）。
  • 使用定义的工具模式与MCP服务器通信。
• MCP服务器（高亮蓝色）：
  • 职责：执行和抽象。
  • 接收来自代理的结构化工具调用。
  • 作为Google表单API的专用接口。
  • 将抽象的工具调用（如create_form）转换为具体的Google表单API请求。
  • 处理与Google表单API的认证、通信和错误处理。
  • 将Google表单API的结果以标准化的MCP格式返回给代理。

为什么需要MCP服务器？

模型上下文协议（MCP）服务器作为关键中间层的原因如下：

1. 抽象：它隐藏了底层Google表单API的复杂性，使CamelAI代理无需了解特定的端点、认证方法或请求/响应格式。代理只需知道简化的MCP工具模式（例如create_form、add_question）。
2. 模块化与可重用性：代理可以设计为与任何公开MCP接口的服务交互。如果想添加对另一个表单服务（如Typeform）的支持，可以为其创建单独的MCP服务器，代理可以通过学习新的MCP工具模式，几乎不需要更改就能使用它。
3. 标准化：MCP提供了一种标准方式让AI模型/代理与外部工具和API交互，这促进了互操作性。
4. 安全与控制：MCP服务器可以实施策略，安全地管理API密钥，处理速率限制，并提供对外部API的受控网关，而不是在代理中直接嵌入敏感凭证或复杂的逻辑。
5. 维护性：将API交互逻辑（MCP服务器）与自然语言理解和规划逻辑（代理）分离，使得系统更容易维护和更新。Google表单API的变化只需要更新MCP服务器，而不需要更新代理本身。

先决条件

• Docker和Docker Compose
• Google云平台账户
• 启用Google表单API
• 从Google云控制台获取OAuth2凭证

设置指南

1. 克隆仓库

git clone https://github.com/yourusername/google-form-mcp-server.git
cd google-form-mcp-server

2. 设置Google表单API

1. 访问Google云控制台
2. 创建新项目
3. 启用Google表单API和Google驱动器API
4. 创建OAuth2凭证
   • Web应用程序类型
   • 添加授权重定向URI：http://localhost:5000/oauth2callback
5. 下载凭证JSON文件

3. 配置环境变量

在根目录下创建.env文件：

# Google API凭证
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REFRESH_TOKEN=your_refresh_token_here

# 服务器配置
FLASK_ENV=development
PORT=5000
DEBUG=True

# CamelAIOrg代理配置
AGENT_ENDPOINT=http://agents:5001/process
AGENT_API_KEY=your_agent_api_key_here

要获得刷新令牌：

1. 使用OAuth 2.0 PlayGround：https://developers.google.com/oauthplayground/
2. 使用您的凭证设置
3. 选择所需的作用域：
   • https://www.googleapis.com/auth/forms
   • https://www.googleapis.com/auth/drive
   • https://www.googleapis.com/auth/drive.file
4. 交换授权码以获取令牌
5. 将刷新令牌复制到您的.env文件中

4. 使用Docker Compose构建和运行

docker-compose up --build

这将启动MCP服务器（端口5000）和CamelAIOrg代理服务（端口5001）。

使用

Web界面

访问Web界面：http://localhost:5000

该界面允许您：

1. 输入自然语言请求（例如，“创建一个包含3个问题的反馈表单”）
2. 查看组件之间的请求流程
3. 查看生成的表单详细信息和链接
4. 查看正在交换的MCP数据包

API端点

MCP服务器端点（端口5000）

• GET /api/health - 健康检查
• GET /api/schema - 获取MCP工具模式
• POST /api/process - 处理MCP请求

CamelAIOrg代理端点（端口5001）

• GET /health - 健康检查
• GET /schema - 获取代理能力
• POST /process - 处理自然语言请求

示例请求

这里有一些您可以尝试的自然语言请求示例：

1. “创建一个客户反馈表单，包含一个从1到5的评分问题和一个额外评论的文本问题”
2. “创建一个关于远程工作偏好的调查，包含3个多项选择题”
3. “创建一个活动回复表单，包含姓名、电子邮件和出席选项”

MCP协议格式

MCP服务器接受以下格式的请求：

{
  "transaction_id": "unique_transaction_id",
  "tool_name": "create_form",
  "parameters": {
    "title": "表单标题",
    "description": "表单描述"
  }
}

并响应：

{
  "transaction_id": "unique_transaction_id",
  "status": "success",
  "result": {
    "form_id": "表单ID",
    "response_url": "https://docs.google.com/forms/d/form_id/viewform",
    "edit_url": "https://docs.google.com/forms/d/form_id/edit",
    "title": "表单标题"
  }
}

开发

项目结构

google-form-mcp-server/
├── server/                 # MCP服务器
│   ├── app.py              # 主Flask应用
│   ├── config.py           # 配置
│   ├── forms_api.py        # Google表单API集成
│   ├── mcp_handler.py      # MCP协议处理器
│   ├── requirements.txt    # Python依赖
│   ├── static/             # 静态资产
│   ├── templates/          # HTML模板
│   └── utils/              # 工具函数
├── agents/                 # CamelAIOrg代理
│   ├── agent_integration.py # 代理实现
│   ├── agent_server.py     # 代理API服务器
│   └── requirements.txt    # Python依赖
├── Dockerfile              # MCP服务器Dockerfile
├── docker-compose.yml      # Docker Compose配置
├── .env.example            # 示例环境变量
└── README.md               # 项目文档

不使用Docker运行

要不使用Docker运行MCP服务器：

cd server
pip install -r requirements.txt
python app.py

要不使用Docker运行代理服务：

cd agents
pip install -r requirements.txt
python agent_server.py

许可证

MIT

致谢

• Google表单API
• CamelAIOrg的代理框架
• 模型上下文协议（MCP）规范