mcp-clj

mcp-clj

使用 Clojure 实现的 Model Context Protocol（MCP），依赖精简，并可在独立的 Clojure REPL 中集成。

快速入门

# Add to deps.edn
{:deps {org.hugoduncan/mcp-clj
        {:git/url   "https://github.com/hugoduncan/mcp-clj"
         :git/sha   "latest-commit-sha"
         :deps/root "projects/server"}}}

;; Start MCP server
(require 'mcp-clj.mcp-server.core)
(def server (mcp-clj.mcp-server.core/create-server {:transport {:type :stdio}}))

;; Server exposes tools like clj-eval and ls
;; Connect with Claude Desktop via stdio transport (see Claude Desktop Setup)

跳转至： 安装 • 客户端用法 • Claude Code 设置 • Claude Desktop 设置 • 开发

是什么以及为什么使用

mcp-clj 提供 Clojure 版本的 MCP 服务和客户端实现：

• 独立 REPL：直接在服务进程中运行 Clojure（不依赖 nREPL）
• 依赖精简：仅需 org.clojure/data.json
• 多种传输方式：SSE（HTTP）、stdio 和用于测试的内存传输
• 内置工具：Clojure 求值（clj-eval）和文件列表（ls），支持 gitignore
• MCP 客户端：从 Clojure 连接到其他 MCP 服务

适用场景：

• 向 Claude Desktop 或其他 MCP 客户端开放 Clojure REPL 功能
• 构建使用 MCP 服务的 Clojure 应用
• 无需外部 REPL 依赖即可轻松部署

与 clojure-mcp 相比的取舍：

• ✅ 设置更简单，求值功能独立运行
• ❌ 无法连接到现有的远程 REPL
• ❌ 内置工具较少

安装

Git 依赖（推荐）

;; deps.edn
{:deps {org.hugoduncan/mcp-clj
        {:git/url   "https://github.com/hugoduncan/mcp-clj"
         :git/sha   "latest-commit-sha"  ; Replace with actual latest SHA
         :deps/root "projects/server"}}}

CLI 用法

# Clone and run directly
git clone https://github.com/hugoduncan/mcp-clj
cd mcp-clj

# Start stdio server (recommended for Claude Desktop)
clj -M:stdio-server

# Start SSE server (HTTP) on port 3001 (default)
clj -M:sse-server

# Start SSE server on custom port
clj -M:sse-server --port 8080

服务用法

基本服务

(require 'mcp-clj.mcp-server.core)

;; Stdio server (recommended for Claude Desktop)
(def server (mcp-clj.mcp-server.core/create-server
             {:transport {:type :stdio}}))

;; SSE server (for HTTP-based clients)
(def server (mcp-clj.mcp-server.core/create-server
             {:transport {:type :sse :port 3001}}))

;; Stop server
((:stop server))

自定义工具

(def echo-tool
  {:name "echo"
   :description "Echo the input text"
   :inputSchema {:type "object"
                 :properties {"text" {:type "string"}}
                 :required ["text"]}
   :implementation (fn [{:keys [text]}]
                     {:content [{:type "text" :text text}]
                      :isError false})})

;; Server with custom tools
(def server (mcp-clj.mcp-server.core/create-server
             {:transport {:type :sse :port 3001}
              :tools {"echo" echo-tool}}))

;; Add tools dynamically
(mcp-clj.mcp-server.core/add-tool! server echo-tool)

内置工具

clj-eval：求值 Clojure 表达式

{"name": "clj-eval", "arguments": {"code": "(+ 1 2 3)"}}
// Returns: "6"

ls：列出文件，支持 gitignore

{"name": "ls", "arguments": {"path": "src", "max-depth": 2, "max-files": 50}}
// Returns: {"files": [...], "truncated": false, "total-files": 12}

客户端用法

从 Clojure 连接到其他 MCP 服务：

(require 'mcp-clj.mcp-client.core)

;; Connect to stdio MCP server
(def client (mcp-clj.mcp-client.core/create-client
             {:transport {:type :stdio
                          :command "clojure"
                          :args ["-M:stdio-server"]}
              :client-info {:name "my-client" :version "1.0.0"}}))

;; Wait for connection
(mcp-clj.mcp-client.core/wait-for-ready client)

;; List available tools
(mcp-clj.mcp-client.core/list-tools client)
;; => {:tools [{:name "clj-eval" :description "..." :inputSchema {...}}]}

;; Call a tool
@(mcp-clj.mcp-client.core/call-tool client "clj-eval" {:code "(* 6 7)"})
;; => {:content [{:type "text" :text "42"}] :isError false}

;; Cleanup
(.close client)

Claude Code 设置

Claude Code 可以通过 stdio 传输方式连接到 mcp-clj 服务。

1. 将 mcp-clj 添加到项目中

在你的 deps.edn 中：

{:aliases
 {:mcp {:extra-deps {org.hugoduncan/mcp-clj
        {:git/url   "https://github.com/hugoduncan/mcp-clj"
         :git/sha   "latest-commit-sha"
         :deps/root "projects/server"}}
 :main-opts ["-m" "mcp-clj.stdio-server.main"]}}}

2. 配置 Claude Code

使用 Claude Code 的 CLI 添加 MCP 服务：

claude mcp add mcp-clj clojure -M:mcp

3. 测试连接

# Verify the MCP server is configured and accessible
claude mcp list

你应该会在可用服务列表中看到 mcp-clj。Claude Code 现在可以在项目上下文中使用 clj-eval 和 ls 工具。

Claude Desktop 设置

Claude Desktop 可以通过 stdio 传输方式直接连接到 mcp-clj，无需额外的代理工具。

1. 将 mcp-clj 添加到项目中

在你的 deps.edn 中：

{:deps {org.hugoduncan/mcp-clj
        {:git/url   "https://github.com/hugoduncan/mcp-clj"
         :git/sha   "latest-commit-sha"
         :deps/root "projects/server"}}

 :aliases
 {:mcp {:main-opts ["-m" "mcp-clj.stdio-server.main"]}}}

2. 配置 Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-clj": {
      "command": "/opt/homebrew/bin/bash",
      "args": [
        "-c",
        "cd /path/to/your/project && clojure -M:mcp"
      ],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

注意：将 /path/to/your/project 替换为你的实际项目目录，并根据需要调整 bash 路径（使用 which bash 查找你的路径）。

3. 重启 Claude Desktop

Claude 现在可以在项目上下文中使用 clj-eval 和 ls 工具。

开发

设置

git clone https://github.com/hugoduncan/mcp-clj
cd mcp-clj

# Start REPL with all components
clj -M:dev

测试

# Fast unit tests (default)
clj -M:kaocha:dev:test

# Integration tests (starts servers)
clj -M:kaocha:dev:test --focus :integration

# All tests
clj -M:kaocha:dev:test --focus :unit :integration

# Specific namespace
clj -M:kaocha:dev:test --focus mcp-clj.mcp-server.core-test

REPL 开发

;; After adding dependencies to deps.edn
(require 'clojure.repl.deps)
(clojure.repl.deps/sync-deps)

;; Reload namespace
(require 'my.namespace :reload)

;; Run tests
(require 'clojure.test)
(clojure.test/run-tests 'mcp-clj.mcp-server.core-test)

更新日志

请参阅 CHANGELOG.md，了解发行说明和版本历史。

在本地生成更新日志

安装 git-cliff：

# macOS
brew install git-cliff

# Or download from https://github.com/orhun/git-cliff/releases

生成更新日志：

# Preview unreleased changes
git cliff --unreleased

# Update CHANGELOG.md
git cliff -o CHANGELOG.md

架构

mcp-clj 采用类似 polylith 的架构，以组件为单位组织：

• 组件（components/）- 可复用功能（mcp-server、mcp-client、json-rpc、tools 等）
• 基础入口（bases/）- 入口点（sse-server、stdio-server）
• 项目（projects/server/）- 可部署的构件

核心组件

• mcp-server/ - MCP 协议服务，包含工具、提示词和资源
• mcp-client/ - 用于连接到服务的 MCP 协议客户端
• json-rpc/ - JSON-RPC 2.0，支持 EDN/JSON 自动转换
• tools/ - 内置 MCP 工具（clj-eval、ls）
• *-transport/ - 多种传输层（SSE、stdio、HTTP、内存）

所有组件均使用 mcp-clj 命名空间，并遵循 JSON-RPC 2.0 和 MCP 协议版本 2024-11-05。

参与贡献

1. Fork 仓库
2. 创建功能分支
3. 修改代码并确保测试通过：clj -M:kaocha:dev:test
4. 提交 pull request

许可证

MIT 许可证。详情请参阅 LICENSE 文件。