IM-MCP エージェント運用・データライフサイクル管理ガイド
本スキルは、Windows および macOS 環境において im-mcp ツールセット（WeChat MCP と DingTalk MCP を含む）を管理するためのエージェント向けガイドです。事前環境確認、オフラインデータベースの初期化と復号、チャットデータ検索、タスク完了後の安全なクリーンアップ を網羅します。
1. 基本方針と実行戦略 (Core Principles & Execution Strategy)
1.1 実行方法の優先順位と戦略
エージェントは導入の案内または支援を行う際、以下の実行戦略に従う必要があります。
- 永続的インストールを優先: Claude Desktop、Cursor など、永続的なツールをサポートするデスクトップクライアント環境では、
uv tool install "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"を推奨します。 - サンドボックス/制限環境でのフォールバック: 現在の AI クライアント環境（Pi サンドボックスなど）がグローバルツールインストールをブロックしている場合（
Blocked ... use uvxのようなメッセージ）、環境のセキュリティポリシーに従い、uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]"を使用してコマンドをアドホックに実行します。 - 国内ネットワークミラー（Gitee ソース）の代替: ユーザーが国内ネットワーク環境におり、GitHub へのアクセスが制限されているか遅い場合、上記の Git アドレスを Gitee ミラーリポジトリに置き換えることができます。
- 永続的インストール:
uv tool install "git+https://gitee.com/ws4m/im-mcp.git" --with "im-mcp[all]" - アドホック実行:
uvx --from "git+https://gitee.com/ws4m/im-mcp.git[all]" <command>
- 永続的インストール:
- プロトコルテストコードの独自作成禁止: インストールと初期化（
wechat-initとdingtalk-init）が完了した後、スクリプトやコードを自作して JSON-RPC/stdio プロトコルを模擬テストすることは固く禁じられています。直接ユーザーに引き渡し、クライアントでの有効化手順を案内する必要があります。 - ホスト環境の認識と導入ガイダンス: エージェントは現在実行中のクライアント環境（Pi、Claude Code/Desktop、Cursor、Cline など）を自律的に判断し、ユーザーに具体的な Skill と MCP の有効化手順（例：
/reloadの入力、クライアントの再起動、サイドバーでの信頼許可）を提示し、日常会話での使用例を 1～2 個直接示す必要があります。
1.2 コマンドマトリックスと権限一覧
# 方法 A：グローバル永続的インストール（推奨）
uv tool install "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"
コマンドマトリックスは以下の通りです。
| コマンド | グローバルインストール後の呼び出し方 | サンドボックス/制限環境での uvx アドホック実行方法 | 適用シナリオ | 権限要件 | 主要な成果物/パス |
|---|---|---|---|---|---|
wechat-init | wechat-init | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" wechat-init | WeChat DBKey を抽出し、オフラインで復号して SQLite データベース化 | Windows：管理者権限（メモリ読み取り）; macOS：--passphrase または設定の永続化に対応 | ~/.wechat_mcp/decrypted/, ~/.wechat_mcp/app.db |
dingtalk-init | dingtalk-init | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" dingtalk-init | DingTalk のキーをオフラインで抽出、DB を復号し WAL トランザクションを統合 | 一般ユーザー権限 | ~/.dingtalk_mcp/decrypted/dingtalk.db |
im-clean | im-clean | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" im-clean | エクスポートされた全ての平文データ、キー、キャッシュをワンクリックで安全に削除 | 一般/管理者権限 | 上記 2 つの復号ライブラリとグローバルデータディレクトリを削除 |
wechat-mcp | wechat-mcp | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" wechat-mcp | WeChat FastMCP 標準サーバーエントリポイント | 一般ユーザー権限 | stdio インターフェース |
dingtalk-mcp | dingtalk-mcp | uvx --from "git+https://github.com/stkoecn/im-mcp.git[all]" dingtalk-mcp | DingTalk FastMCP 標準サーバーエントリポイント | 一般ユーザー権限 | stdio インターフェース |
2. エージェント操作ワークフロー (Lifecycle Workflows)
2.1 タスク開始前：データベースの自動初期化 (Pre-flight Initialization)
ユーザーが「最近の WeChat/DingTalk のやり取りを分析して」「週報を生成して」「〇〇というグループのファイルを探して」と要求し、MCP が「データベースが見つからない」エラーや空の結果を返した場合、エージェントは自律的に初期化を実行する必要があります。
DingTalk データベース初期化
DingTalk は純粋な Python によるローカルオフライン復号であり、ほぼ 100% 自動化されており、管理者権限は不要です。
# エージェントが初期化を実行
dingtalk-init
- 期待される出力: アクティブな UID を検出し、
🎉 钉钉数据初始化同步成功！と出力します。 - 環境事前判定（盲目的スキャン禁止）: データディレクトリや UID が見つからないというメッセージが表示された場合、エージェントはホストマシン上で無目的にプロセスやディスクを再帰的に深くスキャンしてはいけません。すぐに停止し、ユーザーに状況を説明し、DingTalk クライアントが現在のマシンにログインしているかどうかを確認するよう促してください。
WeChat データベース初期化
WeChat はキーを必要とし、WCDB データベースの復号と検証を実行します。
- Windows:
# Windows：管理者として実行 wechat-initwechat-initはエラーを報告します。 - macOS:
# macOS：64 ビットの passphrase を直接渡すことができます wechat-init --passphrase <64桁の16進数passphrase>~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/*/db_storage）を特定し、システムネイティブのCommonCrypto（CCCrypt）を呼び出してキーを派生し、復号を完了します。 - WeChat 実行前チェック（盲目的スキャン禁止）:
- 重要な制約: WeChat プロセスが見つからないか、キーの材料が不足している場合、エージェントは関連のないシステムプロセスを推測してスキャンしたり、システム全体のディレクトリを走査したりしてはいけません！
- 正しい対処法: 現在の環境状態をユーザーに明確に説明し、環境の準備や passphrase の入力を促す必要があります。
- 権限判定: Windows で
Access Deniedエラーが発生した場合、その理由をユーザーに説明し、管理者として実行することを提案します。 - 成功の兆候: ユーザーデータディレクトリ
~/.wechat_mcp/decrypted/に復号されたデータベースが生成され、~/.wechat_mcp/app.dbで FTS5 インデックスがクリーンアップされます。データクリーンアップとインデックス作成のみを再実行する必要がある場合は、wechat-init --etl-onlyを実行します。
2.2 タスク実行中：MCP ツール呼び出し規範
初期化が成功した後、エージェントは生の SQL クエリを直接使用する代わりに、MCP ツールを介して検索することを優先する必要があります。
WeChat 推奨呼び出し順序：
list_wechat_sessions(limit=20): 最近アクティブなセッション/グループを一覧表示し、重要なsession_id（例：xxx@chatroomまたは WeChat ID）を取得します。search_wechat_messages(query="キーワード", limit=50): チャットコンテンツのグローバル全文検索（offsetによるページネーション対応）。get_session_history(session_id="...", limit=100): ターゲットセッションのコンテキストメッセージストリームを取得します。get_message_image(message_id=...): チャット画像のオンデマンド復号。検索結果や履歴メッセージに[图片]が含まれている場合、対応するメッセージidを使用してこのツールを呼び出します。- デフォルトモード：復号された画像のローカル物理絶対パスを返します（
~/.wechat_mcp/images/にキャッシュ）。大きな画像の Base64 による Agent コンテキストの肥大化を防止します。 - マルチモーダル画像分析モード：現在の Agent が画像分析を必要とする場合、
include_base64=Trueを設定して Base64 文字列を抽出し、モデルで解釈できるようにします。
- デフォルトモード：復号された画像のローカル物理絶対パスを返します（
search_shared_files(keyword="...", limit=20): グループまたは個別チャット内で送信されたファイルのパスを特定します。
WeChat 側では他にも、get_messages_by_date / get_messages_by_range（日付または時間範囲でのデータ取得）、search_contacts（連絡先の逆引き）、list_chatroom_members（グループメンバーリスト）、search_media_files（画像/動画のディスクパス）、list_favorites（お気に入り）、list_emoticons（表情）、get_chat_activity_stats（アクティビティ統計）、get_persona_style（コミュニケーションスタイルの抽出）、get_sync_status（インデックスの鮮度）が利用可能です。get_messages_by_date / get_messages_by_range は search_wechat_messages と同様に offset によるページネーションをサポートします。
DingTalk 推奨呼び出し順序：
list_dingtalk_conversations(limit=20): 最近のグループと個別チャットのリストを取得します（最新の実名とグループ名が自動マッピングされます）。search_dingtalk_messages(keyword="キーワード", limit=50): 128 のシャードテーブルにまたがるテキスト検索を集約します。get_dingtalk_messages(cid="...", limit=100): 特定の DingTalk グループまたは個別チャットの会話の詳細を表示します。list_dingtalk_contacts(keyword="名前/ピンイン"): 連絡先 UID と実名を迅速に逆引きします。
2.3 バージョンアップグレードと更新メンテナンス (Project Upgrade & Version Maintenance)
ユーザーが「im-mcp を更新して」「WeChat/DingTalk MCP をアップグレードして」「最新の修正を取得して」と要求した場合、または新機能/バグ修正のリリースを発見した場合、エージェントは現在のインストール方法に基づいてスムーズなアップグレードを実行する必要があります。
1. グローバル永続的インストールモードでのアップグレード（推奨）：
ユーザーが以前 uv tool install でインストールした場合、uv tool update を使用するか、Git リポジトリを再指定してアップグレードします。
# 標準グローバルワンクリック更新
uv tool upgrade im-mcp
# または、強制的に最新のリモートリポジトリバージョンで再インストール（最新の Git HEAD をサポート）
uv tool install --force "git+https://github.com/stkoecn/im-mcp.git" --with "im-mcp[all]"
# 国内ネットワーク環境（Gitee ソース）
uv tool install --force "git+https://gitee.com/ws4m/im-mcp.git" --with "im-mcp[all]"
2. アドホック実行モード (uvx)：
サンドボックスで uvx を使用している場合、uvx はデフォルトで古いバージョンの Wheel をキャッシュする可能性があります。アップグレードまたはバージョンキャッシュの強制リフレッシュを実行します。
# uvx の一時ツールキャッシュをクリアして、最新の Git コードを確実に取得
uv cache clean im-mcp
# または、次回 uvx 呼び出し時に --refresh パラメータを追加して最新バージョンを強制取得
uvx --refresh --from "git+https://github.com/stkoecn/im-mcp.git[all]" <command>
3. アップグレード後のスムーズなリロード：
アップグレードが完了したら、エージェントはユーザーにクライアントの更新またはリロードを促し、最新バージョンの MCP サービス定義とツールセットをロードする必要があります。
- Pi / Pebrel：
/reloadの入力を促します。 - Claude Desktop / Cursor / WorkBuddy：クライアントの再起動または MCP サーバーへの再接続を促します。
- 今回のアップグレードがデータベースクリーンアップロジックの変更を伴う場合、
wechat-init --etl-onlyを実行すると、時間のかかる再抽出や復号を行わずに、2 秒以内に最新の FTS インデックスを安全に再構築できます。
2.4 タスク終了後：データプライバシーとストレージのクリーンアップ (Post-flight Cleanup)
週報や工数集計の完了後、またはユーザーが「環境をクリーンアップして」「エクスポートされたチャット履歴を削除して」と明確に要求した場合、エージェントは積極的に im-clean を呼び出す必要があります。
削除予定ファイルのプレビュー（読み取り専用の安全確認）：
im-clean --dry-run
完全なクリーンアップの実行：
# -y パラメータを使用して、エクスポートされたすべての平文 SQLite、キー、中間キャッシュをサイレントに削除（常駐プロセスロックの自動検出と処理をサポート）
im-clean -y
# 残留ハンドルロックが発生した場合、--force を追加して MCP サービスを強制終了し、完全削除を実行
im-clean -y --force
特定プラットフォームのデータのみをクリーンアップ：
# WeChat データのみをクリーンアップし、DingTalk は保持
im-clean --scope wechat -y
# DingTalk データのみをクリーンアップし、WeChat は保持
im-clean --scope dingtalk -y
2.5 完全アンインストールとクライアントクリーンアップの連携 (Full Uninstallation Guidance)
ユーザーが「この MCP を完全にアンインストールして」「チャットツールと設定を完全に削除して」と明確に要求した場合、エージェントは以下の階層的な標準手順でクリーンアップを支援し、どの手順をユーザーがクライアントインターフェースで手動操作する必要があるかを積極的に伝える必要があります。
- クライアントの終了またはサービスの停止：最初に現在の AI クライアントを終了するか、
im-clean -y --forceに残留 MCP プロセスを自動処理させるようユーザーに促します。 - データの自動クリーンアップ：エージェントは
im-clean -y --forceを実行して~/.wechat_mcpと~/.dingtalk_mcpを完全に削除します（戻りコードが 0 であることを確認します。0 でない場合、成功を誤って報告してはいけません）。 - 依存関係の自動アンインストール：エージェントは
uv tool uninstall im-mcpまたはuv cache cleanを実行して環境とキャッシュをクリーンアップします。 - クライアントの手動クリーンアップについてユーザーに積極的に通知：
- エージェントは現在のホストクライアントに基づいて、設定ファイルの手動クリーンアップ方法をユーザーに通知する必要があります（各環境の一般的なパスについては、本スキルの最後にある【付録：主要な Agent ホスト環境の参考ディレクトリ】を参照してください）。
3. 一般的なトラブルシューティングとエージェント行動規範 (Troubleshooting & Agent Rules)
-
核心的な禁則：エラーが発生したらすぐに停止し、コードの分析や無闇な試行を禁止する：
- インストール、初期化、またはテスト呼び出し中に未知のエラー、環境の競合、または実行例外が発生した場合：
- 絶対禁止：エージェントはソースコードを深く掘り下げたり、パッチを自作してコードを修正したり、推測による再試行を繰り返したり、システム環境を盲目的に調査したりしてはいけません。
- 必須：エラーステップで直ちに停止し、コアエラーの概要をそのまま表示し、ユーザーに明確に次のように尋ねます。
"現在のステップでエラーが発生しました:
[エラーの概要]。問題を調査して自分で解決しますか、それとも操作を中止しますか？" - 制御権をユーザーに委ね、ユーザーが続行または終了を確認した後に行動します。
-
インストールと初期化後は即座にユーザーに引き渡し、プロトコルを模擬するテストコードを独自に作成して繰り返しテストすることを禁止する：
- エージェントはツールのインストール（例：
uv tool install）、設定ファイルの書き込み、およびinit初期化が完了した時点で、デプロイメントプロセス全体が完了しています。 - 絶対禁止：エージェントはPython/Node のテストスクリプトを自作して JSON-RPC 2.0 ハンドシェイク、パイプ通信、プロトコル内部の詳細を模擬してはいけません。これはトークン消費と予測不可能なエラーリスクを増大させるだけでなく、ユーザーのリアルタイムな認識と制御権を奪います。
- 必須：インストールと初期化が完了したら、直接ユーザーに引き渡し、最も簡潔で親しみやすい使用ガイダンスを提供します。
- 現在のクライアントでこの MCP を有効化/信頼する方法を明確にユーザーに伝えます（例：Pi ユーザーに
/reloadの実行、Claude Desktop/Cursor ユーザーにクライアントの再起動を促す）。 - 1～2 個のシンプルで直感的な自然言語の使用例を示し、ユーザーに体験を促します。例：
"インストールと初期化が完了しました！クライアントでこの MCP の信頼/有効化を確認してください（例：
/reloadの実行）。その後、以下のように話しかけるだけで使用を開始できます。 👉 「最近のプロジェクトグループの会話を調べて」 👉 「DingTalk で成鹏が送ったレポートの統計結果を探して」 👉 「先週の〇〇要件に関するコミュニケーション記録をまとめて週報にして」"
- 現在のクライアントでこの MCP を有効化/信頼する方法を明確にユーザーに伝えます（例：Pi ユーザーに
- エージェントはツールのインストール（例：
-
クライアントとアプリケーションの認証信頼（ホスト環境の自律認識と有効化ガイダンス）：
- Agent は現在のセッションの特徴から、ユーザーが使用しているクライアントホストを自律的に認識する必要があります。
- 「お使いのクライアントで有効にしてください」のような曖昧な出力は禁止であり、現在のホストに基づいて対応するクライアント固有の有効化方法を提供する必要があります（例：Pi での
/reload入力の促し、デスクトップアプリケーションでの再起動の促し。具体的な特徴については付録を参照）。
-
WeChat/DingTalk プロセスが見つからない場合の行動禁忌：
- 禁止：ホストマシン上で時間のかかる侵入的な全ディスクスキャンや他のシステムプロセスの推測を実行すること。
- 必須：直ちに停止し、ユーザーにクライアントのログイン状態を確認するよう友好的に伝えること。
-
WeChat 増分メッセージ同期の問題： WeChat クライアントがオンラインの場合、新しいメッセージは元の暗号化ライブラリに書き込まれます。新しく生成されたメッセージを取得する必要がある場合、エージェントはユーザーに「
wechat-initを再実行」してローカルの復号ライブラリを更新するよう促すことができます。 -
DingTalk WAL ロックの問題：
dingtalk-initには自動コピーメカニズムが組み込まれているため、DingTalk が実行中で WAL トランザクション中であっても、SQLite のロック競合は発生しません。 -
プライバシーとセキュリティの原則： 復号された SQLite データベースは機密性の高いローカルプライバシーです。パブリックマシンやマルチテナント環境では、作業終了後に必ず
im-clean -yを実行するように促すか、自動的に実行します。 -
デプロイメントフィードバックレポートとコミュニティ自動開発メカニズム (Deployment Feedback & Auto-Development)：
- デプロイメントと初期化が成功したか、失敗したかに関わらず、エージェントはプロセスの終了時に、構造化された簡潔な**「デプロイメントと運用フィードバックレポート」**を自発的に整理してユーザーに生成し、GitHub に Issue を送信するためにワンクリックでコピーできるようにする必要があります。
- ⚠️ 重要なハイライトの原則（明確に強調し、曖昧さを避ける）：
- レポートのタイトルと最初の行のステータスバーには、非常に目立つ視覚的識別子（例：
【状态：🟢 部署成功 / SUCCESS】または【状态：🔴 部署受阻 / FAILED】）を使用する必要があります。 - 曖昧でニュートラルな表現は絶対に避け、質問者や調査エージェントが成功か失敗かを一目で判断できるようにします。
- レポートのタイトルと最初の行のステータスバーには、非常に目立つ視覚的識別子（例：
- エージェントの自動化運用の約束：ユーザーに次のように促します。「本プロジェクトは GitHub Agent の自動化コラボレーションパイプラインに接続されています。提出された Issue は専任のエージェントが自動的に再現調査、コード修正、そしてマージを行います！」
- レポート生成の標準テンプレート：
- 成功時 (SUCCESS)：
### 📋 im-mcp デプロイメントフィードバックレポート 【状态：🟢 部署成功 / SUCCESS】 > **最終結論**：✅ 全ての依存関係のインストールが成功し、データ抽出とインデックス同期が完了しました。サービスは即座に呼び出し可能です！ - **コアステータス**：🟢 SUCCESS - **環境情報**：OS バージョン（例：Win11 23H2）、クライアントホスト（例：WorkBuddy / Pi / Claude Desktop）、Python および uv バージョン - **インストールモード**：`uv tool install` / `uvx` / ローカルソース - **初期化指標**：所要時間（例：WeChat 12s / DingTalk 3s）、連絡先/会話/メッセージ同期件数 - **使用上のアドバイス**：コールドスタート体験、増分同期ガイダンス、または今後の機能への期待 - **フィードバック窓口**：[GitHub Issues](https://github.com/stkoecn/im-mcp/issues) にて経験を共有いただけます。コミュニティ Agent が自動追跡し、最適化します！ - 失敗時または障害発生時 (FAILED)：
### ⚠️ im-mcp デプロイメントフィードバックレポート 【状态：🔴 部署受阻 / FAILED】 > **最終結論**：❌ プロセスが途中で中断されました。コアサービスは正常に起動できません。以下の障害特定を参照してください。 - **コアステータス**：🔴 FAILED - **障害発生段階**：依存関係のインストール / WeChat キー抽出 / DingTalk 復号 / データベースインデックス構築 / クライアントマウント - **環境の特徴**：OS バージョン、クライアントホスト、WeChat バージョン（例：4.x / 3.x）、DingTalk バージョン（例：7.x V3） - **主要なエラー概要**：コアエラースタックまたはシステムプロンプトの抜粋（例：Access Denied / プロセスが実行されていません / ファイルロック拒否） - **試行済みの対策**：権限昇格の試行、`--force` または `--etl-only` の試行 - **改善提案**：現在のフローでスムーズでない点や、ツールの自動フォールトトレランスが必要な箇所を指摘 - **ワンクリックフィードバック**：このレポートをコピーして [GitHub Issues](https://github.com/stkoecn/im-mcp/issues) に直接送信してください。リポジトリの専任エージェントがログを自動分析し、修正を開始します！
- 成功時 (SUCCESS)：
4. 付録：主要な Agent ホスト環境の参考ディレクトリ（参考情報）
💡 声明：本ディレクトリは、現在の主要な AI クライアント/エージェント環境のデフォルトの動作と設定の特徴をまとめたものであり、参考情報として提供されます。各プラットフォームのバージョンアップデートに伴い変更される可能性があるため、各プラットフォームの公式ドキュメントを参照してください。
| クライアント環境 | 典型的な識別特徴 | 設定/有効化方法の参考 | アンインストールとクリーンアップ方法の参考 |
|---|---|---|---|
| Pi / Pebrel | PI_* 環境変数または ~/.pi/ ディレクトリが存在 | ~/.pi/agent/mcp.json を編集し、セッションで /reload を入力して再読み込み | mcp.json からエントリを削除し、~/.agents/skills/im-mcp を削除し、/reload を入力 |
| Claude Desktop | ローカル AppData に Claude 設定が存在 | %APPDATA%\Claude\claude_desktop_config.json を編集し、クライアントアプリケーションを完全に再起動 | 設定ファイルの mcpServers からエントリを削除し、ソフトウェアを再起動、スキルディレクトリを削除 |
| Cursor | VS Code 派生、Cursor 設定が存在 | Settings ➔ Features ➔ MCP Servers で追加し、インターフェースで即座にマウント | MCP サーバーリストで該当エントリの Delete / Remove をクリック |
| Cline / Roo Code | VS Code 拡張機能パネル | 拡張機能サイドバーの MCP タブで設定を追加し、「Enabled」に切り替えて有効化・承認 | サイドバーの MCP リストでスイッチをオフにするか、ゴミ箱アイコンをクリックして削除 |
| Cherry Studio | デスクトップマルチモデル管理ツール | 设置 ➔ MCP 服务器 で stdio コマンドを追加し、保存すると即時有効 | MCP サーバーリストで選択し「删除」をクリックし、設定を保存 |
| WorkBuddy | ~/.workbuddy/ ディレクトリまたは関連設定が存在 | ~/.workbuddy/mcp.json を編集し、コネクタ管理インターフェースで手動で「信任/启用」をクリック | mcp.json から設定ブロックを削除し、インターフェースでコネクタを削除 |