Elisp Dev Mcp

What is Elisp Dev Mcp

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 in Elisp coding tasks by offering a structured API to interact with Emacs and manipulate Elisp code, leveraging the mcp-server-lib.el for its underlying infrastructure.

Use cases

This package is useful for developers who want to enhance their Elisp coding experience by integrating AI assistance. It allows for automatic retrieval of documentation, function definitions, and variable descriptions, thus streamlining the coding process and facilitating better understanding of existing code.

How to use

To use elisp-dev-mcp, first install mcp-server-lib and register elisp-dev-mcp with your MCP client. You can start the MCP server in Emacs with the command M-x mcp-server-lib-start and stop it with M-x mcp-server-lib-stop. Various handlers are available to perform tasks such as retrieving function definitions and variable descriptions.

Key features

Key features of elisp-dev-mcp include detailed documentation retrieval for functions and variables, sourcing of function definitions, looking up symbols in Info documentation, and reading Elisp source files. It ensures secure file access within allowed directories and can process compressed Elisp files seamlessly.

Where to use

elisp-dev-mcp is intended for use within Emacs, particularly in development environments where Elisp coding is performed. It’s suitable for developers and users of Emacs looking to leverage AI for enhanced coding and understanding of Emacs Lisp functionalities.

#+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]]

• 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

• 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
#+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
• Parameters:
  • =file-path=: Absolute path to =.el= file (string)
• Returns:
  • The complete file contents as a string
  • or =error=: Error message if file not found, invalid format, or access denied (string)
• Examples:
  • =“/opt/homebrew/Cellar/emacs-mac/emacs-29.1-mac-10.0/share/emacs/29.1/lisp/files.el”= - Read system file
  • =“/Users/name/.emacs.d/elpa/package-1.0/package.el”= - Read ELPA package
• Security:
  • Only reads from Emacs system lisp directories and =~/.emacs.d/elpa/=
  • Rejects paths with =…= traversal
  • Resolves symlinks to prevent escaping allowed directories
• Features:
  • Transparently handles =.el.gz= compressed files
  • Works directly with paths from =elisp-get-function-definition=
  • Returns complete file contents as string

• License

This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details.