# kie-suno6-mcp

![version](https://img.shields.io/badge/version-0.5.0-brightgreen)
![license](https://img.shields.io/badge/license-MIT-blue)
![node](https://img.shields.io/badge/node-%3E%3D18.17.0-green)

Suno V6-first MCP server for [Kie.ai](https://kie.ai). 13 tools, zero
dependencies, stdio JSON-RPC. Pluggable provider registry (Kie.ai default).

## Features
- All 13 tools live-verified against Kie.ai (generate, wait, poll, download,
  download_url, upload, upload_extend, cover, persona, extend, credits,
  tasks, info)
- Dual V6 result parser (`resultJson` + `sunoData`), per-take candidate URL
  lists (asset URL first — stream URLs observed serving 0 bytes post-SUCCESS)
- Browser-UA downloads with sha256 two-take CDN-collision detection + auto-retry
- KIE error-code mapping (400/402/409/422/429/433/451) with actionable hints
- Key self-heal: `KIE_SUNO_CONFIG` > `KIE_SUNO_ENV_FILE` (.env) > spawn env —
  rotated keys need no re-registration
- Local, opt-in telemetry (0.5.0): per-call usage log, deduped API-error
  corpus, terminal result-shape fixtures — off by default, zero network,
  the API key is never written
- 45 zero-credit unit tests (local HTTP server + fixtures + telemetry)

## Requirements
- Node.js >= 18.17.0 (tested on 22). No npm install.
- Kie.ai API key: https://kie.ai/api-key

## Install
```bash
git clone https://github.com/jk123/kie-suno6-mcp
```

MCP client (stdio) — Hermes `config.yaml` style:
```yaml
kie-suno6-mcp:
  command: node
  args: ["/path/to/kie-suno6-mcp/server.js"]
  env:
    KIE_AI_API_KEY: "sk-..."        # or KIE_SUNO_ENV_FILE: /path/to/.env
```

mcpm:
```bash
mcpm new kie-suno6-mcp --type stdio --command node --args /path/to/kie-suno6-mcp/server.js
```

## Configuration
| Variable | Default | Purpose |
|---|---|---|
| `KIE_SUNO_PROVIDER` | `kieai` | Provider registry key |
| `KIE_AI_API_KEY` | — | Kie.ai key (any of the 3 resolution paths) |
| `KIE_SUNO_CONFIG` | — | Path to JSON config overriding env |
| `KIE_SUNO_ENV_FILE` | `~/.hermes/.env` | .env with `KIE_AI_API_KEY` |
| `KIE_SUNO_DOWNLOAD_DIR` | cwd | Where `download` writes takes |
| `KIE_SUNO_RETRY_DELAY_MS` | `35000` | Collision-retry delay |
| `KIE_SUNO_TELEMETRY` | `off` | Set `on` to write usage/error/shape capture to `.telemetry/` |
| `KIE_SUNO_TELEMETRY_DIR` | `<repo>/.telemetry` | Where telemetry files are written |

## Tools (credit cost)
Free: `suno_info`, `suno_credits`, `suno_poll`, `suno_tasks`, `suno_download`, `suno_download_url`, `suno_wait`.
Paid: `suno_generate` (~12 cr/task, 2 takes), `suno_extend`, `suno_upload`, `suno_upload_extend`, `suno_cover` (≈2 × generate, source-dependent), `suno_persona` (≈2 × generate).

## Known behaviors
- `suno_persona` upserts on `taskId+audioId` (no 409; re-calls overwrite name/description in place)
- `suno_download` prefers persistent `tempfile.aiquickdraw.com` asset URLs over `audiostream.kie.ai` stream URLs
- `suno_extend` / `suno_upload_extend`: `defaultParamFlag=false` inherits source params; `true` requires `prompt`+`style`+`title`+`continueAt`
- Fresh V6 tasks return results via `sunoData`, not `resultJson`

## Telemetry (0.5.0)

Local, opt-in, zero-network usage + debug capture for driving the next dev
cycle. Everything writes to `<repo>/.telemetry/` (gitignored) and nothing
ever leaves the machine.

- **Default: OFF** for anyone who clones. Enable with `KIE_SUNO_TELEMETRY=on`
  (spawn env, or a `KIE_SUNO_TELEMETRY=on` line in your `KIE_SUNO_ENV_FILE`
  `.env` — same self-healing source as the API key).
- **What it captures:**
  - `usage-YYYY-MM-DD.jsonl` — one line per boot + per tool call: tool,
    sanitized args, duration, ok/error, and a compact result summary. Pruned
    after 30 days.
  - `errors.json` — a *deduped* index of API-error responses (code + msg hash
    → count, first/last seen, URL, 2 KB body excerpt). This is where a live
    433/402/451/429 gets its real shape captured.
  - `shapes/*.json` + `shapes-index.jsonl` — terminal record-info payloads,
    deduped by structural signature, so a first-ever V6_WILD (or a new
    `resultJson` shape) becomes a drop-in unit-test fixture. Capped at 60 files.
- **Privacy floor:** the API key is **never** written (only its *source label*,
  e.g. `env-file(~/.hermes/.env)`); `fileBase64` becomes a byte-length stub;
  `prompt`/`description` are truncated to 80 chars + total length.
- **Self-disarm:** a failed write disables telemetry for the process lifetime
  instead of ever breaking a tool call.
- **Digest for the next version:** `node telemetry-report.js` (add `--json`
  for machine output) → per-tool call/error counts + p50/p95 latency, top
  captured errors, and a **test-candidates** list (error codes / result shapes
  seen live but not yet fixture-tested).

## Test
```bash
node test/unit.js   # 45/45, no API access needed
node smoke.js       # JSON-RPC handshake, free
node telemetry-report.js   # digest of .telemetry/ (if enabled)
```

## Not yet tested live
433/402/451/429 error paths and the V6_WILD `resultJson` shape are still
unit-mapped/fixture-only — **with telemetry on, the first live occurrence is
now captured automatically** into `.telemetry/` (see `node telemetry-report.js`
→ test candidates), so they can be promoted to fixtures as they happen.
A/B persona quality remains an ear test.

MIT. No secrets in this repo.