Merge pull request #2 from theYahia/fix/tts-endpoint-mime-tls

fix: correct TTS endpoint, recognition MIME types & Sber TLS onboarding (v1.2.0)

Author: theYahia

.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": ["-y", "@theyahia/salutespeech-mcp"],
       "env": {
-        "SALUTE_AUTH_KEY": ""
+        "SALUTESPEECH_API_KEY": ""
       }
     }
   }

CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-06-23
+
+### Fixed
+- **Text-to-speech was completely broken.** `synthesize_speech` POSTed to the non-existent
+  `/speech:synthesize`; the correct SaluteSpeech endpoint is `/text:synthesize`. Every TTS
+  call previously failed.
+- **Recognition MIME types were wrong** for several formats. SaluteSpeech has no `audio/wav`
+  content-type — WAV is now sent as `audio/x-pcm;bit=16;rate=<sr>` with the sample rate read
+  from the file header. `.flac` now uses `audio/flac` (was `audio/x-flac`), and `.pcm` now
+  requires a `sample_rate` and emits `audio/x-pcm;bit=16;rate=<sr>`. `.mp3`, `.ogg`, and
+  `.opus` were already correct and are unchanged.
+
+### Added
+- Configurable OAuth scope via `SALUTE_SPEECH_SCOPE` (default `SALUTE_SPEECH_PERS`), so
+  corporate accounts (`SALUTE_SPEECH_CORP`, `SALUTE_SPEECH_B2B`) can authenticate.
+- `list_models` now reports the English voice **Kira** (`Kin_24000`/`Kin_8000`), the 8000 Hz
+  telephony variants of every voice, the `alaw` synthesis format, and a note that the sample
+  rate comes from the voice id suffix and other languages are selected via SSML.
+- Friendly size guard: recognition input over the 2 MB / 1 minute synchronous limit now
+  fails with an actionable message pointing to the async flow (instead of a raw HTTP 413).
+- TLS troubleshooting: a clear OAuth error hint and a README section about installing the
+  Russian Trusted Root CA (НУЦ Минцифры) via `NODE_EXTRA_CA_CERTS`.
+- All tool handlers now return `isError` on failure, so the model sees readable errors
+  instead of opaque protocol errors.
+- `.alaw`/`.ulaw` recognition input mapping (`audio/pcma`/`audio/pcmu`).
+- New tests: WAV header parsing, size guard, recognition output shaping, exported
+  `getAuthKey` priority, TLS-hint wrapping, and client retry behavior (429/500/abort).
+  Handler tests assert request URL + content-type, locking in the endpoint and MIME fixes.
+
+### Changed
+- Recognition tools now return a flattened `text` transcript alongside `emotions` and the
+  raw API body (the transcript lives in `result[]`).
+- Synthesis input is validated to 1–4000 characters (the documented limit).
+- `.mcp.json` example uses `SALUTESPEECH_API_KEY` to match the README.
+- Removed unused type interfaces (`RecognitionResult`, `SynthesisResponse`, `SaluteModel`).
+
+## [1.1.0]
+
+- Upgrade to 5 tools, Vitest test suite, and Streamable HTTP transport.
+
+## [1.0.0]
+
+- Initial release.

README.md

@@ -47,7 +47,9 @@ Three options (checked in order):
 | `SALUTE_AUTH_KEY` | Same (legacy alias) |
 | `SALUTE_SPEECH_CLIENT_ID` + `SALUTE_SPEECH_CLIENT_SECRET` | Raw credentials (auto-encoded) |
 
-OAuth tokens (scope `SALUTE_SPEECH_PERS`) are obtained and refreshed automatically.
+OAuth tokens are obtained and refreshed automatically. The scope defaults to
+`SALUTE_SPEECH_PERS` (individuals); set `SALUTE_SPEECH_SCOPE` for corporate accounts
+(`SALUTE_SPEECH_CORP` — postpaid, `SALUTE_SPEECH_B2B` — prepaid).
 Get credentials at [developers.sber.ru](https://developers.sber.ru).
 
 ## Tools (5)
@@ -73,6 +75,34 @@ Synthesize "Hello world" with voice Bys_24000 in wav16 format
 List available voices
 ```
 
+## Limits
+
+`recognize_speech` / `recognize_file` use the **synchronous** endpoint, capped at
+**2 MB / 1 minute** of audio (larger input returns HTTP 413). For multi-channel audio only
+the first channel is recognized. Longer recordings need the asynchronous flow
+(`data:upload` → `speech:async_recognize` → `task:get` → `data:download`) — not yet exposed
+as tools; `get_task_status` covers the polling step.
+
+Synthesis input is capped at **4000 characters** (incl. spaces and SSML markup).
+
+## Troubleshooting
+
+### `self-signed certificate in certificate chain` / `UNABLE_TO_VERIFY_LEAF_SIGNATURE`
+
+Sber's endpoints use the **Russian Trusted Root CA (НУЦ Минцифры)**, which is **not** in
+Node.js's default trust store — so the very first OAuth call fails until you trust it.
+
+Fix: download the root CA (`russian_trusted_root_ca_pem.crt`) from
+[gosuslugi.ru/crt](https://www.gosuslugi.ru/crt) and point Node at it:
+
+```bash
+export NODE_EXTRA_CA_CERTS=/path/to/russian_trusted_root_ca_pem.crt
+```
+
+In an MCP client, add it to the server's `env` block. **Do not** set
+`NODE_TLS_REJECT_UNAUTHORIZED=0` in production — it disables TLS verification entirely.
+Official guide: [SaluteSpeech certificates](https://developers.sber.ru/docs/ru/salutespeech/certificates).
+
 ## License
 
 MIT