コンテンツにスキップ

MCP v2 - テストケース設計

このページは I/O 定義 とテストケースの対応を定義する。目標契約の条項に対応するテストケースがない場合、それは実装ギャップとして扱う。

テスト ID は MCPV2-<layer>-<NN> 形式を使う。

Layer Scope Tooling
Unit (U) schema validation、key parsing、scrypt verification、scope checks、backend request mapping、response mapping Vitest、ネットワークなし
Handler (C) PostgreSQL auth と backend internal API を mock した MCP tool handlers vi.mock を使った Vitest
E2E (E) CloudFront/API Gateway、MCP v2、PostgreSQL auth、backend internal API、SQS、guinness-ai-v2、S3 artifact、backend webhook、DocumentDB design/code reads を通す dev smoke path 手動または CI smoke 
flowchart LR
    U["Unit tests<br/>schemas/auth/mappers"] --> C["Handler tests<br/>MCP + mocked backend"]
    C --> E["E2E smoke<br/>MCP -> backend -> AI"]
    E --> Result["project-scoped<br/>design/code/des2code flow"]

カバレッジマトリックス

契約領域 正常系 異常系 冪等性
CloudFront token auth MCPV2-U-01 MCPV2-U-02 -
PostgreSQL API-key auth MCPV2-U-03 MCPV2-U-04, MCPV2-U-05, MCPV2-U-06 -
project/user scope MCPV2-U-07 MCPV2-U-08 -
tool input schemas MCPV2-U-09 MCPV2-U-10 -
backend internal API delegation MCPV2-U-11, MCPV2-C-01, MCPV2-C-03, MCPV2-C-05 MCPV2-C-02, MCPV2-C-04, MCPV2-C-06, MCPV2-C-08 MCPV2-C-09
backend producer payloads MCPV2-U-12 MCPV2-U-13 -
backend downstream SQS / AI-v2 MCPV2-E-02 MCPV2-E-04 MCPV2-E-03
per-request MCP server MCPV2-C-09 - MCPV2-C-09
last_used_at update MCPV2-C-10 MCPV2-C-11 -
deployed integration MCPV2-E-01, MCPV2-E-02 MCPV2-E-04 MCPV2-E-03

ユニットテスト

MCPV2-U-01 - 有効な CloudFront token を通過させる

  • Given X-MCP-Token が CLOUDFRONT_SECRET_HEADER と一致する。
  • When edge-token validation を実行する。
  • Then validation が通過する。

MCPV2-U-02 - 不正な CloudFront token を拒否する

  • Given ENVIRONMENT=local 以外で X-MCP-Token が missing または mismatch。
  • When edge-token validation を実行する。
  • Then request は HTTP 401 で拒否される。

MCPV2-U-03 - 有効な PostgreSQL API key を通過させる

  • Given PostgreSQL mcp_api_keys が既知の key_hash と salt を持つ active row を返す。
  • When guinness_<prefix>_<secret> を parse して検証する。
  • Then auth context に id, user_id, project_id, permission, key_prefix が含まれる。

MCPV2-U-04 - 未知の key prefix を失敗させる

  • Given parsed prefix に一致する PostgreSQL row がない。
  • Then authentication は失敗し、hash verification は実行されない。

MCPV2-U-05 - revoke/expire/delete 済み key を失敗させる

  • revoked_at, past expires_at, deleted_at を parameterize する。
  • Then tool execution より前に authentication が失敗する。

MCPV2-U-06 - MySQL model import が存在しない

  • Given 移行後の実装。
  • Then apps/mcp-v2 は @guinness-backend/models/mysql または mysql2 を import しない。

MCPV2-U-07 - 許可された project scope を通過させる

  • Given auth context が project_id = 42 に scope されている。
  • When project_id = 42 で tool を呼び出す。
  • Then scope validation が通過する。

MCPV2-U-08 - cross-project scope を backend I/O 前に拒否する

  • Given auth context が project_id = 42 に scope されている。
  • When project_id = 43 で tool を呼び出す。
  • Then response は isError: true になる。
  • And backend internal API call は実行されない。

MCPV2-U-09 - tool schema が有効な input を受け付ける

  • trigger-des2code, get-des2code, list-designs, list-code, get-design-detail, get-code-detail を cover する。
  • Then limit = 20 と offset = 0 の default が適用される。

MCPV2-U-10 - tool schema が不正な input を拒否する

  • empty IDs、255 文字超 ID、invalid ID characters、project_id <= 0、organization_id <= 0、limit > 100、offset < 0 を parameterize する。
  • Then field-level validation errors が返る。

