io.modelcontext/clojure-sdk

io.modelcontext/clojure-sdk

Model Context Protocol サーバーを作成するための clojure-sdk です！

目次 :TOC_4:

• io.modelcontext/clojure-sdk
  • 使い方
    • 依存関係
    • クイックスタート用テンプレート
    • 例
      • 例の JAR のビルド
      • Calculator：calculator_server
      • Vega-lite：vegalite_server
      • コード分析：code_analysis_server
  • コアコンポーネント
  • 通信フロー
  • 保留中の作業
  • SDK の開発
  • 着想元
  • ライセンス

使い方

calculator_server.clj ファイル と vegalite_server.clj ファイル には、MCP サーバーを定義するための完全に動作するコード例が含まれています。

examples は deps-new アプリプロジェクトです。さまざまなサーバー例のコンパイルと実行手順は、examples/README.md ファイル に記載されています（このセクションの下にも掲載しています）。

依存関係

clojure-sdk の依存関係は次のとおりです。

{io.modelcontextprotocol/mcp-clojure-sdk
 {:git/url "https://github.com/unravel-team/mcp-clojure-sdk.git"
  :git/sha "d42474c5f66b6f5ad1e4d6ce2a4e8972640fb831"}}

クイックスタート用テンプレート

簡単に使えるように、deps-new テンプレートと Github テンプレートも用意されています。詳しくは次をご覧ください。

1. mcp-clojure-server-deps-new 新しい MCP サーバーをすばやく作成するための、deps-new ベースのテンプレートです。
2. example-cool-mcp-server 新しい MCP サーバーをすばやく作成するための Github テンプレートプロジェクトです。

例

例の JAR のビルド

$ make clean && make examples-jar

例の JAR には、次のサーバーが含まれています。

1. Calculator：calculator_server
2. Vega-lite：vegalite_server
3. コード分析：code_analysis_server

Calculator：calculator_server

基本的な算術ツールを提供します：add、subtract、multiply、 divide、power、square-root、average、factorial

Claude Desktop または Inspector で試せるコマンドの例：

1. [1, 2, 3, 4, 5] の平均はいくつですか？
2. 15 の階乗はいくつですか？
3. 2 の 1000 乗はいくつですか？
4. 64 の平方根はいくつですか？

calculator MCP サーバーを実行する前に：

次の点に注意してください。

1. システム上の例の JAR のフルパスを使用してください

Claude Desktop の場合

    "calculator": {
      "command": "java",
      "args": [
        "-Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory",
        "-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog",
        "-Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector",
        "-Dlog4j2.configurationFile=log4j2-mcp.xml",
        "-Dbabashka.json.provider=metosin/jsonista",
        "-Dlogging.level=INFO",
        "-cp",
        "/Users/vedang/mcp-clojure-sdk/examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar",
        "calculator_server"
      ]
    }

MCP Inspector の場合

npx @modelcontextprotocol/inspector java -Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog -Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector -Dlog4j2.configurationFile=log4j2-mcp.xml -Dbabashka.json.provider=metosin/jsonista -Dlogging.level=INFO -cp examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar calculator_server

Vega-lite：vegalite_server

Vega-lite チャートを生成するツールを提供します：save-data、 visualize-data。

前提条件： vl-convert CLI をインストールする必要があります。

Claude Desktop または Inspector で試せるコマンドの例：

次のサンプルデータを使ってください。

[
    { "year": 2011, "value": 14.6, "growth_type": "Market Cap Growth" },
    { "year": 2011, "value": 11.4, "growth_type": "Revenue Growth" },
    { "year": 2011, "value": 26.6, "growth_type": "Net Income Growth" },
    { "year": 2012, "value": 40.1, "growth_type": "Market Cap Growth" },
    { "year": 2012, "value": 42.7, "growth_type": "Revenue Growth" },
    { "year": 2012, "value": 36.9, "growth_type": "Net Income Growth" },
    { "year": 2013, "value": 16.9, "growth_type": "Market Cap Growth" },
    { "year": 2013, "value": 14.6, "growth_type": "Revenue Growth" },
    { "year": 2013, "value": 15.3, "growth_type": "Net Income Growth" },
    { "year": 2014, "value": 9.6, "growth_type": "Market Cap Growth" },
    { "year": 2014, "value": 7.9, "growth_type": "Revenue Growth" },
    { "year": 2014, "value": 10.9, "growth_type": "Net Income Growth" },
    { "year": 2015, "value": 5.8, "growth_type": "Market Cap Growth" },
    { "year": 2015, "value": 6.7, "growth_type": "Revenue Growth" },
    { "year": 2015, "value": 6.2, "growth_type": "Net Income Growth" },
    { "year": 2016, "value": -12.4, "growth_type": "Market Cap Growth" },
    { "year": 2016, "value": -3.9, "growth_type": "Revenue Growth" },
    { "year": 2016, "value": -32.2, "growth_type": "Net Income Growth" },
    { "year": 2017, "value": 25.3, "growth_type": "Market Cap Growth" },
    { "year": 2017, "value": 5.9, "growth_type": "Revenue Growth" },
    { "year": 2017, "value": 43.9, "growth_type": "Net Income Growth" }
]

