Claude CodeのTDengine IDMPプラグインで安全に確認し運用する

Claude CodeからTDengine IDMPを扱うには、TAOS Dataが公開している idmp-plugin を入れます。中身はスキル(SKILL.md)の束で、IDMPのサーバーを実際に叩くのは別途インストールする idmp-cli です。

このプラグインの特徴は、書き込みや削除の前に「対象・操作・理由・影響範囲」を提示し、利用者の yes を待つよう同梱スキルが指示している点です。この記事では、導入の手順、スキルの分担、確認ルールの中身、読んでから書く運用の流れを順に説明します。

idmp-pluginは何を入れるものか

マーケットプレイスの説明文は「発見、スキーマ確認、安全な運用ワークフローのためのスキルを同梱したTDengine IDMPプラグイン」です。提供元はTaosDataで、導入先はClaude Codeと表示されています。

構成は単純です。リポジトリのレイアウトでは、プラグインの定義ファイルと skills/ ディレクトリだけが並びます。MCPサーバーやフックの定義はこの構成に含まれません。

プラグインを入れてもidmp-cliのインストールとIDMPへのログインは行われません。READMEが明記している点で、先にここを済ませないとスキルが指示するコマンドが動きません。

導入手順

前提は、Node.js 16以上、npmまたはnpx、IDMP環境へのネットワーク到達性、そしてユーザー名とパスワードか事前発行のAPIキーのどちらかです。

コマンドはREADMEの手順どおりです。

npm install -g @tdengine/idmp-cli
idmp-cli --version
 
printf '%s\n' "$IDMP_PASSWORD" | idmp-cli config init \
  --profile default --server http://your-idmp:6042 \
  --username admin@example.com --password-stdin
idmp-cli config show
idmp-cli auth check

事前発行のAPIキーを使う場合は、パスワードの代わりに --api-key-stdin を指定します。どちらの方法でも、秘密情報は引数に書かず標準入力で渡す形です。

続いてClaude Code側です。

claude plugin marketplace add taosdata/agent-skills
claude plugin install idmp-plugin@taosdata

READMEによれば、idmp-plugin は対応するスキルをすでに同梱しているため、Claude Codeではスキルを別にコピーする必要はありません。マーケットプレイスやインストール先の考え方はClaude Codeプラグイン完全ガイドにまとめています。

環境が複数あるときはプロファイルを分ける

検証用と本番用など、接続先が複数ある場合は別名のプロファイルとして保存し、切り替えます。

idmp-cli config init --profile staging \
  --server http://staging-idmp:6042 --username admin@example.com
idmp-cli profile use staging
idmp-cli config show

セッションが切れたときは、保存済みプロファイルに対して idmp-cli auth login で再認証するだけで足ります。Claude Codeに作業を頼む前に config show で今どのプロファイルが有効かを見る習慣をつけると、検証用のつもりで本番に書く事故を避けやすくなります。

23のスキルは何を分担しているか

プラグインのリポジトリには、skills/ 配下に23個のスキルがあります。名前は idmp- で始まり、大きく4つの役割に分かれます。

ほかに、スキーマ上のパスや必須入力を調べる idmp-openapi-explorer があります。構造化されたコマンドで足りないときだけ、生のAPI呼び出しへ降りるための入口です。

ドメイン別のスキルは、冒頭で必ず idmp-shared を先に読むよう指示しています。確認ルールが各スキルに散らばらず、1か所で更新される作りです。スキルの書き方そのものはClaude Code Skillsの解説が参考になります。

書き込みの前に止まる確認ルール

idmp-shared の先頭にあるのが、必須とされる「破壊的操作の確認」です。DELETE、読み取り専用でない POST / PUT / PATCH、--ack-risk を付けるコマンド、ローカルの config remove / profile remove / auth logout --clear の前に、次の4項目を示して明示的な yes を待つよう定めています。

安全ルール集には、そのまま出力に使える雛形も載っています。

WARNING: destructive operation pending. Please confirm:
- Target: <type> id=<id>, name="<name>" (<other context>)
- Action: <METHOD> <path> (<schemaPath>) payload=<summary>
- Reason: <why>
- Impact: <downstream effects / rollbackability / dependent objects>
Continue? (yes/no)

get / list / search / path / tree のような読み取りには、この確認は要りません。--dry-run だけの実行も対象外です。ただし --dry-run が確かめるのはローカルでのJSONの構文とパスパラメーターだけで、DTOの完全性、権限、接続、サーバー側の意味までは検証しません。プレビューが通ったことを、書き込みが成功する根拠にはできません。

複数のオブジェクトに同じ操作をする場合は、N件すべての対象と理由を列挙し、1件ずつ実行するのか、失敗で止めるのか、失敗しても続けるのかを説明させます。途中で失敗したら、その場で止めてもう一度確認するルールです。

確認を省略してよいのはいつか

ルールが省略を認めるのは2つの場合だけです。利用者が現在のセッションでまとめて許可した場合か、削除対象の具体的な一覧を示したうえで実行を指示した場合です。後者でも、対象一覧を改めて書き出すことが勧められています。

削除したいものが決まっているなら、対象を一覧にして渡す形が、このルールに沿った頼み方です。

読んでから書く標準フロー

書き込みを伴う作業の流れは、idmp-shared が5段階で定めています。

1. search / list / path で対象を特定する
2. get や attributes などで現在の状態を読む
3. new-name、sub-templates、trigger-types など依存関係を解決する
4. スキーマを調べ、--dry-run でプレビューし、読み取り専用でない生成コマンドには --ack-risk を付ける
5. get か list で書き込みが残ったことを確かめる

