Google Forms MCP Server with CamelAIOrg Agents Integration

集成 CamelAIOrg Agents 的 Google Forms MCP 服务

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

概述

本项目支持通过自然语言请求创建和管理 Google Forms。它由两个主要组件构成：

1. MCP 服务：基于 Flask 的服务，实现模型上下文协议（MCP），将 Google Forms 操作作为工具开放。
2. CamelAIOrg Agents：一个 AI Agent 框架，用于处理自然语言请求，并将其转换为 MCP 工具调用。

系统采用深色主题 UI，并通过动态可视化展示前端、Agents、MCP 服务与 Google API 之间的请求流。

功能

• 根据自然语言请求创建 Google Forms
• 添加不同类型的问题（文本、段落、单选题、复选框）
• 获取表单回复
• 可视化请求和回复的流转过程
• 带动画效果的深色主题 UI
• 完全符合 MCP（模型上下文协议）规范
• 使用 Docker 容器化，便于部署

架构

┌─────────────┐    ┌─────────────┐    ┌────────────┐    ┌────────────┐
│             │    │             │    │            │    │            │
│   Frontend  │◄──►│ CamelAIOrg  │◄──►│ MCP Server │◄──►│  Google    │
│    (UI)     │    │   Agents    │    │            │    │ Forms API  │
│             │    │             │    │            │    │            │
└─────────────┘    └─────────────┘    └────────────┘    └────────────┘

流程图

该图展示了用户请求在系统中的流转过程：

graph TD
    subgraph "User Interface"
        A[Frontend UI]
    end
    
    subgraph "Processing Logic"
        B((CamelAIOrg Agent))
        C((MCP Server))
    end
    
    subgraph "External Service"
        D{{Google Forms API}}
    end
    
    A -->|"1. User enters: Create feedback form"| B
    B -->|"2. Interprets request, sends tool call"| C
    C -->|"3. Translates to API request"| D
    D -->|"4. Returns formId and URL"| C
    C -->|"5. Processes API response"| B
    B -->|"6. Formats final result to 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 Agent（黄色高亮）：
  • 职责： 理解和规划。
  • 接收原始自然语言请求。
  • 解析请求，理解用户意图并提取关键信息（表单标题、问题、类型等）。
  • 确定满足请求所需的操作顺序（MCP 工具调用）。
  • 使用定义好的工具架构与 MCP 服务通信。
• MCP 服务（蓝色高亮）：
  • 职责： 执行和抽象。
  • 接收来自 Agent 的结构化工具调用。
  • 作为 Google Forms API 的专用接口。
  • 将抽象的工具调用（例如 create_form）转换为具体的 Google Forms API 请求。
  • 处理与 Google Forms API 的身份验证、通信和错误。
  • 将 Google Forms API 返回的结果以标准化的 MCP 格式传回 Agent。

为什么需要 MCP 服务？

模型上下文协议（MCP）服务之所以是至关重要的中间层，有以下几个原因：

1. 抽象： 它将底层 Google Forms API 的复杂性对 CamelAI Agent 隐藏起来。Agent 无需了解 Google API 的具体端点、身份验证方式或请求/回复格式，只需了解简化后的 MCP 工具架构（例如 create_form、add_question）。
2. 模块化与可复用性： Agent 可以与任何提供 MCP 接口的服务交互。如果要添加对其他表单服务（例如 Typeform）的支持，可以为其单独创建一个 MCP 服务；Agent 只需学习新的 MCP 工具架构，就可能以最少的改动使用该服务。
3. 标准化： MCP 为 AI 模型/Agent 提供了与外部工具和 API 交互的标准方式，从而促进互操作性。
4. 安全与控制： MCP 服务可以强制执行策略、安全管理 API 密钥、处理速率限制，并为外部 API 提供受控的网关，无需在 Agent 中直接嵌入敏感凭据或复杂逻辑。
5. 可维护性： 将 API 交互逻辑（MCP 服务）与自然语言理解和规划逻辑（Agent）分离，可使系统更易于维护和更新。Google Forms API 的变更只需更新 MCP 服务，无需修改 Agent 本身。

先决条件

• Docker 和 Docker Compose
• Google Cloud Platform 账号
• 已启用 Google Forms API
• 从 Google Cloud Console 获取的 OAuth2 凭据

设置说明

1. 克隆仓库

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

2. 设置 Google Forms API

1. 前往 Google Cloud Console
2. 创建新项目
3. 启用 Google Forms API 和 Google Drive API
4. 创建 OAuth2 凭据
   • Web 应用类型
   • 添加授权重定向 URI：http://localhost:5000/oauth2callback
5. 下载凭据 JSON 文件

3. 配置环境变量

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

# Google API Credentials
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REFRESH_TOKEN=your_refresh_token_here

# Server Configuration
FLASK_ENV=development
PORT=5000
DEBUG=True

# CamelAIOrg Agents Configuration
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 Agent 服务（端口 5001）。

使用方法

Web 界面

通过 http://localhost:5000 访问 Web 界面

该界面允许你：

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

API 端点

MCP 服务端点（端口 5000）

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

CamelAIOrg Agent 端点（端口 5001）

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

请求示例

以下是一些可以尝试的自然语言请求示例：

1. “创建一个客户反馈表单，包含一个 1-5 分的评分问题和一个用于补充评论的文本问题”
2. “创建一份关于远程办公偏好的调查问卷，包含 3 个多选题”
3. “创建一个活动 RSVP 表单，包含姓名、电子邮件和出席选项”

MCP 协议格式

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

{
  "transaction_id": "unique_transaction_id",
  "tool_name": "create_form",
  "parameters": {
    "title": "Form Title",
    "description": "Form Description"
  }
}

并返回：

{
  "transaction_id": "unique_transaction_id",
  "status": "success",
  "result": {
    "form_id": "form_id",
    "response_url": "https://docs.google.com/forms/d/form_id/viewform",
    "edit_url": "https://docs.google.com/forms/d/form_id/edit",
    "title": "Form Title"
  }
}

开发

项目结构

google-form-mcp-server/
├── server/                 # MCP Server
│   ├── app.py              # Main Flask application
│   ├── config.py           # Configuration
│   ├── forms_api.py        # Google Forms API integration
│   ├── mcp_handler.py      # MCP protocol handler
│   ├── requirements.txt    # Python dependencies
│   ├── static/             # Static assets
│   ├── templates/          # HTML templates
│   └── utils/              # Utility functions
├── agents/                 # CamelAIOrg Agents
│   ├── agent_integration.py # Agent implementation
│   ├── agent_server.py     # Agent API server
│   └── requirements.txt    # Python dependencies
├── Dockerfile              # MCP Server Dockerfile
├── docker-compose.yml      # Docker Compose configuration
├── .env.example            # Example environment variables
└── README.md               # Project documentation

不使用 Docker 运行

不使用 Docker 运行 MCP 服务：

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

不使用 Docker 运行 Agents 服务：

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

许可证

MIT

致谢

• Google Forms API
• CamelAIOrg 提供的 Agent 框架
• Model Context Protocol（MCP）规范