MCP v2 概要

guinness-backend/apps/mcp-v2 は V2 design-to-code workflow の MCP server です。coding assistant に project scope の design/code/Des2Code tool 6 件を公開します。

MCP v2 は transport、CloudFront token validation、PostgreSQL-backed MCP API-key authentication、project/write permission check、request-scoped tool registration を 所有します。domain operation はすべて guinness-backend/apps/app internal API に delegate し、SQS、DocumentDB、AI-v2、S3 を直接呼びません。

目標アーキテクチャ

flowchart TD
    Client["MCP client"] --> CF["CloudFront<br/>X-MCP-Token"]
    CF --> MCP["apps/mcp-v2<br/>stateless HTTP /mcp"]
    MCP --> Auth["PostgreSQL mcp_api_keys"]
    MCP -->|"X-API-Key + X-MCP-Project-ID"| Backend["apps/app internal API"]
    Backend --> PG[("PostgreSQL<br/>design/code/project scope")]
    Backend -->|"trigger"| Q["SQS des2code"]
    Q --> Worker["guinness-ai-v2 apps/des2code"]
    Worker --> DocDB[("DocumentDB<br/>design/code/variation/graph/index")]
    Worker --> S3[("S3 request artifact")]
    Worker -->|"AI-status webhook"| Backend
    Backend -->|"source/index read"| AIAPI["guinness-ai-v2 internal API"]
    AIAPI --> DocDB
    Backend -->|"latest result read"| S3

Area	Owner	Rule
MCP transport/edge auth	apps/mcp-v2	request ごとに fresh McpServer/transport。local 以外は CloudFront token 必須
MCP API-key auth	apps/mcp-v2 + PostgreSQL	active mcp_api_keys を authenticate、valid project scope 必須、trigger は write permission 必須
Domain authorization/orchestration	apps/app	project/org/design scope、design readiness、current AI-v2 index readiness、SQS dispatch を再検証
Source detail/list	backend 経由 AI-v2 DocumentDB	backend が AI-v2 service-token route を proxy し vector を除外
Des2Code execution	AI-v2 worker	scoped canonical retrieval/matching、S3 artifact、webhook
Des2Code result	Backend + S3	design を authorize して newest contract-valid artifact を返す。PostgreSQL result row なし

---

MCP ツール

Tool	Purpose	MCP v2 downstream
trigger-des2code	imported design の matching を queue	POST /internal/des2code
get-des2code	design の newest success/failure artifact	GET /internal/des2code/{design_id}
list-designs	imported design source list	GET /internal/designs
list-code	imported code source list	GET /internal/code
get-design-detail	vector を除く design source detail	GET /internal/designs/{design_id}
get-code-detail	vector を除く code source detail	GET /internal/code/{code_id}

trigger-des2code は WRITE permission の MCP key が必要です。server が受け付ける MCP API key はすべて project-scoped である必要があります。code-index rebuild/status と codebase-rule CRUD は現在の MCP v2 tool ではありません。

---

MCP 認証契約

MCP v2 は PostgreSQL mcp_api_keys で API key を authenticate します。

flowchart LR
    Header["MCP-API-Key<br/>or Authorization: Bearer"] --> Parse["guinness_prefix_secret parse"]
    Parse --> PG["key_prefix で PostgreSQL lookup"]
    PG --> Verify["scrypt verify"]
    Verify --> State["deleted/revoked/expired check"]
    State --> Scope["positive project_id required"]
    Scope --> LastUsed["async last_used_at update"]

Requirement	Behavior
Edge token	ENVIRONMENT=local 以外で X-MCP-Token と CLOUDFRONT_SECRET_HEADER を constant-time compare
API-key header	MCP-API-Key 優先、Authorization: Bearer <api-key> も受付
Database	PostgreSQL/Drizzle、mcp_api_keys
Lookup	key_prefix + deleted_at IS NULL
Validity	revoked/expired/deleted/malformed/unknown key を reject
Scope	positive project ID のない key を reject。全 tool を同 project に制約
Permission	trigger-des2code は WRITE。read tool は authenticated project scope
Audit	last_used_at を async update。failure は log し non-blocking

Schema: PostgreSQL mcp_api_keys

---

Backend Internal API 契約

MCP v2 は authenticated project ID を backend に送り、backend は PostgreSQL、 SQS、AI-v2、S3 access 前に scope を再検証します。

