内容
# MCP Commander
<!-- mcp-name: io.github.dpc00/sublime-mcp -->
通过模型上下文协议，将Sublime Text暴露给AI助手（如Claude Code、Cursor等）。MCP服务器直接内置于ST插件中，无需单独的进程或外部依赖。
63种工具，涵盖阅读、导航、编辑、搜索、构建、Terminus集成、设置、布局、菜单、控制台日志和实时Python脚本等。
## 架构
插件启动时运行两个本地服务器：
| 服务器 | 默认端口 | 目的 |
|--------|-------------|---------|
| MCP SSE | 9502（Win）/ 9503（Mac/Linux） | MCP 2024-11-05 SSE传输 — 连接你的代理 |
| HTTP桥 | 9500（Win）/ 9501（Mac/Linux） | SSE调度器使用的内部REST API |
```
Claude Code（MCP客户端）
│ MCP SSE （端口9502）
▼
sublime_mcp.py ← ST插件 — MCP服务器 + HTTP桥，合二为一
│ sublime API
▼
Sublime Text 4
```
## 安装
### 1. 通过Package Control安装
1. 打开命令面板（`Ctrl+Shift+P`）
2. 运行 **Package Control: Install Package**
3. 搜索 **MCP Commander** 并安装
插件自动加载。检查 `View › Show Console` 中的：
```
sublime-mcp: MCP SSE on 127.0.0.1:9502, HTTP bridge on 127.0.0.1:9500
```
> **手动安装：** 将 `sublime_mcp.py` （和可选的 `sublime_mcp_browse.py`）复制到你的 `Packages/User/` 目录中。
### 2. 注册到Claude Code
在 `~/.claude/settings.json` 中添加以下内容到 `"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" }
```
重启Claude Code。工具将以 `mcp__sublime-mcp__` 前缀显示。
## 服务器管理
MCP服务器在ST加载插件时自动启动。要停止或重启它，打开命令面板并运行：
> **MCP Commander: Server Status**
面板显示服务器是否正在运行以及在哪个端口，并允许你通过按键启动或停止它。
## 标签和工作表索引
**重要：** 用户通过1为基础的编号引用标签（标签1，标签2等），但 `get_sheets()` 返回0为基础的索引。在使用前始终将用户标签引用转换为索引：
- 用户 **标签1** = 索引0
- 用户 **标签2** = 索引1
当目标是特定标签时，首先调用 `get_sheets()` 以验证索引。
## 工具
### 读取 / 检视
| 工具 | 描述 |
|------|-------------|
| `get_active_file` | 路径，完整内容，光标行/列，脏标志和语法名称 |
| `get_selection` | 当前选择：文本和每个选择的开始/结束行+列 |
| `get_cursor_context` | 光标上下 `lines` 行，带有1为基础的行编号 |
| `get_open_files` | 当前窗口中所有打开的文件（路径，名称，是否脏） |
| `get_sheets` | 窗口中的所有工作表（标签）索引 — 包括图像和未标题缓冲区 |
| `get_sheet_content` | 通过工作表索引（从 `get_sheets`）获取任何标签的内容 |
| `get_project_folders` | 项目根文件夹路径 |
| `get_file_content` | 通过路径获取任何已打开文件的完整内容 |
| `get_view_content` | 通过名称获取任何打开标签的完整内容（部分匹配，不区分大小写） |
| `get_view_size` | 任何打开标签的总字符数 |
| `get_view_chars` | 文本在字符偏移 `begin..end` （0为基础，结束独占） |
| `get_view_phantoms` | 命名视图的幻影HTML和提取的纯文本 |
| `get_output_panel` | 命名输出面板的内容（`name='exec'` 用于构建输出） |
| `get_active_panel` | 活动面板ID和（如果是输出面板）其内容 |
| `get_symbols` | 活动文件中的所有符号（函数，类等）及其行号 |
| `lookup_symbol` | 在所有打开的文件中查找符号定义 |
| `get_project_data` | 当前项目的原始 `.sublime-project` JSON |
| `get_variables` | ST构建变量： `$file` ， `$project_path` ， `$platform` 等 |
| `get_command_palette` | 已安装的 `*.sublime-commands` 资源中的命令面板条目 |
| `get_commands` | 加载的命令类中的可运行命令ID |
| `get_menu_items` | `*.sublime-menu` 资源中的菜单项 |
| `get_syntaxes` | ST中可用的所有语法定义（名称+路径） |
| `get_scope_at_cursor` | 光标位置的完整语法作用域字符串 |
| `get_word_at_cursor` | 光标下的单词及其行/列 |
| `get_bookmarks` | 活动文件中的所有书签位置 |
| `get_line_count` | 活动文件的总行数 |
| `get_encoding` | 活动文件的字符编码 |
| `get_setting` | 通过键获取ST设置。 `scope='view'` （默认）或 `'window'` |
| `get_layout` | 当前窗口布局（组，单元格）和每个组中的文件 |
### 导航
| 工具 | 描述 |
|------|-------------|
| `open_file` | 打开文件，可选跳转到特定行和列 |
| `goto_line` | 移动光标到活动文件中的行（和可选列） |
| `show_panel` | 将输出面板带到前面。默认 `name='exec'` 用于构建面板 |
| `focus_group` | 通过0为基础的索引将焦点移动到窗格组 |
### 编辑
| 工具 | 描述 |
|------|-------------|
| `str_replace_based_edit_tool` | ST原生编辑器： `str_replace` ， `insert` ， `create` ， `view` 。完整撤销，沟槽差异，30秒高亮 |
| `replace_selection` | 用文本替换当前选择 |
| `replace_lines` | 在活动文件中替换行 `begin..end` （包含，1为基础） |
| `insert_snippet` | 在光标处插入ST代码段语法 |
| `duplicate_line` | 复制当前行 |
| `toggle_comment` | 切换行注释，或如果 `block=True` 则切换块注释 |
| `sort_lines` | 排序选定行，或如果未选择任何行则排序所有行 |
| `select_lines` | 选择行 `begin..end` （1为基础，包含） |
| `fold_lines` | 在活动文件中折叠（折起）行 `begin..end` |
| `undo` | 撤销最后一次编辑 |
| `redo` | 重做最后一次撤销的编辑 |
| `run_command` | 运行任何ST命令，带有可选参数 |
### 搜索
| 工具 | 描述 |
|------|-------------|
| `find_in_file` | 在活动文件中查找模式的所有出现 |
| `find_in_files` | 跨项目文件夹搜索。跳过 `.git` ， `__pycache__` ， `node_modules` ， `.venv` |
### 文件 / 项目
| 工具 | 描述 |
|------|-------------|
| `save_file` | 保存活动文件（或通过路径保存特定文件） |
| `save_all` | 保存所有打开的文件 |
| `close_file` | 关闭文件通过路径，或如果省略路径则关闭活动文件 |
| `revert_file` | 将活动文件恢复到其最后保存的状态 |
| `add_folder` | 将文件夹添加到当前项目 |
| `remove_folder` | 通过路径从当前项目中删除文件夹 |
### 语法 / 编码
| 工具 | 描述 |
|------|-------------|
| `set_syntax` | 通过名称（不区分大小写，部分匹配）设置活动文件的语法 |
| `set_encoding` | 设置活动文件的字符编码 |
### 设置 / 窗口
| 工具 | 描述 |
|------|-------------|
| `set_setting` | 通过键设置ST设置 |
| `toggle_sidebar` | 显示或隐藏侧边栏 |
| `set_layout` | 设置窗口窗格布局 |
| `set_status` | 将消息写入ST的状态栏 |
### 构建
| 工具 | 描述 |
|------|-------------|
| `run_build` | 触发当前构建系统，或传递 `cmd`/`shell_cmd` 以获取自定义命令 |
### Terminus集成
[Terminus](https://github.com/randy3k/Terminus) 是流行的ST终端包。 `send_to_view` 是Terminus感知的：当目标是Terminus标签时，它使用 `terminus_send_string` 在终端会话中输入文本。
| 工具 | 描述 |
|------|-------------|
| `send_to_view` | 将文本发送到任何打开的标签。对于Terminus标签，输入如同用户输入一样。包含 `\n` 以执行 |
### 脚本
| 工具 | 描述 |
|------|-------------|
| `eval_python` | 在ST的主线程中执行任意Python。返回 `output` 中的捕获stdout |
| `eval_python_latest` | 在ST沙箱外部的系统解释器中执行Python |
| `get_console_log` | 最近的ST控制台输出。 `tail=N` 限制为最后N个条目 |
| `get_console_full` | 自启动以来捕获的整个ST控制台缓冲区 |
## 配置
### 端口
| 服务器 | Windows | Mac/Linux | 环境变量覆盖 |
|--------|---------|-----------|-----------------|
| MCP SSE | 9502 | 9503 | `SUBLIME_MCP_MCP_PORT` |
| HTTP桥 | 9500 | 9501 | `SUBLIME_MCP_PORT` |
### 告诉Claude如何使用工具
在项目的 `CLAUDE.md` （或 `~/.claude/CLAUDE.md`）中添加类似的章节：
```markdown
## Sublime Text MCP工具
MCP Commander已连接。在ST中工作时优先使用它而不是标准文件工具：
- 使用 `get_active_file` 或 `get_file_content` 读取文件，而不是读取工具
- 使用 `str_replace_based_edit_tool` 编辑 — 编辑实时显示，带有沟槽差异和撤销
- 使用 `find_in_files` 进行项目范围搜索
- 使用 `send_to_view` 在Terminus终端标签中运行命令
- 使用 `eval_python` 进行一次性ST脚本编写（无需插件文件）
- 在插件行为异常时检查 `get_console_log`
标签索引： `get_sheets()` 返回0为基础的索引；用户引用标签为1为基础。始终在目标特定标签时首先调用 `get_sheets()`。
```
## 安全注意事项
两个服务器都只绑定到 `127.0.0.1` 并接受任何请求而无需身份验证。不要将这些端口暴露到网络接口上。
## 要求
- Sublime Text 4
- Terminus包（可选 — 仅在终端标签上使用 `send_to_view` 时需要）
## 已知限制
- **无多窗口支持** — 工具针对最近聚焦的ST窗口
- **无图像编辑** — `get_sheet_content` 为图像标签返回路径，而不是像素数据
- **无ST3支持** — 插件广泛使用ST4 API
## 测试
测试套件需要Sublime Text运行并加载 `sublime_mcp.py`。
```
cd /path/to/sublime-mcp
pip install httpx pytest
pytest tests/ -v
```
## 贡献
**添加工具：**
1. 在 `sublime_mcp.py` 中添加处理函数（通过 `_on_main` 调用ST API）
2. 在 `_MCP_TOOLS` 和 `_GET` / `_POST` 路由字典中添加条目
3. 在 `README.md` 中的工具表中添加一行
**良好入手的问题：**
- 多窗口支持（`sublime.windows()` 而不是 `sublime.active_window()`）
- `get_diagnostics` — 暴露LSP错误/警告注释
- `set_bookmark` / `clear_bookmarks` — 编写 `get_bookmarks` 的对应函数
在 [GitHub](https://github.com/dpc00/sublime-mcp) 上打开问题或PR。
