# Vision

**Ternary Bonsai 27B** image analysis via **Together AI** → fixed English JSON. Async worker only (does not block other MCP tools).

1. Upload image (multipart, no base64):
   - `POST /vision/upload` or `POST /staging/upload`
2. `vision_job_start({ image_url })` → `job_id`
3. Poll `vision_job_status` → `vision_job_result`

Max edge 4K. Credits: base + MiB.

**Service id:** `vision`  
**Version:** `0.2.0`  
**Status:** `available`

## Authentication

MCP endpoint: `https://mcp.glc-rag.hu/mcp` (streamable HTTP)

**Agents (recommended):** self-register with `account_type=agent` to get an
auto-approved token — see [https://mcp.glc-rag.hu/guide/agent](https://mcp.glc-rag.hu/guide/agent).

Or register as a human on the public site (all listed services are auto-approved),
wait for system-admin approval, then create a token.

```http
Authorization: Bearer mcp_...
```

Cursor `mcp.json` example:

```json
{
  "mcpServers": {
    "vision": {
      "url": "https://mcp.glc-rag.hu/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}
```

## Tools

### `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.

**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
}
```

**Examples:**

```json
{
  "image_url": "https://mcp.glc-rag.hu/staging/0123456789abcdef0123456789abcdef"
}
```

### `vision_job_status`

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

**Input schema:**

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

**Examples:**

```json
{
  "job_id": "0123456789abcdef0123456789abcdef"
}
```

### `vision_job_result`

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

**Input schema:**

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

**Examples:**

```json
{
  "job_id": "0123456789abcdef0123456789abcdef"
}
```

### `vision_status`

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

**Input schema:**

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

**Examples:**

```json
{}
```

## Usage notes

```bash
curl -sS -X POST 'https://mcp.glc-rag.hu/vision/upload' \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -F "file=@/path/to/photo.jpg"
# → {"url":"https://mcp.glc-rag.hu/staging/…"}
```
Then MCP: vision_job_start({ image_url }) → status → result. Backend: Together AI `Prism-ML/Ternary-Bonsai-27B`. One concurrent job.

## Errors / limits

Missing Together API key, bad URL, queue full, JSON parse fail after retry → failed job. Need vision approved for tools; upload needs vision or staging approved.

## Agent discovery

- Agent registration: `https://mcp.glc-rag.hu/guide/agent`
- Markdown: `https://mcp.glc-rag.hu/guide/vision.md`
- Index: `https://mcp.glc-rag.hu/llms.txt`
- MCP resource: `docs://vision`