使用说明

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将应用程序容器化的说明。

入门指南/开始使用

先决条件

Java Java 11 或更高版本。
Maven： Maven 3.6.0 或更高版本。
Docker： 安装 Docker 如果你计划使用Docker镜像。

安装

克隆仓库：

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用户名）

使用 Maven 构建项目：
```
mvn clean install
```

运行服务器

没有Docker

运行Spring Boot应用程序：
```
java -jar target/mcp-lucene-server-0.0.1-SNAPSHOT.jar
```
（该名称的准确表述为 .jar 文件可能会根据您的项目版本略有不同。)
服务器将在端口启动 8080 默认情况下。

使用Docker

确保已安装Docker： 遵循官方Docker网站上的说明： https://docs.docker.com/get-docker/ 的中文翻译为：“https://docs.docker.com/获取Docker/” 或者更流畅地表达为：“https://docs.docker.com/下载Docker/”。不过，通常我们会直接使用英文原链接，因为网址本身在技术文档中是通用的，不需要翻译。但如果要解释这个链接的作用，可以说：“该链接用于获取或下载Docker的安装指南和相关文档。”
构建Docker镜像： 在你的终端中导航到项目根目录，然后运行：
```
docker build -t mcp-lucene-server .
```
运行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 <<'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获取服务器/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 许可证。

使用说明

MCP Lucene 服务器

描述

特点/功能

目录

入门指南/开始使用

先决条件

安装

运行服务器

没有Docker

使用Docker

Claude Desktop 的 MCP 插件

先决条件

1) 运行Spring Boot服务器

2) 运行MCP垫片（或：运行MCP shim程序/模块）

3) 配置Claude桌面版

4) 可用工具

5) 适用于Claude Desktop的示例提示

6) 故障排除

API终端（用于Curl）

示例

配置

许可证

相关 MCP

Meilisearch MCP 搜索服务器

Gemini API文档搜索服务

文档管理服务

犹太文献搜索服务器

API测试管理工具

文档管理服务器