# MCPServer

`MCPServer` is a Sublime Text package that exposes MCP tools over local HTTP from inside Sublime's Python runtime.

Today it ships with MCP tools for unsaved buffers:
- `list_open_buffers`
- `read_buffer`
- `close_buffer`

## Use Cases

- Read temporary scratch notes or prompts directly from open unsaved tabs.
- Summarize or refine a draft in an AI client, then send the result to another MCP such as Notion.
- Clean up working tabs by closing consumed scratch buffers via `close_buffer`.
- Build lightweight editor automations without saving throwaway notes to disk.

The architecture is fully in-process. By default it starts:
- Sublime bridge on `127.0.0.1:6123`
- MCP endpoint on `127.0.0.1:6124/mcp`

No separate Node or TypeScript MCP server is required.

## Requirements

- Sublime Text 4 build `4171` or newer
- Python 3.8 compatibility for the plugin package
- Python 3.11+ if you want to run the repo tests locally
- A local MCP client that can talk to a streamable HTTP MCP endpoint

## Project Layout

- `sublime_mcp_server/`: bridge logic and in-process MCP HTTP server
- `sublime_mcp_server_plugin.py`: Sublime Text plugin entrypoint
- `messages.json` and `messages/*.txt`: Package Control install and upgrade messages
- `python_tests/`: pytest coverage for bridge and MCP behavior

## Install The Sublime Plugin

For normal usage, install the packaged artifact into Sublime's `Installed Packages` folder.

On macOS:

```bash
mkdir -p "$HOME/Library/Application Support/Sublime Text/Installed Packages"
cp dist/MCPServer.sublime-package \
  "$HOME/Library/Application Support/Sublime Text/Installed Packages/MCPServer.sublime-package"
```

If you previously installed an unpacked development copy, remove it first so Sublime does not load the package twice:

```bash
rm -rf "$HOME/Library/Application Support/Sublime Text/Packages/MCPServer"
```

Restart Sublime Text after copying the files.

The packaged release includes the repository's tracked [.python-version](/Users/song.yue/git/sublime-mcp/.python-version) file at the package root so Sublime can select the correct Python runtime when loading the archive.

For local development, you can still use an unpacked checkout under `Packages/MCPServer`, but that is now a development-only workflow instead of the recommended installation method.

## Port Configuration

The package reads its host and port configuration from [MCPServer.sublime-settings](/Users/song.yue/git/sublime-mcp/MCPServer.sublime-settings).

Default values:

```json
{
  "bridge_host": "127.0.0.1",
  "bridge_port": 6123,
  "mcp_host": "127.0.0.1",
  "mcp_port": 6124
}
```

To override them in Sublime Text:

1. Open the command palette.
2. Run `Preferences: MCPServer Settings`.
3. Put your overrides in the right-hand user settings pane.
4. Restart Sublime Text.

Example:

```json
{
  "bridge_port": 7001,
  "mcp_port": 7002
}
```

The bridge and MCP ports must be different when using the same host.

## Package And Release

There are two common release paths for Sublime Text packages:

- Package Control default channel: publish this repo on GitHub, create a semantic version tag such as `0.2.5`, and submit the repository to Package Control once. After approval, future semver tags are how users receive updates.
- Custom distribution: build a `.sublime-package` archive and host your own `packages.json` channel if you do not want to use Package Control's default channel.

This repo now includes release-facing metadata:

- central package display name, MCP server name, version, and description in [sublime_mcp_server/__init__.py](/Users/song.yue/git/sublime-mcp/sublime_mcp_server/__init__.py)
- Package Control install and upgrade messages in [messages.json](/Users/song.yue/git/sublime-mcp/messages.json)
- release notes for `0.2.5` in [messages/0.2.5.txt](/Users/song.yue/git/sublime-mcp/messages/0.2.5.txt)

Suggested release checklist:

1. Update the version in [pyproject.toml](/Users/song.yue/git/sublime-mcp/pyproject.toml) and [sublime_mcp_server/__init__.py](/Users/song.yue/git/sublime-mcp/sublime_mcp_server/__init__.py).
2. Add a matching upgrade note under `messages/`.
3. Build a `.sublime-package` artifact from the repo root:

```bash
python3 scripts/build_release.py
```

4. Run `pytest` and `python3 -m py_compile sublime_mcp_server_plugin.py sublime_mcp_server/*.py`.
5. Commit the release changes.
6. Create and push a semver tag such as `0.2.5`.
7. If this is the first public release, submit the GitHub repository URL to Package Control.

For manual installs, use the generated `dist/MCPServer.sublime-package` file. The stable filename keeps the package name clean in Sublime, and the builder injects `package-metadata.json` so the description and version are visible in package UIs.

## Verify The Plugin Is Running

Once Sublime restarts, the plugin should start two localhost services:

- `GET http://127.0.0.1:6123/buffers`
- `POST http://127.0.0.1:6124/mcp`

Check the bridge:

```bash
curl -sf http://127.0.0.1:6123/buffers | python3 -m json.tool
```

Check the MCP endpoint:

```bash
curl -sf \
  -X POST http://127.0.0.1:6124/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0.0"}}}' \
  | python3 -m json.tool
```

You should see `serverInfo.name` set to `sublime_mcp_server`.

If you changed the ports in settings, use those values instead of `6123` and `6124`.

## MCP Client Setup

This project serves MCP over HTTP from inside Sublime, so your MCP client only needs to connect to the plugin's endpoint.

Recommended MCP client configuration:

```json
{
  "mcpServers": {
    "sublime_mcp_server": {
      "type": "http",
      "url": "http://127.0.0.1:6124/mcp"
    }
  }
}
```

## Available Tools

### `list_open_buffers`

Lists unsaved open Sublime buffers. Each buffer descriptor includes:

- `buffer_id`
- `title`
- `window_id`
- `is_dirty`
- `syntax`
- `preview`

### `read_buffer`

Reads the current live text and metadata for one unsaved Sublime buffer.

Input:

```json
{
  "buffer_id": "38"
}
```

### `close_buffer`

Force-closes an unsaved Sublime buffer and discards its current contents.

Input:

```json
{
  "buffer_id": "38"
}
```

## Manual End-To-End Check

1. Open Sublime Text.
2. Create one or more new unsaved tabs.
3. Add some test text.
4. Verify the buffer list:

```bash
curl -sf http://127.0.0.1:6123/buffers | python3 -m json.tool
```

5. Use an MCP client or direct JSON-RPC request to list tools and read a buffer.

Direct JSON-RPC example:

```bash
curl -sf \
  -X POST http://127.0.0.1:6124/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | python3 -m json.tool
```

```bash
curl -sf \
  -X POST http://127.0.0.1:6124/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"read_buffer","arguments":{"buffer_id":"38"}}}' \
  | python3 -m json.tool
```

```bash
curl -sf \
  -X POST http://127.0.0.1:6124/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"close_buffer","arguments":{"buffer_id":"38"}}}' \
  | python3 -m json.tool
```

## Development

Run tests:

```bash
pytest
```

Check syntax:

```bash
python3 -m py_compile sublime_mcp_server_plugin.py sublime_mcp_server/*.py
```