Claudia Partner™DocsAPI・MCP 共通ドキュメント0.7.0-experimental
ドキュメント/AIエージェント/MCPの対応範囲とトラブル対応

AIエージェント

MCPの対応範囲とトラブル対応

対応範囲

文書対象のMCPは、クライアント1.0.1の取込用8ツールです 環境による。全APIサービスへの対応は 準備中 です。

DBへの直接の接続、任意のSQL、署名鍵は、MCPの対象に含めません。現在の8ツールの動作を、全APIの提供として扱わないでください。導入の手順は、MCPの導入。

8ツールの契約

imports_catalog

登録済み取込データ・元キー・関連表を一覧する。

json{
  "name": "imports_catalog",
  "description": "登録済み取込データ・元キー・関連表を一覧する。",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": [],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  }
}
imports_prepare

指定CSVを検査し差分計画を作る。まだ業務表へ反映しない。ファイルは転送フォルダ内に限定する。大きなファイルは分割して送信し、確認は裏で進む（stateがpreparingのとき）。stateがpreparedになるまでimports_statusで確認してから、imports_runを行う。

json{
  "name": "imports_prepare",
  "description": "指定CSVを検査し差分計画を作る。まだ業務表へ反映しない。ファイルは転送フォルダ内に限定する。大きなファイルは分割して送信し、確認は裏で進む（stateがpreparingのとき）。stateがpreparedになるまでimports_statusで確認してから、imports_runを行う。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dataset": {
        "type": "string"
      },
      "source_file": {
        "type": "string"
      }
    },
    "required": [
      "dataset",
      "source_file"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  }
}
imports_run

確認済み計画を最大4区間反映/再開する。同じplan_idとsource_sha256を保持し、verifiedまで再呼出する。

json{
  "name": "imports_run",
  "description": "確認済み計画を最大4区間反映/再開する。同じplan_idとsource_sha256を保持し、verifiedまで再呼出する。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "plan_id": {
        "type": "string"
      },
      "source_sha256": {
        "type": "string"
      }
    },
    "required": [
      "plan_id",
      "source_sha256"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "idempotentHint": true,
    "openWorldHint": false
  }
}
imports_status

計画の状態、確認中（preparing）の進み具合、完了区間数を確認する。prepare_failedのときはerror.codeが失敗理由。

json{
  "name": "imports_status",
  "description": "計画の状態、確認中（preparing）の進み具合、完了区間数を確認する。prepare_failedのときはerror.codeが失敗理由。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "plan_id": {
        "type": "string"
      }
    },
    "required": [
      "plan_id"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  }
}
imports_history

本人の取込履歴と再開可能な計画を一覧する。

json{
  "name": "imports_history",
  "description": "本人の取込履歴と再開可能な計画を一覧する。",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": [],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  }
}
imports_cancel

未実行の計画のみ取り消す。実行開始後は受領票を保持し同じ計画から再開する。

json{
  "name": "imports_cancel",
  "description": "未実行の計画のみ取り消す。実行開始後は受領票を保持し同じ計画から再開する。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "plan_id": {
        "type": "string"
      }
    },
    "required": [
      "plan_id"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  }
}
imports_verify

取込結果を基盤から再取得し全値を照合する。

json{
  "name": "imports_verify",
  "description": "取込結果を基盤から再取得し全値を照合する。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "plan_id": {
        "type": "string"
      }
    },
    "required": [
      "plan_id"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  }
}
imports_export

対象の登録形式に従った更新用CSVを転送フォルダへ保存する。既存ファイルを上書きしない。

json{
  "name": "imports_export",
  "description": "対象の登録形式に従った更新用CSVを転送フォルダへ保存する。既存ファイルを上書きしない。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dataset": {
        "type": "string"
      },
      "output_file": {
        "type": "string"
      }
    },
    "required": [
      "dataset",
      "output_file"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": false,
    "openWorldHint": false
  }
}

ツールの出力と状態

ツールは、APIのJSONの結果を、MCPのcontent[0].textに、JSONの文字列として返します。

ツール出力と扱い
imports_catalog取込の形式の配列。idを、datasetに使います。headers、key_columns、format、field_typesで、形式を確認します
imports_prepare計画。id、dataset、source_rows、created・updated・unchangedの件数、absent_retained、source_sha256、encoding、stateなど。imports_runなどのplan_idには、このidを渡します。差分を示して、反映してよいか確認します
imports_run同じplan_idとsource_sha256で、最大4区間ずつ進めます。最後の区間の後は、自動で照合します
imports_status計画の状態と、完了した区間の数を、取得し直します
imports_verify全区間が完了した計画を、基盤の値と照合します。成功はstate=verifiedです。未完了はPLAN_INCOMPLETE、不一致はVERIFY_MISMATCHです
imports_history利用者の計画の配列（最新100件まで）
imports_cancelpreparedの計画だけを、cancelledにします。実行した後は、取り消せず、RESUME_REQUIREDになります
imports_export新しいファイルに保存して、saved_fileとbytesを返します。既存のファイルは、上書きしません

準備中はpreparing、準備完了はprepared、準備失敗はprepare_failedです。preparedを確認してから実行します。実行後は、通常、running、verifiedの順に進みます。実行の失敗はfailed、実行前の取り消しはcancelledです。通信が切れただけで、失敗や未反映と決めず、imports_statusで確認します。同じ計画と、同じ受領のキーを保持して、新しい計画を作って、二重に反映しないでください。

接続できないとき

クライアントが「Connection interrupted」とだけ表示する場合、原因は、HTTPのステータス、content-type、本文で見分けます。次の原因が確認されています。どの場合も、TLS検証の無効化、認証ヘッダーの手動での付与、クライアントの識別の偽装は行いません。

接続の前にTLS検証が失敗する（例: certificate has expired）

HTTP 403、content-typeがtext/plain、本文がerror code: 1010

HTTP 401、JSONのerrorがauthentication_required

JSONのerrorが返るときは、アプリまで届いています。text/plainの本文だけが返るときは、入口で拒否されています。この違いが、連絡するときの、最初の手がかりになります。

キーの保存や読み取りが失敗する

実行しているユーザーと、Secret Serviceのロックを確認します。OSごとの保存条件とキーの保存手順を確認します。利用者用のアクセストークンを、取込のキーの代わりに保存しないでください。