40ants-mcp - The framework for building MCP servers and clients in Common Lisp.

40ANTS-MCP ASDF System Details

• Description: The framework for building MCP servers and clients in Common Lisp.
• Licence: Unlicense
• Author: Alexander Artemenko [email protected]
• Homepage: https://40ants.com/mcp/
• Bug tracker: https://github.com/40ants/mcp/issues
• Source control: GIT
• Depends on: alexandria, bordeaux-threads, cl-ppcre, clack, clack-sse, jsonrpc, lack, lack-request, lack-response, local-time, log4cl, log4cl-extras, openrpc-client, openrpc-server, sento, serapeum, sse-server, trivial-gray-streams, uuid, yason

About

A comprehensive framework for building Model Context Protocol (MCP) servers in Common Lisp. This library provides a complete implementation of the MCP specification with an easy-to-use API for creating servers that can interact with AI assistants like Claude Desktop.

Active development is ongoing and the interface is likely to change.

Features

• ✅ STDIO Transport: Native support for STDIO-based communication
• ✅ StreamableHTTP Transport: Allowing to create remotely hosted MCP servers
• ✅ Tools System: Register and execute custom tools with JSON Schema validation
• ✅ Built on OpenRPC: Leverages the robust 40ants OpenRPC library
• ✅ CLOS-based: Object-oriented design with proper encapsulation
• ✅ Easy Integration: Simple API for adding functionality
• ✅ Error Handling: Comprehensive error management with proper JSON-RPC error codes
• ✅ Interactive Editing: MCP tools can be edited and updated on the fly, using REPL driven approach

Roadmap

• 🔄 Full MCP Specification Support: Complete implementation of MCP protocol version 2025-06-18
• 🔄 Resources System: Serve dynamic and static resources via URI
• 🔄 Prompts System: Provide prompt templates with argument interpolation
• 🔄 MCP Client Protocol: Implement client-side protocol for connecting to MCP servers

Installation

You can install this library from Quicklisp, but you want to receive updates quickly, then install it from Ultralisp.org:

(ql-dist:install-dist "http://dist.ultralisp.org/"
                      :prompt nil)
(ql:quickload :40ants-mcp)

Usage

Here's a quick example of how to create an MCP server with custom tools:

