coda-automation

通过 Rube MCP 自动化 Coda

通过 Rube MCP 使用 Composio 的 Coda 工具包，自动执行 Coda 文档和数据操作。

前提条件

• 必须已连接 Rube MCP（RUBE_SEARCH_TOOLS 可用）
• 通过 RUBE_MANAGE_CONNECTIONS 激活 Coda 连接，工具包为 coda
• 始终先调用 RUBE_SEARCH_TOOLS，获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。添加端点不会对 Coda 进行身份验证；请使用主机支持的授权连接。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 使用工具包 coda 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请通过返回的授权链接完成 Coda 身份验证
4. 运行任何工作流之前，确认连接状态显示 ACTIVE

核心工作流

写入前确认确切的文档、表格和行 ID，以及所请求的更改。授予权限可能会通知接收者；发布会将内容公开。这些操作需要用户明确提出请求，并说明接收者／访问权限或发布范围。一键调用可能触发外部操作，而不只是编辑单元格：请先检查其影响。行写入可能是异步的；在支持的情况下，使用返回的变更／请求状态，然后读取数据进行确认。重试 upsert 前先核实超时操作的状态，不要覆盖公式／计算列。不要在公开报告中泄露临时导出 URL 和私人文档内容。限制轮询次数，并妥善处理失败／过期的任务。

1. 搜索和浏览文档

适用场景：用户想要查找、列出或检查 Coda 文档

工具调用顺序：

1. CODA_SEARCH_DOCS 或 CODA_LIST_AVAILABLE_DOCS - 查找文档［必需］
2. CODA_RESOLVE_BROWSER_LINK - 将 Coda URL 解析为文档／页面／表格 ID［可选替代］
3. CODA_LIST_PAGES - 列出文档中的页面［可选］
4. CODA_GET_A_PAGE - 获取特定页面的详细信息［可选］

关键参数：

• query：用于查找文档的搜索词
• isOwner：筛选用户拥有的文档
• docId：页面操作所用的文档 ID
• pageIdOrName：页面标识符或名称
• url：用于解析操作的浏览器 URL

注意事项：

• 文档 ID 是字母数字字符串（例如，'AbCdEfGhIj'）
• CODA_RESOLVE_BROWSER_LINK 是将 Coda URL 转换为 API ID 的最佳方式
• 文档内的页面名称可能不唯一；优先使用页面 ID
• 搜索结果包括与用户共享的文档，不仅限于用户拥有的文档

2. 使用表格和数据

适用场景：用户想要读取、写入或查询表格数据

工具调用顺序：

1. CODA_LIST_TABLES - 列出文档中的表格［前置条件］
2. CODA_LIST_COLUMNS - 获取表格的列定义［前置条件］
3. CODA_LIST_TABLE_ROWS - 列出所有行，可选应用筛选条件［必需］
4. CODA_SEARCH_ROW - 按查询条件搜索特定行［可选替代］
5. CODA_GET_A_ROW - 按 ID 获取特定行［可选］
6. CODA_UPSERT_ROWS - 在表格中插入或更新行［可选］
7. CODA_GET_A_COLUMN - 获取特定列的详细信息［可选］

关键参数：

• docId：包含该表格的文档 ID
• tableIdOrName：表格标识符或名称
• query：用于搜索行的筛选查询
• rows：用于 upsert 操作的行对象数组
• keyColumns：upsert 匹配时使用的列 ID
• sortBy：用于排序结果的列
• useColumnNames：在行数据中使用列名称而不是 ID

注意事项：

• 表格名称可能包含空格；必要时请进行 URL 编码
• CODA_UPSERT_ROWS 会在 keyColumns 中没有匹配项时插入，在找到匹配项时更新
• keyColumns 必须引用具有唯一值的列，才能可靠地执行 upsert
• 列 ID 与列名称不同；请先列出列，将名称映射为 ID
• useColumnNames: true 允许在行数据中使用易读的名称
• 行数据值必须与列类型（文本、数字、日期等）匹配

3. 管理公式

适用场景：用户想要列出或计算文档中的公式

工具调用顺序：

1. CODA_LIST_FORMULAS - 列出文档中所有命名公式【必需】
2. CODA_GET_A_FORMULA - 获取指定公式的当前值【可选】

关键参数：

• docId：文档 ID
• formulaIdOrName：公式标识符或名称

注意事项：

• 公式是在文档中定义的命名计算
• 公式值由服务端计算；结果反映当前状态
• 公式名称区分大小写

4. 导出文档内容

适用场景：用户想要将文档或页面导出为 HTML 或 Markdown

工具调用顺序：

1. CODA_BEGIN_CONTENT_EXPORT - 启动导出任务【必需】
2. CODA_CONTENT_EXPORT_STATUS - 轮询导出状态，直到完成【必需】

关键参数：

• docId：要导出的文档 ID
• outputFormat：导出格式（'html' 或 'markdown'）
• pageIdOrName：要导出的指定页面（可选；省略则导出整个文档）
• requestId：用于轮询状态的导出请求 ID

注意事项：

• 导出是异步的；轮询状态，直到 status 为 'complete'
• 大型文档可能需要较长时间才能导出
• 完成响应中的导出 URL 是临时的；请及时下载
• 过于频繁地轮询可能触发速率限制；请以 2-5 秒为间隔

