MCP API

Katatan MCP API は Model Context Protocol (MCP) を通じて AI エージェントがテスト管理機能を操作するインターフェースです。

エンドポイント: https://mcp.katatan.com/mcp（HTTP transport）

すべての通信は MCP プロトコルの tools/call リクエスト経由で行われます。HTTP ヘッダーはトランスポート層の設定として渡し、ツール引数にトークンを含める必要はありません。

認証

HTTP transport（推奨）

Authorization: Bearer ヘッダーに MCP アクセストークンを指定します。

Copy{
  "mcpServers": {
    "katatan": {
      "type": "http",
      "url": "https://api.katatan.com/mcp",
      "headers": {
        "Authorization": "Bearer kat_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

stdio transport（ローカル開発用）

KATATAN_TOKEN 環境変数にアクセストークンを指定します。

Copy{
  "mcpServers": {
    "katatan": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/src/scripts/local-mcp.js"],
      "env": {
        "DATABASE_URL": "postgresql://...",
        "KATATAN_TOKEN": "kat_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

レート制限

レート制限超過時はエラーコード RATE_LIMIT_EXCEEDED が返ります。

共通事項

author パラメータ（全ツール共通・オプション）

すべてのツールは author パラメータを受け付けます。Audit ログおよびデータの createdBy/updatedBy に記録される操作者名です。未指定の場合はアクセストークンのUUIDが使用されます。

Copyauthor: string（最大100文字、省略可）

複合ID フォーマット

エラー仕様

ツール呼び出しがエラーになった場合、MCP レスポンスの isError: true フラグが立ち、content[0].text に以下の JSON が含まれます。

Copy{
  "error": {
    "code": "ERROR_CODE",
    "message": "エラーメッセージ",
    "details": {}
  }
}

共通レスポンス型

TestSpec オブジェクト

Copy{
  id: string                    // UUID
  projectId: string             // プロジェクトID
  name: string                  // 仕様書名
  description: string | null
  webhookId: string | null
  webhook: {
    url: string
    headers: Record<string, string> | null
  } | null
  requiredTesterEnv: string | null
  requiredProductEnv: string | null
  testCaseCount?: number        // 一覧取得時のみ付与
  labels?: Label[]              // 一覧取得時のみ付与
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
}

TestCase オブジェクト

Copy{
  id: string                    // UUID（内部ID）
  specId: string                // 所属仕様書UUID
  index: number                 // 表示順（並び替え・削除で変動する）
  caseNumber: number            // 安定ID（UI表示: "case-{caseNumber}"）
  labels: Label[]
  testSubject: string
  preconditions: string | null
  steps: string[]
  expectedResult: string
  notes: string | null
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
}

TestReport オブジェクト

Copy{
  id: string                    // UUID
  specId: string                // 元となる仕様書UUID
  name: string
  notes: string | null
  status: "NOT_STARTED" | "IN_PROGRESS" | "COMPLETED" | "ABORTED"
  webhookEnabled: boolean
  startedAt: string             // ISO 8601
  completedAt: string | null    // 初回完了日時
  lastCompletedAt: string | null
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
  reportResults?: TestReportResult[]  // 詳細取得（get_test_report）時のみ付与
}

TestReportResult オブジェクト

Copy{
  id: string                    // UUID
  reportId: string
  testCaseId: string
  testResult: "OK" | "NG" | "SKIP" | null
  tester: string | null
  notes: string | null
  executionResultLink: string | null
  resultRecordedAt: string | null   // 結果入力日時
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
  // スナップショット列（レポート作成時点のテストケース内容）
  snapshotCaseNumber: number | null
  snapshotTestSubject: string | null
  snapshotPreconditions: string | null
  snapshotSteps: string[] | null
  snapshotExpectedResult: string | null
  snapshotLabels: { id: string; name: string; color: string }[] | null
  snapshotNotes: string | null
}

Label オブジェクト

Copy{
  id: string
  workspaceId: string
  name: string
  color: "gray" | "red" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink"
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
}

DictionaryEntry オブジェクト

Copy{
  id: string
  projectId: string
  key: string
  value: string
  description: string | null
  createdBy: string | null
  updatedBy: string | null
  createdAt: string             // ISO 8601
  updatedAt: string             // ISO 8601
}

MCPツール一覧