# ParrotScribe MCP Server (Deprecated) & Lex Copilot

> [!WARNING]
> This MCP server is deprecated. It will **continue to work** for users who stay on Parrot Scribe versions before `0.4.0`, but it will **not** work once you upgrade to `0.4.0` or newer.
> Use the integrated MCP server built into Parrot Scribe instead.

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that enables AI agents to interact with the [ParrotScribe](https://parrotscribe.com) transcription service on macOS.

## Meet Lex: Your Tactical Meeting Copilot

If you are using **Opencode**, I recommend that you use the pre-configured agent called **Lex**. Lex transforms passive transcription into an active research and navigation tool.

- **Real-time Context**: Ask "What's that?" or "What did they just say?" to get instant explanations.
- **Zero-Latency Knowledge**: Proactively loads domain-specific skills based on transcript keywords.
- **Tactical Summaries**: Generates structured meeting notes, identifying key facts and action items.
- **Persona-Ready**: Tailor Lex to any role (Journalist, Researcher, Engineer) via private directives.

### Installing Lex
1. Ensure you are on Parrot Scribe `< 0.4.0` and this MCP server is configured in your environment.
2. Copy `agent/lex.md` from this repository into your local `.opencode/agent/` directory.

---

## What It Does

ParrotScribe captures real-time audio from your microphone and system audio, transcribes it using Whisper, and this MCP server exposes that transcription data to AI agents. This enables workflows like:

- **Meeting Monitor**: AI monitors a live call and surfaces relevant information
- **Action Item Tracker**: AI detects commitments and prepares follow-up actions
- **Real-time Researcher**: AI looks up technical terms mentioned in conversation
- **Session Summarizer**: AI generates structured summaries after calls

## Prerequisites

- **macOS** with [ParrotScribe](https://parrotscribe.com) installed
- **Node.js** 18 or higher
- The `pscribe` CLI must be available in your PATH (it will be if ParrotScribe is installed correctly)
- **Parrot Scribe version < 0.4.0** (once `0.4.0` is released, this package is unsupported)

## Legacy Installation (Parrot Scribe < 0.4.0 only)

If you are using Parrot Scribe `0.4.0` (or newer), do not install this package. Use the app's integrated MCP server.

### Option 1: NPX (Recommended)

No installation needed. Configure your AI agent to run:

```
npx @johanthoren/parrotscribe-mcp-server
```

### Option 2: Global Install

```bash
npm install -g @johanthoren/parrotscribe-mcp-server
```

Then run with:

```
parrotscribe-mcp-server
```

### Option 3: From Source

```bash
git clone https://github.com/johanthoren/parrotscribe-mcp.git
cd parrotscribe-mcp
npm install
npm run build
node dist/index.js
```

## Configuration

### Opencode

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

```jsonc
{
  "mcp": {
    "parrotscribe": {
      "type": "local",
      "command": ["npx", "@johanthoren/parrotscribe-mcp-server"]
    }
  }
}
```

### Claude Code

Add to your project's `.mcp.json` or global MCP config:

```json
{
  "mcpServers": {
    "parrotscribe": {
      "command": "npx",
      "args": ["@johanthoren/parrotscribe-mcp-server"]
    }
  }
}
```

### Claude Desktop

Add to your `claude_desktop_config.json` (typically at `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "parrotscribe": {
      "command": "npx",
      "args": ["@johanthoren/parrotscribe-mcp-server"]
    }
  }
}
```

### Environment Variables (Optional)

| Variable | Description | Default |
|----------|-------------|---------|
| `PSCRIBE_PATH` | Path to the `pscribe` executable. Only needed if `pscribe` is not in your PATH (edge case). | `pscribe` |

## Available Tools

| Tool | Description |
|------|-------------|
| `pscribe_start` | Start real-time audio transcription |
| `pscribe_stop` | Stop/pause the current transcription |
| `pscribe_status` | Get service status, session ID, duration |
| `pscribe_tail` | Get recent transcript entries with filtering |
| `pscribe_cat` | Display complete sessions with time-based filtering |
| `pscribe_grep` | Search for patterns across transcript sessions |
| `pscribe_sessions` | List past transcription sessions |
| `pscribe_new` | Force start a new session |

### pscribe_tail Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `n` | number | Number of entries to return (default: 10) |
| `since_line` | number | Start from line N (for polling) |
| `status` | string | Filter: `all`, `confirmed`, `unconfirmed`, `translated`, `speech` |
| `session_id` | string | Read from a specific session |

### pscribe_cat Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `session_ids` | string[] | Session IDs to display (from pscribe_sessions) |
| `since` | string | Show sessions starting after this ISO8601 timestamp |
| `until` | string | Show sessions starting before this ISO8601 timestamp |
| `last` | number | Show last N sessions |
| `status` | string | Filter: `all`, `confirmed`, `unconfirmed`, `speech` |

Use `pscribe_cat` for historical queries like "summarize yesterday's standup" - the AI converts natural language time references to ISO8601.

### pscribe_grep Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pattern` | string | The pattern to search for (regex supported) - **required** |
| `since` | string | Only search sessions starting after this ISO8601 timestamp |
| `until` | string | Only search sessions starting before this ISO8601 timestamp |
| `status` | string | Filter: `all`, `confirmed`, `unconfirmed`, `speech` |
| `ignore_case` | boolean | Case-insensitive search |
| `count` | boolean | Show match count per session instead of matches |
| `after_context` | number | Show N lines after each match (-A) |
| `before_context` | number | Show N lines before each match (-B) |
| `context` | number | Show N lines before and after each match (-C) |

Use `pscribe_grep` for queries like "did anyone mention deployment last week?" or "find all references to the API".

## Output Format: TOON

The server returns transcript data in [TOON format](https://github.com/toon-format/toon), a token-efficient format designed for LLM consumption:

```
transcript{timestamp,source,status,segment,confidence,duration,language,text}:
  2024-01-15T14:30:00+01:00,M,C,1,0.95,2.5,en,Hello world
  2024-01-15T14:30:05+01:00,S,C,2,0.92,3.1,sv,Hej dar
```

### Fields

| Field | Description |
|-------|-------------|
| `timestamp` | ISO8601 with timezone |
| `source` | `M` (microphone), `S` (system audio), `E` (events) |
| `status` | `C` (confirmed), `U` (unconfirmed), `T` (translated), `N` (no_speech) |
| `segment` | Incrementing segment number |
| `confidence` | Whisper confidence score (0.0-1.0) |
| `duration` | Segment duration in seconds |
| `language` | ISO 639-1 code (e.g., `en`, `sv`, `de`) |
| `text` | Transcribed content |

## Polling Strategy

For real-time monitoring, agents should:

1. Call `pscribe_status` to ensure a session is active
2. Call `pscribe_tail` with `n: 10` to get initial context
3. Note the `last_line` number from the response metadata
4. Periodically call `pscribe_tail` with `since_line: last_line + 1`
5. Use `status: "confirmed"` to focus on finalized transcriptions

## Example Prompts

See the `examples/` directory for ready-to-use prompts:

- **standup.md**: Daily standup meeting assistant
- **retro.md**: Sprint retrospective facilitator
- **code-review.md**: Code review meeting tracker
- **pair-programming.md**: Pair programming session monitor
- **adr.md**: Architecture Decision Record generator

## Security & Privacy

- **Local-Only**: Data flows exclusively from the local `pscribe` CLI to the local AI agent via stdio
- **Zero-Cloud**: No analytics, no telemetry, no intermediate servers
- **User Control**: You decide when transcription is active and which AI agent receives the data

## Development

```bash
# Install dependencies
npm install

# Development mode (auto-reload)
npm run dev

# Build
npm run build

# Test with MCP inspector
npm run inspect
```

## License

MIT

## Links

- [ParrotScribe App](https://parrotscribe.com)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [TOON Format](https://github.com/toon-format/toon)