IDの推測は禁止です。elementId、elementTemplateId、rootElementId は検索かパス取得で出してから使います。

idmp-cli schema element.elements.search
idmp-cli element elements search \
  --params '{"keyword":"beijing","current":1,"limitSize":20}'
idmp-cli element elements path --params '{"elementId":123}'
idmp-cli analysis analyses list \
  --params '{"elementId":123,"current":1,"size":20}'

要素モードとテンプレートモード

最初に決めるのは作業モードです。実在する要素やライブのデータ・ダッシュボード・イベントが対象なら要素モード(element / attribute / analysis / panel / dashboard / event)、再利用可能なテンプレートが対象ならテンプレートモード(template / attr-template / analysis-template / panel-template)です。elementId と elementTemplateId は混ぜないよう明記されています。

rootElementIdはリーフではなく業務ルート

要素モードの書き込みで落とし穴になるのが rootElementId です。これは「現在のリーフ要素」ではなく、要素パス上の業務ルート(最上位の祖先)から取ります。実際に書き込む先のリーフと、業務ルートは別の入力として扱います。

パスが曖昧なときは、element elements path、element fullpath get、element by-path list の3つが同じルートからリーフまでの経路に戻ってくるかを突き合わせます。戻ってこなければ、リーフ要素を rootElementId として流用せず、パスの解決からやり直します。

完了の証明は再読み出しで行う

このプラグインのスキルは、成功メッセージを完了とみなしません。

• 作成: オブジェクトを読み直し、最終的なID、所属範囲、確保した名前、状態を確かめる
• 更新: 同じオブジェクトを読み直し、変更が保持されたかを見る
• 削除: 範囲を絞った list か、構造化されたnot foundの get で不在を示す

書き込みが成功と返ったのに再読み出しで変更が見えない場合は、未完了として扱い、新しい変更を送る前に読み直します。設定の書き込みが通っても実行時の挙動は保証されない点も明記されています。分析が Ready のまま残ったり、アラートで履歴の埋め直しが必要になったりするため、resume で Running まで進める手順が組み込まれています。

失敗したときの切り分け

エラー回復の表は、症状ごとに次の行動と再試行の方針を定めています。抜粋すると次のとおりです。

停止条件も決まっています。認証や接続が不調、所有者や業務ルートが不明、必要な認証情報がない、同じ構造化500が再現した、権限境界に当たった、のいずれかなら、書き込みを止めて失敗を明確に返します。リトライは「最初のエラーを保存する、所有オブジェクトを読み直す、必要ならスキーマも読み直す、変えるのは1点だけ、新しい読み出しが理由を説明するときだけ1回再試行する」という順です。

アラートの原因を調べる手順

workflow-alert-debug は、読み取り中心で進めるワークフローです。症状を「イベントが開かなかった」と「イベントは開いたが通知が届かなかった」に分け、次の順に読みます。

1. event count list と event events list で、イベントが無いのか、通知が無いのかを切り分ける
2. event events get と event events items で、1件のイベントと中身を固定する
3. 証拠を記録してから、必要な場合だけ confirm か resend(どちらも --ack-risk が必要)
4. notification config list で通知設定を確認する
5. notification page list で配信履歴を見る

確認と再送には副作用があるため、イベントの証拠を先に残すことがスキルに明記されています。再送の直後に配信履歴が空でも、履歴の反映遅れや通知間隔の制限があり得ます。失敗と断定せず、読み直して詳細レコードを見る進め方です。

Claude Codeへの頼み方の例

次の依頼文は、スキルの設計に沿って組み立てた例です。実際の応答は環境と版によって変わります。

READMEのCodex向けの例では、接続確認とルート要素の一覧を読み取り専用で頼む形が示されています。Claude Codeでも同じ発想で、最初は読み取りだけを頼むと安全です。

idmp-plugin の idmp-shared と idmp-element を使って、
IDMP への接続を確認し、ルート要素を一覧してください。
書き込みはしないでください。

書き込みを頼むときは、対象と範囲を先に固定します。

要素「Beijing/Chaoyang/Pump-01」の属性一覧を読み、
新しい分析を作る前に trigger-types と new-name を確認してください。
作成は私が yes と答えるまで実行しないでください。

後者は、new-name で名前を確保し、trigger-types で使える起動条件を調べる、というスキル側の事前確認を頼みの中に明示した形です。「yesと答えるまで実行しない」という指示は、スキル側の確認ルールと同じ向きです。

運用で気をつける点

• 本番とステージングでプロファイルを分け、作業前に config show で有効なプロファイルを確かめる
• パスワードやAPIキーは標準入力か環境変数で渡し、スクリプトやログに残さない
• --dry-run は構文確認止まりで、権限や接続は検証しない
• 共有環境では、通知ルールのように作成と対になる削除の流れがない対象があり、既存のものを更新する前提で進める
• 分析を作ったあとに状態が Running でなければ、読み直したうえで resume を検討する

同じ型の導入記事に、CockroachDBプラグインがあります。データベースの種類が違っても、「読み取りを既定にして、書き込みを明示的に許す」設計は共通しています。プラグインの設定項目が未入力のままになっていないかは、claude plugin configureで確認できます。

まとめ

idmp-plugin は、IDMPを操作する権限そのものではなく、操作の作法をClaude Codeに持たせるプラグインです。実際の操作は idmp-cli とログイン済みのプロファイルが担うので、権限はその利用者のものになります。

まず読み取りだけで接続とルート要素を確かめ、書き込みは4項目の確認と yes を挟み、最後に再読み出しで確かめる。この順番を守る限り、スキルは確認を省かない側に倒れる作りです。環境が複数あるなら、プロファイルの切り替えを最初の習慣にしてください。