sequenceDiagram
    participant Client as MCP client
    participant MCP as apps/mcp-v2
    participant Backend as apps/app internal API
    participant AI as guinness-ai-v2 internal API/worker
    participant S3 as S3
    Client->>MCP: tools/call
    MCP->>MCP: edge + API-key auth, schema, permission/scope
    MCP->>Backend: X-API-Key + X-MCP-Project-ID
    alt trigger-des2code
        Backend->>Backend: design authorize + completed requirement
        Backend->>AI: current code_index read; ready requirement
        Backend->>AI: flat design/scope/request SQS
        AI->>S3: request artifact write
        AI->>Backend: AI-status webhook
    else get-des2code
        Backend->>S3: authorized design prefix list
        Backend-->>MCP: newest strict artifact projection
    else list/detail source
        Backend->>AI: service-token scoped read
        AI-->>Backend: vector なし source
    end
    Backend-->>MCP: JSON result
    MCP-->>Client: text + structuredContent

Header	必須	Purpose
X-API-Key	Yes	backend internal service auth
X-MCP-Project-ID	Yes	authenticated project scope の再 enforcement

Route	Backend responsibility
POST /internal/des2code	design/project/org/MCP scope、completed design、ready AI-v2 index を要求し request ID を作って SQS send
GET /internal/des2code/{design_id}	design authorize、newest canonical S3 artifact、full scope/shape validation
GET /internal/designs	scope validate + paginated AI-v2 design summary proxy
GET /internal/designs/{design_id}	design/project scope validate + vector なし detail proxy
GET /internal/code	scope validate + paginated AI-v2 code summary proxy
GET /internal/code/{code_id}	code/project/optional org validate + vector なし detail proxy

---

Backend / SQS / AI-v2 契約

backend は readiness check 後に以下だけを worker へ送ります。

{
  "design_id": "42_file_node:1",
  "project_id": 42,
  "organization_id": 1,
  "request_id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"
}

schema_version, operation, codebase_index_token はありません。backend は internal API で current AI-v2 DocumentDB code_index を check し、worker も retrieval 前に current scoped index の ready を独立して要求します。

worker は {organization_id}/{project_id}/des2code/{design_id}/{request_id}.json （または {request_id}-failed.json）を書き shared AI-status webhook を送ります。 webhook は design scope を validate/log しますが result/artifact pointer を PostgreSQL に保存しません。

design/code list/detail の path は常に以下です。

MCP v2 -> backend internal API -> AI-v2 internal API -> DocumentDB

---

Backend API ハンドオフ

get-des2code structuredContent は matched_codes, usage_matches, code_index_id, request_id, diagnostics、matcher configuration、model summary、 artifact、status、processed time、error を返します。

implementation 時の client flow:

1. 必要なら list-designs で design ID を取得。
2. exact design/project/organization scope で trigger-des2code。
3. artifact が返るまで get-des2code を poll。
4. usage_matches で Figma node/state mapping を確認。
5. selected code_id ごとに get-code-detail で full source/CSS を取得。
6. 別途 Figma MCP で referenced node geometry/content を確認。

---

環境変数

Variable	必須	Purpose
CLOUDFRONT_SECRET_HEADER	Yes	expected X-MCP-Token
ENVIRONMENT	No	local では edge-token presence を必須にしない
DATABASE_RDS_PROXY_ENDPOINT or DATABASE_HOST	local 以外 Yes	PostgreSQL connection
DATABASE_PORT	deployment-specific	PostgreSQL port
DATABASE_NAME	Yes	PostgreSQL database
DATABASE_USER	Yes	PostgreSQL user
DATABASE_PASSWORD	Yes	PostgreSQL password
DATABASE_CONNECTION_LIMIT	No	pool limit
BACKEND_INTERNAL_URL	Yes	backend internal base URL
BACKEND_INTERNAL_API_KEY	Yes	backend へ送る X-API-Key
BACKEND_INTERNAL_TIMEOUT_MS	No	default 10000、max 120000

MCP v2 は AWS/SQS/S3/DocumentDB/AI provider/Figma/webhook credential を必要としません。

---

移行チェックリスト

• [x] PostgreSQL API-key auth と正の project scope を要求する。
• [x] 6 domain tool をすべて backend internal API に委譲する。
• [x] SQS、S3、DocumentDB、provider、Figma、webhook access を MCP v2 に持たせない。
• [x] matching 前に backend と worker の両方で code-index readiness を検証する。
• [x] flat request payload と immutable request-scoped artifact を使う。
• [x] component/variation evidence を backend-normalized result で返す。

---

関連ドキュメント

• MCP v2 I/O 定義
• MCP v2 テストケース設計
• AI Des2Code 概要
• AI Des2Code I/O
• Des2Code 作成 API
• Des2Code 取得 API