MCP Lucene Server

MCP Lucene Server

説明

MCP Lucene Server は、Apache Lucene を使用して効率的な検索および取得機能を提供するよう設計された、Java ベースの Model Context Protocol（MCP）実装です。このサーバーを使用すると、Lucene の強力なインデックス作成機能と検索機能を活用して、ドキュメントを管理および検索できます。簡単にセットアップしてデプロイできるよう、Spring Boot を使用して構築されています。

機能

• MCP 準拠： Model Context Protocol のコア機能を実装しています。

• Lucene を活用： 全文検索とインデックス作成に Apache Lucene を使用します。

• RESTful API： サーバーとやり取りするための RESTful API を提供します。

• ドキュメント管理：

  • 追加・更新： Lucene インデックスにドキュメントを追加または更新します。

  • 削除： Lucene インデックスからドキュメントを削除します。

  • 一覧表示： インデックスからドキュメントの一覧を取得します。

• クエリ：

  • Lucene クエリ構文を使用した複雑なクエリをサポートします。

  • フィルタリング：ドキュメントのメタデータに基づいてクエリをフィルタリングします。

• ステータス： サーバーのステータスを確認します。

• Spring Boot： 簡単にセットアップしてデプロイできるよう、Spring Boot を使用して構築されています。

• Docker 化： Docker を使用してアプリケーションをコンテナ化する手順が含まれています。

目次

• 説明

• 機能

• はじめに

  • 前提条件

  • インストール

  • サーバーの実行

• 使用方法

  • API エンドポイント

  • 例

• 設定

• ライセンス

はじめに

前提条件

• Java： Java 11 以降。

• Maven： Maven 3.6.0 以降。

• Docker： Docker イメージを使用する場合は、Docker をインストールしてください。

インストール

1. リポジトリをクローンします：

   git clone [https://github.com/your-username/mcp-lucene-server.git](https://github.com/your-username/mcp-lucene-server.git)
   cd mcp-lucene-server
   

   （your-username を GitHub のユーザー名に置き換えてください）

2. Maven を使用してプロジェクトをビルドします：

   mvn clean install
   

サーバーの実行

Docker を使用しない場合

1. Spring Boot アプリケーションを実行します：

   java -jar target/mcp-lucene-server-0.0.1-SNAPSHOT.jar
   

   （.jar ファイルの正確な名前は、プロジェクトのバージョンによって多少異なる場合があります。）

2. サーバーはデフォルトでポート 8080 で起動します。

Docker を使用する場合

1. Docker がインストールされていることを確認します： Docker の公式ウェブサイトの手順に従ってください：https://docs.docker.com/get-docker/

2. Docker イメージをビルドします： ターミナルでプロジェクトのルートディレクトリに移動し、次を実行します：

   docker build -t mcp-lucene-server .
   

3. Docker コンテナを実行します：

   docker run -p 8080:8080 mcp-lucene-server
   

   これにより、ホストマシンのポート 8080 がコンテナ内のポート 8080 に割り当てられます。

Claude Desktop 用 MCP Shim

このプロジェクトにはオプションの MCP shim（mcp-shim/）が含まれており、サーバーの REST エンドポイントを STDIO 経由で MCP ツールとして公開するため、Claude Desktop から直接使用できます。

前提条件

• Java 17+
• Node.js 18+
• Maven 3.6+

1) Spring Boot サーバーを実行する

mvn spring-boot:run

API は http://localhost:8080/mcp/v1 で利用できます。

2) MCP shim を実行する

cd mcp-shim
npm install
# JSON + text output (default)
LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start
# If your client cannot render JSON tool outputs, force text-only
MCP_FORCE_TEXT=1 LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start

3) Claude Desktop を設定する

~/.claude/mcp/config.json を更新します：

{
  "mcpServers": {
    "lucene": {
      "command": "/opt/homebrew/bin/node",
      "args": [".../MCP-Lucene-Server/mcp-shim/server.js"],
      "env": {
        "LUCENE_BASE_URL": "http://localhost:8080/mcp/v1",
        "MCP_FORCE_TEXT": "1"
      }
    }
  }
}

または、ラッパースクリプトを使用して shim のログを /tmp/mcp-lucene-shim.stderr.log に記録します：

cat > .../MCP-Lucene-Server/mcp-shim/run-shim.sh <<'SH'
#!/usr/bin/env bash
set -euo pipefail
export LUCENE_BASE_URL="${LUCENE_BASE_URL:-http://localhost:8080/mcp/v1}"
exec node .../MCP-Lucene-Server/mcp-shim/server.js \
  2> /tmp/mcp-lucene-shim.stderr.log
SH
chmod +x .../MCP-Lucene-Server/mcp-shim/run-shim.sh

次に、~/.claude/mcp/config.json に以下を設定します：

{
  "mcpServers": {
    "lucene": {
      "command": ".../MCP-Lucene-Server/mcp-shim/run-shim.sh",
      "env": {
        "LUCENE_BASE_URL": "http://localhost:8080/mcp/v1",
        "MCP_FORCE_TEXT": "1"
      }
    }
  }
}