このデータを Vega-lite で可視化してください。

vegalite MCP サーバーを実行する前に

次の点に注意してください。

1. 例の JAR のフルパスを、システム上の正しいパスに置き換えてください
2. システム上の vl-convert のフルパスを指定してください

Claude Desktop の場合

    "vegalite": {
      "command": "java",
      "args": [
        "-Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory",
        "-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog",
        "-Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector",
        "-Dlog4j2.configurationFile=log4j2-mcp.xml",
        "-Dbabashka.json.provider=metosin/jsonista",
        "-Dlogging.level=INFO",
        "-Dmcp.vegalite.vl_convert_executable=/Users/vedang/.cargo/bin/vl-convert",
        "-cp",
        "/Users/vedang/mcp-clojure-sdk/examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar",
        "vegalite_server"
      ]
    }

MCP Inspector の場合

システム上の例の JAR のフルパスを使用するか、mcp-clojure-sdk リポジトリからこのコマンドを実行してください。

npx @modelcontextprotocol/inspector java -Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog -Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector -Dlog4j2.configurationFile=log4j2-mcp.xml -Dbabashka.json.provider=metosin/jsonista -Dlogging.level=INFO -Dmcp.vegalite.vl_convert_executable=/Users/vedang/.cargo/bin/vl-convert -cp examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar vegalite_server

コード分析：code_analysis_server

このサーバーは、ツールではなくプロンプトを提供するサーバーの例です。次のプロンプトを利用できます：analyse-code と poem-about-code。

Claude Desktop または Inspector でプロンプトを試すことができます。これらのプロンプトは非常に基本的なものですが、この手法で強力なプロンプトを公開する方法を確認するのに適しています。

code-analysis MCP サーバーを実行する前に

次の点に注意してください。

1. 例の JAR のフルパスを、システム上の正しいパスに置き換えてください

Claude Desktop の場合

    "code-anaylsis": {
      "command": "java",
      "args": [
        "-Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory",
        "-Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog",
        "-Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector",
        "-Dlog4j2.configurationFile=log4j2-mcp.xml",
        "-Dbabashka.json.provider=metosin/jsonista",
        "-Dlogging.level=INFO",
        "-cp",
        "/Users/vedang/mcp-clojure-sdk/examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar",
        "code_analysis_server"
      ]
    }

MCP Inspector 内

（お使いのシステム上の examples JAR のフルパスを使用するか、 mcp-clojure-sdk リポジトリからこのコマンドを実行してください）

npx @modelcontextprotocol/inspector java -Dclojure.tools.logging.factory=clojure.tools.logging.impl/log4j2-factory -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog -Dlog4j2.contextSelector=org.apache.logging.log4j.core.async.AsyncLoggerContextSelector -Dlog4j2.configurationFile=log4j2-mcp.xml -Dbabashka.json.provider=metosin/jsonista -Dlogging.level=INFO -cp examples/target/io.modelcontextprotocol.clojure-sdk/examples-1.2.0.jar code_analysis_server

コアコンポーネント

1. サーバーの実装：サーバーの中核機能は server.clj に実装されており、さまざまな MCP メソッドの リクエスト／レスポンスのサイクルを処理します。

2. トランスポート層：SDK は stdio_server.clj で STDIO トランスポートを実装し、 io_chan.clj を使用して IO ストリームと core.async チャネル間を変換します。

3. エラー処理：カスタムエラー処理は mcp/errors.clj で定義されています。

4. プロトコル仕様：すべてのプロトコル仕様は specs.clj で定義されており、リクエスト、レスポンス、 サーバーコンポーネントの検証を行います。

通信フロー

シーケンス図は、MCP クライアントとサーバー間のやり取りにおける 典型的なライフサイクルを示しています。

