sublime-mcp 1.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Donald Chitester
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,405 @@
+# sublime-mcp
+
+<!-- mcp-name: io.github.dpc00/sublime-mcp -->
+
+The most complete Sublime Text / AI integration available. sublime-mcp lets
+Claude Code (or any MCP client) do anything in ST that a human can do from the
+keyboard — read files, navigate, edit with full undo history, search across the
+project, run builds, send commands to a Terminus terminal, evaluate arbitrary
+Python in ST's main thread, and more. If you use ST as your primary editor,
+this closes the gap between "AI that edits files" and "AI that works in your
+editor."
+
+63 tools covering reading, navigation, editing, searching, build, Terminus
+integration, settings, layout, menus, console log, and live Python scripting.
+
+## Architecture
+
+```
+Claude Code (MCP client)
+        │  stdio / MCP protocol
+        ▼
+  mcp_server.py          ← Python process you run outside ST
+        │  HTTP  127.0.0.1:9500
+        ▼
+  sublime_mcp.py         ← ST plugin, HTTP server on ST's main thread
+        │  sublime API
+        ▼
+  Sublime Text 4
+```
+
+| File | Role |
+|------|------|
+| `sublime_mcp.py` | ST plugin — runs an HTTP server inside Sublime Text |
+| `mcp_server.py` | MCP server — wraps the HTTP API for MCP clients |
+
+## Installation
+
+### 1. Install the ST plugin via Package Control
+
+1. Open the Command Palette (`Ctrl+Shift+P`)
+2. Run **Package Control: Install Package**
+3. Search for **sublime-mcp** and install
+
+ST loads it automatically. You should see:
+
+```
+sublime-mcp: listening on 127.0.0.1:9500
+```
+
+in the ST console (`View › Show Console`).
+
+> **Manual install (alternative):** copy `sublime_mcp.py` and `sublime_mcp_browse.py`
+> from the repo into your `Packages/User/` folder.
+
+### 2. Install the MCP server
+
+```
+pip install sublime-mcp
+```
+
+### 3. Register with Claude Code
+
+Add to `~/.claude/mcp.json` (or `~/.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "sublime-mcp": {
+      "command": "sublime-mcp"
+    }
+  }
+}
+```
+
+Then restart Claude Code. Tools will appear with the `mcp__sublime-mcp__` prefix.
+
+## Windows + WSL setup
+
+If you run Sublime Text on **both** Windows and WSL, you can give Claude Code
+in each environment its own MCP entry pointing at the local ST instance, plus
+an optional cross-side entry for the other one.
+
+**Requirements:** WSL2 with [mirrored networking](https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking)
+(Windows 11 default). This makes `127.0.0.1` on the WSL side reach Windows
+ports, and vice versa.
+
+### How it works
+
+| ST instance | Port | Reached from |
+|---|---|---|
+| Windows ST | `9500` | Windows `127.0.0.1:9500` or WSL `127.0.0.1:9500` (mirrored) |
+| WSL ST | `9501` | WSL `127.0.0.1:9501` |
+
+Each ST instance runs its own copy of `sublime_mcp.py` on its own port. The
+MCP server process always runs on the same side as Claude Code — it just points
+at the right port via `SUBLIME_MCP_BASE`.
+
+### Step 1 — Install the plugin in both ST instances
+
+Install via Package Control in each ST instance (Windows and WSL ST separately).
+
+**WSL ST** — after installing, edit the port in the installed plugin:
+
+```
+~/.config/sublime-text/Packages/sublime-mcp/sublime_mcp.py
+```
+
+```python
+_PORT = 9501   # line 22 of sublime_mcp.py
+```
+
+### Step 2 — Install the MCP server on both sides
+
+**Windows:**
+```
+pip install sublime-mcp
+```
+
+**WSL:**
+```
+pip3 install sublime-mcp
+```
+
+### Step 3 — Windows `~/.claude/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "sublime-mcp": {
+      "command": "sublime-mcp"
+    },
+    "sublime-mcp-wsl": {
+      "command": "wsl",
+      "args": ["sublime-mcp"],
+      "env": { "SUBLIME_MCP_BASE": "http://127.0.0.1:9501" }
+    }
+  }
+}
+```
+
+- `sublime-mcp` runs as a Windows process → auto-detects port `9500` → Windows ST
+- `sublime-mcp-wsl` runs inside WSL via the `wsl` command → `127.0.0.1:9501` is WSL's loopback → WSL ST
+
+### Step 4 — WSL `~/.claude/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "sublime-mcp": {
+      "command": "sublime-mcp",
+      "env": { "SUBLIME_MCP_BASE": "http://127.0.0.1:9501" }
+    },
+    "sublime-mcp-win": {
+      "command": "sublime-mcp",
+      "env": { "SUBLIME_MCP_BASE": "http://127.0.0.1:9500" }
+    }
+  }
+}
+```
+
+- `sublime-mcp` runs in WSL → `127.0.0.1:9501` → WSL ST
+- `sublime-mcp-win` runs in WSL → `127.0.0.1:9500` reaches Windows ST via mirrored networking
+
+### Tool prefixes
+
+| Claude Code session | Tool prefix for WSL ST | Tool prefix for Windows ST |
+|---|---|---|
+| Windows | `mcp__sublime-mcp-wsl__` | `mcp__sublime-mcp__` |
+| WSL | `mcp__sublime-mcp__` | `mcp__sublime-mcp-win__` |
+
+## 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
+- User **tab 3** = index 2
+- etc.
+
+When closing or targeting a specific tab, always verify the index by calling `get_sheets()` 
+first, and close by path (preferred) or by focusing then closing the active file. 
+**Never change focus without user awareness.**
+
+## 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. Returns index, type, path, name, is_dirty |
+| `get_sheet_content` | Content of any tab by sheet index (from `get_sheets`). Works for text, untitled, and Terminus tabs; returns path only for image tabs |
+| `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). Works for Terminus tabs and nameless views |
+| `get_view_size` | Total character count of any open tab. Use to compute offsets before `get_view_chars` |
+| `get_view_chars` | Text at character offsets begin..end (0-based, end exclusive). Clamps to buffer bounds |
+| `get_view_phantoms` | Phantom HTML and extracted plain text from a named view; filters by phantom key |
+| `get_output_panel` | Text content of a named output panel. Omit name for the active 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; filterable by package, command, or caption |
+| `get_commands` | Runnable command ids from loaded command classes, optionally merged with palette metadata |
+| `get_menu_items` | Menu items from `*.sublime-menu` resources; filterable by menu filename, caption, or command |
+| `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` (unique match), `insert` (after line N), `create` (new file), `view` (numbered content). Full undo, gutter diff, 30s highlight. Auto-opens file if needed |
+| `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 (`$1` for tab stops, etc.) |
+| `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. `scope='window'` (default) or `'view'` |
+
+### Search
+
+| Tool | Description |
+|------|-------------|
+| `find_in_file` | Find all occurrences of a pattern in the active file. Returns `{line, col, text}` list |
+| `find_in_files` | Search across project folders (or a supplied list). Skips `.git`, `__pycache__`, `node_modules`, `.venv`. Returns `{path, line, match}` list, capped at `max_results` (default 200) |
+
+### File / Project
+
+| Tool | Description |
+|------|-------------|
+| `save_file` | Save the active file |
+| `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 (no-op if already present) |
+| `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 (e.g. `'UTF-8'`, `'Western (Windows 1252)'`) |
+
+### Settings / Window
+
+| Tool | Description |
+|------|-------------|
+| `set_setting` | Set a ST setting by key. `scope='view'` (default) or `'window'` |
+| `toggle_sidebar` | Show or hide the sidebar |
+| `set_layout` | Set the window pane layout. Accepts a ST layout dict with `cols`, `rows`, `cells` |
+| `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` + `working_dir` 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 rather than
+inserting into a buffer.
+
+| Tool | Description |
+|------|-------------|
+| `send_to_view` | Send a string to any open tab by name. For Terminus tabs, types the text as if the user typed it. Include a trailing `\n` to execute a command |
+
+### Scripting
+
+| Tool | Description |
+|------|-------------|
+| `eval_python` | Execute arbitrary Python in ST's main thread. Locals available: `sublime`, `window`, `view`, `print`. Returns captured stdout in `output` |
+| `get_console_log` | Recent ST console output (plugin log messages and stdout). `tail=N` limits to last N entries; `tail=0` returns all |
+
+## Configuration
+
+### Port
+
+The plugin listens on `9500` by default. The MCP server auto-detects the port:
+- Windows → `9500`
+- WSL / Linux → `9501`
+
+Override with the `SUBLIME_MCP_BASE` environment variable:
+
+```json
+{
+  "mcpServers": {
+    "sublime-mcp": {
+      "command": "sublime-mcp",
+      "env": { "SUBLIME_MCP_BASE": "http://127.0.0.1:9500" }
+    }
+  }
+}
+```
+
+To change the plugin's port, edit `_PORT` near the top of `sublime_mcp.py` in your ST `Packages/sublime-mcp/` folder.
+
+### Timeout
+
+The MCP server waits up to 10 seconds for each HTTP response. Edit `TIMEOUT` in
+`mcp_server.py` if you need longer (e.g. for slow `eval_python` calls).
+
+## Security note
+
+The HTTP server binds to `127.0.0.1` only and accepts any request without
+authentication. Do not expose port 9500 to a network interface.
+
+## Requirements
+
+- Sublime Text 4
+- Python 3.10+ (for the MCP server process)
+- `pip install mcp httpx`
+- Terminus package (optional, required only for `send_to_view` on terminal tabs)
+
+## Getting Claude to use the tools well
+
+Add a section like this to your project's `CLAUDE.md` (or `~/.claude/CLAUDE.md`
+for global use):
+
+```markdown
+## Sublime Text MCP tools
+
+sublime-mcp is connected. Prefer it over standard file tools when working in ST:
+
+- Read files with `get_active_file` or `get_file_content` rather than 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.
+```
+
+## Known limitations / Roadmap
+
+- **No multi-window support** — tools target the most recently focused ST window only
+- **No image editing** — `get_sheet_content` returns the path for image tabs, not pixel data
+- **Terminus dependency is optional** — `send_to_view` degrades gracefully if Terminus isn't installed, but terminal interaction requires it
+- **No ST3 support** — the plugin uses ST4 APIs throughout
+
+Contributions welcome in any of these areas. See below.
+
+## Testing
+
+The test suite requires Sublime Text to be running with `sublime_mcp.py` loaded.
+
+```
+cd C:\Users\donal\projects\sublime-mcp
+pip install httpx pytest
+pytest tests/test_http_api.py -v
+```
+
+111 tests covering all 60 HTTP API endpoints. Expected result: 109 passed, 2 skipped
+(the skips are environment-dependent: one requires an open saved file, one requires
+a Terminus tab). Zero failures on a clean ST session.
+
+## Contributing
+
+The project has two independent pieces — the ST plugin (`sublime_mcp.py`) and
+the MCP server (`mcp_server.py`) — which makes it easy to contribute to either
+without touching the other.
+
+**Adding a tool:**
+1. Add an HTTP handler in `sublime_mcp.py` (runs on ST's main thread via `_on_main`)
+2. Add the corresponding `@mcp.tool()` function in `mcp_server.py`
+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`
+- Any gap identified in the [JetBrains MCP feature set](https://github.com/JetBrains/mcp-jetbrains)
+
+Open an issue or PR on [GitHub](https://github.com/dpc00/sublime-mcp).

package/index.js

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const port = process.platform === 'win32' ? 9500 : 9501;
+const BASE = process.env.SUBLIME_MCP_BASE ?? `http://127.0.0.1:${port}`;
+const TIMEOUT = 10_000;
+
+process.stderr.write(`mcp-commander: BASE=${BASE} platform=${process.platform}\n`);
+
+async function get(endpoint, params = {}) {
+  const url = new URL(endpoint, BASE);
+  for (const [k, v] of Object.entries(params)) {
+    url.searchParams.set(k, String(v));
+  }
+  const r = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT) });
+  if (!r.ok) throw new Error(`HTTP ${r.status} from ${endpoint}`);
+  return r.json();
+}
+
+async function post(endpoint, body = {}) {
+  const r = await fetch(new URL(endpoint, BASE), {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(TIMEOUT),
+  });
+  if (!r.ok) throw new Error(`HTTP ${r.status} from ${endpoint}`);
+  return r.json();
+}
+
+function ok(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+}
+
+const server = new McpServer({ name: 'sublime-mcp', version: '1.2.4' });
+
+// ── no-parameter passthrough tools ────────────────────────────────────────────
+
+const PASSTHROUGH = [
+  ['get_active_file', 'GET', '/active_file', "Return the active file's path, full content, cursor line/col, dirty flag, and syntax name."],
+  ['get_selection', 'GET', '/selection', 'Return the current selection(s): text and begin/end line+col for each.'],
+  ['get_open_files', 'GET', '/open_files', 'List all files open in the current window (path, name, is_dirty).'],
+  ['get_sheets', 'GET', '/sheets', 'List ALL sheets (tabs) in the current window by index, including images and untitled buffers.\nReturns index, type (TextSheet/ImageSheet), path, name, is_dirty for each.\nUse index with get_sheet_content to read a specific tab.'],
+  ['get_project_folders', 'GET', '/project_folders', "Return the project's root folder paths."],
+  ['get_symbols', 'GET', '/symbols', 'Return all symbols (functions, classes, etc.) in the active file with line numbers.'],
+  ['get_project_data', 'GET', '/project_data', 'Return the raw .sublime-project JSON data for the current project.'],
+  ['get_variables', 'GET', '/variables', "Return Sublime Text's build variables: $file, $project_path, $platform, etc."],
+  ['get_active_panel', 'GET', '/active_panel', 'Return the active panel id and, if it is an output panel, its content.'],
+  ['get_syntaxes', 'GET', '/syntaxes', 'List all syntax definitions available in Sublime Text (name + path).'],
+  ['get_encoding', 'GET', '/encoding', 'Return the character encoding of the active file.'],
+  ['get_scope_at_cursor', 'GET', '/scope_at_cursor', 'Return the full syntax scope string at the cursor position.'],
+  ['get_word_at_cursor', 'GET', '/word_at_cursor', 'Return the word under the cursor and its line/col.'],
+  ['get_bookmarks', 'GET', '/bookmarks', 'Return all bookmarked positions in the active file.'],
+  ['get_line_count', 'GET', '/line_count', 'Return the total number of lines in the active file.'],
+  ['get_layout', 'GET', '/layout', 'Return the current window layout (groups, cells) and which files are in each group.'],
+  ['save_all', 'POST', '/save_all', 'Save all open files.'],
+  ['revert_file', 'POST', '/revert_file', 'Revert the active file to its last saved state, discarding unsaved changes.'],
+  ['undo', 'POST', '/undo', 'Undo the last edit in the active file.'],
+  ['redo', 'POST', '/redo', 'Redo the last undone edit in the active file.'],
+  ['duplicate_line', 'POST', '/duplicate_line', 'Duplicate the current line(s) in the active file.'],
+  ['toggle_sidebar', 'POST', '/toggle_sidebar', 'Show or hide the Sublime Text sidebar.'],
+];
+
+for (const [name, method, endpoint, description] of PASSTHROUGH) {
+  server.registerTool(name, { description }, async () =>
+    ok(await (method === 'GET' ? get(endpoint) : post(endpoint)))
+  );
+}
+
+// ── parameterised tools ───────────────────────────────────────────────────────
+
+server.registerTool('get_cursor_context', {
+  description: 'Return `lines` lines above and below the cursor with 1-based line numbers prepended.',
+  inputSchema: { lines: z.number().int().default(10) },
+}, async ({ lines }) => ok(await get('/cursor_context', { lines })));
+
+server.registerTool('get_sheet_content', {
+  description: 'Return the content of any tab by its sheet index (from get_sheets).\nWorks for text tabs including untitled buffers and Terminus tabs.\nFor image tabs returns the file path only.',
+  inputSchema: { index: z.number().int() },
+}, async ({ index }) => ok(await get('/sheet_content', { index })));
+
+server.registerTool('get_file_content', {
+  description: 'Return the full content of an already-open file by its path.',
+  inputSchema: { path: z.string() },
+}, async ({ path }) => ok(await get('/file_content', { path })));
+
+server.registerTool('get_view_content', {
+  description: 'Return the full content of any open tab by name (partial match, case-insensitive).\nWorks for Terminus tabs and other nameless views that have no file path.\nUse index (0-based, from get_open_files) to target a tab by position instead of name.\nOmit both to read the active view.',
+  inputSchema: { name: z.string().default(''), index: z.number().int().default(-1) },
+}, async ({ name, index }) => ok(await get('/view_content', { name, index })));
+
+server.registerTool('get_view_size', {
+  description: 'Return the total character count of any open tab by name (partial match, case-insensitive).\nUse before get_view_chars to compute offsets — e.g. begin=size-5000, end=size for the tail.\nOmit name for the active view.',
+  inputSchema: { name: z.string().default('') },
+}, async ({ name }) => ok(await get('/view_size', { name })));
+
+server.registerTool('get_view_chars', {
+  description: 'Return text at character offsets begin..end (0-based, end exclusive) from any open tab.\nWorks for Terminus tabs and any other view. Clamps to buffer bounds automatically.\nUse get_view_size first, then e.g. begin=size-5000, end=size to read the last 5000 chars.\nOmit name for the active view.',
+  inputSchema: { begin: z.number().int(), end: z.number().int(), name: z.string().default('') },
+}, async ({ begin, end, name }) => ok(await get('/view_chars', { name, begin, end })));
+
+server.registerTool('get_view_phantoms', {
+  description: "Return phantom HTML and extracted text from a view by name.\nIf key is omitted, defaults to the common 'pybackup' phantom key.",
+  inputSchema: { name: z.string().default(''), key: z.string().default('') },
+}, async ({ name, key }) => ok(await get('/view_phantoms', { name, key })));
+
+server.registerTool('get_output_panel', {
+  description: "Return the text content of an output panel.\nIf name is omitted, read the active output panel. Use name='exec' for build output.",
+  inputSchema: { name: z.string().default('') },
+}, async ({ name }) => ok(await get('/output_panel', { name })));
+
+server.registerTool('lookup_symbol', {
+  description: 'Find where a symbol is defined across all open files.',
+  inputSchema: { symbol: z.string() },
+}, async ({ symbol }) => ok(await get('/lookup_symbol', { symbol })));
+
+server.registerTool('add_folder', {
+  description: 'Add a folder to the current project.',
+  inputSchema: { path: z.string() },
+}, async ({ path }) => {
+  const data = (await get('/project_data')).project_data ?? {};
+  const folders = data.folders ?? [];
+  if (folders.some(f => f.path === path)) return ok({ ok: true, note: 'already present' });
+  folders.push({ path });
+  data.folders = folders;
+  return ok(await post('/set_project_data', { data }));
+});
+
+server.registerTool('remove_folder', {
+  description: 'Remove a folder from the current project by path.',
+  inputSchema: { path: z.string() },
+}, async ({ path }) => {
+  const data = (await get('/project_data')).project_data ?? {};
+  const folders = data.folders ?? [];
+  const newFolders = folders.filter(f => f.path !== path);
+  if (newFolders.length === folders.length) return ok({ ok: false, note: 'folder not found' });
+  data.folders = newFolders;
+  return ok(await post('/set_project_data', { data }));
+});
+
+server.registerTool('send_to_view', {
+  description: 'Send a string to any open tab by name (partial match, case-insensitive).\nFor Terminus tabs this types the text into the terminal as if the user typed it.\nInclude a trailing newline (\\n) to execute a command.\nUse index (0-based, from get_open_files) to target a tab by position instead of name.\nOmit both name and index to target the active view.',
+  inputSchema: { text: z.string(), name: z.string().default(''), index: z.number().int().default(-1) },
+}, async ({ text, name, index }) => ok(await post('/send_to_view', { text, name, index })));
+
+server.registerTool('open_file', {
+  description: 'Open a file in Sublime Text, optionally jumping to a specific line and column.',
+  inputSchema: { path: z.string(), line: z.number().int().default(0), col: z.number().int().default(0) },
+}, async ({ path, line, col }) => ok(await post('/open_file', { path, line, col })));
+
+server.registerTool('goto_line', {
+  description: 'Move the cursor to a line (and optional column) in the active file.',
+  inputSchema: { line: z.number().int(), col: z.number().int().default(1) },
+}, async ({ line, col }) => ok(await post('/goto_line', { line, col })));
+
+server.registerTool('show_panel', {
+  description: "Bring an output panel to the front. Use name='exec' for the build panel.",
+  inputSchema: { name: z.string().default('exec') },
+}, async ({ name }) => ok(await post('/show_panel', { name })));
+
+server.registerTool('replace_selection', {
+  description: 'Replace the current selection(s) with text.',
+  inputSchema: { text: z.string() },
+}, async ({ text }) => ok(await post('/replace_selection', { text })));
+
+server.registerTool('replace_lines', {
+  description: 'Replace lines begin through end (inclusive, 1-based) in the active file with text.\nPass path to target a specific open file regardless of which tab is focused.\nUse index (0-based, from get_open_files) to target a nameless tab by position.',
+  inputSchema: {
+    begin: z.number().int(),
+    end: z.number().int(),
+    text: z.string(),
+    path: z.string().default(''),
+    index: z.number().int().default(-1),
+  },
+}, async ({ begin, end, text, path, index }) =>
+  ok(await post('/replace_lines', { begin, end, text, path, index })));
+
+server.registerTool('run_command', {
+  description: "Run any Sublime Text command. scope='window' (default) or 'view'.",
+  inputSchema: {
+    command: z.string(),
+    args: z.record(z.unknown()).optional(),
+    scope: z.string().default('window'),
+  },
+}, async ({ command, args, scope }) =>
+  ok(await post('/run_command', { command, args: args ?? {}, scope })));
+
+server.registerTool('run_build', {
+  description: 'Trigger the current build system, or pass cmd/shell_cmd to run a specific command.',
+  inputSchema: {
+    cmd: z.array(z.string()).optional(),
+    shell_cmd: z.string().optional(),
+    working_dir: z.string().default(''),
+  },
+}, async ({ cmd, shell_cmd, working_dir }) => {
+  const body = {};
+  if (cmd) body.cmd = cmd;
+  if (shell_cmd) body.shell_cmd = shell_cmd;
+  if (working_dir) body.working_dir = working_dir;
+  return ok(await post('/run_build', body));
+});
+
+server.registerTool('set_status', {
+  description: "Write a message to Sublime Text's status bar.",
+  inputSchema: { value: z.string(), key: z.string().default('sublime_mcp') },
+}, async ({ value, key }) => ok(await post('/set_status', { key, value })));
+
+server.registerTool('save_file', {
+  description: 'Save a file. Pass path to save a specific open file; omit path to save the active file.',
+  inputSchema: { path: z.string().default('') },
+}, async ({ path }) => ok(await post('/save_file', path ? { path } : {})));
+
+server.registerTool('close_file', {
+  description: 'Close a file by path, or close the active file if path is omitted.',
+  inputSchema: { path: z.string().default('') },
+}, async ({ path }) => ok(await post('/close_file', { path })));
+
+server.registerTool('toggle_comment', {
+  description: 'Toggle line comment (or block comment if block=true) on the current selection.',
+  inputSchema: { block: z.boolean().default(false) },
+}, async ({ block }) => ok(await post('/toggle_comment', { block })));
+
+server.registerTool('sort_lines', {
+  description: 'Sort the selected lines (or all lines if nothing is selected).',
+  inputSchema: { case_sensitive: z.boolean().default(false) },
+}, async ({ case_sensitive }) => ok(await post('/sort_lines', { case_sensitive })));
+
+server.registerTool('select_lines', {
+  description: 'Select lines begin through end (1-based, inclusive). end defaults to begin.',
+  inputSchema: { begin: z.number().int(), end: z.number().int().default(0) },
+}, async ({ begin, end }) => ok(await post('/select_lines', { begin, end: end || begin })));
+
+server.registerTool('fold_lines', {
+  description: 'Fold (collapse) lines begin through end (1-based) in the active file.',
+  inputSchema: { begin: z.number().int(), end: z.number().int() },
+}, async ({ begin, end }) => ok(await post('/fold_lines', { begin, end })));
+
+server.registerTool('insert_snippet', {
+  description: "Insert a snippet at the cursor using Sublime Text's snippet syntax (e.g. $1 for tab stops).",
+  inputSchema: { contents: z.string() },
+}, async ({ contents }) => ok(await post('/insert_snippet', { contents })));
+
+server.registerTool('find_in_file', {
+  description: 'Find all occurrences of pattern in the active file. Returns list of {line, col, text}.',
+  inputSchema: {
+    pattern: z.string(),
+    case_sensitive: z.boolean().default(false),
+    regex: z.boolean().default(false),
+  },
+}, async ({ pattern, case_sensitive, regex }) =>
+  ok(await post('/find_in_file', { pattern, case_sensitive, regex })));
+
+server.registerTool('find_in_files', {
+  description: 'Search for pattern across project folders (or the supplied folder list).\nSkips .git, __pycache__, node_modules, .venv. Returns list of {path, line, match}.',
+  inputSchema: {
+    pattern: z.string(),
+    folders: z.array(z.string()).optional(),
+    case_sensitive: z.boolean().default(false),
+    regex: z.boolean().default(false),
+    max_results: z.number().int().default(200),
+  },
+}, async ({ pattern, folders, case_sensitive, regex, max_results }) => {
+  const body = { pattern, case_sensitive, regex, max_results };
+  if (folders) body.folders = folders;
+  return ok(await post('/find_in_files', body));
+});
+
+server.registerTool('get_command_palette', {
+  description: 'List Command Palette entries from installed *.sublime-commands resources.\nOptional filters: package, command id, or caption substring.',
+  inputSchema: {
+    package: z.string().default(''),
+    command: z.string().default(''),
+    caption: z.string().default(''),
+  },
+}, async ({ package: pkg, command, caption }) =>
+  ok(await get('/command_palette', { package: pkg, command, caption })));
+
+server.registerTool('get_commands', {
+  description: 'List runnable Sublime command ids from loaded command classes, optionally enriched\nwith matching Command Palette entries from installed packages.',
+  inputSchema: {
+    package: z.string().default(''),
+    command: z.string().default(''),
+    include_palette: z.boolean().default(true),
+  },
+}, async ({ package: pkg, command, include_palette }) =>
+  ok(await get('/commands', { package: pkg, command, include_palette: String(include_palette) })));
+
+server.registerTool('get_menu_items', {
+  description: 'List installed menu items from *.sublime-menu resources.\nOptional filters: menu filename, caption substring, or command id substring.',
+  inputSchema: {
+    menu: z.string().default(''),
+    caption: z.string().default(''),
+    command: z.string().default(''),
+  },
+}, async ({ menu, caption, command }) =>
+  ok(await get('/menu_items', { menu, caption, command })));
+
+server.registerTool('set_syntax', {
+  description: 'Set the syntax of the active file by name (case-insensitive partial match is fine).',
+  inputSchema: { name: z.string() },
+}, async ({ name }) => ok(await post('/set_syntax', { name })));
+
+server.registerTool('set_encoding', {
+  description: "Set the character encoding of the active file (e.g. 'UTF-8', 'Western (Windows 1252)').",
+  inputSchema: { encoding: z.string() },
+}, async ({ encoding }) => ok(await post('/set_encoding', { encoding })));
+
+server.registerTool('get_setting', {
+  description: "Get a Sublime Text setting by key. scope='view' (default) or 'window'.",
+  inputSchema: { key: z.string(), scope: z.string().default('view') },
+}, async ({ key, scope }) => ok(await post('/get_setting', { key, scope })));
+
+server.registerTool('set_setting', {
+  description: "Set a Sublime Text setting by key. scope='view' (default) or 'window'.",
+  inputSchema: { key: z.string(), value: z.unknown(), scope: z.string().default('view') },
+}, async ({ key, value, scope }) => ok(await post('/set_setting', { key, value, scope })));
+
+server.registerTool('focus_group', {
+  description: 'Move focus to a pane group by 0-based index.',
+  inputSchema: { group: z.number().int() },
+}, async ({ group }) => ok(await post('/focus_group', { group })));
+
+server.registerTool('set_layout', {
+  description: 'Set the window pane layout. layout must be a ST layout dict with cols, rows, cells keys.',
+  inputSchema: { layout: z.record(z.unknown()) },
+}, async ({ layout }) => ok(await post('/set_layout', { layout })));
+
+server.registerTool('str_replace_based_edit_tool', {
+  description: `ST-native file editor implementing the standard str_replace_based_edit_tool interface.
+Edits appear live in Sublime Text with full undo (Ctrl+Z), gutter diff markers,
+and 30-second highlight annotations showing what changed.
+
+command='str_replace': replace old_str with new_str in path.
+  old_str must match exactly once (whitespace-sensitive).
+  Returns error if 0 or 2+ matches, listing ambiguous line numbers.
+
+command='insert': insert insert_text after line insert_line (1-based).
+  insert_line=0 inserts at the very start of the file.
+
+command='create': create a new file at path with file_text content.
+  Syntax is auto-detected from the file extension. Errors if path exists.
+
+command='view': return file content with 1-based line numbers prepended.
+  Optional view_range=[start, end] to read a slice (end=-1 for EOF).
+
+All commands auto-open the file in ST if not already open.`,
+  inputSchema: {
+    command: z.string(),
+    path: z.string().default(''),
+    old_str: z.string().optional(),
+    new_str: z.string().optional(),
+    insert_line: z.number().int().optional(),
+    insert_text: z.string().optional(),
+    file_text: z.string().optional(),
+    view_range: z.array(z.number().int()).length(2).optional(),
+  },
+}, async ({ command, path, old_str, new_str, insert_line, insert_text, file_text, view_range }) => {
+  const body = { command, path };
+  if (old_str !== undefined) body.old_str = old_str;
+  if (new_str !== undefined) body.new_str = new_str;
+  if (insert_line !== undefined) body.insert_line = insert_line;
+  if (insert_text !== undefined) body.insert_text = insert_text;
+  if (file_text !== undefined) body.file_text = file_text;
+  if (view_range !== undefined) body.view_range = view_range;
+  return ok(await post('/edit_file', body));
+});
+
+server.registerTool('eval_python', {
+  description: "Execute arbitrary Python in Sublime Text's main thread.\nLocals: sublime, window, view, print. Returns captured stdout in 'output'.",
+  inputSchema: { code: z.string() },
+}, async ({ code }) => ok(await post('/eval_python', { code })));
+
+server.registerTool('get_console_log', {
+  description: 'Return recent Sublime Text console output (plugin log messages and stdout).\ntail=N limits to the last N entries. tail=0 returns all captured entries.',
+  inputSchema: { tail: z.number().int().default(100) },
+}, async ({ tail }) => ok(await get('/console_log', { tail })));
+
+server.registerTool('get_console_full', {
+  description: 'Capture the FULL Sublime Text Python console (entire session history) by simulating Ctrl+A, Ctrl+C in the console output panel and reading the clipboard.\nReturns the complete text including startup messages, plugin load events, and all errors.\nNote: briefly takes keyboard focus from ST to perform the macro.',
+  inputSchema: {},
+}, async () => ok(await get('/console_full')));
+
+server.registerTool('eval_python_latest', {
+  description: "Execute Python code using the system Python 3.12 interpreter (via 'py -3.12') outside Sublime Text's embedded Python 3.8 sandbox.\nUseful for code that requires Python 3.9+ syntax, newer stdlib features, or third-party packages not available in ST.\nReturns stdout, stderr, and returncode.",
+  inputSchema: { code: z.string() },
+}, async ({ code }) => ok(await post('/eval_python_latest', { code })));
+
+// ── startup ───────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "sublime-mcp",
+  "version": "1.2.4",
+  "description": "MCP server for Sublime Text 4 — exposes editor state and editing tools to AI assistants via the Model Context Protocol.",
+  "type": "module",
+  "bin": {
+    "sublime-mcp": "./index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dpc00/sublime-mcp.git"
+  },
+  "keywords": ["sublime-text", "mcp", "ai", "claude"],
+  "author": "Donald Chitester",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dpc00/sublime-mcp/issues"
+  },
+  "homepage": "https://github.com/dpc00/sublime-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}