MCP Lucene Server

MCP Lucene 服务器

描述

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

特点/功能

• MCP合规性： 实现了核心模型上下文协议。

• 由Lucene驱动： 使用Apache Lucene进行全文搜索和索引。

• RESTful API: 提供一个用于与服务器交互的RESTful API。

• 文档管理：

- Upsert：（数据库操作术语，指“插入或更新”操作） 在Lucene索引中添加或更新文档。

- 删除： 从Lucene索引中删除文档。

- 列表： 从索引中检索文档列表。

• 查询：

- 支持使用Lucene查询语法进行复杂查询。

- 过滤：根据文档元数据过滤查询。

• 状态： 检查服务器状态。

• Spring Boot： 使用Spring Boot构建，便于设置和部署。

• 容器化： 包含使用Docker将应用程序容器化的说明。

目录

• 描述

• 特点/功能

• 入门指南

- 先决条件

- 安装

- 运行服务器

• 使用方法

- API 端点

- 示例

• 配置

• 许可证

入门指南/开始使用

先决条件

• Java Java 11 或更高版本。

• Maven： Maven 3.6.0 或更高版本。

• Docker： 如果你计划使用Docker镜像。

安装

1. 克隆仓库：

   git clone 
   cd mcp-lucene-server

(替换 your-username （附上您的GitHub用户名）

1. 使用 Maven 构建项目：

   mvn clean install

运行服务器

没有Docker

1. 运行Spring Boot应用程序：

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

（该名称的准确表述为 .jar 文件可能会根据您的项目版本略有不同。)

1. 服务器将在端口启动 8080 默认情况下。

使用Docker

1. 确保已安装Docker： 遵循官方Docker网站上的说明：

1. 构建Docker镜像：

在你的终端中导航到项目根目录，然后运行：

   docker build -t mcp-lucene-server .

1. 运行Docker容器：

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

这将映射端口 8080 在你的主机上将（服务）映射到端口 8080 在容器内。

Claude Desktop 的 MCP 插件

这个项目包含一个可选的MCP垫片（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垫片（或：运行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桌面版

更新 ~/.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  /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获取服务器/index状态
• 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显示“不支持的格式”，则以纯文本输出启动适配层：

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

• 查看垫片日志（在使用包装器时）：

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

• 确保你路径中的（内容/设置等） config.json 如果（这些设置）是绝对且正确的，那么请重启Claude Desktop。

API终端（用于Curl）

服务器提供以下API接口：

• GET /mcp/v1/status

- 返回服务器的状态。

• POST /mcp/v1/upsert

- 插入或更新一个或多个文档（Upserts）。

- 请求体：

    {
      "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"
           }
         }
      ]
    }

- queryLucene查询字符串。

- 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.pathLucene索引目录的路径。这是存储索引数据的地方。如果未设置，则使用默认位置。强烈建议将此配置为持久存储位置。

你可以在一个（配置/设置）中设置这些属性 application.properties 或者 application.yml 在你的（文件夹/文件中） src/main/resources 通过目录，或者使用环境变量。

示例 application.properties：

服务器端口=8080 lucene.index.path=/路径/到/lucene/索引

许可证

这个项目遵循以下许可协议： Apache 2.0 许可证。