Elisp Mcp Dev

What is Elisp Mcp Dev

elisp-mcp-dev is an Emacs package that provides a Machine Code Protocol (MCP) server for agentic Elisp development. It facilitates AI agents in assisting with Elisp coding tasks through a structured API for interacting with Emacs and manipulating Elisp code.

Use cases

Use cases include retrieving documentation for Elisp functions, obtaining function definitions, and leveraging AI agents to enhance productivity in Elisp development.

How to use

To use elisp-mcp-dev with an MCP client like Claude Code, register it using the emacs-mcp-stdio.sh script from mcp.el. Start the MCP server in Emacs with M-x mcp-start and stop it with M-x mcp-stop when finished.

Key features

Key features include Elisp function documentation retrieval, source code definition access, and structured API interactions for enhanced Elisp development with AI assistance.

Where to use

elisp-mcp-dev is primarily used in software development environments where Emacs is utilized for Elisp programming, particularly in projects that benefit from AI-assisted coding.

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