# @txscribe/mcp

An [MCP](https://modelcontextprotocol.io) server for the txscribe developer API. It lets an AI
assistant transcribe a link with your txscribe account and read the transcript and the summary
back, through the same API documented at <https://txscribe.ai/developers>.

There are two ways to connect, with the same eight tools:

- **Hosted** — `https://txscribe.ai/mcp` (Streamable HTTP). Claude and ChatGPT connect to it as
  a custom connector and sign you in to txscribe with OAuth; nothing to install. Clients that
  take a header can send an API key instead.
- **Local** — this package, run as a command (`npx -y @txscribe/mcp`) by Claude Desktop, Claude
  Code, Cursor and other clients that start MCP servers themselves, with your API key in its
  environment.

Both are thin wrappers: every tool is one call to the developer API as you. What a tool may do,
and the minutes it uses, is exactly what your account may do in the app. Nothing is cached or
stored on your machine.

## Hosted: Claude and ChatGPT

- **Claude** (claude.ai, the desktop app): Settings → Connectors → Add custom connector, URL
  `https://txscribe.ai/mcp`. Claude opens txscribe; sign in and choose **Allow**.
- **ChatGPT** (with developer mode on): add a connector with the URL `https://txscribe.ai/mcp`
  and OAuth as its authentication, then allow it on the txscribe page that opens.
- **Claude Code**: `claude mcp add --transport http txscribe https://txscribe.ai/mcp` (it signs in
  with OAuth), or with a key:
  `claude mcp add --transport http txscribe https://txscribe.ai/mcp --header "Authorization: Bearer txs_live_…"`.
- **Cursor and others** that take a URL and headers: the URL above with the header
  `Authorization: Bearer txs_live_…`.

A connection made with **Allow** is an API key the app holds for you. It is listed under **Plan and
billing → Developer API**, where **Revoke** disconnects that app. It does not expire on its own.

## Local: this package

1. In the app, open **Plan and billing → Developer API** and make a key (it starts with
   `txs_live_`; you see it once).
2. Add the server to your client with the key in its environment.

Claude Desktop (`claude_desktop_config.json`) or any client that takes a command:

```json
{
  "mcpServers": {
    "txscribe": {
      "command": "npx",
      "args": ["-y", "@txscribe/mcp"],
      "env": { "TXSCRIBE_API_KEY": "txs_live_…" }
    }
  }
}
```

Claude Code:

```bash
claude mcp add txscribe --env TXSCRIBE_API_KEY=txs_live_… -- npx -y @txscribe/mcp
```

`TXSCRIBE_API_BASE` points the server at another deployment (default
`https://txscribe.ai/api/v1`).

## Tools

| Tool | What it does | Writes? |
|---|---|---|
| `list_transcriptions` | Your transcriptions, newest first, with paging | no |
| `search_transcriptions` | Which recordings said a word or phrase, and when: up to five matches each, with the second they start at. Reads the finished ones among your newest 500 recordings; searches what was said, not titles. | no |
| `transcribe_link` | Create a transcription from a link (YouTube, Google Drive, Dropbox …). The recording is transcribed, never downloaded. Uses your minutes. | yes |
| `get_transcription` | Status and metadata of one transcription | no |
| `get_transcript` | The finished transcript as `json` (segments, word timings, speakers), `txt`, `srt` or `vtt`; `from` and `to` (seconds) for only the paragraphs around a moment, `summaryOnly` for the summary instead | no |
| `get_summary` | The summary and its status | no |
| `request_summary` | Ask for a summary, or a new one, in a language and for a kind of recording | yes |
| `delete_transcription` | Delete a transcription and everything made from it. Cannot be undone. | yes, destructive |

Five tools only read; three change your account. Uploading a file is not a tool: the API's
upload is a signed PUT of the whole file, which an assistant cannot make from a chat. Use the
app, or the API directly, for files.

A typical exchange: *"Transcribe this talk and give me the three claims to check"* →
`transcribe_link` → `get_transcription` until `status` is `done` → `get_transcript` (txt) →
the assistant reads it; `request_summary` + `get_summary` for the summary txscribe makes.

Finding something in recordings you already have: *"What did we agree about the budget?"* →
`search_transcriptions` ("budget") → `get_transcript` with `from`/`to` around the matches it
returned, instead of whole transcripts.

## Errors

API refusals come back as tool errors with the API's own code (`invalid_api_key`,
`quota_exceeded`, `not_ready`, `unsupported_link` …), the HTTP status, the request id to quote
to support and, on 429, the `Retry-After` seconds. Neither server retries anything itself.

## Develop

```bash
npm ci
npm test
```

The tests run the server over an in-memory transport against a fake `fetch`; nothing reaches
the network. The hosted server lives in the web app (`web/src/lib/mcp/`), and its tests check
that its tool list matches this one.

## Publish (maintainers)

```bash
cd mcp
npm ci && npm test
npm login                      # an npm account that owns the @txscribe scope
npm publish                    # publishConfig makes it public; prepublishOnly runs the tests
```

`server.json` is the entry for the MCP Registry (registry.modelcontextprotocol.io); its `name`
matches `mcpName` in package.json, which is how the registry checks the npm package is ours.
Publish it after the npm package is up and the hosted endpoint is switched on, with
[`mcp-publisher`](https://github.com/modelcontextprotocol/registry) and DNS proof of txscribe.ai.