Skip to main content
Glama
README.md
# kurdvoice

Kurdish is spoken in two major written dialects — Sorani and Kurmanji — and good speech tooling for either is hard to find. kurdvoice is a small local bridge to the hosted KurdishTTS MCP service: you can turn Sorani or Kurmanji text into spoken audio, transcribe Kurdish audio back into text, open a live transcription session for a microphone stream, browse the voice catalogue, and check what your plan allows.

Nothing is synthesized or transcribed on your own machine. This package answers `tools/list` locally from the captured tool definitions and forwards every `tools/call` to the hosted service over a streamable-HTTP JSON-RPC session, returning whatever the service sends back unchanged.

## The tools

The dialect, voice and plan tools are free metadata reads that need no API key. Synthesis and transcription are metered against your own plan allowance — characters for speech, audio minutes for transcription, one session for a live stream — exactly as the upstream service meters them. No tool buys anything, tops up credit, checks out, or creates an API key.

- **`list_dialects`** — The supported Kurdish dialects and their scripts. A static capability descriptor: it costs nothing and needs no key.
- **`list_voices`** — The text-to-speech voice catalogue, filterable by dialect and gender and paged with `limit`/`offset`. Voice catalogues are versioned (`v3` is the default compatibility catalogue, `v4` the large one, `v5` the curated one with Cast and Studio voices), and a speaker id only exists inside the catalogue it came from — call this with the same `model_version` you will pass to `synthesize_speech`.
- **`get_plan`** — What this connection may use. With an API key it reports your current plan, remaining allowance and which catalogues and voices you may render; without a key it returns the purchasable plan ladder and how to get a key. It is the fastest first call when another tool answers 401 or 403.
- **`synthesize_speech`** — Turns Kurdish text into one complete audio clip, base64-encoded in the result, in `mp3` (default), `opus` or `wav`. Needs a TTS API key; characters are billed against your plan. Up to 4000 characters per call (600 with `wav`, and free plans are capped at 500 server-side). `speed` runs from 0.25 to 4, and `include_timestamps` returns word-level timestamps instead of an audio block. The dialect is normally inferred from the speaker id; pass it explicitly for Cast or Studio voices reading Kurmanji.
- **`transcribe_audio`** — Transcribes base64-encoded audio (WAV, MP3, FLAC, OGG or M4A, up to 3 MB decoded) to text, metered per audio minute against your plan. The `dialect` argument selects the decoder and nothing detects it for you: transcribing Sorani audio as Kurmanji returns fluent, confident, wrong text. Pass `"auto"` when unsure — it transcribes with both decoders and returns both transcripts, billing the audio twice.
- **`start_streaming_transcription`** — Opens a live speech-to-text session for listening — a microphone or audio stream transcribed in real time. It returns a `websocket_url` to stream PCM16 mono 16 kHz audio chunks into. Calling it immediately consumes one streaming session from your plan quota, so call it only when you are ready to connect.

## Install and run

As an MCP server via npm:

```bash
npx -y @reneturcios/kurdvoice mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "kurdvoice": {
      "command": "npx",
      "args": ["-y", "@reneturcios/kurdvoice", "mcp"]
    }
  }
}
```

As a container:

```bash
docker run -i ghcr.io/cloudcorprecords/kurdvoice
docker run --rm ghcr.io/cloudcorprecords/kurdvoice synthesize_speech '{"text":"Slaw","speaker_id":"sorani_85"}'
```

## CLI

One binary serves both the command line and the MCP server. Each tool is a subcommand taking a single JSON string with that tool's arguments:

```bash
kurdvoice list_dialects '{}'
kurdvoice list_voices '{"model_version":"v4","dialect":"sorani","limit":50}'
kurdvoice get_plan '{}'
kurdvoice synthesize_speech '{"text":"Slaw","speaker_id":"sorani_85"}'
kurdvoice transcribe_audio '{"audio_base64":"UklGRg==","dialect":"auto"}'
kurdvoice start_streaming_transcription '{"dialect":"kurmanji"}'
kurdvoice --version
```

Exit codes: `0` when the forwarded call succeeds, `1` when the upstream result is an error, and `2` for usage problems such as an unknown subcommand or a malformed JSON argument.

## Configuration

- `KURDISHTTS_MCP_URL` — Overrides the upstream endpoint. The default is the pinned hosted endpoint, `https://www.kurdishtts.com/api/mcp`. (The override variable is a reconstruction added by this rebuild.)
- `KURDISHTTS_API_KEY` — When set, its value is sent to the upstream on every request as an `Authorization: Bearer <value>` header. When it is not set, no key header is sent at all, matching the keyless behaviour the tool surface was captured with. (The service's registry record declares a secret `Authorization` header on its remote; the variable name and the Bearer form are reconstructions added by this rebuild.)

Upstream failures — a JSON-RPC error from the service, a non-2xx response, an unreadable body, or a request that fails outright — are reported to the caller as an error result whose text starts with `kurdvoice error:`.

## How forwarding works

The first forwarded call opens a session: an `initialize` request (protocol version `2025-03-26`), followed by a `notifications/initialized` notification, then the `tools/call` itself. If the service answers the initialize request with an `Mcp-Session-Id` header, that value is carried on every later request, and the open session is reused for the rest of the process. Replies are accepted either as plain JSON or as server-sent events. Successful results pass through verbatim, including any `isError` flag and any extra fields the service includes.

## Development

```bash
npm install
npm run build   # tsc -> dist/ (dist/cli.js is the bin)
npm test        # tsx --test test/*.test.ts — stubbed upstream, no network
npm run dev     # run the CLI from source
```

The test suite checks the served tool list against the captured surface tool by tool, exercises the session handshake and its reuse, covers both key-header branches, and verifies that arguments go upstream untouched and results come back untouched.

## License

MIT — see `LICENSE`. Copyright (c) 2026 Rene Turcios.