dingtalk-ai-table

DingTalk AI テーブル操作（新版 MCP）

🚀 5 分でクイックスタート

1️⃣ 自分のテーブルを一覧表示

mcporter call '<DINGTALK_MCP_URL>' .list_bases limit=5

2️⃣ 新しいテーブルを作成

mcporter call '<DINGTALK_MCP_URL>' .create_base baseName='我的项目'

3️⃣ レコードを追加

mcporter call '<DINGTALK_MCP_URL>' .create_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_name":"张三"}}]}'

4️⃣ レコードを検索

mcporter call '<DINGTALK_MCP_URL>' .query_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":10}'

5️⃣ 一括インポート

python3 scripts/import_records.py base_xxx tbl_xxx data.csv

---

コアコンセプト

新版 MCP schema に基づいて動作します：

• Base：baseId
• Table：tableId
• Field：fieldId
• Record：recordId

旧版の dentryUuid / sheetIdOrName / fieldIdOrName は使用しないでください。

mcporter 0.8.1 以降の使用を推奨します。

出力モードの互換性に関する説明：

• mcporter 0.8.1+ では直接呼び出せます
• それより古いバージョンでは --output text を明示的に追加する必要があります
• AI テーブル MCP は、どのモードを使用しても、レスポンス本文自体は標準 JSON です。違いは主に mcporter の出力処理方法にあります

バージョン確認ルール（各 MCP Server アドレスにつき、強制チェックは 1 回のみ）

AI テーブルの操作を実際に開始する前に、現在 mcporter に登録されている dingtalk-ai-table MCP server が実際に返す tools schema を確認する必要があります。ただし、この確認を毎回繰り返す必要はありません。同じ MCP Server アドレスにつき、強制チェックは 1 回のみです。

1 回限りのチェック方針

1. まず、現在 mcporter に登録されている dingtalk-ai-table に対応する MCP Server アドレスを読み取ります。
2. このアドレスから、ローカルのチェックマーカーを生成します（完全な URL またはそのハッシュに基づく方法など）。
3. チェック結果をワークスペースに保存します。たとえば、次の場所に保存します：

~/.openclaw/workspace/.cache/dingtalk-ai-table/

推奨ファイル名の形式：

schema-check-<url-hash>.json

4. 現在のアドレスに対応するチェックマーカーがすでに存在し、結果が「新版 schema を確認済み」であれば、重複チェックをスキップして、そのまま後続の AI テーブル操作に進みます。
5. 次の場合に限り、強制チェックを再実行します：
   • 初回実行で、チェックマーカーがない
   • mcporter に登録されている MCP Server アドレスが変更された
   • 以前のチェック結果が旧版 schema またはチェック失敗だった
   • ユーザーから再確認を明示的に求められた

強制チェックの実行

mcporter list dingtalk-ai-table --schema

判定基準

返される tools が次のような旧版のままである場合：

• get_root_node_of_my_document
• create_base_app
• list_base_tables
• add_base_record
• search_base_record
• list_base_field

または、全体が依然として次の項目に基づいている場合：

• dentryUuid
• sheetIdOrName
• fieldIdOrName

skill ファイルは新版でも、mcporter に登録されている MCP server アドレスは旧版のままなので、操作を続行できません。

旧版 schema が検出された場合の必須案内

この場合、ユーザーに次の内容を明確に案内する必要があります：

1. 次のページを開きます： https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail
2. 右側の 「获取 MCP Server 配置」 ボタンをクリックします
3. 新しい MCP Server アドレスをコピーします
4. 新しいアドレスで、mcporter に登録済みの dingtalk-ai-table アドレスを置き換えます
5. 置き換え後、次を再実行します：

mcporter list dingtalk-ai-table --schema

返される tools が次のような新版 schema になった場合に限り、実際の AI テーブル操作を続行できます：

• list_bases
• get_base
• get_tables
• get_fields
• query_records
• create_records
• update_records
• delete_records
• prepare_attachment_upload

チェック通過後の処理

現在の MCP Server アドレスが新版 schema を返すことを確認したら、その結果をローカルのチェックマーカーに書き込みます。以降、mcporter に登録されている dingtalk-ai-table のアドレスが変更されていない限り、この確認手順を繰り返さないでください。

ユーザーへの案内文（そのまま使用できます）

当前 mcporter 里注册的 dingtalk-ai-table 还是旧版 MCP schema，暂时不能按新版技能操作。
请打开 https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail ，点击右侧“获取 MCP Server 配置”按钮，复制新的 MCP Server 地址，并替换 mcporter 里已注册的 dingtalk-ai-table 地址。替换后重新检查 schema，确认出现 list_bases / get_base / create_records 等新版 tools 后，再继续操作 AI 表格。

前提条件

mcporter CLI のインストール

npm install -g mcporter
# 或
bun install -g mcporter

確認：

mcporter --version

MCP Server の設定

DingTalk MCP マーケットプレイス https://mcp.dingtalk.com/#/detail?mcpId=9555&detailType=marketMcpDetail から、新版 DingTalk AI テーブル MCP の Streamable HTTP URL を取得します。

方法 1：mcporter に直接設定

mcporter config add dingtalk-ai-table --url "<Streamable_HTTP_URL>"

方法 2：環境変数を使用

export DINGTALK_MCP_URL="<Streamable_HTTP_URL>"

この URL にはアクセストークンが含まれており、パスワードと同等です。漏えいしないようにしてください。