MCPV2-U-11 - backend internal request mapping が正しい

  • Given 有効な tool arguments と authenticated project scope。
  • Then MCP v2 は expected backend internal route、method、query/body、X-API-Key、X-MCP-Project-ID を組み立てる。
  • And MCP v2 は SQS、DocumentDB、AI-v2 client を直接 import / call しない。

MCPV2-U-12 - backend producer payload が MCP v2 の ID を共有する

  • Given backend design/code/des2code API の request data。
  • When design-import, code-import, des2code 用の producer payload を組み立てる。
  • Then design_id, code_id, project_id, organization_id が access control に使う PostgreSQL row と一致する。

MCPV2-U-13 - design producer が figma_url を含めない

  • Given backend が Figma URL を parse 済みの design-create request。
  • Then design-import payload は organization_id, project_id, file_id, node_id, design_id を含む。
  • And payload は figma_url を含まない。

Handler テスト

MCPV2-C-01 - trigger tool が backend に委譲する

  • Given 有効な auth と有効な trigger input。
  • When trigger-des2code を実行する。
  • Then MCP は BACKEND_INTERNAL_URL の POST /internal/des2code を呼び出す。
  • And MCP response は structuredContent.success = true を持つ。

MCPV2-C-02 - backend trigger failure を MCP error として返す

  • Given backend internal POST /internal/des2code が 5xx または validation error を返す。
  • Then MCP response は isError: true を持つ。
  • And error text は mapped backend message を含む。

MCPV2-C-03 - get des2code が backend success を map する

  • Given backend internal API が des2code summary を返す。
  • Then MCP response は matched_code_count, matched_codes, artifact, processed_at を含む。

MCPV2-C-04 - get des2code が not found を map する

  • Given backend internal API が not-found response を返す。
  • Then MCP response は isError: true を持ち、成功 result payload は含まれない。

MCPV2-C-05 - list designs/code が pagination を map する

  • Given backend internal API が total_count, returned_count, limit, offset, source items を返す。
  • Then MCP structured content は pagination fields を保持する。

MCPV2-C-06 - limit が 100 を超える list request を backend HTTP 前に失敗させる

  • Given limit = 101。
  • Then validation が失敗し、backend internal API は呼び出されない。

MCPV2-C-07 - detail tools が embedding なし source detail を返す

  • Given backend internal API が design または code source detail を返す。
  • Then MCP response は visual.vector_embedding, semantics.vector_embedding, structural.vector_embedding を含まない。

MCPV2-C-08 - backend internal API 到達不能を service error に map する

  • Given backend internal API が timeout する、または 5xx を返す。
  • Then MCP response は service-unavailable text 付きの isError: true になる。

MCPV2-C-09 - request ごとに server を分離する

  • Given 2 つの concurrent JSON-RPC requests。
  • When 両方の request を実行する。
  • Then それぞれが新しい MCP server と transport を作成する。
  • And response ID/content は request 間で漏れない。

MCPV2-C-10 - last_used_at update が非同期に成功する

  • Given 有効な authentication。
  • Then verification 成功後に last_used_at update が schedule される。

MCPV2-C-11 - last_used_at update failure は非ブロッキング

  • Given auth は成功するが update が throw する。
  • Then tool execution は継続し、failure は log される。

E2E スモークテスト

MCPV2-E-01 - デプロイ済み tool list

  • Given dev CloudFront/API Gateway endpoint と有効な PostgreSQL-backed MCP API key。
  • When tools/list を呼び出す。
  • Then 6 つすべての MCP v2 tools が返る。

MCPV2-E-02 - trigger から backend、SQS、des2code、webhook まで到達する

  • Given 同じ organization/project に属する imported design と code sources。
  • When trigger-des2code を呼び出す。
  • Then MCP v2 は backend internal POST /internal/des2code を呼び出す。
  • And backend は SQS message を guinness-ai-v2/apps/des2code に送る。
  • And guinness-ai-v2/apps/des2code は timestamp 付き S3 result artifact を書き込む。
  • And guinness-ai-v2/apps/des2code は artifact metadata 付きで POST /v1/webhooks/ai-status を送る。
  • And backend は最新の des2code result/status と artifact reference を PostgreSQL に保存する。

MCPV2-E-03 - 再 trigger が latest result を置き換える

  • Given design に PostgreSQL-backed des2code result と artifact reference がすでに存在する。
  • When 同じ design を再度 trigger する。
  • Then その design_id の latest result と artifact reference が置き換わる。
  • And MCP read tool は backend internal API 経由で latest result を返す。

MCPV2-E-04 - cross-project access を拒否する

  • Given project A に scope された MCP API key。
  • When project B に対して tool を呼び出す。
  • Then backend internal API、SQS、AI-v2 read I/O より前に call が失敗する。