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 文件。