1. 初期化フェーズ：

   • クライアントが接続し、initialize リクエストを送信します
   • サーバーが自身の機能を応答します
   • クライアントが initialized 通知で確認します

2. 探索フェーズ：

   • クライアントは tools/list、resources/list、prompts/list メソッドを使用して、 利用可能なツール、リソース、プロンプトを探索します
   • これらはコンテキストの作成時にサーバーへ登録されます

3. ツールの利用：

   • クライアントは引数を指定してツールを呼び出せます
   • サーバーは適切なハンドラー関数に処理を振り分けます
   • 結果がクライアントに返されます

4. リソースの利用：

   • クライアントは URI を指定してリソースを読み取れます
   • サーバーはリソースの内容を取得します

5. プロンプトの利用：

   • クライアントは定義済みのプロンプトをリクエストできます
   • サーバーは適切なメッセージを返します

6. オプション機能：

   • 更新を受け取るためのリソースサブスクリプション
   • ping／pong によるヘルスチェック

sequenceDiagram
    participant Client
    participant MCPServer
    participant Tool
    participant Resource
    participant Prompt

    Note over Client,MCPServer: Initialization Phase
    Client->>+MCPServer: initialize
    MCPServer-->>-Client: initialize response (capabilities)
    Client->>MCPServer: notifications/initialized

    Note over Client,MCPServer: Discovery Phase
    Client->>+MCPServer: tools/list
    MCPServer-->>-Client: List of available tools

    Client->>+MCPServer: resources/list
    MCPServer-->>-Client: List of available resources

    Client->>+MCPServer: prompts/list
    MCPServer-->>-Client: List of available prompts

    Note over Client,MCPServer: Tool Interaction
    Client->>+MCPServer: tools/call (name, arguments)
    MCPServer->>+Tool: handler(arguments)
    Tool-->>-MCPServer: result
    MCPServer-->>-Client: Tool response

    Note over Client,MCPServer: Resource Interaction
    Client->>+MCPServer: resources/read (uri)
    MCPServer->>+Resource: handler(uri)
    Resource-->>-MCPServer: contents
    MCPServer-->>-Client: Resource contents

    Note over Client,MCPServer: Prompt Interaction
    Client->>+MCPServer: prompts/get (name, arguments)
    MCPServer->>+Prompt: handler(arguments)
    Prompt-->>-MCPServer: messages
    MCPServer-->>-Client: Prompt messages

    Note over Client,MCPServer: Optional Subscription
    Client->>+MCPServer: resources/subscribe (uri)
    MCPServer-->>-Client: Empty response
    MCPServer-->>Client: notifications/resources/updated

    Note over Client,MCPServer: Health Check
    Client->>+MCPServer: ping
    MCPServer-->>-Client: pong

保留中の作業

読者の皆さん、ぜひご協力ください！todo.org file を確認して、保留中の変更一覧をご覧ください。おおよそ、私が 取り組む予定の順に並んでいます。

SDK の開発

clojure-sdk は標準的な deps-new プロジェクトなので、 すべての deps-new コマンドが想定どおりに動作するはずです。それでも：

プロジェクトのテストを実行します：

$ make test ## or clojure -T:build test

プロジェクトの CI パイプラインを実行し、JAR をビルドします：

$ make build ## or clojure -T:build ci

これにより、target/classes 内の META-INF ディレクトリに 依存関係を同期した最新の pom.xml ファイルが生成され、 JAR は target に生成されます。生成された pom.xml のバージョン（および SCM タグ） 情報は、build.clj を更新することで変更できます。

ローカルにインストールします：

$ make install ## or clojure -T:build install

Clojars にデプロイします。CLOJARS_USERNAME と CLOJARS_PASSWORD の環境変数が必要です（事前に ci タスクを 実行する必要があります）：

$ make deploy ## or clojure -T:build deploy

ライブラリは、デフォルトで clojars.org の io.modelcontext/clojure-sdk にデプロイされます。

着想元

この SDK は jsonrpc4clj を基盤としており、 JSON-RPC ベースのサーバーで発生するあらゆるエッジケースへの対応という難題を解決してくれます。私はこのレイヤーを手作業で構築し、すべてのエッジケースを把握してから、jsonrpc4clj を使うほうが賢明だと気づきました。コードは非常によく書かれており、私の要件に合わせて簡単に変更できます。

ライセンス

Copyright © 2025 Unravel.tech

MIT License の下で配布されています