# emacsclient-mcp

> Emacs MCP server + Pi extension — 22 Emacs tools for LLM-assisted editing, search, buffer management, and PR review.

[![Crates.io](https://img.shields.io/crates/v/emacsclient-mcp)](https://crates.io/crates/emacsclient-mcp)
[![npm](https://img.shields.io/npm/v/@bimawa/emacsclient-mcp)](https://www.npmjs.com/package/@bimawa/emacsclient-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## What is this?

A Model Context Protocol (MCP) server that gives LLMs direct access to Emacs — no `emacsclient` binary needed. It communicates via Unix socket using the Emacs server protocol, implementing `&`-quoting as defined in `emacsclient.c` and `server.el`.

Comes with:
- **Rust MCP binary** — 22 tools over JSON-RPC stdio
- **Pi extension** — auto-spawns the binary, registers all tools
- **PR review agent** — 4-phase workflow (Setup → Analysis → Issues → Report)

## Quick Start

### 1. Install

```bash
# Option A: Pi package (recommended — gets extension + agent)
pi install npm:@bimawa/emacsclient-mcp

# Option B: Rust binary only (for other MCP clients)
cargo install emacsclient-mcp

# Option C: Homebrew (macOS)
brew install bimawa/tap/emacsclient-mcp
```

### 2. Start Emacs server

```elisp
M-x server-start
;; or:
emacs --daemon
```

### 3. Reload Pi

```
/reload
```

Pi picks up the extension, spawns the binary, discovers 22 Emacs tools, and registers the `emacs-pr-review` agent.

## Tools

| Category | Tools |
|----------|-------|
| **Eval** | `emacs_eval` — run arbitrary Elisp |
| **Buffers** | `emacs_list_buffers`, `emacs_create_buffer`, `emacs_set_buffer_content`, `emacs_get_buffer_content`, `emacs_save_buffer`, `emacs_kill_buffer` |
| **Navigation** | `emacs_find_file`, `emacs_switch_to_buffer`, `emacs_goto_line`, `emacs_get_cursor_position`, `emacs_get_line` |
| **Search** | `emacs_search`, `emacs_replace` |
| **Editing** | `emacs_insert_at_point`, `emacs_get_region`, `emacs_set_mark` |
| **Windows** | `emacs_split_window_right`, `emacs_split_window_below`, `emacs_other_window`, `emacs_delete_other_windows`, `emacs_display_in_other_window` |

## PR Review Agent

Activate with `/agent emacs-pr-review` in Pi. The agent:

1. **Setup** — gets the diff, opens review buffer in `org-mode`, splits Emacs windows
2. **Analysis** — reads each changed file, applies review heuristics (R1–R4)
3. **Findings** — documents issues by severity: BLOCKER / CRITICAL / WARNING / SUGGESTION
4. **Report** — shows summary in Emacs, offers inline comments

## Protocol

Implements the exact Emacs server protocol from `server.el`:
- **Client sends first** (no server greeting)
- **Single-line commands**: `-auth KEY -eval EXPR\n`
- **`&`-quoting**: spaces → `&_`, newlines → `&n`, leading `-` → `&-`, `&` → `&&`
- **Response**: `-emacs-pid PID\n-print RESULT\n`

## Binary Resolution

The extension finds the binary in this order:
1. `EMACS_MCP_BINARY` environment variable
2. Pre-built binary alongside the extension (package distro)
3. `~/.cargo/bin/emacsclient-mcp` (cargo install)
4. `which emacsclient-mcp` (PATH / Homebrew)
5. `cargo run --release` (dev mode)

## Development

```bash
# Build the Rust binary
cargo build --release

# Run locally with Pi
pi -e ./extension/index.ts

# Test the MCP binary directly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | ./target/release/emacsclient-mcp
```

## License

MIT © [bimawa](https://github.com/bimawa)