# TypeWriter MCP

MCP server for the [Typewriter](https://typewriter.gg/) Minecraft plugin. It lets AI assistants in Cursor, Claude Desktop, and other MCP clients read and edit storylines: pages, dialogues, facts, triggers, and the rest of the entry graph.

You can work live against a running server over websocket, or edit page JSON files offline.

## What it does

Typewriter stores story content as pages and entries. The web editor is fine for manual work, but slow when you want an agent to draft whole branches, fix dialogue, or wire up triggers across dozens of entries. This server exposes that data as MCP tools so the assistant can do the editing for you.

In socket mode it uses the same protocol as the official web editor. Changes land in staging first, show up in the panel, and can be published to production without clobbering work you have open elsewhere.

## Modes

**Socket (recommended for live servers)**

Connect to the running plugin over websocket. Best for production and any setup where you want changes visible in the web panel before they go live.

**File (offline)**

Edit `plugins/Typewriter/pages/*.json` directly. Useful when the server is down or you want to batch-edit files and reload later. Run `/typewriter reload` on the server after saving.

## Install

```bash
git clone https://github.com/yurchik228336/TypeWriter-MCP.git
cd TypeWriter-MCP
npm install
npm run build
```

Requires Node.js 18+.

## Cursor / Claude Desktop config

Add this to your MCP config (for Cursor: `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "typewriter": {
      "command": "node",
      "args": ["C:/path/to/TypeWriter-MCP/dist/index.js"],
      "env": {
        "TYPEWRITER_MODE": "socket",
        "TYPEWRITER_URL_FILE": "C:/path/to/TypeWriter-MCP/.typewriter-session-url"
      }
    }
  }
}
```

With this setup the server starts in socket mode and waits for a connect URL. When you want to work live, run `/typewriter connect` in-game and paste the full link into chat. The agent calls `connect_live` and keeps the socket open for the rest of the session. You do not need to paste the link again while that connection is still alive.

If you prefer a fixed URL in config instead:

```json
"env": {
  "TYPEWRITER_MODE": "socket",
  "TYPEWRITER_URL": "http://host:8080/#/connect?host=1.2.3.4&port=9092&token=<uuid>"
}
```

Note: with `auth: session`, that token expires when the player who generated it logs out.

**File mode:**

```json
"env": {
  "TYPEWRITER_MODE": "file",
  "TYPEWRITER_PAGES_DIR": "C:/server/plugins/Typewriter/pages"
}
```

## Typewriter plugin setup (socket)

1. Enable websocket in `plugins/Typewriter/config.yml`:

```yaml
enabled: true
websocket:
  port: 9092
  auth: session
```

Restart the server after editing the config.

2. In-game, run `/typewriter connect`. You get a URL like:

```
http://host:8080/#/connect?host=1.2.3.4&port=9092&token=<uuid>
```

3. Paste that URL to your agent or set it in `TYPEWRITER_URL`.

Plain websocket URLs work too: `ws://host:9092?token=<uuid>`

For a trusted local network you can set `auth: none` and skip tokens. Only do that if you know what you are exposing.

## Typical agent workflow

1. Paste the connect URL when starting a live session.
2. `list_pages` / `read_page` to see what exists.
3. `create_page`, `add_entry`, `connect_entries` to build or extend the story.
4. `validate_storyline` to catch broken trigger references.
5. `publish` to apply staging changes in-game (socket mode only).

If the session drops or the token expires, send a fresh connect URL.

## Example prompts

Paste these into Cursor or Claude Desktop when the Typewriter MCP is connected. For live work, include your connect URL in the first message.

**Connect and inspect**

```
Here is my Typewriter connect URL: http://host:8080/#/connect?host=1.2.3.4&port=9092&token=...
Connect to the server and list all pages. Tell me what storylines already exist.
```

```
Read the page named "chapter1" and summarize every dialogue entry and how the triggers are wired.
```

**Create a new storyline**

```
Connect with this URL: ...
Create a static page called "village_npcs" with a simple_speaker entry for a villager named Mira.
Then create a sequence page called "village_intro" with a spoken_dialogue where Mira greets the player.
Wire the dialogue flow with connect_entries and run validate_storyline when you are done.
Publish the changes.
```

```
Add a new option_dialogue to page "chapter2" with two choices:
1) "I'll help you" -> sets a permanent_fact "agreed_to_help"
2) "Not now" -> ends the conversation
Link the options to the correct follow-up entries.
```

**Edit existing content**

```
Search all pages for the text "old quest name" and update every matching dialogue line to "new quest name".
Do not change entry ids or trigger links.
```

```
On page "main_quest", find the entry where the blacksmith speaks and change his line to:
"We need iron from the mines. Bring me ten ingots and I'll pay you well."
```

**Debug and validate**

```
Run validate_storyline across the whole project and fix any broken trigger references you can resolve without guessing missing entries.
Show me what you changed.
```

```
Search for entries that reference fact id "abc123" and list which pages use it.
```

**File mode (offline)**

```
Using file mode, read everything under plugins/Typewriter/pages.
Create a new sequence page "side_quest_rat" with three spoken_dialogue entries: start, middle, reward.
Save the files. I will run /typewriter reload on the server myself.
```

## Tools

| Tool | Description |
|------|-------------|
| `connection_status` | Current mode, connection state, saved URL |
| `connect_live` | Connect using a `/typewriter connect` URL |
| `list_pages` | List pages (id, name, type, entry count) |
| `read_page` | Read a full page by name or id |
| `create_page` | Create a page (`sequence`, `static`, `cinematic`, `manifest`) |
| `rename_page` | Rename a page |
| `delete_page` | Delete a page and all its entries |
| `add_entry` | Add an entry (dialogue, speaker, fact, etc.) |
| `update_entry` | Update one field by dotted path (`text`, `speaker`, `criteria.0.value`) |
| `replace_entry` | Replace an entry, keeping the same id |
| `delete_entry` | Delete an entry by id |
| `connect_entries` | Append a trigger link between two entries |
| `search_entries` | Full-text search across all pages |
| `validate_storyline` | Find broken references in triggers / triggeredBy |
| `publish` | Publish staging to production (socket mode only) |

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `TYPEWRITER_MODE` | `socket` | `socket` or `file` |
| `TYPEWRITER_URL` | — | Optional fixed connect URL |
| `TYPEWRITER_URL_FILE` | `.typewriter-session-url` in cwd | Where the last connect URL is stored |
| `TYPEWRITER_PAGES_DIR` | `plugins/Typewriter/pages` | Pages directory for file mode |

## License

MIT. Use it however you want: personal projects, servers, forks, commercial work, no permission needed. See [LICENSE](LICENSE).

## Not affiliated

This is an unofficial community tool. Typewriter is developed by its own team; this MCP just speaks their websocket and file formats.