ワークスペースのサンドボックス

スクリプトがローカルファイルを読み込む際、許可されたルートディレクトリとして、まず OPENCLAW_WORKSPACE を使用します：

export OPENCLAW_WORKSPACE="$HOME/.openclaw/workspace"

設定されていない場合は、現在の作業ディレクトリをデフォルトで使用します。

コアツールセット

Base 層

• list_bases
• search_bases
• get_base
• create_base
• update_base
• delete_base
• search_templates

Table 層

• get_tables
• create_table
• update_table
• delete_table

Field 層

• get_fields
• create_fields
• update_field
• delete_field

Record 層

• query_records
• create_records
• update_records
• delete_records

添付ファイル層

• prepare_attachment_upload

推奨ワークフロー

1. まず Base を探す

mcporter call dingtalk-ai-table list_bases limit=10
mcporter call dingtalk-ai-table search_bases query="销售"

2. 次に Table の一覧を取得

mcporter call dingtalk-ai-table get_base baseId="base_xxx"

3. 次にテーブル構造を展開

mcporter call dingtalk-ai-table get_tables \
  --args '{"baseId":"base_xxx","tableIds":["tbl_xxx"]}'

4. フィールドが複雑な場合は完全な設定を読む

mcporter call dingtalk-ai-table get_fields \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","fieldIds":["fld_xxx"]}'

5. 次にレコードを検索／書き込み

mcporter call dingtalk-ai-table query_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","limit":20}'

mcporter call dingtalk-ai-table create_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_name":"张三"}}]}'

6. 添付ファイルフィールドへの書き込み

attachment フィールドでは、次の 3 通りの書き方がサポートされています：

方法 1：先にアップロードしてから fileToken を書き込む（推奨。信頼性があります）

# Step 1：申请上传地址（返回 uploadUrl 和 fileToken）
mcporter call dingtalk-ai-table prepare_attachment_upload \
  --args '{"baseId":"base_xxx","fileName":"report.pdf","size":102400,"mimeType":"application/pdf"}'

# Step 2：把文件 PUT 到 uploadUrl（必须带 Content-Type，值必须与 mimeType 完全一致）
curl -X PUT "<uploadUrl>" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

# Step 3：把 fileToken 写入记录
mcporter call dingtalk-ai-table create_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_attach":[{"fileToken":"ft_xxx"}]}}]}'

方法 2：外部 URL を直接渡す（非同期で保存。best-effort）

mcporter call dingtalk-ai-table create_records \
  --args '{"baseId":"base_xxx","tableId":"tbl_xxx","records":[{"cells":{"fld_attach":[{"url":"https://example.com/file.pdf"}]}}]}'

URL の保存は best-effort の非同期処理です。成功レスポンスは受け付け済みであることだけを示し、すぐに読み取り可能になることを保証するものではありません。確実に書き込むには、fileToken 方式を使用してください。

方法 3：既存の添付ファイルデータをそのまま返す（既存の添付ファイルを保持／追加する場合に使用）

query_records から読み取った attachment セルのデータは、完全なオブジェクト配列です。フィールドの形式は次のとおりです：

[
  {
    "filename": "a.xlsx",
    "size": 92250,
    "type": "xls",
    "resourceId": "<id>",
    "resourceUrl": "<resourceUrl>"
  }
]

type はファイル種別の列挙値で、一般的な値は "xls"、"image" などです。resourceUrl は通常、有効期限付きのダウンロードリンクです。

既存の添付ファイルを保持するには、読み取った値をそのまま戻してください。新しい添付ファイルを追加するには、新しい {"fileToken":"ft_xxx"} を既存のオブジェクトと結合し、1 つの配列として渡してください。

update_records の attachment フィールドも同じ形式です。渡すと、そのフィールド全体が上書きされます。

スクリプト

フィールドの一括追加

python3 scripts/bulk_add_fields.py <baseId> <tableId> fields.json

fields.json の例：

[
  {"fieldName":"任务名","type":"text"},
  {"fieldName":"优先级","type":"singleSelect","config":{"options":[{"name":"高"},{"name":"中"},{"name":"低"}]}}
]

互換性に関する項目：

• name は自動的に fieldName にマッピングされます
• phone は自動的に telephone にマッピングされます

レコードの一括インポート

python3 scripts/import_records.py <baseId> <tableId> data.csv
python3 scripts/import_records.py <baseId> <tableId> data.json 50

説明：

• CSV のヘッダーは、デフォルトで fieldId として解釈されます
• JSON は次の形式をサポートしています：
  • [{"cells": {...}}]
  • [{"fld_xxx": "value"}]

セキュリティルール

• ファイルパスは OPENCLAW_WORKSPACE サンドボックスの制限を受けます
• ワークスペース内の .json／.csv ファイルのみ読み取りを許可します
• Base／Table／Field／Record ID はすべて形式を検証します
• 一括処理の上限は MCP server の実際の制限に従います：
  • create_fields：最大 15
  • get_tables / get_fields：最大 10
  • create_records / update_records / delete_records：最大 100

调试原则

• 先 get_base，再 get_tables，必要时 get_fields
• 不要猜 fieldId
• 复杂参数一律用 --args JSON
• singleSelect / multipleSelect 过滤时必须传 option ID，不是 option name

参考

• API 参考：references/api-reference.md
• 错误排查：references/error-codes.md