Modex：Clojure 原生 MCP 服务器与客户端开发库

从一个客服场景说起

深夜，一家使用 Datomic 数据库的公司收到了客户的紧急告警：数据库连接异常。传统做法是工程师登录服务器，翻日志、查配置、判断网络——平均耗时数十分钟。但有了 Modex + MCP，AI 模型可以直接"看到"数据库 schema、执行查询、对比集群实际状态与期望状态，诊断时间压缩到分钟级。

这就是 Modex 的核心价值：让 AI 模型拥有真实世界的数据访问能力。

什么是 Model Context Protocol（MCP）

MCP 是 Anthropic 提出的开放协议，旨在标准化 AI 模型与外部工具/数据的交互方式。它定义了三种核心原语：

• Tools（工具）：AI 可以调用的函数，如查数据库、调 API、读文件
• Resources（资源）：AI 可以读取的数据，如 PDF 文档、数据库 schema
• Prompts（提示模板）：预定义的工作流指令

MCP 的传输层支持两种模式：stdio（标准输入/输出）和 SSE（Server-Sent Events）。Modex 选择原生实现 stdio，这意味着无需中间代理即可直接与 Claude Desktop 等客户端通信。

Modex 的诞生背景

在 Modex 出现之前，Clojure 开发者如果想在 MCP 生态中使用自己的语言，只能依赖 mcp-clj——但它使用 SSE 传输，需要额外的 mcp-proxy 进行协议转换，增加部署复杂度。作者 Petrus Theron 在生产环境中受够了这个障碍，于是用纯 Clojure 从头实现了 MCP。

Modex 的定位很明确：给 Clojure 开发者一个零妥协的 MCP 入口。

核心技术实现

数据结构

Modex 用 Clojure 记录（record）定义 MCP 核心对象：

(defrecord Tool [name doc args handler])
(defrecord Parameter [name doc type required default])

工具参数支持类型验证（string/number），可选参数通过 :or map 隐式标记。

JSON-RPC 2.0 通信

Modex 内部使用 JSON-RPC 2.0 格式封装消息，三种消息类型：

;; 请求
{:keys [id method ?params]}
;; 响应
{:keys [id result ?error]}
;; 通知（无 id）
{:keys [method ?params]}

宏设计

tool 和 tools 宏提供了声明式的工具定义 DSL，handler 支持 map 解构风格和废弃的 vector 参数风格：

(def add-tool
  (tools/tool
    (add [{:keys [x y]
           :type {x :number, y :number}
           :or {y 0}
           :doc {x "第一个数", y "第二个数"}}]
         [(+ x y)])))

服务器与客户端

(require '[modex.mcp.server :as server])
(def my-server
  (server/->server
    {:name "My MCP Server"
     :version "0.0.1"
     :initialize (fn [_init-params] ...)
     :tools my-tools
     :prompts nil
     :resources nil}))

(server/start-server! my-server)

技术栈一览

组件	技术选型
核心语言	Clojure 1.12
Schema 验证	metosin/malli 0.17
JSON 编解码	metosin/jsonista 0.3
日志	com.taoensso/timbre 6.7
REPL	nrepl 1.3
构建工具	io.github.clojure/tools.build
构建输出	Uberjar（可执行 JAR）

代码目录结构：

src/modex/mcp/
  client.clj      # MCP 客户端实现
  core.clj       # 核心示例
  json_rpc.clj   # JSON-RPC 2.0 编解码
  protocols.clj  # 协议定义
  reflection.clj # 反射工具
  schema.clj     # Schema 定义
  server.clj     # MCP 服务器实现
  tools.clj      # 工具宏与调用逻辑

上手体验

Modex 本身是一个开发库，而非开箱即用的应用。上手门槛中等：

1. 构建：运行 ./build.sh 或 clojure -T:build uber，生成 uberjar
2. 配置：在 Claude Desktop 配置文件中注册 MCP Server
3. 使用：重启 Claude Desktop，AI 即可调用注册的工具

对于不熟悉 Clojure 的开发者，JavaScript/TypeScript 生态有 modelcontextprotocol/spec 官方 SDK，C++/Python/Java 也各有官方实现，Modex 的差异化在于函数式编程范式的深度集成。

生产实践案例

Modex 已被以下公司采用：

• Nextdoc：Salesforce 文档流式处理，用 MCP 暴露内部文档 API
• Huppi：小型企业会计软件，用 MCP 连接账务数据库
• Datomic MCP：Petrus 自研项目，将 Datomic 数据库暴露给 Claude Desktop，用于生产支持问题自动诊断

现状与局限

已实现：

• ✓ MCP Server + Client（stdio 传输）
• ✓ 工具定义与调用（支持验证和错误处理）
• ✓ nREPL 实时调试
• ✓ 测试覆盖

未完成 / 规划中：

• ✗ Resources（资源读取）
• ✗ Prompts（提示模板）
• ⏳ SSE 传输支持（受限网络场景）
• ⏳ Streaming HTTP（2025-03-26 MCP spec）

许可限制：Modex 采用 GPLv3 开源，但商业使用需付费购买许可证（$20 一次性），这是值得注意的合规风险。

行业意义

MCP 正快速成为 AI Agent 领域的"USB 接口"——让不同厂商的模型与工具能互相连接。Modex 的出现补全了 Clojure 生态在这个趋势中的位置，虽然 118 颗星的影响力尚属早期，但其生产级实现（SSE 规划中、nREPL 调试、malli 验证）与商业采用记录值得关注。