<div align="center">

# 🎤 OpenCode Voice MCP Server

### Voice Input for AI Coding Assistants

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![npm version](https://img.shields.io/npm/v/@yuvarjbhado/voice-mcp.svg)](https://www.npmjs.com/package/@yuvarjbhado/voice-mcp)
[![GitHub stars](https://img.shields.io/github/stars/YuvrajSinghBhadoria2/opencode-voice-mcp)](https://github.com/YuvrajSinghBhadoria2/opencode-voice-mcp)
[![GitHub issues](https://img.shields.io/github/issues/YuvrajSinghBhadoria2/opencode-voice-mcp)](https://github.com/YuvrajSinghBhadoria2/opencode-voice-mcp)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

**Speak your prompts. No typing required.**

[Installation](#installation) • [Quick Start](#quick-start) • [Tools](#tools) • [Configuration](#configuration) • [Architecture](#architecture) • [Contributing](#contributing)

</div>

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🎤 **Voice Recording** | Record audio from microphone with configurable duration |
| 🗣️ **Speech-to-Text** | Transcribe using local Whisper model (100% offline) |
| ⌨️ **Auto-Typing** | Type transcribed text at cursor position |
| 🔒 **Privacy First** | No cloud API — audio never leaves your machine |
| 🌍 **Multi-Language** | Support for 99+ languages via Whisper |
| 🔌 **MCP Standard** | Works with OpenCode, Claude Code, Cursor, and more |

## 📦 Installation

```bash
# Install globally
npm install -g @yuvarjbhado/voice-mcp

# Or use with npx (no install required)
npx @yuvarjbhado/voice-mcp
```

### Prerequisites

<details>
<summary><strong>macOS</strong></summary>

```bash
# Install recording tool
brew install sox

# Install transcription engine
pip install faster-whisper
```
</details>

<details>
<summary><strong>Linux (Ubuntu/Debian)</strong></summary>

```bash
# Install recording tool
sudo apt install sox

# Install transcription engine
pip install faster-whisper
```
</details>

<details>
<summary><strong>Windows</strong></summary>

```bash
# Install FFmpeg (via scoop)
scoop install ffmpeg

# Install transcription engine
pip install faster-whisper
```
</details>

## 🚀 Quick Start

### Step 1: Configure MCP Server

Add to your MCP config file:

| Tool | Config Location |
|------|-----------------|
| **OpenCode** | `~/.config/opencode/config.json` |
| **Claude Code** | `~/.claude/claude_desktop_config.json` |
| **Cursor** | `~/.cursor/mcp.json` |

**OpenCode** (use `mcp` key):
```json
{
  "mcp": {
    "voice": {
      "command": "npx",
      "args": ["-y", "@yuvarjbhado/voice-mcp"]
    }
  }
}
```

**Claude Desktop / Cursor** (use `mcpServers` key):
```json
{
  "mcpServers": {
    "voice": {
      "command": "npx",
      "args": ["-y", "@yuvarjbhado/voice-mcp"]
    }
  }
}
```

### Step 2: Restart Your Tool

Restart OpenCode, Claude Code, or Cursor to load the MCP server.

### Step 3: Use Voice Input

```
@voice voice_transcribe
@voice voice_type
@voice voice_status
```

## 🛠️ Tools

### `voice_transcribe`

Record audio from microphone and transcribe to text.

```json
{
  "name": "voice_transcribe",
  "arguments": {
    "duration": 10,
    "language": "en"
  }
}
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `duration` | number | `10` | Recording duration in seconds |
| `language` | string | `auto` | Language code (e.g., `en`, `es`, `fr`) |

**Returns:** Transcribed text as string.

---

### `voice_type`

Record audio, transcribe to text, and type it at the cursor position.

```json
{
  "name": "voice_type",
  "arguments": {
    "duration": 10,
    "language": "en"
  }
}
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `duration` | number | `10` | Recording duration in seconds |
| `language` | string | `auto` | Language code |

**Returns:** Confirmation message with typed text.

---

### `voice_status`

Check if voice recording and transcription are available.

```json
{
  "name": "voice_status",
  "arguments": {}
}
```

**Returns:**
```json
{
  "recording": "rec",
  "transcription": "faster-whisper (local)",
  "platform": "darwin",
  "ready": true
}
```

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `WHISPER_MODEL` | Whisper model size | `base` |
| `WHISPER_DEVICE` | Device to use (`cpu`, `cuda`, `auto`) | `auto` |
| `WHISPER_COMPUTE` | Compute type (`int8`, `float16`, `float32`) | `int8` |

### Model Sizes

| Model | Size | Speed | Accuracy | VRAM |
|-------|------|-------|----------|------|
| `tiny` | ~75MB | ⚡⚡⚡⚡ | ⭐⭐ | ~1GB |
| `base` | ~150MB | ⚡⚡⚡ | ⭐⭐⭐ | ~1GB |
| `small` | ~500MB | ⚡⚡ | ⭐⭐⭐⭐ | ~2GB |
| `medium` | ~1.5GB | ⚡ | ⭐⭐⭐⭐⭐ | ~5GB |
| `large-v3` | ~3GB | 🐌 | ⭐⭐⭐⭐⭐ | ~10GB |

**Recommendation:** Use `base` for best balance of speed and accuracy.

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                               │
│                  (OpenCode / Claude Code / Cursor)              │
└──────────────────────────┬──────────────────────────────────────┘
                           │ JSON-RPC
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Voice MCP Server                             │
│                     (Node.js)                                   │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │ voice_record │  │voice_transcribe│ │  voice_type  │         │
│  │    Tool      │  │     Tool     │  │    Tool      │         │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘         │
│         │                 │                 │                   │
│         ▼                 ▼                 ▼                   │
│  ┌─────────────────────────────────────────────────────┐       │
│  │              Audio Recording Layer                   │       │
│  │         (sox / ffmpeg / macOS rec)                  │       │
│  └─────────────────────────┬───────────────────────────┘       │
│                            │                                    │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────┐       │
│  │           Transcription Engine                      │       │
│  │      (faster-whisper / OpenAI API)                  │       │
│  └─────────────────────────┬───────────────────────────┘       │
│                            │                                    │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────┐       │
│  │              Output Layer                           │       │
│  │    ┌─────────────┐  ┌─────────────────────┐        │       │
│  │    │ Return Text │  │ Type at Cursor      │        │       │
│  │    │   (MCP)     │  │ (osascript/xdotool) │        │       │
│  │    └─────────────┘  └─────────────────────┘        │       │
│  └─────────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────────┘
```

### Data Flow

```
┌─────────┐    ┌─────────┐    ┌─────────────┐    ┌─────────┐
│  User   │───▶│  Micro- │───▶│  Whisper    │───▶│  Text   │
│  Speaks │    │  phone  │    │  Transcribe │    │  Output │
└─────────┘    └─────────┘    └─────────────┘    └─────────┘
     │              │               │                │
     │              │               │                │
     ▼              ▼               ▼                ▼
  "Hello      Records 16kHz    Processes with    Returns text
   world"     mono audio      base model        or types it
```

## 🔧 Development

### Setup

```bash
# Clone repository
git clone https://github.com/YuvrajSinghBhadoria2/opencode-voice-mcp.git
cd opencode-voice-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev
```

### Project Structure

```
opencode-voice-mcp/
├── src/
│   └── index.ts          # MCP server implementation
├── dist/
│   └── index.js          # Compiled output
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript config
├── build.sh              # Build script
└── publish.sh            # npm publish script
```

### Available Scripts

| Command | Description |
|---------|-------------|
| `npm run build` | Compile TypeScript to JavaScript |
| `npm run dev` | Run in development mode with tsx |
| `npm run start` | Run compiled server |
| `./publish.sh` | Build and publish to npm |

## 🤝 Contributing

Contributions are welcome! Please follow these steps:

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feat/amazing-feature`)
3. **Commit** your changes (`git commit -m 'feat: add amazing feature'`)
4. **Push** to the branch (`git push origin feat/amazing-feature`)
5. **Open** a Pull Request

### Development Guidelines

- Follow TypeScript best practices
- Add tests for new features
- Update documentation as needed
- Use conventional commit messages

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io) - Standard for AI tool integration
- [faster-whisper](https://github.com/SYSTRAN/faster-whisper) - Fast Whisper implementation
- [OpenCode](https://github.com/anomalyco/opencode) - AI coding assistant
- [OpenAI Whisper](https://github.com/openai/whisper) - Speech recognition model

---

<div align="center">

**Built with ❤️ for the developer community**

[Report Bug](https://github.com/YuvrajSinghBhadoria2/opencode-voice-mcp/issues) • [Request Feature](https://github.com/YuvrajSinghBhadoria2/opencode-voice-mcp/issues) • [Discussions](https://github.com/YuvrajSinghBhadoria2/opencode-voice-mcp/discussions)

</div>