sublime-mcp 1.0.0__tar.gz

sublime_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: sublime-mcp
+Version: 1.0.0
+Summary: MCP server for Sublime Text 4 — lets Claude Code read and control a running ST instance
+Author-email: Donald Chitester <donaldchitester@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dpc00/sublime-mcp
+Project-URL: Repository, https://github.com/dpc00/sublime-mcp
+Keywords: mcp,sublime-text,claude,ai,editor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Editors
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp
+Requires-Dist: httpx
+
+# sublime-mcp
+
+<!-- mcp-name: io.github.dpc00/sublime-mcp -->
+
+
+MCP server for Sublime Text 4. Lets Claude Code (or any MCP client) read and
+control a running ST instance via a local HTTP bridge.
+
+58 tools covering reading, navigation, editing, searching, build, Terminus
+integration, settings, layout, 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
+
+Copy `sublime_mcp.py` to your Sublime Text `Packages/User/` folder:
+
+```
+%APPDATA%\Sublime Text\Packages\User\sublime_mcp.py
+```
+
+ST loads it automatically on start (or via `Tools › Developer › New Plugin…`
+then save over it). You should see:
+
+```
+sublime-mcp: listening on 127.0.0.1:9500
+```
+
+in the ST console (`View › Show Console`).
+
+### 2. Install the MCP server
+
+```
+pip install sublime-mcp
+```
+
+### 3. Register with Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "sublime": {
+      "command": "sublime-mcp"
+    }
+  }
+}
+```
+
+Then restart Claude Code. Tools will appear with the `mcp__sublime__` prefix.
+
+Then restart Claude Code. Tools will appear with the `mcp__sublime__` prefix.
+
+## 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_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 |
+|------|-------------|
+| `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` |
+
+## Configuration
+
+### Port
+
+Default is `9500`. To change it, edit `_PORT` in `sublime_mcp.py` and `BASE` in `mcp_server.py`.
+
+### 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)

sublime_mcp-1.0.0/README.md

@@ -0,0 +1,212 @@
+# sublime-mcp
+
+<!-- mcp-name: io.github.dpc00/sublime-mcp -->
+
+
+MCP server for Sublime Text 4. Lets Claude Code (or any MCP client) read and
+control a running ST instance via a local HTTP bridge.
+
+58 tools covering reading, navigation, editing, searching, build, Terminus
+integration, settings, layout, 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
+
+Copy `sublime_mcp.py` to your Sublime Text `Packages/User/` folder:
+
+```
+%APPDATA%\Sublime Text\Packages\User\sublime_mcp.py
+```
+
+ST loads it automatically on start (or via `Tools › Developer › New Plugin…`
+then save over it). You should see:
+
+```
+sublime-mcp: listening on 127.0.0.1:9500
+```
+
+in the ST console (`View › Show Console`).
+
+### 2. Install the MCP server
+
+```
+pip install sublime-mcp
+```
+
+### 3. Register with Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "sublime": {
+      "command": "sublime-mcp"
+    }
+  }
+}
+```
+
+Then restart Claude Code. Tools will appear with the `mcp__sublime__` prefix.
+
+Then restart Claude Code. Tools will appear with the `mcp__sublime__` prefix.
+
+## 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_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 |
+|------|-------------|
+| `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` |
+
+## Configuration
+
+### Port
+
+Default is `9500`. To change it, edit `_PORT` in `sublime_mcp.py` and `BASE` in `mcp_server.py`.
+
+### 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)

sublime_mcp-1.0.0/mcp_server.py

