TDuck MCP Server 与 OAuth 2.0 接入指南

TDuck 表单开放平台现已原生支持 Model Context Protocol (MCP) 标准协议与 OAuth 2.0 (PKCE) 自动授权流。

通过 MCP，用户可以直接在 Claude Desktop、 Cursor、 Windsurf 等支持 MCP 协议的现代 AI 工具中，使用自然语言与 TDuck 表单引擎无缝交互（如创建表单、管理题目、查询填报数据、提交数据等），无需手动编写任何代码！

---

💡 两种接入方式对比

TDuck MCP Server 支持以下两种鉴权接入模式，您可以根据使用场景选择：

接入方式	适用场景	优点	配置方式
方式一：OAuth 2.0 自动授权 (推荐)	Cursor、Claude Desktop、Windsurf 等现代 AI 客户端	最快捷，只需配置服务端地址，首次连接自动拉起浏览器登录并授权，无需手动申请或复制 Key。	仅需配置 "url": "..."
方式二：OpenAPI 永久密钥 (Basic Auth)	自动化脚本、CI/CD、无浏览器环境、或需要长期免交互的环境	永久有效，无需周期性弹窗确认，适合服务端或无头客户端直连。	在 headers 中携带 Authorization: Basic

---

🚀 方式一：OAuth 2.0 快捷接入 (推荐・一分钟上手)

[!IMPORTANT] 服务地址说明： 以下配置中的 http://localhost:8996/tduck-api/mcp 为本地开发环境示例。 实际接入使用时，请务必将 localhost:8996 替换为您自己部署的实际域名与端口（例如 https://your-domain.com/tduck-api/mcp 或 http://192.168.1.x:8996/tduck-api/mcp）。

1. Cursor 快捷配置

在项目根目录创建 .cursor/mcp.json（或在 Cursor 设置 Settings -> Features -> MCP 中添加）：

{
  "mcpServers": {
    "tduck": {
      "url": "http://localhost:8996/tduck-api/mcp"
    }
  }
}

(注：请将 url 中的 localhost:8996 替换为您自己的服务域名与端口)

2. Claude Desktop 快捷配置

编辑 Claude Desktop 配置文件（Mac: ~/Library/Application Support/Claude/claude_desktop_config.json / Windows: %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "tduck": {
      "url": "http://localhost:8996/tduck-api/mcp"
    }
  }
}

(注：请将 url 中的 localhost:8996 替换为您自己的服务域名与端口)

3. 一键授权与使用

1. 保存配置后，AI 客户端会自动检测并弹出浏览器打开 TDuck 授权页面；
2. 登录并点击“确认授权”，连接即可瞬间激活；
3. 直接在 AI 对话框中下达指令，例如：
   • “帮我查一下我最近创建的所有 TDuck 表单”
   • “帮我创建一个‘2026年秋季校园招聘简历登记表’，包含姓名、性别、手机号、毕业院校、专业和附件简历”
   • “把表单 ICGqvdBR 最近提交的 5 条数据列出来”
   • “帮我把表单 ICGqvdBR 发布出去，把公开填写的网址告诉我”

---

🔑 方式二：OpenAPI 永久密钥接入 (Basic Auth)

如果您在无浏览器环境（如远程服务器、后台脚本），或希望永久免弹窗授权，可以使用 OpenAPI 密钥方式接入：

1. 获取认证 Token

1. 进入 TDuck 平台管理端，在「管理后台 / 其他工具 / 应用接入 」中创建或获取您的 AppId 与 AppSecret；
2. 计算 Basic Token 凭据：Base64(AppId:AppSecret)（例如 AppId=admin、AppSecret=123456，则对应 Base64 为 YWRtaW46MTIzNDU2）。

2. 客户端配置 Headers

在客户端配置中，通过 headers 传入 Authorization: Basic <Token>：

{
  "mcpServers": {
    "tduck": {
      "url": "http://localhost:8996/tduck-api/mcp",
      "headers": {
        "Authorization": "Basic YWRtaW46MTIzNDU2"
      }
    }
  }
}

(注：请将 url 替换为实际服务地址，并将 Basic YWRtaW46MTIzNDU2 替换为您真实的凭据)

---

🔄 MCP OAuth 2.0 协议流程细节

TDuck 严格遵循 IETF 与 MCP 官方 RFC 国际标准协议：

[Claude / Cursor 客户端]                 [TDuck 后端服务]                 [用户浏览器]
          │                                      │                            │
 1. GET /mcp (无 Token) ────────────────────────>│                            │
          │<── 401 + WWW-Authenticate 元数据头 ──│                            │
          │                                      │                            │
 2. GET /.well-known/oauth-protected-resource ──>│ (返回授权服务器地址)         │
          │                                      │                            │
 3. GET /.well-known/oauth-authorization-server ─>│ (返回 authorize/token 端点)│
          │                                      │                            │
 4. POST /open/oauth/register (动态客户端注册) ─>│ (生成 client_id)            │
          │                                      │                            │
 5. 生成 PKCE (code_verifier / code_challenge)   │                            │
    拉起浏览器打开授权页 ────────────────────────────────────────────────────>│
          │                                      │                            │ 用户确认授权
          │<── 回调 redirect_uri?code=xxx ─────────────────────────────────────│
          │                                      │                            │
 6. POST /open/oauth/token (code + verifier) ───>│ (校验 PKCE，下发 Token)     │
          │<── access_token ─────────────────────│                            │
          │                                      │                            │
 7. POST /mcp (Authorization: Bearer Token) ────>│ ──> 执行 MCP Tool 分发     │

🛠️ TDuck MCP Tools 工具集

TDuck MCP Server 目前提供了涵盖表单全生命周期管理的 30 个 Tools，支持 AI Agent 独立完成表单创建、修改、主题美化、逻辑跳题、数据录入分析等操作。

👉 详细工具入参说明与完整清单请查阅独立文档：TDuck MCP Tools 完整清单指南 (mcp-tools.md)

主要分类概览：

• 👤 账号与身份信息 (get_current_user)
• 📑 表单生命周期与整体管理 (list_forms, create_form, update_form, publish_form, stop_form, delete_form 等)
• 🔀 显隐跳题逻辑与计算公式 (get_form_logic, update_form_logic)
• 📝 单题精细化维护 (list_form_items, add_form_item, update_form_item, delete_form_item)
• 📁 文件夹归档管理 (list_folders, create_folder, move_form_folder)
• 📊 表单数据回收与填报 (query_form_data, submit_form_data, batch_submit_form_data 等)
• 🛡️ 数据安全防护 (check_field_data)
• 📤 文件与图片直传通道 (get_upload_ticket, upload_file)
• 🔍 公开自助查询页 (list_opensearch_queries, create_opensearch_query 等)

---

⚙️ 配置文件说明 (application.yml)

可在 Spring Boot 配置中自定义 MCP 服务的外部访问域名与 Token 有效期（issuer 会自动以 server-url 为准）：

tduck:
  mcp:
    server-url: http://localhost:8996/tduck-api # 外部访问根地址（支持根据反向代理域名调整）
    access-token-expire-seconds: 604800         # Token 有效期（默认 7 天）
    auth-code-expire-seconds: 300               # 授权码有效期（默认 5 分钟）
    scopes-supported: # TDuck 平台专属权限范围
      - tduck:all                               # 完整读写与管理权限
      - tduck:form:manage                       # 表单设计与生命周期管理
      - tduck:data:read                         # 表单回收数据查询
      - tduck:data:write                        # 表单数据录入与填报
      - tduck:user:profile                      # 用户信息