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                      # 用户信息