Metadata-Version: 2.4
Name: speak-global-mcp
Version: 0.1.2
Summary: MCP server for the SpeakGlobal Developer API (/v1).
Project-URL: Homepage, https://pypi.org/project/speak-global-mcp/
Project-URL: Repository, https://github.com/Design-Aura/speak-global-MCP
Project-URL: Changelog, https://github.com/Design-Aura/speak-global-MCP/releases
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.8
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"

# speak-global-mcp

Connect desktop AI apps and editors that support the **Model Context Protocol** (MCP) to [SpeakGlobal](https://speakglobal.ai): voice-style TTS, recordings, transcription, and audio processing via the same **Developer API** (`/v1`) as your dashboard key (**Account → Developer**).

| | |
|--|--|
| **Install** | [PyPI: `speak-global-mcp`](https://pypi.org/project/speak-global-mcp/) — `pip install` / `pipx install` |
| **Source & issues** | [github.com/Design-Aura/speak-global-MCP](https://github.com/Design-Aura/speak-global-MCP) |

**Limits:** Export billing APIs are not exposed as MCP tools (`/v1/tts/export`, export-status, `/v1/recordings/export`).

---

## Requirements

- **Python 3.10+**
- A **SpeakGlobal Developer API key** (`sg_live_…`) from the dashboard

---

## Install

### From PyPI (recommended)

**pipx** (keeps dependencies separate — good for CLI-style tools):

```bash
pipx install speak-global-mcp
pipx ensurepath
```

Open a **new** terminal so `speakglobal-mcp` is on your `PATH`.

Pin a version if you want (see [PyPI versions](https://pypi.org/project/speak-global-mcp/#history)):

```bash
pipx install "speak-global-mcp==X.Y.Z"
```

**venv + pip:**

```bash
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS / Linux
pip install speak-global-mcp
```

---

## Connect an MCP client

This server speaks MCP over **stdio**: your app starts `speakglobal-mcp` (or `python -m speak_global_mcp.server`) **locally**. Put the API key only in that app’s config — never commit it.

Most clients use the same shape: a top-level **`mcpServers`** object with one entry per server: **`command`**, optional **`args`**, and **`env`** for `SPEAKGLOBAL_*`.

Use **`SPEAKGLOBAL_ENVIRONMENT=production`** with the live API (HTTPS + non-empty key). Restart or reload MCP in the app after editing config.

### Example: `speakglobal-mcp` on `PATH` (after pipx)

```json
{
  "mcpServers": {
    "speakglobal": {
      "command": "speakglobal-mcp",
      "env": {
        "SPEAKGLOBAL_ENVIRONMENT": "production",
        "SPEAKGLOBAL_API_BASE": "https://api.speakglobal.ai",
        "SPEAKGLOBAL_API_KEY": "sg_live_REPLACE_ME"
      }
    }
  }
}
```

### Example: Python from a venv (command not on `PATH`)

Use your real interpreter path. On Windows, escape backslashes in JSON or use forward slashes.

```json
{
  "mcpServers": {
    "speakglobal": {
      "command": "C:/path/to/.venv/Scripts/python.exe",
      "args": ["-m", "speak_global_mcp.server"],
      "env": {
        "SPEAKGLOBAL_ENVIRONMENT": "production",
        "SPEAKGLOBAL_API_BASE": "https://api.speakglobal.ai",
        "SPEAKGLOBAL_API_KEY": "sg_live_REPLACE_ME"
      }
    }
  }
}
```

### Where to paste it (by app)

| App | Config file (typical location) |
|-----|--------------------------------|
| **[Cursor](https://cursor.com)** | Windows: `%USERPROFILE%\.cursor\mcp.json` — macOS/Linux: `~/.cursor/mcp.json` |
| **[Claude Desktop](https://claude.ai/download)** | Windows: `%APPDATA%\Claude\claude_desktop_config.json` — macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **[Windsurf](https://codeium.com/windsurf)** | MCP settings in the editor (often under AI / MCP); same `mcpServers` JSON — see Windsurf docs for the exact file or UI path. |
| **[VS Code](https://code.visualstudio.com/)** (MCP extension) | Use the extension’s MCP configuration (command + env); format matches the examples above where the extension expects stdio servers. |
| **Other MCP hosts** | Any product that supports **stdio** MCP servers: use the same `command` / `args` / `env` pattern and follow that product’s documentation for where config lives. |

Remote MCP over HTTP (`sse` / `streamable-http`) is optional for self-hosting; see [CONTRIBUTING.md](CONTRIBUTING.md). Many desktop apps only support **local stdio**.

---

## Voice clone & TTS

The server **does not create** voice profiles. Create or clone a voice in the web app first, for example:

`https://speakglobal.ai/dashboard/tts/create-profile`

Then use MCP tools such as `list_voice_profiles` and `generate_tts` with the profile’s `session_id` (or your account default when set).

---

## What the tools do

| Tool | What it’s for |
|------|----------------|
| `account_summary` | Account, credits, default voice session |
| `list_voice_profiles` / `get_voice_profile` | Voice profiles for TTS |
| `list_recordings` / `get_recording` | Library & detail |
| `generate_tts` | Text → speech (voice clone) |
| `presign_audio_upload` | Upload new audio (then PUT file, register URL) |
| `register_recording_from_url` | Register recording from a URL |
| `start_transcription` | Transcribe |
| `start_enhance` / `edit_transcript` / `start_re_enhance` | Processing pipeline |
| `get_job_status` / `list_jobs_for_session` | Job tracking |

API scopes apply to your key — use a key with only the scopes you need.

---

## Optional: Docker (self-hosted MCP over HTTP)

For **SSE** / **streamable-http** behind your own TLS, you can run the container (see [CONTRIBUTING.md](CONTRIBUTING.md) for defaults and env vars). Do not expose it publicly without TLS and access control.

---

## Security

- Treat `SPEAKGLOBAL_API_KEY` like a password; rotate it if leaked.
- One running server typically uses **one** key (one SpeakGlobal account).

---

## Contributing & development

Clone, tests, release process, full env reference, Docker, and CI: **[CONTRIBUTING.md](CONTRIBUTING.md)**.
