# WriteBetter MCP Extension

A Claude Desktop extension (MCP server) that connects Claude to the
[WriteBetter](https://svenbadalyan.com/tools/) macOS app running on the same
Mac. Claude can work with your local WriteBetter library: commands, the
Prompt Library, context folders, run history and usage stats.

Everything stays on your machine. The extension only talks to WriteBetter
over `127.0.0.1:51515`.

## Requirements

- macOS with the **WriteBetter** app installed and running
  (download: https://svenbadalyan.com/tools/)
- Claude Desktop

## Install

1. In WriteBetter, open **Settings** and turn on **AI Assistant Integration**.
   Keep the app running.
2. Download `writebetter.mcpb` from this repository.
3. Open Claude Desktop → **Settings → Extensions → Advanced settings →
   Install Extension…** and select the downloaded file.
4. Ask Claude, for example:
   - *"List my WriteBetter commands."*
   - *"Create a WriteBetter command called `de` that translates English text
     into German and keeps the tone."*
   - *"Show me the run history of my `de` command and suggest how to improve
     its prompt."*

## How it works

- WriteBetter listens on `127.0.0.1:51515` (loopback only, never the
  network), and only while **AI Assistant Integration** is turned on.
- `index.js` is the MCP server. Each tool call opens a short TCP connection
  to that port, sends one JSON line, and relays the JSON response back.
- Every call goes through WriteBetter's own validation (duplicate names,
  chain rules, value ranges), exactly as in the app.
- **Safety switches** (WriteBetter → Settings → AI Assistant Integration):
  - *Ask before deleting or running* (on by default): every delete/clear
    tool and `run_command` shows an Allow / Deny dialog in WriteBetter and
    waits up to 90 s for an answer (Deny is the default button).
  - *Read-only*: only the read tools work; everything else is refused.

## Build from source

```bash
npm install
npm run build:mcpb   # produces writebetter.mcpb
```

Manual alternative without the extension: add this to
`~/Library/Application Support/Claude/claude_desktop_config.json` and restart
Claude Desktop (use only one of the two methods):

```json
"mcpServers": {
  "writebetter": {
    "command": "node",
    "args": ["/absolute/path/to/writebetter-mcp-extension/index.js"]
  }
}
```

## Tools exposed

Tools marked ⚠︎ ask for approval in WriteBetter first (unless turned off).

**General:** `get_status`, `search_history`, `get_usage_stats`

**Commands:** `list_commands` (filters: `include_inactive`, `type`),
`get_command` (by id or shortcut, with settings and prompt structure),
`match_command` (best match for a phrase, with scores), `create_command`,
`update_command`, `update_command_settings` (model, temperature, reasoning,
retries, generation mode, saved-history size), `set_command_active`
(inactive commands appear in the app's Commands tab behind the eye button),
`get_command_history`, ⚠︎ `clear_command_history`, ⚠︎ `delete_command`,
⚠︎ `run_command` (runs on the user's API keys and is saved to history)

**Prompts:** `list_prompts` (filters: `query`, `tag`), `get_prompt` (by id or
name), `create_prompt`, `update_prompt`, ⚠︎ `delete_prompt`

**Context folders:** `list_context_folders`, `get_context_folder`,
`get_active_context`, `create_context_folder` (does not change the active
folder unless `make_active: true`), `rename_context_folder`,
`select_context_folder`, `add_context_snippet`, `update_context_snippet`,
⚠︎ `delete_context_snippet`, ⚠︎ `clear_context_folder`,
⚠︎ `delete_context_folder`, `set_context_enabled`, `list_context_labels`,
`create_context_label`, ⚠︎ `delete_context_label`

Image snippets are listed by file name only; image data is not sent.

## Troubleshooting

If a tool call fails with "Could not reach WriteBetter on 127.0.0.1:51515",
the app either isn't running or the toggle in Settings is off. After
updating WriteBetter or this extension, make sure both are the new version:
an older app answers new tools with "Unknown action".

## Privacy Policy

This extension only talks to the WriteBetter app running on the same Mac, over `127.0.0.1:51515`. It makes no other network connections, collects no telemetry, and sends nothing to WriteBetter or any third party. Commands, prompts, context, run history and usage data stay in WriteBetter's local storage.

Full policy:

- English: https://svenbadalyan.com/writebetter/privacy/
- Deutsch: https://svenbadalyan.com/de/writebetter/privacy/

## Support

contact@svenbadalyan.com

## License

MIT, see [LICENSE](LICENSE). The license covers this extension only; the
WriteBetter app itself is a separate product.