Caoliao QR Code MCP (草料二维码 MCP)
Créez et gérez des codes QR Caoliao depuis votre assistant IA : générez des codes par lots à partir d’une liste, configurez des formulaires et des calendriers d’inspection, et consultez ou analysez les enregistrements en langage courant.
Serveur MCP hébergé
npx add-mcp 'https://open.cli.im/mcp'S’installe dans Claude Code, Codex, Cursor et plus
Documentation
把草料二维码接进你配置的 MCP 客户端或自己开发的 Agent。使用 WorkBuddy、千问办公、豆包工作的普通用户,看 管理端 MCP 快速开始 即可。
连接后,AI 可以访问你授权的草料二维码组织:建立台账、批量生成二维码、上传文件、搭建表单与周期任务,或查询记录和扫码数据。具体范围见 工具列表 。只需读取单张码的公开内容时,用 扫码端 MCP 。
DeepSeek Harness 用户可直接 安装草料二维码插件 ,插件包含 MCP 连接和 Skill。
服务信息
| 项目 | 内容 |
|---|---|
| 服务地址 | https://open.cli.im/mcp |
| 传输方式 | Streamable HTTP |
| 鉴权方式 | OAuth 授权,不需要密钥 |
| 推荐连接器名 | caoliao-admin |
连接与 OAuth 授权
添加 MCP → 完成 OAuth 授权 → 让 AI 安装 Skill → 核对 Skill 和组织后开始任务。
最省事的做法是把 安装提示词 复制给 AI,由它添加配置并带你完成后面的步骤。想自己配置,按下面对应客户端的写法添加。
各客户端的配置
Claude Code
claude mcp add --transport http caoliao-admin https://open.cli.im/mcp
添加后在 Claude Code 里输入 /mcp ,选择 caoliao-admin 完成授权。
Cursor
点击在 Cursor 中安装 ,或在 ~/.cursor/mcp.json 里加入:
{
"mcpServers": {
"caoliao-admin": {
"url": "https://open.cli.im/mcp"
}
}
}
然后在 Cursor 的 MCP 设置里找到 caoliao-admin ,按提示登录授权。
VS Code
在工作区的 .vscode/mcp.json 里加入:
{
"servers": {
"caoliao-admin": {
"type": "http",
"url": "https://open.cli.im/mcp"
}
}
}
Claude 网页版和桌面版
在「设置 → 连接器」里添加自定义连接器,名称填 caoliao-admin ,地址填 https://open.cli.im/mcp ,其他项留空。
其他客户端
{
"mcpServers": {
"caoliao-admin": {
"type": "streamable-http",
"url": "https://open.cli.im/mcp"
}
}
}
type 的取值因客户端而异,部分客户端使用 http ;以客户端要求为准,服务地址不变。
安装 Skill
授权完成后,将 Skill 安装提示词 复制给 AI。提示词只安装 caoliao-admin Skill,保留已配好的 MCP。
授权机制
OAuth 授权页可选的档位受组织「最高权限」限制。超级管理员可 设置组织策略 。调高组织上限后,需要更高档位的客户端应重新授权。
管理端 MCP 按 MCP 授权规范(OAuth 2.1)实现。支持自动发现的客户端只需要服务地址,其余信息从元数据读取。自己开发客户端时,按下表对接。
| 项目 | 内容 |
|---|---|
| 资源元数据 | https://open.cli.im/.well-known/oauth-protected-resource |
| 授权服务器 | https://oauth.cli.im |
| 授权服务器元数据 | https://oauth.cli.im/.well-known/oauth-authorization-server |
| 授权方式 | 授权码 + PKCE、刷新令牌、设备码 |
| PKCE | 必须使用,只支持 S256 |
| 客户端认证 | none (公开客户端)、 client_secret_basic 、 client_secret_post |
| 令牌传递 | 请求头 Authorization: Bearer <access_token> |
端点地址以授权服务器元数据返回的为准,不要写死在代码里。
客户端注册
| 方式 | 是否支持 | 说明 |
|---|---|---|
| 动态注册(RFC 7591) | 支持 | 向元数据里的 registration_endpoint 发送 POST,返回 client_id 。主流 MCP 客户端会自动完成,不需要事先申请或预注册 |
| 客户端元数据文档(CIMD) | 暂不支持 | 元数据中没有 client_id_metadata_document_supported |
动态注册时注意:
- 不带登录态注册只能登记公开客户端,
token_endpoint_auth_method为none或不传。 grant_types不传时登记全部支持的授权方式。要用设备码授权,登记值里必须包含urn:ietf:params:oauth:grant-type:device_code。redirect_uris在授权时按登记值精确匹配。登记值是http://localhost或http://127.0.0.1这类本机回环地址时,授权请求可以换端口,主机和路径必须一致。
设备码授权:没有浏览器的环境
服务器、容器或 SSH 会话里的 Agent 打不开浏览器,也接收不了本地回调,用设备码授权(RFC 8628):终端显示一个网址和一串码,用户在手机或另一台电脑上确认。
- 向元数据里的
device_authorization_endpoint发送 POST,带上client_id,可选scope。返回device_code、user_code、verification_uri、verification_uri_complete、expires_in和interval。 - 把
verification_uri和user_code展示给用户,或把verification_uri_complete显示成二维码。用户打开后登录草料二维码账号、选择组织并同意。 - 按
interval给出的秒数轮询token_endpoint,参数为grant_type=urn:ietf:params:oauth:grant-type:device_code、device_code和client_id。
curl -X POST https://oauth.cli.im/oauth/device_authorization \
-d "client_id=<你的 client_id>"
轮询时的返回:
| 返回 | 含义 | 处理 |
|---|---|---|
authorization_pending | 用户还没确认 | 按原间隔继续轮询 |
slow_down | 轮询太快 | 加大间隔后继续 |
access_denied | 用户拒绝了授权 | 停止轮询 |
expired_token | 超过 expires_in 仍未确认 | 停止轮询,重新发起 |
返回 access_token | 授权完成 | 保存令牌,用 refresh_token 续期 |
scope 说明
| scope | 管什么 |
|---|---|
mcp:tools | 连接 MCP 客户端 |
qrcodes.read | 读码和浏览分区 |
metrics.read | 读指标定义、查询统计结果 |
content.edit_all | 配合写入 scope 修改成员手工创建的受支持内容 |
content.delete | 配合 qrcodes.write 或 templates.write 预览和执行删除 |
records.read | 读取填写记录及后续动态、周期计划和完成情况 |
records.write | 提交填写记录、核销凭证(REST 接口使用) |
templates.read | 读取可生成二维码的目标、可编辑模板及结构、官方模板、标签配置和预览 |
templates.write | 新建和编辑模板、表单;用官方模板生成二维码时与 qrcodes.write 同时需要 |
qrcodes.write | 新建和编辑二维码、批量生成二维码及查询任务结果、导出标签 |
assets.write | 上传图片和文件 |
授权页不让用户逐个勾选 scope,而是三选一:只读、读写、完全。个人 API Key 用同一套档位。
| 档位 | 包含的 scope |
|---|---|
| 只读 | mcp:tools 、 qrcodes.read 、 templates.read 、 records.read 、 metrics.read |
| 读写 | 只读的全部,加 qrcodes.write 、 templates.write 、 records.write 、 assets.write |
| 完全 | 读写的全部,加 content.edit_all 、 content.delete |
每个工具需要的 scope 见 工具列表 。自己开发客户端时按最小权限申请:
- 连接后查询表单记录用
records.read,查指标用metrics.read,读码用qrcodes.read。 - 还要生成二维码和搭建表单:再加
templates.read、templates.write、qrcodes.write;需要上传照片或附件时加assets.write。
scope 只决定能调用哪类工具。能读写哪些数据,仍由授权人在所选组织里的权限决定。
授权范围与撤销
OAuth 使用你在所选组织的当前权限,仍受授权 scope、分区、资源和字段可见范围限制。授权页不提供逐分区勾选,也不会自动扩大你的权限。
新建和编辑会实际保存到授权组织。修改已有内容前,先核对目标、改动及影响;模板编辑可能影响已有子码,见 工具列表 。
撤销或切换组织:在草料二维码管理中心进入「 全局设置 → 安全与溯源 → 授权管理 」,取消对应客户端;需要时重新授权。
验证连接
连接后可以对 AI 说:
请使用 caoliao-admin Skill 和同名 MCP,确认 Skill 已加载、当前组织及可用能力。只验证,不创建或修改数据。
Skill 已加载,且能返回当前组织与能力信息,即表示配置完成。
工具名称和参数以当前连接返回的 schema 为准,不以固定数量判断接入是否成功。
常见失败与排查
| 现象 | 原因 | 处理 |
|---|---|---|
| 工具列表为空,或调用返回 401 | 还没完成授权,或令牌已失效、已被撤销 | 在客户端里重新连接并完成授权 |
授权页或令牌接口返回 invalid_client | client_id 不存在,回调地址没有登记,或带密钥的客户端认证失败 | 清除客户端保存的草料二维码授权信息后重新连接,让它重新注册 |
| 提示回调地址不匹配 | 授权请求里的 redirect_uri 与登记值不一致 | 用登记时的回调地址;地址变了就重新注册。本机回环地址只允许端口不同 |
| 本地回调端口被占用,授权后页面打不开 | 客户端监听的本机端口被其他程序占用 | 关闭占用端口的程序后重试,或让客户端换一个端口;换端口不需要重新注册 |
invalid_scope | 申请了不支持的 scope | 只申请 上表 列出的 scope |
unauthorized_client | 客户端没有登记这种授权方式,常见于设备码 | 重新注册,并在 grant_types 里加上需要的授权方式 |
access_denied | 用户拒绝了授权,或账号没有可授权的组织 | 换用有权限的账号或组织后重新授权 |
| 授权成功但查不到数据 | 授权了别的组织,或授权人在该组织没有对应资源的权限 | 在「授权管理」里撤销后重新授权,选对组织 |
| 没有浏览器,无法完成授权 | 运行环境打不开授权页,也收不到本地回调 | 改用 设备码授权 |
仍无法解决时,把报错信息和发生时间,不要发送令牌或授权码。