MCP Lucene Server

MCP Lucene 服务

描述

MCP Lucene 服务是基于 Java 的模型上下文协议（MCP）实现，旨在使用 Apache Lucene 提供高效的搜索和检索功能。此服务支持管理和查询文档，并充分利用 Lucene 强大的索引和搜索功能。它基于 Spring Boot 构建，易于设置和部署。

功能

• 符合 MCP 规范： 实现模型上下文协议的核心功能。

• 由 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/），它会通过 STDIO 将服务的 REST 端点公开为 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 日志（使用 wrapper 时）：

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

• 确保 config.json 中的路径是绝对路径且正确，然后重启 Claude Desktop。

API 端点（用于 Curl）

服务提供以下 API 端点：

• GET /mcp/v1/status

  • 返回服务状态。

• POST /mcp/v1/upsert

  • 插入或更新一个或多个文档。

  • 请求正文：

    {
      "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 许可。