# emacs-mcp

An MCP (Model Context Protocol) server that bridges Claude Code with Emacs via emacsclient.

## Features

### Phase 1: Core (Buffer & Eval)
| Tool | Description |
|------|-------------|
| `emacs_eval` | Execute arbitrary Elisp code |
| `emacs_buffer_read` | Read contents of a buffer |
| `emacs_buffer_write` | Write/replace content in a buffer |
| `emacs_buffer_edit` | Apply targeted edits (find and replace) |
| `emacs_buffer_list` | List all open buffers |
| `emacs_buffer_switch` | Switch to a buffer |
| `emacs_buffer_create` | Create a new buffer |
| `emacs_buffer_kill` | Close/kill a buffer |

### Phase 2: File & Project Operations
| Tool | Description |
|------|-------------|
| `emacs_file_open` | Open a file (with optional line/column) |
| `emacs_file_save` | Save buffer to file |
| `emacs_file_save_as` | Save buffer to new path |
| `emacs_file_info` | Get file metadata |
| `emacs_project_list` | List known projects |
| `emacs_project_current` | Get current project info |
| `emacs_project_switch` | Switch to a project |
| `emacs_project_files` | List files in project |
| `emacs_project_search` | Search files by pattern |
| `emacs_workspace_list` | List workspaces/tabs |
| `emacs_workspace_current` | Get current workspace |
| `emacs_workspace_switch` | Switch workspace |
| `emacs_workspace_create` | Create new workspace |
| `emacs_workspace_delete` | Delete workspace |
| `emacs_workspace_save` | Save workspace state |

### Phase 3: Org-mode Integration
| Tool | Description |
|------|-------------|
| `emacs_org_read` | Read org document (raw or parsed structure) |
| `emacs_org_write` | Write content to org buffer |
| `emacs_org_heading_add` | Add a new heading |
| `emacs_org_heading_update` | Update heading title/content |
| `emacs_org_heading_delete` | Delete a heading and subtree |
| `emacs_org_heading_move` | Move heading (up/down/promote/demote) |
| `emacs_org_todo_set` | Set TODO state for a heading |
| `emacs_org_todo_list` | List all TODO items |
| `emacs_org_tag_set` | Set tags for a heading |
| `emacs_org_property_set` | Set a property for a heading |
| `emacs_org_export` | Export to html/pdf/markdown/latex/ascii/odt |
| `emacs_org_agenda` | Query agenda (day/week/month) |
| `emacs_org_capture` | Create entry via capture template |
| `emacs_org_search` | Search org files (text/heading/tag/property) |

### Phase 4: Git/Magit Integration
| Tool | Description |
|------|-------------|
| `emacs_git_status` | Get git status (staged, unstaged, untracked) |
| `emacs_git_diff` | Get diff (staged/unstaged/committed) |
| `emacs_git_log` | Get commit log |
| `emacs_git_stage` | Stage files for commit |
| `emacs_git_unstage` | Unstage files |
| `emacs_git_commit` | Create a commit |
| `emacs_git_branch_list` | List branches |
| `emacs_git_branch_current` | Get current branch |
| `emacs_git_branch_checkout` | Checkout a branch |
| `emacs_git_stash_list` | List stashes |
| `emacs_git_stash_push` | Create a stash |
| `emacs_git_stash_pop` | Pop a stash |
| `emacs_git_blame` | Show git blame for a file |

### Phase 5: Ediff & Comparison
| Tool | Description |
|------|-------------|
| `emacs_ediff_files` | Compare two files (unified/context/side-by-side) |
| `emacs_ediff_buffers` | Compare two buffers |
| `emacs_ediff_regions` | Compare two text strings |
| `emacs_ediff_3way` | Three-way file comparison (for merges) |
| `emacs_diff_summary` | Get summary of differences |

### Resources
| URI | Description |
|-----|-------------|
| `emacs://buffers` | List of all open buffers |
| `emacs://buffer/{name}` | Contents of a buffer |
| `emacs://projects` | List of known projects |
| `emacs://project/current` | Current project info |
| `emacs://project/{path}/files` | Files in a project |
| `emacs://workspaces` | List of workspaces |
| `emacs://workspace/current` | Current workspace |
| `emacs://org/agenda` | Today's agenda items |
| `emacs://org/todos` | All TODO items |
| `emacs://org/files` | Org-agenda files |
| `emacs://org/capture-templates` | Available capture templates |
| `emacs://git/status` | Current git status |
| `emacs://git/branch` | Current branch info |

### Compatibility
- **Vanilla Emacs**: Uses `project.el` and `tab-bar-mode`
- **Doom Emacs**: Uses `projectile` and `+workspace` (auto-detected)

## Prerequisites

1. **Emacs 28+** with daemon support
2. **Node.js 18+**
3. Running Emacs daemon:
   ```bash
   emacs --daemon
   ```

## Installation

```bash
npm install
npm run build
```

## Configuration

Add to your Claude Code `.mcp.json`:

```json
{
  "mcpServers": {
    "emacs": {
      "command": "node",
      "args": ["/path/to/emacs-mcp/dist/index.js"],
      "env": {
        "EMACS_SOCKET": "/run/user/1000/emacs/server",
        "EMACSCLIENT_PATH": "/usr/bin/emacsclient"
      }
    }
  }
}
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `EMACS_SOCKET` | Path to Emacs daemon socket | Auto-detect |
| `EMACSCLIENT_PATH` | Path to emacsclient binary | `emacsclient` |
| `EMACS_TIMEOUT` | Default timeout for operations (ms) | `5000` |
| `EMACS_ORG_DIRECTORY` | Org files directory | `~/org` |

## Usage Examples

```
Claude: Read the contents of the *scratch* buffer
> Uses emacs_buffer_read tool

Claude: List all open buffers
> Uses emacs_buffer_list tool

Claude: Evaluate (+ 1 2 3) in Emacs
> Uses emacs_eval tool

Claude: What projects do I have open?
> Uses emacs_project_list tool

Claude: Switch to workspace "main"
> Uses emacs_workspace_switch tool

Claude: Open /path/to/file.ts at line 42
> Uses emacs_file_open tool

Claude: Show me my TODO items
> Uses emacs_org_todo_list tool

Claude: Add a TODO heading "Review PRD" to notes.org
> Uses emacs_org_heading_add tool

Claude: What's on my agenda this week?
> Uses emacs_org_agenda tool

Claude: Export my notes.org to PDF
> Uses emacs_org_export tool

Claude: What's my git status?
> Uses emacs_git_status tool

Claude: Show me the recent commits
> Uses emacs_git_log tool

Claude: Stage all changes and commit
> Uses emacs_git_stage and emacs_git_commit tools

Claude: What branch am I on?
> Uses emacs_git_branch_current tool

Claude: Compare file.ts with file.ts.bak
> Uses emacs_ediff_files tool

Claude: Show me the differences between these two buffers
> Uses emacs_ediff_buffers tool

Claude: Do a three-way merge comparison
> Uses emacs_ediff_3way tool
```

## Development

```bash
# Watch mode
npm run dev

# Run tests
npm test

# Lint
npm run lint
```

## Roadmap

See [PRD.md](./PRD.md) for full roadmap:
- [x] Phase 1: Core Infrastructure (MVP)
- [x] Phase 2: File & Project Operations
- [x] Phase 3: Org-mode Integration
- [x] Phase 4: Git/Magit Integration
- [x] Phase 5: Ediff & Advanced Features

## License

MIT