# EarSay MCP

MCP server for [EarSay](https://github.com/your-org/earsay) — continuous voice-to-text for coding agents.

Connects to a running EarSay transcription server and exposes voice input as MCP tools that any MCP-compatible agent (OpenCode, Claude, etc.) can use.

## Features

- **Start/stop/pause/resume** — full control over the transcription server
- **Poll for new text** — call `voice_get_new` to check what the user said since last time
- **Checkpoints** — mark what you've already read so you only get new content
- **Status** — check if the server is listening, paused, or stopped

## Installation

```bash
pip install earsay-mcp
```

Requires [EarSay](https://github.com/your-org/earsay) to be installed separately.

## Usage

### With OpenCode

Add to `~/.config/opencode/opencode.jsonc`:

```jsonc
{
  "mcpServers": {
    "earsay": {
      "command": "earsay-mcp"
    }
  }
}
```

The agent will see these tools:

| Tool | Description |
|------|-------------|
| `voice_start` | Start the transcription server |
| `voice_stop` | Stop the server |
| `voice_pause` | Pause transcription |
| `voice_resume` | Resume transcription |
| `voice_get_text` | Get all transcribed text |
| `voice_get_new` | Get text since last checkpoint |
| `voice_set_checkpoint` | Mark text as read |
| `voice_status` | Server status |

### With Claude Desktop

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

## How It Works

```
Microphone → EarSay (faster-whisper) → HTTP API (localhost:3009)
                                              ↑
                                         earsay-mcp (stdio JSON-RPC)
                                              ↑
                                         OpenCode Agent (MCP client)
```

The MCP server starts EarSay as a subprocess on first `voice_start` call, then translates all MCP tool calls into HTTP requests to EarSay's API.

## Requirements

- Python 3.10+
- EarSay installed (`pip install earsay`)
- Working microphone

## License

MIT