# Transcript MCP spike

A small Model Context Protocol server that lets an LLM inspect and search mock
transcripts stored in `data/transcripts.json`.

## Requirements

- Node.js 18 or newer
- npm

## Transports

This server supports two transports:

1. **stdio** — the MCP client spawns the process (default)
2. **Streamable HTTP** — you run the server and point the client at
   `http://127.0.0.1:3000/mcp`

### HTTP (localhost)

Start the server:

```sh
npm run mcp:http
```

Or with auto-reload while editing TypeScript:

```sh
npm run dev:http
```

Then configure the client with a URL:

```json
{
  "mcpServers": {
    "transcripts": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```

Optional env vars:

- `PORT` — listen port (default `3000`)
- `MCP_TRANSPORT=http` — same as passing `--http`

Inspector:

```sh
npx @modelcontextprotocol/inspector http://127.0.0.1:3000/mcp
```

### stdio (spawned by the client)

No separate server process. Point the client at the TypeScript source:

```json
{
  "mcpServers": {
    "transcripts": {
      "command": "npx",
      "args": [
        "tsx",
        "/absolute/path/to/mcp-spike/src/server.ts"
      ]
    }
  }
}
```

Or use the compiled build after `npm run build`:

```json
{
  "mcpServers": {
    "transcripts": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-spike/dist/server.js"]
    }
  }
}
```

## MCP capabilities

Resource:

- `transcripts://all` returns the complete JSON dataset.

Tools:

- `list_transcripts` lists metadata and supports participant and tag filters.
- `get_transcript` returns a full transcript by ID.
- `search_transcripts` searches titles, participants, tags, speakers, and spoken
  text.

Edits to `data/transcripts.json` are picked up on the next tool/resource call.
Invalid data is rejected using a Zod schema.