#+title: ragmacs-mcp
#+author: Lander M. Kerbey
#+options: toc:t num:nil

An MCP server that gives LLMs live introspective access to a running Emacs
instance. It exposes tools for reading documentation, browsing Info manuals,
inspecting source code, and querying completions — all against your actual
running Emacs environment.

The inspiration for this MCP is due to [[https://github.com/positron-solutions][Positron Solutions]], who created
[[https://github.com/positron-solutions/ragmacs/tree/master][ragmacs]]. This is as much of a straight port to MCP as my limited
ability allows at present.

* Rationale

Given how easy it is to set up =ragmacs= via standard Emacs
configuration, why bother with porting it to MCP? In the course of my
day job, I have identified a number of workflows for which LLMs with
tool-calling capabilities are very well suited, but the scope of the
projects are such that the token consumption that comes with the
necessary tool use would ramp up AI spend too much. Following on from
articles by [[https://www.anthropic.com/engineering/code-execution-with-mcp][Anthropic]] and [[https://blog.cloudflare.com/code-mode/][Cloudflare]], I've been tinkering with
MCP-based code-execution workflows. This is meant to facilitate that.

* Prerequisites

** Emacs

You need a running Emacs with a server started. Add this to your Emacs config:

#+begin_src emacs-lisp
(require 'server)
(unless (server-running-p)
  (server-start))
#+end_src

Or start it interactively with ~M-x server-start~.

** orderless

The completion tools (~function_completions~, ~command_completions~,
~variable_completions~) require the [[https://github.com/oantolin/orderless][orderless]] package. Install it via your
package manager of choice, for example with ~use-package~:

#+begin_src emacs-lisp
(use-package orderless)
#+end_src

** emacsclient

~emacsclient~ must be on your ~PATH~. Verify this works before proceeding:

#+begin_src bash
emacsclient --eval "(emacs-version)"
#+end_src

** C source (optional)

~function_source~ and ~variable_source~ can retrieve source code for C
built-ins if the Emacs C source is available on disk. If you are using a
packaged Emacs binary, you may need to install an additional package such as
~emacs-src~ to make this work. If C source is unavailable, the tools return a
helpful message explaining the situation rather than failing silently.

* Installation

#+begin_src bash
npm install
npm run build
#+end_src

* Configuration

Add the following to your MCP client configuration. The exact file location
depends on your client — for mcpproxy it is typically
=~/.mcpproxy/mcp_config.json=:

#+begin_src json
  "mcpServers": [
    {
      "name": "ragmacs",
      "command": "node",
      "args": ["ragmacs-mcp/dist/index.js"],
      "protocol": "stdio",
      "enabled": true
    }
  ]
#+end_src

If you have multiple Emacs servers running and need to target a specific one,
set the ~EMACS_SOCKET_NAME~ environment variable:

#+begin_src json
  "mcpServers": [
    {
      "name": "ragmacs",
      "command": "node",
      "args": ["ragmacs-mcp/dist/index.js"],
      "protocol": "stdio",
      "enabled": true,
      "env": {
        "EMACS_SOCKET_NAME": "/run/user/1000/emacs/server"
      }
    }
  ]
#+end_src

* Tools

| Tool                   | Description                                   |
|------------------------+-----------------------------------------------|
| ~elisp_eval~             | Evaluate an arbitrary Elisp expression        |
| ~symbol_exists~          | Check if a symbol exists in obarray           |
| ~load_paths~             | Return Emacs load paths                       |
| ~list_features~          | Return loaded features                        |
| ~list_manuals~           | List available Info manuals                   |
| ~list_manual_nodes~      | List nodes within a manual                    |
| ~manual_node_contents~   | Read the contents of a manual node            |
| ~check_feature~          | Check if a feature is loaded or available     |
| ~library_source~         | Read the full source of an Elisp library      |
| ~symbol_manual_section~  | Find the manual section for a symbol          |
| ~function_source~        | Read the source code of a function            |
| ~variable_source~        | Read the source code of a variable definition |
| ~variable_value~         | Read the current global value of a variable   |
| ~function_documentation~ | Read the docstring of a function              |
| ~variable_documentation~ | Read the docstring of a variable              |
| ~function_completions~   | List functions matching a prefix              |
| ~command_completions~    | List commands matching a prefix               |
| ~variable_completions~   | List variables matching a prefix              |

* Development

#+begin_src bash
npm test        # run tests (requires a running Emacs)
npm run build   # compile TypeScript
npm start       # run the server
#+end_src