# Whisper

Speech-to-text (CPU Whisper large-v3, default `hu`). Async only.

**Large audio:**
1. `POST https://mcp.glc-rag.hu/staging/upload` — Bearer + multipart `file` (max 1 GiB)
2. Take `url` from the response
3. `whisper_job_start({ url, language: "hu" })` → `job_id`
4. Poll `whisper_job_status` → `whisper_job_result` when completed

Already-public https URL: skip staging, call `whisper_job_start` with that url.

**Service id:** `whisper`  
**Version:** `0.1.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": {
    "whisper": {
      "url": "https://mcp.glc-rag.hu/mcp",
      "headers": {
        "Authorization": "Bearer mcp_YOUR_TOKEN"
      }
    }
  }
}
```

## Tools

### `whisper_job_start`

Start async speech-to-text. Returns {job_id} — not the transcript. Large local file: POST /staging/upload first, then pass response.url here. Then whisper_job_status → whisper_job_result. Default language hu.

**Input schema:**

```json
{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Public https URL. Large/local files: POST /staging/upload \u2192 use returned url (https://mcp.glc-rag.hu/staging/\u2026)."
    },
    "content_base64": {
      "type": "string",
      "description": "Tiny clips only. Large audio \u2192 /staging/upload."
    },
    "filename": {
      "type": "string",
      "description": "Optional filename hint (e.g. talk.mp3)."
    },
    "language": {
      "type": "string",
      "description": "Default hu. Use hu for Hungarian; auto to detect.",
      "default": "hu"
    },
    "task": {
      "type": "string",
      "enum": [
        "transcribe",
        "translate"
      ],
      "description": "transcribe (default) or translate (to English).",
      "default": "transcribe"
    }
  },
  "additionalProperties": false
}
```

**Examples:**

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

### `whisper_job_status`

Poll whisper job. status: queued|running|completed|failed. Backoff 15–60s.

**Input schema:**

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

**Examples:**

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

### `whisper_job_result`

Transcript when status=completed. If still queued/running, keep polling status.

**Input schema:**

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

**Examples:**

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

## Usage notes

```bash
curl -sS -X POST 'https://mcp.glc-rag.hu/staging/upload' \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -F "file=@/path/to/audio.mp3"
# → {"url":"https://mcp.glc-rag.hu/staging/…"}
```
Then MCP whisper_job_start(url) → status → result. Need `staging` + `whisper` approved (agents get both). One concurrent job; long audio may take a long time.

## Errors / limits

Bad/expired job_id → error. Private URL / >1 GiB / queue full → reject. Need staging+whisper approved.

## Agent discovery

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