4) 利用可能なツール

• lucene_status：サーバー／インデックスの状態を取得します
• lucene_upsert：ドキュメントを登録または更新します
• lucene_query：ドキュメントを検索します（メタデータによるフィルターは任意）
• lucene_delete：IDを指定して削除します
• lucene_list：ページネーションを使用してドキュメントを一覧表示します

5) Claude Desktop 用のプロンプト例

• lucene_status を実行します
• 次の引数で lucene_list を実行します：{ "limit": 10, "offset": 0 }
• 次の引数で lucene_upsert を実行します：{"documents":[{"id":"doc-1","text":"hello world","metadata":{"lang":"en"}}]}
• 次の引数で lucene_query を実行します：{"queries":[{"query":"hello","top_k":5}]}
• 次の引数で lucene_delete を実行します：{ "ids": ["doc-1"] }

6) トラブルシューティング

• API が JSON を返すことを確認します：

curl -i http://localhost:8080/mcp/v1/status

• Claude に「unsupported format」と表示される場合は、テキストのみを出力する設定で shim を起動します：

MCP_FORCE_TEXT=1 LUCENE_BASE_URL=http://localhost:8080/mcp/v1 npm start

• ラッパーを使用している場合は、shim のログを確認します：

tail -n +1 /tmp/mcp-lucene-shim.stderr.log

• config.json 内のパスが絶対パスであり、正しいことを確認してから、Claude Desktop を再起動します。

API エンドポイント（Curl 用）

サーバーは次の API エンドポイントを提供します：

• GET /mcp/v1/status

  • サーバーの状態を返します。

• POST /mcp/v1/upsert

  • 1件以上のドキュメントを登録または更新します。

  • リクエストボディ：

    {
      "documents": [
        {
          "id": "doc1",
          "text": "This is the text of document 1.",
          "metadata": {
            "category": "example",
            "language": "english"
          }
        },
        {
          "id": "doc2",
          "text": "This is document 2's text.",
          "metadata": {
            "category": "sample",
            "language": "spanish"
          }
        }
      ]
    }
    

• POST /mcp/v1/query

  • Lucene インデックスを検索します。

  • リクエストボディ：

    {
      "queries": [
        {
          "query": "document",
          "top_k": 10,
          "filter": {
            "language": "english"
          }
        },
         {
          "query": "text search",
          "filter": {
             "category": "example"
           }
         }
      ]
    }
    

  • query：Lucene のクエリ文字列です。

  • top_k：（任意）返す結果の最大数です（デフォルト：10）。

  • filter：（任意）フィルターに使用するメタデータのフィールドと値のマップです。

• POST /mcp/v1/delete

  • Lucene インデックスからドキュメントを削除します。

  • リクエストボディ：

    {
        "ids": ["doc1", "doc2"]
    }
    

• GET /mcp/v1/list

  • Lucene インデックス内のドキュメントを一覧表示します。

  • リクエストボディ：

    {
        "ids": ["doc1", "doc2"]
    }
    

例

サーバーの状態を取得：

curl http://localhost:8080/mcp/v1/status

ドキュメントを登録または更新：

curl -X POST 

http://localhost:8080/mcp/v1/upsert 

-H 'Content-Type: application/json' 

-d '{
"documents": [
{
"id": "doc1",
"text": "This is the text of document 1.",
"metadata": {
"category": "example",
"language": "english"
}
},
{
"id": "doc2",
"text": "This is document 2''s text.",
"metadata": {
"category": "sample",
"language": "spanish"
}
}
]
}'

ドキュメントを検索：

curl -X POST 

http://localhost:8080/mcp/v1/query 

-H 'Content-Type: application/json' 

-d '{
"queries": [
{
"query": "document text",
"top_k": 5,
"filter": {
"language": "english"
}
}
]
}'

ドキュメントを削除：

curl -X POST 

http://localhost:8080/mcp/v1/delete 

-H 'Content-Type: application/json' 

-d '{
"ids": ["doc1"]
}'

ドキュメントを一覧表示：

curl -X POST 

http://localhost:8080/mcp/v1/list 

-H 'Content-Type: application/json' 

-d '{
"ids": ["doc1", "doc2"]
}'

設定

サーバーは Spring Boot のアプリケーションプロパティを使用して設定できます。主なプロパティは次のとおりです：

• server.port：サーバーがリッスンするポートです（デフォルト：8080）。

• lucene.index.path：Lucene インデックスディレクトリへのパスです。インデックス化されたデータはここに保存されます。設定されていない場合は、デフォルトの場所が使用されます。永続ストレージの場所に設定することを強くおすすめします。

これらのプロパティは、src/main/resources ディレクトリ内の application.properties または application.yml ファイルに設定するか、環境変数を使用して設定できます。

application.properties の例：

server.port=8080 lucene.index.path=/path/to/lucene/index

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。