TDucKX技术文档
产品能力分析
表单数据对接
TDuckMCP 和 Skill
TDuckX 后端项目
TDuckX 前端项目
Uniapp 移动端
表单开放API
【文件夹】移动表单到文件夹
【表单】复合更新表单
【表单】修改单题
【表单】修改表单基础信息
【表单】停止表单收集
TDuck 表单开放平台 V2 题型与配置模型手册
【表单】全量覆盖替换题目
【文件夹】创建文件夹
【文件夹】获取文件夹列表
【表单数据】批量新增填报数据
【表单数据】删除单条填报数据
【表单】发布表单
【表单】获取表单列表
【表单】获取题目列表
【表单】查询表单详情
【表单】逻辑删除表单
【表单】删除单题
【表单】创建表单 (V2 极简模式)
【表单】复制表单
【表单】追加单题
【表单数据】上传附件 / 图片
【表单数据】修改单条填报数据
【表单数据】获取表单数据列表
【表单数据】获取单条数据明细
【表单数据】新增单条填报数据
TDuck MCP Server 与 OAuth 2.0 接入指南
接入说明
用户登录集成
多数据库适配
系统配置
如何部署或更新

TDuck MCP Server 与 OAuth 2.0 接入指南

TDuck MCP Server 与 OAuth 2.0 接入指南

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

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


🚀 快速接入 (一分钟上手)

1. Cursor 接入配置

在项目根目录创建 .cursor/mcp.json(或在 Cursor 设置中添加 MCP Server):

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

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"
    }
  }
}

3. 授权与使用体验

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

🔄 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 完整清单 (共 23 个)

1. 表单生命周期与管理

工具名称 (Tool Name) 功能描述 核心入参
list_forms 查询当前用户的表单列表 keyword, status (RELEASE/STOP), folderId, current, size
get_form_detail 获取表单完整的扁平题目结构与设置 formKey (必填)
create_form 快速创建全新表单或在线考试(极简模型) name (表单名), description, type, items (题目列表)
copy_form 复制已有表单的题目、设置与主题外观生成新表单 formKey (必填), name, folderId
update_form 复合更新表单基础信息、题目、主题外观或全局设置 formKey (必填), name, status, items, theme, setting, logic
replace_form_items 全量覆盖并重置指定表单的题目列表 formKey (必填), items (全新题目数组)
publish_form 发布表单开启数据收集通道,返回公开填报链接 formKey (必填)
stop_form 停止表单收集,关闭对外公开填写通道 formKey (必填)
delete_form 逻辑删除指定表单及其关联数据 formKey (必填)
update_form_basic 仅修改表单名称和描述信息 formKey (必填), name, description

2. 单题精细化维护

工具名称 (Tool Name) 功能描述 核心入参
list_form_items 获取指定表单的所有题目列表详情 formKey (必填)
add_form_item 在指定表单末尾追加一道新题目 formKey (必填), item (题目对象)
update_form_item 根据题目 ID 修改题目的标题、必填、选项等 formKey (必填), item (包含 id 的题目对象)
delete_form_item 从指定表单中删除某一道题目 formKey (必填), id (自定义题目 ID)

3. 文件夹管理

工具名称 (Tool Name) 功能描述 核心入参
list_folders 获取当前用户的所有一级文件夹列表 -
create_folder 创建新的表单归档一级文件夹 name (文件夹名称)
move_form_folder 将表单移动到指定文件夹(0 表示根目录) formKey (必填), folderId (文件夹 ID)

4. 表单数据与填报

工具名称 (Tool Name) 功能描述 核心入参
query_form_data 分页查询表单已收集的数据(自动映射题目ID) formKey (必填), keyword, beginDateTime, endDateTime, current, size
get_form_data_detail 根据 dataId 查询单条填报数据的完整内容 formKey (必填), dataId (数据 ID)
submit_form_data 向表单录入一条新数据(直接使用题目ID填报) formKey (必填), data (键值字典)
batch_submit_form_data 批量向表单写入多条填报数据(最多100条) formKey (必填), list (数据数组)
update_form_data 根据 dataId 修改单条已提交的数据内容 formKey (必填), dataId, data (修改键值)
delete_form_data 根据 dataId 删除指定的单条填报数据 formKey (必填), dataId (数据 ID)

⚙️ 配置文件说明 (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                      # 用户信息
官方文档·
约 10 分钟阅读 (3621 字)