# Vision — canonical payload contracts

Image analysis with Ternary Bonsai 27B via Together AI (English JSON). Async: POST /vision/upload or /staging/upload → vision_job_start({ image_url }) → status → result.

**Service id:** `vision`  
**Docs:** [https://mcp.glc-rag.hu/guide/vision](https://mcp.glc-rag.hu/guide/vision)  
**Markdown docs:** [https://mcp.glc-rag.hu/guide/vision.md](https://mcp.glc-rag.hu/guide/vision.md)  
**MCP resource:** `docs://vision/payload`

POST `https://mcp.glc-rag.hu/mcp`. Values below are **type slots** from the live input schema (e.g. `<string, required>`), not example data. Fill them from the user task.

RPC result wrapper: `result.structuredContent` is the object in **Output schema**. `result.isError` mirrors `structuredContent.is_error`.

## `vision_job_start`

Start async image analysis (Together AI Ternary Bonsai 27B). Returns {job_id} only. Upload via POST /vision/upload or /staging/upload first, then pass image_url. No base64. Poll vision_job_status → vision_job_result. English JSON output.

**Required arguments:** `image_url`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "vision_job_start",
    "arguments": {
      "image_url": "<string, required>",
      "focus": "<string, optional>",
      "filename": "<string, optional>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "image_url": {
      "type": "string",
      "description": "Public or staging HTTPS image URL (from /vision/upload or /staging/upload)."
    },
    "focus": {
      "type": "string",
      "description": "Optional English focus hint (e.g. product label)."
    },
    "filename": {
      "type": "string",
      "description": "Optional filename hint."
    }
  },
  "required": [
    "image_url"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Hex job id from vision_job_start"
    },
    "status": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "job_id"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `vision_job_status`

Poll vision job. status: queued|running|completed|failed. phase may be starting_model|running|parsing. Backoff 15–60s.

**Required arguments:** `job_id`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "vision_job_status",
    "arguments": {
      "job_id": "<string, required>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "From vision_job_start"
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Hex job id from vision_job_start"
    },
    "status": {
      "type": "string"
    }
  },
  "additionalProperties": true,
  "required": [
    "job_id",
    "status"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `vision_job_result`

Fixed English analysis JSON when status=completed. If queued/running, keep polling status.

**Required arguments:** `job_id`

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "vision_job_result",
    "arguments": {
      "job_id": "<string, required>"
    }
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "From vision_job_start"
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "Hex job id from vision_job_start"
    },
    "status": {
      "type": "string"
    },
    "result": {
      "type": "object"
    }
  },
  "additionalProperties": true,
  "required": [
    "job_id",
    "status"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```

## `vision_status`

Vision worker/model health, limits, queue counts (free).

**Required arguments:** _(none)_

**Request contract**

```json
{
  "jsonrpc": "2.0",
  "id": "<integer|string>",
  "method": "tools/call",
  "params": {
    "name": "vision_status",
    "arguments": {}
  }
}
```

**Input schema**

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
```

**Output schema** (`structuredContent` on success)

```json
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean"
    }
  },
  "additionalProperties": true,
  "required": [
    "ok"
  ]
}
```

**Error object**

```json
{
  "type": "object",
  "required": [
    "error",
    "is_error"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "is_error": {
      "type": "boolean",
      "const": true
    }
  },
  "additionalProperties": true
}
```