(defpackage #:my-mcp-server
  (:use #:cl)
  (:import-from #:40ants-mcp/content/text
                #:text-content)
  (:import-from #:openrpc-server))

(in-package #:my-mcp-server)

;; Define your API
(openrpc-server:define-api (my-tools :title "My Custom Tools"))

;; Define a tool that adds two numbers
(40ants-mcp/tools:define-tool (my-tools add) (a b)
  (:summary "Adds two numbers and returns the result.")
  (:param a integer "First number to add.")
  (:param b integer "Second number to add.")
  (:result (soft-list-of text-content))
  (list (make-instance 'text-content
                      :text (format nil "The sum of ~A and ~A is: ~A"
                                  a b (+ a b)))))

;; Start the server
(40ants-mcp/server/definition:start-server my-tools)

Running as a Script

For production use, you can create a Roswell script. Create a file my-mcp.ros:

#!/bin/sh
#|-*- mode:lisp -*-|#
#|
exec ros -Q -- $0 \"$@\"
|#

(ql:quickload '(:40ants-mcp :alexandria) :silent t)

;; Your package and tool definitions here...

(defun main (&rest argv)
  (declare (ignore argv))
  (40ants-mcp/server/definition:start-server my-tools))

Build and run the script:

# Build the script
ros build my-mcp.ros

# Run the server
./my-mcp

# With remote debugging support
SLYNK_PORT=4005 ./my-mcp

Each tool you define should return a list of content items. The most common content type is text-content, but you can also return other types defined in the MCP specification.

For more examples, check the examples/ directory in the source code.

API

40ANTS-MCP/CONTENT/BASE

package 40ants-mcp/content/base

Classes

CONTENT

class 40ants-mcp/content/base:content ()

Readers

reader 40ants-mcp/content/base:content-type (content) (:TYPE = "unknown")

40ANTS-MCP/CONTENT/TEXT

package 40ants-mcp/content/text

Classes

TEXT-CONTENT

class 40ants-mcp/content/text:text-content (content)

Readers

reader 40ants-mcp/content/text:content-text (text-content) (:text)

40ANTS-MCP/HTTP-TRANSPORT

package 40ants-mcp/http-transport

Classes

HTTP-TRANSPORT

class 40ants-mcp/http-transport:http-transport ()

HTTP transport implementation for MCP (Model Context Protocol) communication. This class handles JSON-RPC message exchange via HTTP POST requests.

Readers

reader 40ants-mcp/http-transport:transport-lack-app (http-transport) ()

Lack application instance

reader 40ants-mcp/http-transport:transport-message-handler (http-transport) ()

Function to handle incoming messages

reader 40ants-mcp/http-transport:transport-port (http-transport) (:port = 8080)

Port number to listen on.

reader 40ants-mcp/http-transport:transport-running-p (http-transport) (= t)

Flag indicating if transport is active

reader 40ants-mcp/http-transport:transport-server (http-transport) ()

Clack server instance

Accessors

accessor 40ants-mcp/http-transport:transport-lack-app (http-transport) ()

Lack application instance

accessor 40ants-mcp/http-transport:transport-message-handler (http-transport) ()

Function to handle incoming messages

accessor 40ants-mcp/http-transport:transport-running-p (http-transport) (= t)

Flag indicating if transport is active

accessor 40ants-mcp/http-transport:transport-server (http-transport) ()

Clack server instance

40ANTS-MCP/SERVER/DEFINITION

package 40ants-mcp/server/definition

Classes

MCP-SERVER

class 40ants-mcp/server/definition:mcp-server (api)

Readers

reader 40ants-mcp/server/definition:server-tools-collections (mcp-server) (collections = nil)

Functions

function 40ants-mcp/server/definition:start-server tools-collections &key (transport :stdio) (port 8080)

Start the MCP server with specified transport. TRANSPORT can be :stdio or :http. PORT is only used when transport is :http.

40ANTS-MCP/SERVER/ERRORS

package 40ants-mcp/server/errors

Classes

TOOL-ERROR

condition 40ants-mcp/server/errors:tool-error ()

You should signal this error in case if the tool can't accomplish it's job.

Readers

reader 40ants-mcp/server/errors:tool-error-content (tool-error) (:content)

40ANTS-MCP/STDIO-TRANSPORT

package 40ants-mcp/stdio-transport

Classes

STDIO-TRANSPORT

class 40ants-mcp/stdio-transport:stdio-transport ()

STDIO transport implementation for MCP (Model Context Protocol) communication. This class handles JSON-RPC message exchange via standard input/output streams. It is designed to work with the MCP protocol specification for AI model communication.

Readers

reader 40ants-mcp/stdio-transport:transport-input (stdio-transport) (:input-stream = *standard-input*)

Input stream for reading JSON-RPC messages. Defaults to standard-input.

reader 40ants-mcp/stdio-transport:transport-output (stdio-transport) (:output-stream = *standard-output*)

Output stream for writing JSON-RPC responses. Defaults to standard-output.

reader 40ants-mcp/stdio-transport:transport-running-p (stdio-transport) (= t)

Flag indicating if transport is active and processing messages.

Accessors

accessor 40ants-mcp/stdio-transport:transport-input (stdio-transport) (:input-stream = *standard-input*)

Input stream for reading JSON-RPC messages. Defaults to standard-input.

accessor 40ants-mcp/stdio-transport:transport-output (stdio-transport) (:output-stream = *standard-output*)

Output stream for writing JSON-RPC responses. Defaults to standard-output.

accessor 40ants-mcp/stdio-transport:transport-running-p (stdio-transport) (= t)

Flag indicating if transport is active and processing messages.

Generics

generic-function 40ants-mcp/transport/base:receive-message transport

Receive a JSON-RPC message, returns a message or NIL.

generic-function 40ants-mcp/transport/base:send-message transport message

Send a JSON-RPC message, returns no values.

40ANTS-MCP/TOOLS

package 40ants-mcp/tools

Macros

macro 40ants-mcp/tools:define-tool name args &body body

40ANTS-MCP/TRANSPORT/BASE

package 40ants-mcp/transport/base

Generics

generic-function 40ants-mcp/transport/base:receive-message transport

Receive a JSON-RPC message, returns a message or NIL.

generic-function 40ants-mcp/transport/base:send-message transport message

Send a JSON-RPC message, returns no values.

generic-function 40ants-mcp/transport/base:start-loop transport message-handler

Starts message processing using given transport.

generic-function 40ants-mcp/transport/base:stop-loop transport

Stops message processing using given transport.

---

[generated by 40ANTS-DOC]