# MCP Commander

<!-- mcp-name: io.github.dpc00/sublime-mcp -->

Exposes Sublime Text to AI assistants (Claude Code, Cursor, etc.) via the
Model Context Protocol.  The MCP server is built directly into the ST plugin —
no separate process or external dependency required.

63 tools covering reading, navigation, editing, searching, build, Terminus
integration, settings, layout, menus, console log, and live Python scripting.

## Architecture

The plugin runs two local servers on startup:

| Server | Default port | Purpose |
|--------|-------------|---------|
| MCP SSE | 9502 (Win) / 9503 (Mac/Linux) | MCP 2024-11-05 SSE transport — connect your agent here |
| HTTP bridge | 9500 (Win) / 9501 (Mac/Linux) | Internal REST API used by the SSE dispatcher |

```
Claude Code (MCP client)
        │  MCP SSE  (port 9502)
        ▼
  sublime_mcp.py  ←  ST plugin — MCP server + HTTP bridge, all in one file
        │  sublime API
        ▼
  Sublime Text 4
```

## Installation

### 1. Install via Package Control

1. Open the Command Palette (`Ctrl+Shift+P`)
2. Run **Package Control: Install Package**
3. Search for **MCP Commander** and install

The plugin loads automatically.  Check `View › Show Console` for:

```
sublime-mcp: MCP SSE on 127.0.0.1:9502, HTTP bridge on 127.0.0.1:9500
```

> **Manual install:** copy `sublime_mcp.py` (and optionally `sublime_mcp_browse.py`)
> into your `Packages/User/` folder.

### 2. Register with Claude Code

Add to `~/.claude/settings.json` under `"mcpServers"`:

**Windows:**
```json
"sublime-mcp": { "type": "sse", "url": "http://127.0.0.1:9502/sse" }
```

**Mac / Linux:**
```json
"sublime-mcp": { "type": "sse", "url": "http://127.0.0.1:9503/sse" }
```

Restart Claude Code. Tools appear with the `mcp__sublime-mcp__` prefix.

## Server management

The MCP server starts automatically when ST loads the plugin.  To stop or
restart it, open the Command Palette and run:

> **MCP Commander: Server Status**

The panel shows whether the server is running and on which port, and lets you
start or stop it with a single keypress.

## Tab and Sheet Indexing

**IMPORTANT:** Users refer to tabs by 1-based numbering (tab 1, tab 2, etc.), but
`get_sheets()` returns 0-based indexes. Always convert user tab references before using:
- User **tab 1** = index 0
- User **tab 2** = index 1

When targeting a specific tab, call `get_sheets()` first to verify the index.

## Tools

### Read / Introspect

| Tool | Description |
|------|-------------|
| `get_active_file` | Path, full content, cursor line/col, dirty flag, and syntax name |
| `get_selection` | Current selection(s): text and begin/end line+col for each |
| `get_cursor_context` | `lines` lines above and below cursor, with 1-based line numbers prepended |
| `get_open_files` | All files open in the current window (path, name, is_dirty) |
| `get_sheets` | All sheets (tabs) in the window by index — includes images and untitled buffers |
| `get_sheet_content` | Content of any tab by sheet index (from `get_sheets`) |
| `get_project_folders` | Project root folder paths |
| `get_file_content` | Full content of any already-open file by path |
| `get_view_content` | Full content of any open tab by name (partial match, case-insensitive) |
| `get_view_size` | Total character count of any open tab |
| `get_view_chars` | Text at character offsets begin..end (0-based, end exclusive) |
| `get_view_phantoms` | Phantom HTML and extracted plain text from a named view |
| `get_output_panel` | Text content of a named output panel (`name='exec'` for build output) |
| `get_active_panel` | Active panel id and, if it is an output panel, its content |
| `get_symbols` | All symbols (functions, classes, etc.) in the active file with line numbers |
| `lookup_symbol` | Find where a symbol is defined across all open files |
| `get_project_data` | Raw `.sublime-project` JSON for the current project |
| `get_variables` | ST build variables: `$file`, `$project_path`, `$platform`, etc. |
| `get_command_palette` | Command Palette entries from installed `*.sublime-commands` resources |
| `get_commands` | Runnable command ids from loaded command classes |
| `get_menu_items` | Menu items from `*.sublime-menu` resources |
| `get_syntaxes` | All syntax definitions available in ST (name + path) |
| `get_scope_at_cursor` | Full syntax scope string at the cursor position |
| `get_word_at_cursor` | Word under the cursor and its line/col |
| `get_bookmarks` | All bookmarked positions in the active file |
| `get_line_count` | Total number of lines in the active file |
| `get_encoding` | Character encoding of the active file |
| `get_setting` | A ST setting by key. `scope='view'` (default) or `'window'` |
| `get_layout` | Current window layout (groups, cells) and which files are in each group |

### Navigate

| Tool | Description |
|------|-------------|
| `open_file` | Open a file, optionally jumping to a specific line and column |
| `goto_line` | Move cursor to line (and optional column) in the active file |
| `show_panel` | Bring an output panel to the front. Default `name='exec'` for the build panel |
| `focus_group` | Move focus to a pane group by 0-based index |

### Edit

