Metadata-Version: 2.4
Name: prodius-mcp
Version: 0.2.1692
Summary: MCP server shim for Prodius — lets AI agents reach you by voice
Author-email: Prodius <support@prodius.ai>
License-Expression: MIT
Project-URL: Homepage, https://prodius.ai
Project-URL: Connect, https://prodius.ai/connect/
Keywords: mcp,model-context-protocol,voice,prodius,ai-agents,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# prodius-mcp

**Let your AI agents reach you by voice.**

`prodius-mcp` is a lightweight [MCP](https://modelcontextprotocol.io) server that bridges any MCP-capable AI tool (Claude Code, Cursor, Windsurf, Codex CLI, and more) to the [Prodius](https://prodius.ai) desktop app. When an agent needs your input, a popup appears on your screen — wherever you are — and you answer by voice. No switching back to the terminal.

It's a thin stdio shim: **standard library only, no third-party dependencies**, fast startup, and it talks only to the Prodius desktop app running locally on `127.0.0.1`.

## Requirements

- Python 3.10+
- The [Prodius desktop app](https://prodius.ai/download/) installed and running, with **Voice Bridge** enabled in settings.

## Install

```bash
pip install prodius-mcp
```

If `prodius-mcp` isn't found afterwards, make sure the Python environment you installed into is on your `PATH` — or use `pipx install prodius-mcp`.

## Connect your tool

### Claude Code

The quickest start is one command:

```bash
claude mcp add prodius -- prodius-mcp
```

For the full experience (correct agent label in the modal header, automatic conversation reset on `/clear`), add the block below to your `~/.claude/settings.json` instead. The `claude mcp add` shortcut omits both pieces.

```json
{
  "env": { "PRODIUS_AGENT_NAME": "Claude Code" },
  "mcpServers": {
    "prodius": {
      "command": "prodius-mcp",
      "args": [],
      "env": { "PRODIUS_AGENT_NAME": "Claude Code" }
    }
  },
  "hooks": {
    "SessionStart": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "prodius-mcp-reset" }] }
    ]
  }
}
```

The `SessionStart` hook calls `prodius-mcp-reset` whenever you run `/clear` or open a new session so Prodius doesn't carry stale context across conversations. The top-level `env` makes the agent name visible to that hook.

To enable **voice push** (microphone stays available between questions so you can speak to Claude anytime, not just when it asks), start Claude with the channels flag:

```bash
claude --dangerously-load-development-channels server:prodius
```

### Cursor / Windsurf / any MCP client

Add to your client's MCP config (e.g. `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "prodius": { "command": "prodius-mcp" }
  }
}
```

### Codex CLI

```toml
[mcp_servers.prodius]
command = "prodius-mcp"
env = { PRODIUS_AGENT_NAME = "Codex CLI" }
```

Full setup instructions for each tool, including session-reset hooks and optional voice push, live at **[prodius.ai/connect](https://prodius.ai/connect/)**.

## Tools exposed

| Tool | What it does |
| --- | --- |
| `ask_user` | Pops a question on your screen and captures your spoken (or typed) reply. Supports optional clickable answer buttons. |
| `notify` | Reports a result to you via a desktop overlay — meant as the agent's final action so its response is never invisible. |

## Configuration

The shim auto-discovers the running Prodius app. You rarely need to set anything, but these environment variables override the defaults:

| Variable | Purpose | Default |
| --- | --- | --- |
| `PRODIUS_MCP_TOKEN` | Auth token for the local Prodius server. | Read from the Prodius app's `settings.json`. |
| `PRODIUS_BASE_URL` | Prodius local server URL. | Discovered from settings (`http://127.0.0.1:5555`). |
| `PRODIUS_AGENT_NAME` | Label shown so you know which agent is asking. | `Unknown Agent` |

## Console scripts

- `prodius-mcp` — the MCP server (run by your AI tool, not by hand).
- `prodius-mcp-reset` — resets the Prodius conversation. Wire it to a Claude Code `SessionStart` hook (see the snippet above) so a new session doesn't inherit stale context.
- `prodius-permission-hook` — routes Claude Code tool-approval prompts to the Prodius voice overlay so you can speak "allow" / "deny" from anywhere. Add it as a `PreToolUse` hook in `~/.claude/settings.json`:

  ```json
  "hooks": {
    "PreToolUse": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "prodius-permission-hook" }] }
    ]
  }
  ```

  Falls through to the normal terminal prompt if Prodius isn't running — never blocks you. Full instructions at [prodius.ai/connect](https://prodius.ai/connect/).

## Troubleshooting

- **Popup doesn't appear?** Confirm the Prodius desktop app is running with Voice Bridge enabled, and that `prodius-mcp` is on your `PATH`.
- **Agent doesn't receive your answer?** Check your microphone works in Prodius (try a normal dictation), then restart your AI tool after editing its config.

## License

MIT
