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 <svetlyak.40wt@gmail.com>

• 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

Classes

CONTENT

Readers

40ANTS-MCP/CONTENT/TEXT

Classes

TEXT-CONTENT

Readers

40ANTS-MCP/HTTP-TRANSPORT

Classes

HTTP-TRANSPORT

Readers

Accessors

40ANTS-MCP/SERVER/DEFINITION

Classes

MCP-SERVER

Readers

Functions

40ANTS-MCP/SERVER/ERRORS

Classes

TOOL-ERROR

Readers

40ANTS-MCP/STDIO-TRANSPORT

Classes

STDIO-TRANSPORT

Readers

Accessors

Generics

40ANTS-MCP/TOOLS

Macros

40ANTS-MCP/TRANSPORT/BASE

Generics