AI Read API (mcp-api) — I/O 定義

このページは apps/mcp-api/ の公式 I/O contract である。guinness-backend/apps/mcp-v2 が利用する internal HTTP read API であり、endpoint、field、status code、projection、error shape を変更する場合は、このページとテストケースを先に更新する。

概要

flowchart LR
  MCP["MCP v2<br/>(guinness-backend)"] -->|"GET /internal/designs<br/>GET /internal/code<br/>X-AI-Service-Token"| API["AI Read API<br/>(Lambda, VPC internal)"]
  API -->|"find design"| DOCDB_D["DocumentDB<br/>design"]
  API -->|"find code"| DOCDB_C["DocumentDB<br/>code"]
  API -->|"{ ok, data, error }"| MCP

項目	値
トリガー	Lambda Function URL または private HTTP integration への HTTP GET
認証	`X-AI-Service-Token` を `AI_SERVICE_TOKEN` と定数時間比較
読み取り	DocumentDB `design` / `code` collection
書き込み	なし
RDB アクセス	なし。PostgreSQL / MySQL へ接続しない
デプロイ	VPC internal only。backend MCP v2 からのみ inbound 許可

エンドポイント

すべての response は envelope を使う。

{
  "ok": true,
  "data": {},
  "error": null
}

すべての request に以下を含める。

X-AI-Service-Token: <shared-secret>

エンドポイント	目的	DocumentDB 操作
`GET /internal/designs?project_id=42&organization_id=1&limit=20&offset=0`	project の design metadata 一覧	`design.find(filter).skip(offset).limit(limit)`
`GET /internal/designs/{design_id}`	vector embedding を除いた design detail	`design.find_one({"_id": design_id})`
`GET /internal/code?project_id=42&organization_id=1&limit=20&offset=0`	project の code metadata 一覧	`code.find(filter).skip(offset).limit(limit)`
`GET /internal/code/{code_id}`	vector embedding を除いた code detail	`code.find_one({"_id": code_id})`

クエリパラメータ

パラメータ	対象	型	必須	ルール
`project_id`	list endpoints	integer	yes	`> 0`
`organization_id`	list endpoints	integer	no	指定時 `> 0`。指定された場合は DocumentDB filter に含める
`limit`	list endpoints	integer	no	default `20`, max `100`。不正値は default
`offset`	list endpoints	integer	no	default `0`。不正値は default

パスパラメータ

パラメータ	対象	型	必須	ルール
`design_id`	`GET /internal/designs/{design_id}`	string	yes	`^[a-zA-Z0-9_:-]+$`, 1-255 chars
`code_id`	`GET /internal/code/{code_id}`	string	yes	UUID string, 1-255 chars

処理コントラクト

X-AI-Service-Token を検証し、missing / mismatch は HTTP 401。
query parameter の組み合わせではなく path で route する。
DocumentDB query 前に path/query parameter を検証する。
DocumentDB filter を構築する。
design/code list: {"project_id": project_id} に、指定された場合のみ organization_id を追加。
design/code detail は {"_id": id}。
list pagination は limit = min(valid_limit or 20, 100)、offset = valid_offset or 0。
list/detail ともすべての vector_embedding field を projection で除外する。
success/failure とも { ok, data, error } を返す。

この API は DocumentDB、S3、SQS、PostgreSQL、MySQL へ write しない。

出力

Design 一覧

{
  "ok": true,
  "data": {
    "project_id": 42,
    "organization_id": 1,
    "total": 2,
    "items": [
      {
        "id": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
        "project_id": 42,
        "organization_id": 1,
        "name": "Login Screen",
        "image_url": "s3://bucket/designs/42_hDDA9BNori9OTXSClduXqR_40002029:37033.png",
        "node_id": "40002029:37033",
        "file_id": "hDDA9BNori9OTXSClduXqR"
      }
    ]
  },
  "error": null
}

node_id と file_id が個別保存されていない場合は、canonical design_id（{project_id}_{file_id}_{node_id}）から導出できます。

Design 詳細取得

{
  "ok": true,
  "data": {
    "design": {
      "_id": "42_hDDA9BNori9OTXSClduXqR_40002029:37033",
      "organization_id": 1,
      "project_id": 42,
      "name": "Login Screen",
      "type": "screen",
      "based_on": "figma_import",
      "json_schema_url": "s3://bucket/figma_json_schema/42_hDDA9BNori9OTXSClduXqR_40002029:37033.json",
      "generation_context": "Login Screen. Viewport: 375x812...",
      "viewport": { "width": 375, "height": 812, "device_class": "mobile" },
      "visual": { "metadata": { "image_url": "s3://bucket/designs/..." } },
      "semantics": { "metadata": { "words": ["login", "authentication"] } },
      "structural": { "metadata": { "structural_text": "tree=FRAME..." } }
    }
  },
  "error": null
}

すべての *.vector_embedding field は返しません。

Code 一覧

{
  "ok": true,
  "data": {
    "project_id": 42,
    "organization_id": 1,
    "total": 1,
    "items": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "project_id": 42,
        "organization_id": 1,
        "name": "Button Primary",
        "type": 1,
        "based_on": 0,
        "image_url": "s3://bucket/code/660e8400-e29b-41d4-a716-446655440001.png"
      }
    ]
  },
  "error": null
}

List response は compact metadata のみを返す。source_code と css_code は detail endpoint のみが返す。

Code 詳細取得

{
  "ok": true,
  "data": {
    "code": {
      "_id": "660e8400-e29b-41d4-a716-446655440001",
      "organization_id": 1,
      "project_id": 42,
      "name": "Button Primary",
      "type": 1,
      "based_on": 0,
      "source_code": "export function ButtonPrimary() { ... }",
      "css_code": ".buttonPrimary { ... }",
      "visual": { "metadata": { "image_url": "s3://bucket/code/..." } },
      "semantics": { "metadata": { "words": ["button", "primary", "cta"] } }
    }
  },
  "error": null
}