@@ -0,0 +1,495 @@
+"""sublime-mcp — MCP server.
+
+Wraps the HTTP API exposed by sublime_mcp.py (the ST plugin) and
+presents it as MCP tools to Claude Code (or any MCP client).
+
+Requirements: pip install mcp httpx
+Run:          python mcp_server.py
+Register:     add to ~/.claude/settings.json mcpServers
+"""
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+BASE = "http://127.0.0.1:9500"
+TIMEOUT = 10.0
+
+mcp = FastMCP("sublime-mcp")
+
+
+def _get(endpoint: str, **params) -> dict:
+    r = httpx.get(f"{BASE}{endpoint}", params=params, timeout=TIMEOUT)
+    r.raise_for_status()
+    return r.json()
+
+
+def _post(endpoint: str, **body) -> dict:
+    r = httpx.post(f"{BASE}{endpoint}", json=body, timeout=TIMEOUT)
+    r.raise_for_status()
+    return r.json()
+
+
+# ── read ──────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def get_active_file() -> dict:
+    """Return the active file's path, full content, cursor line/col, dirty flag, and syntax name."""
+    return _get("/active_file")
+
+
+@mcp.tool()
+def get_selection() -> dict:
+    """Return the current selection(s): text and begin/end line+col for each."""
+    return _get("/selection")
+
+
+@mcp.tool()
+def get_cursor_context(lines: int = 10) -> dict:
+    """Return `lines` lines above and below the cursor with 1-based line numbers prepended."""
+    return _get("/cursor_context", lines=lines)
+
+
+@mcp.tool()
+def get_open_files() -> dict:
+    """List all files open in the current window (path, name, is_dirty)."""
+    return _get("/open_files")
+
+
+@mcp.tool()
+def get_project_folders() -> dict:
+    """Return the project's root folder paths."""
+    return _get("/project_folders")
+
+
+@mcp.tool()
+def get_file_content(path: str) -> dict:
+    """Return the full content of an already-open file by its path."""
+    return _get("/file_content", path=path)
+
+
+@mcp.tool()
+def get_view_content(name: str = "") -> dict:
+    """Return the full content of any open tab by name (partial match, case-insensitive).
+    Works for Terminus tabs and other nameless views that have no file path.
+    Omit name to read the active view."""
+    return _get("/view_content", name=name)
+
+
+@mcp.tool()
+def get_view_size(name: str = "") -> dict:
+    """Return the total character count of any open tab by name (partial match, case-insensitive).
+    Use before get_view_chars to compute offsets — e.g. begin=size-5000, end=size for the tail.
+    Omit name for the active view."""
+    return _get("/view_size", name=name)
+
+
+@mcp.tool()
+def get_view_chars(begin: int, end: int, name: str = "") -> dict:
+    """Return text at character offsets begin..end (0-based, end exclusive) from any open tab.
+    Works for Terminus tabs and any other view.  Clamps to buffer bounds automatically.
+    Use get_view_size first, then e.g. begin=size-5000, end=size to read the last 5000 chars.
+    Omit name for the active view."""
+    return _get("/view_chars", name=name, begin=begin, end=end)
+
+
+@mcp.tool()
+def get_view_phantoms(name: str = "", key: str = "") -> dict:
+    """Return phantom HTML and extracted text from a view by name.
+    If key is omitted, defaults to the common 'pybackup' phantom key."""
+    return _get("/view_phantoms", name=name, key=key)
+
+
+@mcp.tool()
+def send_to_view(text: str, name: str = "") -> dict:
+    """Send a string to any open tab by name (partial match, case-insensitive).
+    For Terminus tabs this types the text into the terminal as if the user typed it.
+    Include a trailing newline (\\n) to execute a command.
+    Omit name to target the active view."""
+    return _post("/send_to_view", text=text, name=name)
+
+
+@mcp.tool()
+def get_output_panel(name: str = "") -> dict:
+    """Return the text content of an output panel.
+    If name is omitted, read the active output panel.  Use name='exec' for build output.
+    """
+    return _get("/output_panel", name=name)
+
+
+@mcp.tool()
+def get_symbols() -> dict:
+    """Return all symbols (functions, classes, etc.) in the active file with line numbers."""
+    return _get("/symbols")
+
+
+@mcp.tool()
+def lookup_symbol(symbol: str) -> dict:
+    """Find where a symbol is defined across all open files."""
+    return _get("/lookup_symbol", symbol=symbol)
+
+
+@mcp.tool()
+def get_project_data() -> dict:
+    """Return the raw .sublime-project JSON data for the current project."""
+    return _get("/project_data")
+
+
+@mcp.tool()
+def add_folder(path: str) -> dict:
+    """Add a folder to the current project."""
+    data = _get("/project_data").get("project_data") or {}
+    folders = data.get("folders", [])
+    if not any(f.get("path") == path for f in folders):
+        folders.append({"path": path})
+        data["folders"] = folders
+        return _post("/set_project_data", data=data)
+    return {"ok": True, "note": "already present"}
+
+
+@mcp.tool()
+def remove_folder(path: str) -> dict:
+    """Remove a folder from the current project by path."""
+    data = _get("/project_data").get("project_data") or {}
+    folders = data.get("folders", [])
+    new_folders = [f for f in folders if f.get("path") != path]
+    if len(new_folders) == len(folders):
+        return {"ok": False, "note": "folder not found"}
+    data["folders"] = new_folders
+    return _post("/set_project_data", data=data)
+
+
+@mcp.tool()
+def get_variables() -> dict:
+    """Return Sublime Text's build variables: $file, $project_path, $platform, etc."""
+    return _get("/variables")
+
+
+# ── navigate ──────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def open_file(path: str, line: int = 0, col: int = 0) -> dict:
+    """Open a file in Sublime Text, optionally jumping to a specific line and column."""
+    return _post("/open_file", path=path, line=line, col=col)
+
+
+@mcp.tool()
+def goto_line(line: int, col: int = 1) -> dict:
+    """Move the cursor to a line (and optional column) in the active file."""
+    return _post("/goto_line", line=line, col=col)
+
+
+@mcp.tool()
+def show_panel(name: str = "exec") -> dict:
+    """Bring an output panel to the front.  Use name='exec' for the build panel."""
+    return _post("/show_panel", name=name)
+
+
+# ── edit ──────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def replace_selection(text: str) -> dict:
+    """Replace the current selection(s) with text."""
+    return _post("/replace_selection", text=text)
+
+
+@mcp.tool()
+def replace_lines(begin: int, end: int, text: str, path: str = "") -> dict:
+    """Replace lines begin through end (inclusive, 1-based) in the active file with text.
+    Pass path to target a specific open file regardless of which tab is focused."""
+    return _post("/replace_lines", begin=begin, end=end, text=text, path=path)
+
+
+@mcp.tool()
+def run_command(command: str, args: dict = None, scope: str = "window") -> dict:
+    """Run any Sublime Text command.  scope='window' (default) or 'view'."""
+    return _post("/run_command", command=command, args=args or {}, scope=scope)
+
+
+# ── build ─────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def run_build(cmd: list = None, shell_cmd: str = None, working_dir: str = "") -> dict:
+    """Trigger the current build system, or pass cmd/shell_cmd to run a specific command."""
+    body = {}
+    if cmd:
+        body["cmd"] = cmd
+    if shell_cmd:
+        body["shell_cmd"] = shell_cmd
+    if working_dir:
+        body["working_dir"] = working_dir
+    return _post("/run_build", **body)
+
+
+# ── misc ──────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def set_status(value: str, key: str = "sublime_mcp") -> dict:
+    """Write a message to Sublime Text's status bar."""
+    return _post("/set_status", key=key, value=value)
+
+
+# ── file ops ──────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def save_file(path: str = "") -> dict:
+    """Save a file. Pass path to save a specific open file; omit path to save the active file."""
+    return _post("/save_file", path=path) if path else _post("/save_file")
+
+
+@mcp.tool()
+def save_all() -> dict:
+    """Save all open files."""
+    return _post("/save_all")
+
+
+@mcp.tool()
+def close_file(path: str = "") -> dict:
+    """Close a file by path, or close the active file if path is omitted."""
+    return _post("/close_file", path=path)
+
+
+@mcp.tool()
+def revert_file() -> dict:
+    """Revert the active file to its last saved state, discarding unsaved changes."""
+    return _post("/revert_file")
+
+
+# ── edit ops ──────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def undo() -> dict:
+    """Undo the last edit in the active file."""
+    return _post("/undo")
+
+
+@mcp.tool()
+def redo() -> dict:
+    """Redo the last undone edit in the active file."""
+    return _post("/redo")
+
+
+@mcp.tool()
+def duplicate_line() -> dict:
+    """Duplicate the current line(s) in the active file."""
+    return _post("/duplicate_line")
+
+
+@mcp.tool()
+def toggle_comment(block: bool = False) -> dict:
+    """Toggle line comment (or block comment if block=True) on the current selection."""
+    return _post("/toggle_comment", block=block)
+
+
+@mcp.tool()
+def sort_lines(case_sensitive: bool = False) -> dict:
+    """Sort the selected lines (or all lines if nothing is selected)."""
+    return _post("/sort_lines", case_sensitive=case_sensitive)
+
+
+@mcp.tool()
+def select_lines(begin: int, end: int = 0) -> dict:
+    """Select lines begin through end (1-based, inclusive).  end defaults to begin."""
+    return _post("/select_lines", begin=begin, end=end or begin)
+
+
+@mcp.tool()
+def fold_lines(begin: int, end: int) -> dict:
+    """Fold (collapse) lines begin through end (1-based) in the active file."""
+    return _post("/fold_lines", begin=begin, end=end)
+
+
+@mcp.tool()
+def insert_snippet(contents: str) -> dict:
+    """Insert a snippet at the cursor using Sublime Text's snippet syntax (e.g. $1 for tab stops)."""
+    return _post("/insert_snippet", contents=contents)
+
+
+# ── search ────────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def find_in_file(
+    pattern: str, case_sensitive: bool = False, regex: bool = False
+) -> dict:
+    """Find all occurrences of pattern in the active file.  Returns list of {line, col, text}."""
+    return _post(
+        "/find_in_file", pattern=pattern, case_sensitive=case_sensitive, regex=regex
+    )
+
+
+@mcp.tool()
+def find_in_files(
+    pattern: str,
+    folders: list = None,
+    case_sensitive: bool = False,
+    regex: bool = False,
+    max_results: int = 200,
+) -> dict:
+    """Search for pattern across project folders (or the supplied folder list).
+    Skips .git, __pycache__, node_modules, .venv.  Returns list of {path, line, match}.
+    """
+    body = dict(
+        pattern=pattern,
+        case_sensitive=case_sensitive,
+        regex=regex,
+        max_results=max_results,
+    )
+    if folders:
+        body["folders"] = folders
+    return _post("/find_in_files", **body)
+
+
+# ── syntax / encoding ─────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def get_syntaxes() -> dict:
+    """List all syntax definitions available in Sublime Text (name + path)."""
+    return _get("/syntaxes")
+
+
+@mcp.tool()
+def get_command_palette(
+    package: str = "", command: str = "", caption: str = ""
+) -> dict:
+    """List Command Palette entries from installed *.sublime-commands resources.
+    Optional filters: package, command id, or caption substring."""
+    return _get("/command_palette", package=package, command=command, caption=caption)
+
+
+@mcp.tool()
+def get_commands(
+    package: str = "", command: str = "", include_palette: bool = True
+) -> dict:
+    """List runnable Sublime command ids from loaded command classes, optionally enriched
+    with matching Command Palette entries from installed packages."""
+    return _get(
+        "/commands",
+        package=package,
+        command=command,
+        include_palette=str(include_palette).lower(),
+    )
+
+
+@mcp.tool()
+def get_menu_items(menu: str = "", caption: str = "", command: str = "") -> dict:
+    """List installed menu items from *.sublime-menu resources.
+    Optional filters: menu filename, caption substring, or command id substring."""
+    return _get("/menu_items", menu=menu, caption=caption, command=command)
+
+
+@mcp.tool()
+def get_active_panel() -> dict:
+    """Return the active panel id and, if it is an output panel, its content."""
+    return _get("/active_panel")
+
+
+@mcp.tool()
+def set_syntax(name: str) -> dict:
+    """Set the syntax of the active file by name (case-insensitive partial match is fine)."""
+    return _post("/set_syntax", name=name)
+
+
+@mcp.tool()
+def get_encoding() -> dict:
+    """Return the character encoding of the active file."""
+    return _get("/encoding")
+
+
+@mcp.tool()
+def set_encoding(encoding: str) -> dict:
+    """Set the character encoding of the active file (e.g. 'UTF-8', 'Western (Windows 1252)')."""
+    return _post("/set_encoding", encoding=encoding)
+
+
+# ── cursor / scope ────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def get_scope_at_cursor() -> dict:
+    """Return the full syntax scope string at the cursor position."""
+    return _get("/scope_at_cursor")
+
+
+@mcp.tool()
+def get_word_at_cursor() -> dict:
+    """Return the word under the cursor and its line/col."""
+    return _get("/word_at_cursor")
+
+
+@mcp.tool()
+def get_bookmarks() -> dict:
+    """Return all bookmarked positions in the active file."""
+    return _get("/bookmarks")
+
+
+@mcp.tool()
+def get_line_count() -> dict:
+    """Return the total number of lines in the active file."""
+    return _get("/line_count")
+
+
+# ── settings ──────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def get_setting(key: str, scope: str = "view") -> dict:
+    """Get a Sublime Text setting by key.  scope='view' (default) or 'window'."""
+    return _post("/get_setting", key=key, scope=scope)
+
+
+@mcp.tool()
+def set_setting(key: str, value, scope: str = "view") -> dict:
+    """Set a Sublime Text setting by key.  scope='view' (default) or 'window'."""
+    return _post("/set_setting", key=key, value=value, scope=scope)
+
+
+# ── window / layout ───────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def toggle_sidebar() -> dict:
+    """Show or hide the Sublime Text sidebar."""
+    return _post("/toggle_sidebar")
+
+
+@mcp.tool()
+def get_layout() -> dict:
+    """Return the current window layout (groups, cells) and which files are in each group."""
+    return _get("/layout")
+
+
+@mcp.tool()
+def focus_group(group: int) -> dict:
+    """Move focus to a pane group by 0-based index."""
+    return _post("/focus_group", group=group)
+
+
+@mcp.tool()
+def set_layout(layout: dict) -> dict:
+    """Set the window pane layout.  layout must be a ST layout dict with cols, rows, cells keys."""
+    return _post("/set_layout", layout=layout)
+
+
+# ── scripting ─────────────────────────────────────────────────────────────────
+
+
+@mcp.tool()
+def eval_python(code: str) -> dict:
+    """Execute arbitrary Python in Sublime Text's main thread.
+    Locals: sublime, window, view, print.  Returns captured stdout in 'output'."""
+    return _post("/eval_python", code=code)
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

