MCP Lucene Server

🚀 MCP Lucene 服务器

MCP Lucene 服务器是基于 Java 实现的 Model Context Protocol (MCP)，借助 Apache Lucene 提供高效的搜索和检索功能。它支持对文档进行插入、查询、删除和列出等操作，方便用户管理和查询文档。

🚀 快速开始

先决条件

• Java Development Kit (JDK) 1.8 或更高版本
• Maven 或其他构建工具用于项目管理

安装步骤

1. 克隆仓库

git clone https://github.com/your-repository/mcp-lucene.git
cd mcp-lucene

2. 构建项目 使用 Maven 构建：

mvn clean install

3. 运行服务器

java -jar target/mcp-lucene.jar

✨ 主要特性

• 插入或更新（Upsert）：上传一个包含多个文档的 JSON 数组。
• 查询（Query）：根据文本内容和可选过滤条件检索文档，支持指定返回结果的数量上限，默认为 10。
• 删除（Delete）：通过提供文档 ID 列表从索引中移除特定文档。
• 列出（List）：通过提供文档 ID 列表获取特定文档的内容。

📦 安装指南

本地运行

启动服务器后，默认监听 http://localhost:8080 端口。

Docker 部署

1. 打包镜像：

FROM java:8-jdk
COPY target/mcp-lucene.jar /app/
WORKDIR /app
ENTRYPOINT ["java", "-jar", "mcp-lucene.jar"]

2. 构建并运行：

docker build -t mcp-lucene .
docker run -p 8080:8080 mcp-lucene

💻 使用示例

接口说明

插入或更新文档

POST /mcp/v1/upsert
Content-Type: application/json

{
  "documents": [
    {
      "id": "doc1",
      "text": "这是第一个文档的内容。",
      "metadata": {
        "类别": "示例",
        "语言": "中文"
      }
    },
    ...
  ]
}

查询文档

POST /mcp/v1/query
Content-Type: application/json

{
  "queries": [
    {
      "query": "搜索关键词",
      "top_k": 5,
      "filter": {
        "语言": "中文"
      }
    }
  ]
}

删除文档

POST /mcp/v1/delete
Content-Type: application/json

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

列出文档

POST /mcp/v1/list
Content-Type: application/json

{
  "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": "这是第一个文档。",
      "metadata": {
        "类别": "示例",
        "语言": "中文"
      }
    },
    {
      "id": "doc2",
      "text": "这是第二个文档。",
      "metadata": {
        "类别": "测试",
        "语言": "中文"
      }
    }
  ]
}'

查询文档

curl -X POST \
http://localhost:8080/mcp/v1/query \
-H 'Content-Type: application/json' \
-d '
{
  "queries": [
    {
      "query": "测试",
      "top_k": 3,
      "filter": {
        "语言": "中文"
      }
    }
  ]
}'

删除文档

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

📚 详细文档

配置

通过 application.properties 文件配置服务器属性：

• 端口：指定服务器监听的端口号，默认为 8080。
• 线程数：设置处理请求的最大线程数量，建议根据硬件资源调整。

示例配置：

server.port=8081
server.servlet.thread-count=20

项目结构

mcp-lucene/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/MCPServer.java
│   │   └── resources/
│   │       └── application.properties
│   └── test/
│       └── JavaTestCases.java
└── pom.xml

依赖管理

项目使用 Maven 管理依赖，核心依赖包括：

• Jetty：嵌入式 HTTP 服务器。
• JSON Processing：处理 JSON 数据。

开发指南

1. 代码结构：
   • MCPServer.java：主服务类，包含启动逻辑和 REST 接口定义。
   • DocumentService.java：文档存储与检索的业务逻辑实现。
2. 单元测试： 使用 JUnit 和 Mockito 进行单元测试，确保每个功能模块正常工作。

📄 许可证

项目遵循 Apache License 2.0 协议，详细内容请参考 LICENSE 文件。