elisp-dev-mcp

#+TITLE: elisp-dev-mcp: MCP Server for Agentic Elisp Development [[https://github.com/laurynas-biveinis/elisp-dev-mcp/actions/workflows/elisp-test.yml][https://github.com/laurynas-biveinis/elisp-dev-mcp/actions/workflows/elisp-test.yml/badge.svg]] [[https://github.com/laurynas-biveinis/elisp-dev-mcp/actions/workflows/super-linter.yml][https://github.com/laurynas-biveinis/elisp-dev-mcp/actions/workflows/super-linter.yml/badge.svg]] [[https://melpa.org/#/elisp-dev-mcp][https://melpa.org/packages/elisp-dev-mcp-badge.svg]] [[https://stable.melpa.org/#/elisp-dev-mcp][file:https://stable.melpa.org/packages/elisp-dev-mcp-badge.svg]] * Overview =elisp-dev-mcp= is an Emacs package that provides an MCP (Machine Code Protocol) server for agentic Elisp development. It enables AI agents to assist with Elisp coding tasks by providing a structured API to interact with Emacs and manipulate Elisp code. This package leverages [[https://github.com/laurynas-biveinis/mcp-server-lib.el][mcp-server-lib.el]] for the underlying MCP infrastructure. * Installation From [[https://melpa.org/#/elisp-dev-mcp][MELPA]] or [[https://stable.melpa.org/#/elisp-dev-mcp][MELPA Stable]]: =M-x package-install RET elisp-dev-mcp RET= * Usage ** Registering with an MCP Client After =mcp-server-lib= has been properly installed (including =M-x mcp-server-lib-install=), register =elisp-dev-mcp= with your MCP client: #+begin_example claude mcp add -s user -t stdio elisp-dev -- ~/.emacs.d/emacs-mcp-stdio.sh --init-function=elisp-dev-mcp-enable --stop-function=elisp-dev-mcp-disable --server-id=elisp-dev-mcp #+end_example Before using the MCP server, you must start it in Emacs with =M-x mcp-server-lib-start=. Stop it with =M-x mcp-server-lib-stop= when done. ** Available MCP Handlers *** Elisp Function Documentation - Name: =elisp-describe-function= - Description: Get full documentation for an Emacs Lisp function - Parameters: - =function=: The name of the function to describe (string) - Returns: - =description=: The function's documentation (string) - or =error=: Error message if something went wrong (string) *** Elisp Function Definition - Name: =elisp-get-function-definition= - Description: Get the source code definition of an Emacs Lisp function - Parameters: - =function=: The name of the function to retrieve (string) - Returns: - For Elisp functions: - =source=: The function's source code including header comments if present (string) - =file-path=: Path to the file where the function is defined (string) - =start-line=: First line number of the definition including header comments (1-based integer) - =end-line=: Last line number of the definition (1-based integer) - For C-implemented functions: - =is-c-function=: Boolean indicator that this is a C function (always true) - =function-name=: The name of the function (string) - =message=: A message indicating the function is implemented in C source code (string) *** Elisp Variable Description - Name: =elisp-describe-variable= - Description: Get information about an Emacs Lisp variable without exposing its value - Parameters: - =variable=: The name of the variable to describe (string) - Returns: - =name=: Variable name (string) - =bound=: Whether variable is currently bound (boolean, false for declared but unbound variables) - =value-type=: Type of the value (string, e.g. "cons", "string", "integer") - =documentation=: Variable documentation or null if none (string or null) - =source-file=: Path to the file where the variable is defined (string) - =is-custom=: Whether it's a customizable variable (boolean) - =custom-group=: The custom group this variable belongs to (string, only present for custom variables) - =custom-type=: The custom type specification (string, only present for custom variables) - =is-obsolete=: Whether the variable is marked obsolete (boolean) - =obsolete-since=: Version when the variable became obsolete (string, only present if obsolete) - =obsolete-replacement=: Suggested replacement for the obsolete variable (string, only present if obsolete) - =is-alias=: Whether the variable is an alias for another variable (boolean) - =alias-target=: The variable this is an alias for (string, only present if alias) - =is-special=: Whether the variable is a special (dynamically scoped) variable (boolean) - or =error=: Error message if something went wrong (string) *** Elisp Info Documentation Lookup - Name: =elisp-info-lookup-symbol= - Description: Look up Elisp symbols in Info documentation and return the complete documentation node - Parameters: - =symbol=: The Elisp symbol to look up (string) - Returns: - =found=: Whether documentation was found (boolean) - =symbol=: The symbol that was looked up (string) - =node=: The Info node name containing the documentation (string, when found) - =manual=: The Info manual name, typically 'elisp' (string, when found) - =content=: The complete Info node content including all examples, cross-references, and related information (string, when found) - =info-ref=: Info reference like '(elisp)Node Name' for direct access (string, when found) - =message=: Error or not-found message (string, when not found) *** Elisp Source File Reader - Name: =elisp-read-source-file= - Description: Read Elisp source files from Emacs system directories or ELPA packages. Accepts either library names or absolute file paths. - Parameters: - =library-or-path=: Library name (e.g., ="subr"=, ="org"=) or absolute path to =.el= file (string) - Returns: - The complete file contents as a string - or =error=: Error message if library not found, file not found, invalid format, or access denied (string) - Input modes: 1. *Library names* (recommended for built-in and installed packages): - Simple names without path separators: ="subr"=, ="files"=, ="org"= - Resolved via Emacs =locate-library= function (searches =load-path=) - Examples: ="subr"=, ="mcp-server-lib"=, ="org"= 2. *Absolute paths* (for compatibility with other =elisp-dev= tools): - Full paths ending in =.el= - Returned by =elisp-get-function-definition= - Examples: ="/opt/homebrew/.../lisp/files.el"=, ="/Users/name/.emacs.d/elpa/package-1.0/package.el"= - Security: - Only reads from Emacs system lisp directories and ELPA directories - Rejects paths with =..= traversal - Resolves symlinks to prevent escaping allowed directories - Library names must resolve to paths within allowed directories - Features: - Transparently handles =.el.gz= compressed files - Works with both built-in Emacs libraries and installed packages - Returns complete file contents as string ** Configuration for Alternative Package Managers By default, =elisp-read-source-file= can only access Emacs system directories and standard =ELPA= packages. For users of alternative package managers like straight.el, elpaca, or custom package setups, you can configure additional allowed directories: #+begin_src elisp (setq elisp-dev-mcp-additional-allowed-dirs '("~/.emacs.d/straight/build/" "~/.emacs.d/straight/repos/" "~/my-elisp-packages/")) #+end_src *Security Note:* Only add directories you trust, as this allows the MCP server to read any =.el= files in these locations. * License This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details.