5. 管理权限与共享

适用场景：用户想要查看或管理文档访问权限

工具调用顺序：

1. CODA_GET_SHARING_METADATA - 查看当前共享设置【必需】
2. CODA_GET_ACL_SETTINGS - 获取访问控制列表设置【可选】
3. CODA_ADD_PERMISSION - 授予用户或电子邮件地址访问权限【可选】

关键参数：

• docId：文档 ID
• access：权限级别（'readonly'、'write'、'comment'）
• principal：包含收件人电子邮件地址或用户 ID 的对象
• suppressEmail：是否跳过共享通知电子邮件

注意事项：

• 权限级别：'readonly'、'write'、'comment'
• 默认情况下，添加权限会发送电子邮件通知；使用 suppressEmail 可阻止发送
• 在某些情况下，无法通过 API 移除权限；请检查 ACL 设置

6. 发布和自定义文档

适用场景：用户想要发布文档或管理自定义域名

工具调用顺序：

1. CODA_PUBLISH_DOC - 公开发布文档【必需】
2. CODA_UNPUBLISH_DOC - 取消发布文档【可选】
3. CODA_ADD_CUSTOM_DOMAIN - 为已发布文档添加自定义域名【可选】
4. CODA_GET_DOC_CATEGORIES - 获取用于发现文档的类别【可选】

关键参数：

• docId：文档 ID
• slug：已发布文档的自定义 URL 路径
• categoryIds：用于提升可发现性的类别 ID

注意事项：

• 发布后，任何拥有链接的人都可以访问该文档
• 自定义域名需要配置 DNS
• 取消发布会移除公开访问权限，但保留共享访问权限

常见模式

ID 解析

文档 URL -> 文档 ID：

1. Call CODA_RESOLVE_BROWSER_LINK with the Coda URL
2. Extract docId from the response

表名 -> 表 ID：

1. Call CODA_LIST_TABLES with docId
2. Find table by name, extract id

列名 -> 列 ID：

1. Call CODA_LIST_COLUMNS with docId and tableIdOrName
2. Find column by name, extract id

分页

• Coda 使用基于游标的分页，采用 pageToken
• 检查响应中的 nextPageToken
• 在下一次请求中将其作为 pageToken 传入，直到该值不存在
• 默认页面大小因端点而异

行 Upsert 模式

1. Call CODA_LIST_COLUMNS to get column IDs
2. Build row objects with column ID keys and values
3. Set keyColumns to unique identifier column(s)
4. Call CODA_UPSERT_ROWS with rows and keyColumns

已知注意事项

ID 格式：

• 文档 ID：字母数字字符串
• 表/列/行 ID：带前缀的字符串（例如，'grid-abc'、'c-xyz'）
• 使用 RESOLVE_BROWSER_LINK 将 URL 转换为 ID

数据类型：

• 行值必须与列类型相符
• 日期列要求使用 ISO 8601 格式
• 选择/多选列要求使用完全匹配的选项值
• 人员列要求使用电子邮件地址

速率限制：

• Coda API 对每个令牌设有速率限制
• 收到 429 响应时实施退避策略
• 通过 UPSERT_ROWS 批量操作行，比逐条更新更高效

快速参考

任务	工具 Slug	关键参数
搜索文档	CODA_SEARCH_DOCS	query
列出文档	CODA_LIST_AVAILABLE_DOCS	isOwner
解析 URL	CODA_RESOLVE_BROWSER_LINK	url
列出页面	CODA_LIST_PAGES	docId
获取页面	CODA_GET_A_PAGE	docId, pageIdOrName
列出表格	CODA_LIST_TABLES	docId
列出列	CODA_LIST_COLUMNS	docId, tableIdOrName
列出记录行	CODA_LIST_TABLE_ROWS	docId, tableIdOrName
搜索记录行	CODA_SEARCH_ROW	docId, tableIdOrName, query
获取记录行	CODA_GET_A_ROW	docId, tableIdOrName, rowIdOrName
更新或插入记录行	CODA_UPSERT_ROWS	docId, tableIdOrName, rows, keyColumns
获取列	CODA_GET_A_COLUMN	docId, tableIdOrName, columnIdOrName
推送按钮	CODA_PUSH_A_BUTTON	docId, tableIdOrName, rowIdOrName, columnIdOrName
列出公式	CODA_LIST_FORMULAS	docId
获取公式	CODA_GET_A_FORMULA	docId, formulaIdOrName
开始导出	CODA_BEGIN_CONTENT_EXPORT	docId, outputFormat
导出状态	CODA_CONTENT_EXPORT_STATUS	docId, requestId
获取共享信息	CODA_GET_SHARING_METADATA	docId
添加权限	CODA_ADD_PERMISSION	docId, access, principal
发布文档	CODA_PUBLISH_DOC	docId, slug
取消发布文档	CODA_UNPUBLISH_DOC	docId
列出 Pack	CODA_LIST_PACKS	(无)

何时使用

此技能适用于执行概述中描述的工作流或操作。

限制

• 仅当任务明确符合上述范围时才使用此技能。
• 请勿将输出视为环境特定验证、测试或专家评审的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并寻求澄清。