| Tool | Description |
|------|-------------|
| `str_replace_based_edit_tool` | ST-native editor: `str_replace`, `insert`, `create`, `view`. Full undo, gutter diff, 30s highlight |
| `replace_selection` | Replace the current selection(s) with text |
| `replace_lines` | Replace lines begin..end (inclusive, 1-based) in the active file |
| `insert_snippet` | Insert at the cursor using ST snippet syntax |
| `duplicate_line` | Duplicate the current line(s) |
| `toggle_comment` | Toggle line comment, or block comment if `block=True` |
| `sort_lines` | Sort selected lines, or all lines if nothing is selected |
| `select_lines` | Select lines begin..end (1-based, inclusive) |
| `fold_lines` | Fold (collapse) lines begin..end in the active file |
| `undo` | Undo the last edit |
| `redo` | Redo the last undone edit |
| `run_command` | Run any ST command with optional args |

### Search

| Tool | Description |
|------|-------------|
| `find_in_file` | Find all occurrences of a pattern in the active file |
| `find_in_files` | Search across project folders. Skips `.git`, `__pycache__`, `node_modules`, `.venv` |

### File / Project

| Tool | Description |
|------|-------------|
| `save_file` | Save the active file (or a specific file by path) |
| `save_all` | Save all open files |
| `close_file` | Close a file by path, or the active file if path is omitted |
| `revert_file` | Revert the active file to its last saved state |
| `add_folder` | Add a folder to the current project |
| `remove_folder` | Remove a folder from the current project by path |

### Syntax / Encoding

| Tool | Description |
|------|-------------|
| `set_syntax` | Set the syntax of the active file by name (case-insensitive partial match) |
| `set_encoding` | Set the character encoding of the active file |

### Settings / Window

| Tool | Description |
|------|-------------|
| `set_setting` | Set a ST setting by key |
| `toggle_sidebar` | Show or hide the sidebar |
| `set_layout` | Set the window pane layout |
| `set_status` | Write a message to ST's status bar |

### Build

| Tool | Description |
|------|-------------|
| `run_build` | Trigger the current build system, or pass `cmd`/`shell_cmd` for a custom command |

### Terminus Integration

[Terminus](https://github.com/randy3k/Terminus) is a popular ST terminal package.
`send_to_view` is Terminus-aware: when targeting a Terminus tab it uses
`terminus_send_string` to type text into the terminal session.

| Tool | Description |
|------|-------------|
| `send_to_view` | Send text to any open tab. For Terminus tabs, types as if the user typed it. Include `\n` to execute |

### Scripting

| Tool | Description |
|------|-------------|
| `eval_python` | Execute arbitrary Python in ST's main thread. Returns captured stdout in `output` |
| `eval_python_latest` | Execute Python in the system interpreter outside ST's sandbox |
| `get_console_log` | Recent ST console output. `tail=N` limits to last N entries |
| `get_console_full` | Entire captured ST console buffer since startup |

## Configuration

### Ports

| Server | Windows | Mac/Linux | Env var override |
|--------|---------|-----------|-----------------|
| MCP SSE | 9502 | 9503 | `SUBLIME_MCP_MCP_PORT` |
| HTTP bridge | 9500 | 9501 | `SUBLIME_MCP_PORT` |

### Telling Claude how to use the tools

Add a section like this to your project's `CLAUDE.md` (or `~/.claude/CLAUDE.md`):

```markdown
## Sublime Text MCP tools

MCP Commander is connected. Prefer it over standard file tools when working in ST:

- Read files with `get_active_file` or `get_file_content` rather than the Read tool
- Edit with `str_replace_based_edit_tool` — edits appear live with gutter diff and undo
- Use `find_in_files` for project-wide search
- Use `send_to_view` to run commands in a Terminus terminal tab
- Use `eval_python` for one-off ST scripting (no plugin file needed)
- Check `get_console_log` when a plugin isn't behaving as expected

Tab indexing: `get_sheets()` returns 0-based indexes; users refer to tabs
1-based. Always call `get_sheets()` first when targeting a specific tab.
```

## Security note

Both servers bind to `127.0.0.1` only and accept any request without
authentication. Do not expose these ports to a network interface.

## Requirements

- Sublime Text 4
- Terminus package (optional — only required for `send_to_view` on terminal tabs)

## Known limitations

- **No multi-window support** — tools target the most recently focused ST window
- **No image editing** — `get_sheet_content` returns the path for image tabs, not pixel data
- **No ST3 support** — the plugin uses ST4 APIs throughout

## Testing

The test suite requires Sublime Text to be running with `sublime_mcp.py` loaded.

```
cd /path/to/sublime-mcp
pip install httpx pytest
pytest tests/ -v
```

## Contributing

**Adding a tool:**
1. Add a handler function in `sublime_mcp.py` (run via `_on_main` for ST API calls)
2. Add an entry to `_MCP_TOOLS` and the `_GET` / `_POST` routing dicts
3. Add a row to the Tools table in `README.md`

**Good first issues:**
- Multi-window support (`sublime.windows()` instead of `sublime.active_window()`)
- `get_diagnostics` — expose LSP error/warning annotations
- `set_bookmark` / `clear_bookmarks` — write counterparts to `get_bookmarks`

Open an issue or PR on [GitHub](https://github.com/dpc00/sublime-mcp).