mcp.el

#+TITLE: mcp-server-lib.el - Model Context Protocol Server Library for Emacs Lisp [[https://github.com/laurynas-biveinis/mcp-server-lib.el/actions/workflows/elisp-test.yml][https://github.com/laurynas-biveinis/mcp-server-lib.el/actions/workflows/elisp-test.yml/badge.svg]] [[https://github.com/laurynas-biveinis/mcp-server-lib.el/actions/workflows/linter.yml][https://github.com/laurynas-biveinis/mcp-server-lib.el/actions/workflows/linter.yml/badge.svg]] [[https://melpa.org/#/mcp-server-lib][https://melpa.org/packages/mcp-server-lib-badge.svg]] [[https://stable.melpa.org/#/mcp-server-lib][file:https://stable.melpa.org/packages/mcp-server-lib-badge.svg]] * Overview =mcp-server-lib.el= is a library for building [[https://modelcontextprotocol.io/][Model Context Protocol]] (MCP) servers in Emacs Lisp. It provides the infrastructure for Emacs packages to expose their functionality as tools and resources to Large Language Models. * Features - Simple API for registering tools (Elisp functions) and resources - Multi-server support - Resource templates with URI pattern matching (RFC 6570 subset) - Handles MCP protocol communication and JSON-RPC messages - Stdio transport via emacsclient wrapper script - Built-in usage metrics and debugging support * Requirements - Emacs 27.1 or later - Running Emacs daemon (for stdio transport) * MCP servers built on this library - [[https://github.com/laurynas-biveinis/elisp-dev-mcp][elisp-dev-mcp]] - Elisp development support tools - [[https://github.com/laurynas-biveinis/org-mcp][org-mcp]] - read and write Org content * Installation From [[https://melpa.org/#/mcp-server-lib][MELPA]] or [[https://stable.melpa.org/#/mcp-server-lib][MELPA Stable]]: =M-x package-install RET mcp-server-lib RET= * For Users If you're using an MCP server built with this library: 1. Run =M-x mcp-server-lib-install= to install the stdio script 2. The script will be at =~/.emacs.d/emacs-mcp-stdio.sh= 3. Follow your MCP server's documentation for client registration Available commands: - =M-x mcp-server-lib-start= - Start the MCP server - =M-x mcp-server-lib-stop= - Stop the MCP server - =M-x mcp-server-lib-describe-setup= - View registered tools and resources with usage statistics - =M-x mcp-server-lib-show-metrics= - View usage metrics - =M-x mcp-server-lib-uninstall= - Remove the stdio script * For Developers To build your own MCP server, see [[https://github.com/laurynas-biveinis/elisp-dev-mcp][elisp-dev-mcp]] for a complete example. ** Client Registration Register your MCP server with a client using the stdio script: #+BEGIN_EXAMPLE claude mcp add -s user -t stdio your-server -- ~/.emacs.d/emacs-mcp-stdio.sh \ --init-function=your-init-func --stop-function=your-stop-func #+END_EXAMPLE Script options: - =--init-function=NAME= - Emacs function to call on startup - =--stop-function=NAME= - Emacs function to call on shutdown - =--socket=PATH= - Custom Emacs server socket (optional) - =--server-id=ID= - Explicit server identifier (optional, will become mandatory in the future) For debugging, set =EMACS_MCP_DEBUG_LOG= to a file path. ** API Reference *** Registering Tools #+begin_src elisp (mcp-server-lib-register-tool #'my-function :id "tool-name" :description "What this tool does" :title "Display Name" ; optional :read-only t ; optional :server-id "my-server") ; optional ;; Tool handler with one parameter (defun my-handler (location) "Get weather for LOCATION. MCP Parameters: location - city, address, or coordinates" (mcp-server-lib-with-error-handling ;; Your implementation )) ;; Tool handler with multiple parameters (defun update-todo-state (resource-uri current-state new-state) "Update TODO state of a task. MCP Parameters: resource-uri - URI of the task to update current-state - Current TODO state (or empty string) new-state - New TODO state to set" (mcp-server-lib-with-error-handling ;; Direct access to parameters, no alist-get needed (message "Updating %s from %s to %s" resource-uri current-state new-state))) (mcp-server-lib-register-tool #'update-todo-state :id "update-todo" :description "Update task TODO state" :server-id "my-server") ; optional #+end_src **** MCP Parameters Format Parameter descriptions in tool handler docstrings follow an indentation-based format: - Parameter definitions use 2-4 spaces: ~ param-name - description~ - Continuation lines use 6+ spaces: ~ additional text~ - Continuation lines can span multiple lines - All function parameters must be documented Example with multi-line parameter descriptions: #+begin_src elisp (defun fetch-content (url timeout) "Fetch content from a URL. MCP Parameters: url - web address to fetch Supports http, https, and file protocols Must be a valid URI timeout - seconds to wait before giving up Use 0 for no timeout" (mcp-server-lib-with-error-handling ;; Implementation )) #+end_src Tools can have zero, one, or multiple parameters. When a tool has multiple parameters, the JSON object fields from the client are automatically mapped to the function parameters by name (converting from camelCase to kebab-case as needed). Tools do not support =&rest= parameters. Tool handlers must return strings or =nil= (which is converted to an empty string). Other return types will cause an "Invalid Params" error. If a tool cannot complete its operation successfully, it should use =mcp-server-lib-tool-throw= for throwing an error or the implementation should be wrapped with =mcp-server-lib-with-error-handling=. Optional properties: - =:title= - User-friendly display name - =:read-only= - Set to =t= if tool doesn't modify state - =:server-id= - Server identifier (optional, defaults to ="default"=) *** Registering Resources The library uses a unified API for both static and templated resources. The presence of ={variable}= syntax automatically determines whether a resource is static or templated: #+begin_src elisp ;; Static resource (no variables) (mcp-server-lib-register-resource "resource://uri" (lambda () "resource content") :name "Resource Name" :description "What this provides" ; optional :mime-type "text/plain" ; optional :server-id "my-server") ; optional ;; Dynamic resource example (mcp-server-lib-register-resource "buffer://current" (lambda () (buffer-string)) :name "Current Buffer" :server-id "my-server") ; optional ;; Template resource with simple variable (mcp-server-lib-register-resource "org://{filename}" (lambda (params) (with-temp-buffer (insert-file-contents (alist-get "filename" params nil nil #'string=)) (buffer-string))) :name "Org file content" :description "Read any org file by name" :server-id "my-server") ; optional ;; Template with multiple variables (mcp-server-lib-register-resource "org://{filename}/headline/{+path}" (lambda (params) (let ((file (alist-get "filename" params nil nil #'string=)) (path (alist-get "path" params nil nil #'string=))) ;; path can contain slashes with {+path} (org-get-headline-content file path))) :name "Org headline" :description "Get specific headline from org file" :server-id "my-server") ; optional #+end_src Static resource handlers take no arguments and return strings. Template resource handlers receive an alist of parameters extracted from the URI. Supported template syntax (RFC 6570 subset): - ={variable}= - Simple variable expansion - ={+variable}= - Reserved expansion (allows slashes) Direct resources take precedence over templates when both match a URI. *** Resource Error Handling Resource handlers can signal specific JSON-RPC error codes to provide meaningful error information to clients: #+begin_src elisp ;; Signal that client provided invalid parameters (defun my-file-resource-handler (params) (let ((file (alist-get "filename" params nil nil #'string=))) (unless (file-exists-p file) (mcp-server-lib-resource-signal-error mcp-server-lib-jsonrpc-error-invalid-params (format "File not found: %s" file))) (with-temp-buffer (insert-file-contents file) (buffer-string)))) ;; Signal an internal server error (defun my-database-resource-handler () (unless (database-connected-p) (mcp-server-lib-resource-signal-error mcp-server-lib-jsonrpc-error-internal "Database connection unavailable")) (query-database)) #+end_src Available error codes: - =mcp-server-lib-jsonrpc-error-invalid-params= (-32602): Client provided invalid parameters, resource not found - =mcp-server-lib-jsonrpc-error-internal= (-32603): Server-side processing error It is also possible to use regular =error= or =signal= calls, which would return internal error (-32603). *** Working with Resource Templates Resource template handlers receive extracted parameters as an alist. These parameters are matched from the URI but not automatically decoded - if you're working with file paths that might contain special characters, you'll want to decode them: #+begin_src elisp (mcp-server-lib-register-resource "file://{path}" (lambda (params) (let ((path (alist-get "path" params nil nil #'string=))) ;; Decode if needed for filesystem access (with-temp-buffer (insert-file-contents (url-unhex-string path)) (buffer-string)))) :name "File reader" :server-id "my-server") ; optional #+end_src Variable names in templates follow simple rules - stick to letters, numbers, and underscores. The URI scheme (like =file://= or =org://=) needs to be a valid URI scheme starting with a letter. URI schemes are case-insensitive per RFC 3986, so =HTTP://example.com= will match a template registered as =http://{domain}=. When multiple templates could match the same URI, which template is selected is undefined and depends on implementation details. Avoid registering overlapping templates. Templates can match empty values too - =org://= will match =org://{filename}= with an empty filename. Literal segments in templates must match exactly - =test://items/{id}= will match =test://items/123= but not =test://item/123=. The implementation uses non-greedy (first-match) behavior when matching variables. For example, =test://{name}.txt= matching =test://file.config.txt= extracts =name="file.config"=, not =name="file.config.txt"=. To unregister any resource (static or templated): #+begin_src elisp (mcp-server-lib-unregister-resource "org://{filename}" :server-id "my-server") (mcp-server-lib-unregister-resource "resource://uri" :server-id "my-server") #+end_src *** Resource Lists When clients request the resource list, direct resources appear with a =uri= field while templates show up with a =uriTemplate= field. This helps clients distinguish between static resources and dynamic patterns they can use. *** Constants =mcp-server-lib-name= - The name of the MCP server ("emacs-mcp-server-lib") =mcp-server-lib-protocol-version= - The MCP protocol version supported by this server ("2025-03-26") *** Utility Functions For testing and debugging: #+begin_src elisp ;; Create JSON-RPC requests (mcp-server-lib-create-tools-list-request &optional id) (mcp-server-lib-create-tools-call-request tool-name &optional id args) (mcp-server-lib-create-resources-list-request &optional id) (mcp-server-lib-create-resources-read-request uri &optional id) ;; Process requests and get parsed response (mcp-server-lib-process-jsonrpc-parsed request) ;; Server management (mcp-server-lib-start) (mcp-server-lib-stop) #+end_src *** Test Utilities The =mcp-server-lib-ert= module provides utilities for writing ERT tests for MCP servers: **** Server Context Variable Test helper functions use the dynamic variable =mcp-server-lib-ert-server-id= to determine which server to operate on. Child packages testing a single server should set this once at the top of their test file: #+begin_src elisp ;; At the top of your test file (setq mcp-server-lib-ert-server-id "my-mcp-server") #+end_src **** Test Helper Functions #+begin_src elisp ;; Track metrics changes during test execution (mcp-server-lib-ert-with-metrics-tracking ((method expected-calls expected-errors) ...) ;; Test code here ) ;; Example: Verify a method is called once with no errors (mcp-server-lib-ert-with-metrics-tracking (("tools/list" 1 0)) ;; Code that should call tools/list once (mcp-server-lib-process-jsonrpc-parsed (mcp-server-lib-create-tools-list-request))) ;; Simplified syntax for verifying successful single method calls (mcp-server-lib-ert-verify-req-success "tools/list" (mcp-server-lib-process-jsonrpc-parsed (mcp-server-lib-create-tools-list-request))) ;; Process a request and get the successful result (let* ((request (mcp-server-lib-create-tools-list-request)) (tools (mcp-server-lib-ert-get-success-result "tools/list" request))) ;; tools contains the result field from the response (should (arrayp tools))) ;; High-level tool testing helper - simplifies tool calls ;; This function combines request creation, processing, metrics verification, ;; and text extraction into a single call (let* ((params '(("name" . "John") ("greeting" . "Hello"))) (result (mcp-server-lib-ert-call-tool "greet-user" params))) (should (string= "Hello, John!" result))) ;; Get resource list (convenience function) (let ((resources (mcp-server-lib-ert-get-resource-list))) (should (= 2 (length resources))) (should (string= "test://resource1" (alist-get 'uri (aref resources 0))))) ;; Check error response structure (mcp-server-lib-ert-check-error-object response -32601 "Method not found") ;; Verify resource read succeeds with expected fields (mcp-server-lib-ert-verify-resource-read "test://resource1" '((uri . "test://resource1") (mimeType . "text/plain") (text . "test result"))) ;; Run tests with MCP server (mcp-server-lib-ert-with-server :tools nil :resources nil ;; Server is started, initialized, and will be stopped after body (let ((response (mcp-server-lib-process-jsonrpc-parsed (json-encode '(("jsonrpc" . "2.0") ("method" . "tools/list") ("id" . 1)))))) (should-not (alist-get 'error response)))) #+end_src *** JSON-RPC Error Constants The library provides public constants for standard JSON-RPC 2.0 error codes: #+begin_src elisp mcp-server-lib-jsonrpc-error-parse ; -32700 Parse Error mcp-server-lib-jsonrpc-error-invalid-request ; -32600 Invalid Request mcp-server-lib-jsonrpc-error-method-not-found ; -32601 Method Not Found mcp-server-lib-jsonrpc-error-invalid-params ; -32602 Invalid Params mcp-server-lib-jsonrpc-error-internal ; -32603 Internal Error #+end_src These constants can be used when checking error responses in tests: #+begin_src elisp (mcp-server-lib-ert-check-error-object response mcp-server-lib-jsonrpc-error-method-not-found "Method not found") #+end_src *** Debugging Enable JSON-RPC message logging: #+begin_src elisp (setq mcp-server-lib-log-io t) ; Log to *mcp-server-lib-log* buffer #+end_src View usage metrics: #+begin_src elisp M-x mcp-server-lib-show-metrics M-x mcp-server-lib-reset-metrics #+end_src ** Customization To install the script to a different location: #+begin_src elisp (setq mcp-server-lib-install-directory "/path/to/directory") #+end_src * Troubleshooting - **Script not found**: Run =M-x mcp-server-lib-install= first - **Connection errors**: Ensure Emacs daemon is running - **Debugging**: Set =mcp-server-lib-log-io= to =t= and check =*mcp-server-lib-log*= buffer * Similar packages - https://github.com/utsahi/mcp-server.el - https://github.com/rhblind/emacs-mcp-server * License This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details. * Acknowledgments - [[https://modelcontextprotocol.io/][Model Context Protocol]] specification - [[https://github.com/modelcontextprotocol/python-sdk][Python MCP SDK]] implementation