sublime_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sublime-mcp"
+version = "1.0.0"
+description = "MCP server for Sublime Text 4 — lets Claude Code read and control a running ST instance"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["mcp", "httpx"]
+keywords = ["mcp", "sublime-text", "claude", "ai", "editor"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Editors",
+]
+
+[[project.authors]]
+name = "Donald Chitester"
+email = "donaldchitester@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/dpc00/sublime-mcp"
+Repository = "https://github.com/dpc00/sublime-mcp"
+
+[project.scripts]
+sublime-mcp = "mcp_server:main"
+
+[tool.setuptools]
+py-modules = ["mcp_server"]

sublime_mcp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sublime_mcp-1.0.0/sublime_mcp.egg-info/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: sublime-mcp
+Version: 1.0.0
+Summary: MCP server for Sublime Text 4 — lets Claude Code read and control a running ST instance
+Author-email: Donald Chitester <donaldchitester@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/dpc00/sublime-mcp
+Project-URL: Repository, https://github.com/dpc00/sublime-mcp
+Keywords: mcp,sublime-text,claude,ai,editor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Editors
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp
+Requires-Dist: httpx
+
+# sublime-mcp
+
+<!-- mcp-name: io.github.dpc00/sublime-mcp -->
+
+
+MCP server for Sublime Text 4. Lets Claude Code (or any MCP client) read and
+control a running ST instance via a local HTTP bridge.
+
+58 tools covering reading, navigation, editing, searching, build, Terminus
+integration, settings, layout, 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
+
+Copy `sublime_mcp.py` to your Sublime Text `Packages/User/` folder:
+
+```
+%APPDATA%\Sublime Text\Packages\User\sublime_mcp.py
+```
+
+ST loads it automatically on start (or via `Tools › Developer › New Plugin…`
+then save over it). You should see:
+
+```
+sublime-mcp: listening on 127.0.0.1:9500
+```
+
+in the ST console (`View › Show Console`).
+
+### 2. Install the MCP server
+
+```
+pip install sublime-mcp
+```
+
+### 3. Register with Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "sublime": {
+      "command": "sublime-mcp"
+    }
+  }
+}
+```
+
+Then restart Claude Code. Tools will appear with the `mcp__sublime__` prefix.
+
+Then restart Claude Code. Tools will appear with the `mcp__sublime__` prefix.
+
+## 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_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 |
+|------|-------------|
+| `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` |
+
+## Configuration
+
+### Port
+
+Default is `9500`. To change it, edit `_PORT` in `sublime_mcp.py` and `BASE` in `mcp_server.py`.
+
+### 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)

sublime_mcp-1.0.0/sublime_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+mcp_server.py
+pyproject.toml
+sublime_mcp.egg-info/PKG-INFO
+sublime_mcp.egg-info/SOURCES.txt
+sublime_mcp.egg-info/dependency_links.txt
+sublime_mcp.egg-info/entry_points.txt
+sublime_mcp.egg-info/requires.txt
+sublime_mcp.egg-info/top_level.txt

sublime_mcp-1.0.0/sublime_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sublime_mcp-1.0.0/sublime_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sublime-mcp = mcp_server:main

sublime_mcp-1.0.0/sublime_mcp.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mcp
+httpx

sublime_mcp-1.0.0/sublime_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcp_server