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

This page is the authoritative I/O contract for apps/mcp-api/ in guinness-ai-v2. It is the internal HTTP read API consumed by guinness-backend/apps/mcp-v2. Any endpoint, field, status code, projection, or error-shape change must be reflected here and in Test Cases before implementation.

Overview

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

Item	Value
Trigger	HTTP GET request to Lambda Function URL or private HTTP integration
Authentication	`X-AI-Service-Token` header, compared to `AI_SERVICE_TOKEN` using constant-time comparison
Reads	DocumentDB `design` and `code` collections
Writes	None
RDB access	None — this API never connects to PostgreSQL or MySQL
Deployment	VPC internal only; security group allows inbound from backend MCP v2 only

Endpoints

All responses use this envelope:

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

All requests include:

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

Endpoint	Purpose	DocumentDB operation
`GET /internal/designs?project_id=42&organization_id=1&limit=20&offset=0`	List design metadata for a project	`design.find(filter).skip(offset).limit(limit)`
`GET /internal/designs/{design_id}`	Get one design document without vector embeddings	`design.find_one({"_id": design_id})`
`GET /internal/code?project_id=42&organization_id=1&limit=20&offset=0`	List code metadata for a project	`code.find(filter).skip(offset).limit(limit)`
`GET /internal/code/{code_id}`	Get one code document without vector embeddings	`code.find_one({"_id": code_id})`

Query Parameters

Parameter	Applies to	Type	Required	Rules
`project_id`	list endpoints	integer	Yes	`> 0`
`organization_id`	list endpoints	integer	No	`> 0` when provided; included in the DocumentDB filter when present
`limit`	list endpoints	integer	No	default `20`, max `100`; invalid values fall back to default
`offset`	list endpoints	integer	No	default `0`; invalid values fall back to default

Path Parameters

Parameter	Applies to	Type	Required	Rules
`design_id`	`GET /internal/designs/{design_id}`	string	Yes	`^[a-zA-Z0-9_:-]+$`, length 1-255
`code_id`	`GET /internal/code/{code_id}`	string	Yes	UUID string, length 1-255

Processing Contract

Validate X-AI-Service-Token; missing or mismatched token returns HTTP 401.
Route by path, not by mutually exclusive query parameters.
Validate path/query parameters before querying DocumentDB.
Build the DocumentDB filter:
list design/code: {"project_id": project_id} plus organization_id when provided.
detail design/code: {"_id": id}.
Apply list pagination with limit = min(valid_limit or 20, 100) and offset = valid_offset or 0.
Project out every vector_embedding field for both list and detail responses.
Return { ok, data, error } for success and failure.

No endpoint writes to DocumentDB, S3, SQS, PostgreSQL, or MySQL.

Outputs

List Designs

{
  "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 and file_id may be derived by splitting the canonical design_id ({project_id}_{file_id}_{node_id}) if they are not stored separately.

Get Design Detail

{
  "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
}

All *.vector_embedding fields must be omitted.

List 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 responses are compact metadata. source_code and css_code are returned only by the detail endpoint.

Get Code Detail

{
  "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
}