GemFireMCPServer

GemFireMCPServer

一个基于 Spring Boot 的模型上下文协议（MCP）服务，使用 VMware GemFire 和 Spring AI，对财务文档进行快速的向量搜索。

概述

本项目演示了 MCP 客户端（例如 Claude Desktop）如何与 GemFire 后端服务交互，对文档进行语义搜索。财务文件会被切分为文本块、嵌入为向量表示，并存储在 GemFire 中，以支持使用检索增强生成（RAG）工作流进行快速、智能的查询。

用户可以：

• 上传文档 — 文件会被切分为文本块、嵌入为向量，并存储在 GemFire 中。元数据（例如文件名和大小）会单独存储在专用的 GemFire 区域中。
• 浏览已上传内容 — 获取并查看所有已存储文档的元数据。
• 查询文档（RAG） — 从 MCP 客户端提交自然语言问题。服务会执行向量相似度搜索，并将排名靠前的结果传递给大模型以生成回答。

功能

• 🔗 符合 MCP 规范的文档摄取、列表查询和查询端点
• 🧠 使用 Spring AI 的本地 ONNX 嵌入
• 💾 在 VMware GemFire 中存储向量和元数据
• 🧾 在专用的 GemFire 区域中存储文件元数据
• 🔍 快速的内存语义搜索

---

所需条件

• Java 17+
• Gradle（本演示推荐使用）或 Maven
• GemFire VectorDB
• VMware GemFire 10.x+
• Claude Desktop（或 MCP 客户端）

---

GemFire MCP 服务设置

确保 Java 与机器匹配（避免出现 Unexpected flavor: cpu）

某些依赖包含特定于架构的本机二进制文件。如果 JDK 架构与机器的架构不匹配，这些库就无法正确加载，你可能会看到类似 Unexpected flavor: cpu 的错误。

1. 检查 JDK 版本和架构

在用于构建 JAR 的同一终端中运行：

java -XshowSettings:properties -version 2>&1 | grep -E 'java.vendor|java.runtime.version|os\.name|os\.arch'

示例输出：

java.runtime.version = 17.0.5+8-LTS
java.vendor = BellSoft
os.arch = aarch64
os.name = Mac OS X

2. 确认以下两点

• Java 17 或更新版本（java.runtime.version ≥ 17）

• 架构匹配：os.arch 应与机器的 CPU 架构一致

  • Apple Silicon/M1–M4：aarch64（也称为 arm64）
  • Intel/AMD：x86_64（也称为 amd64）

（可选）确认机器的架构：

uname -m
# arm64 or x86_64

3. 如果两者不匹配

安装与机器匹配的 JDK（例如，Apple Silicon 使用 aarch64/arm64 JDK，Intel 使用 x86_64 JDK）。架构不匹配可能导致构建失败，并出现类似 Unexpected flavor: cpu 的错误。

克隆代码仓库并准备 ONNX 嵌入模型

要为 PDF 文档生成嵌入向量，Spring AI 需要一个嵌入模型。 此示例使用 sentence-transformers/all-MiniLM-L6-v2 的 ONNX 导出版本进行本地推理。

完整详情请参阅 Spring AI 的 ONNX 文档，或按照以下步骤操作：

1. 克隆 GemFire Examples 仓库

   git clone https://github.com/gemfire/gemfire-examples.git
   cd extensions/gemfireVectorDatabase/gemfire-model-context-protocol-server
   

2. 在你偏好的 IDE 中打开项目。

3. 在终端中进入 gemfire-model-context-protocol-server 目录（可在 IDE 内打开终端，也可单独打开终端）。

4. 创建虚拟环境

   python3 -m venv venv
   

5. 激活虚拟环境

   source ./venv/bin/activate
   

6. 升级 pip 并安装构建工具

   pip install --upgrade pip setuptools wheel
   

7. 安装所需的 Python 包

   pip install optimum onnx onnxruntime sentence-transformers
   

8. 将模型导出到 resources/onnx 目录

   optimum-cli export onnx --model sentence-transformers/all-MiniLM-L6-v2 src/main/resources/onnx
   

   这会在以下位置生成 model.onnx 和 tokenizer.json：

   extensions/gemfireVectorDatabase/gemfire-model-context-protocol-server/src/main/resources/onnx
   

   Spring AI 会自动从此位置加载模型。

9. 确认文件存在

   ls -lh src/main/resources/onnx
# Should see: model.onnx, tokenizer.json

10. 停用虚拟环境

deactivate

可能遇到的问题

ONNX 导出期间缺少依赖项

如果看到此错误：

Weight deduplication check in the ONNX export requires accelerate. Please install accelerate to run it.

请安装缺少的依赖项，然后重新运行第 8 步中的导出命令：

pip install accelerate
optimum-cli export onnx --model sentence-transformers/all-MiniLM-L6-v2 src/main/resources/onnx

---

配置 GemFire 构件访问权限

要解析 GemFire 依赖项，你需要 Broadcom 提供的访问凭据。

1. 使用客户凭据登录 Broadcom Customer Support Portal。
2. 前往 VMware Tanzu GemFire 下载页面，选择 VMware Tanzu GemFire，然后点击 Show All Releases。
3. 找到名为 Click Green Token for Repository Access 的版本，然后点击右侧的 Token Download 图标。这会打开 GemFire 构件仓库的使用说明。页面顶部会显示 Access Token。点击 Copy to Clipboard。你将使用此 Access Token 作为密码。

如果使用 Gradle

将凭据添加到 ~/.gradle/gradle.properties（或项目级 gradle.properties）：

gemfireRepoUsername=EXAMPLE-USERNAME
gemfireRepoPassword=MY-PASSWORD

• EXAMPLE-USERNAME 是你的 support.broadcom.com 用户名。
• MY-PASSWORD 是你在第 3 步复制的 Access Token。

如果使用 Maven：

更新你的 ~/.m2/settings.xml：

<settings>
  <servers>
    <server>
      <id>gemfire-release-repo</id>
      <username>EXAMPLE-USERNAME</username>
      <password>MY-PASSWORD</password>
    </server>
  </servers>
</settings>

• EXAMPLE-USERNAME 是你的 support.broadcom.com 用户名。
• MY-PASSWORD 是你在第 3 步复制的 Access Token。

配置 application.properties

打开 application.properties 文件并配置以下属性：

• spring.main.web-application-type=none — 此示例使用 MCP 客户端（Claude Desktop）的 STDIO 连接，因此必须禁用内嵌 Web 服务器，因为它不需要处理 HTTP 请求。
• spring.main.banner-mode=off — 禁用应用启动时显示的横幅。
• logging.pattern.console= — 禁用格式化日志输出，以减少控制台噪声。
• spring.ai.mcp.server.stdio=true — 启用 MCP STDIO 服务。
• spring.ai.vectorstore.gemfire.port=7070 — GemFire HTTP 服务使用的端口；必须与集群使用的 --http-service-port 匹配。
• spring.ai.vectorstore.gemfire.initialize-schema=true — 在 GemFire 中自动创建向量索引和区域。如果你要手动管理索引，请设为 false。
• spring.ai.vectorstore.gemfire.index-name=financialDocuments — GemFire 中向量索引的名称。
• spring.ai.embedding.transformer.onnx.model-uri=classpath:onnx/model.onnx — 之前创建的 ONNX 模型文件路径。
• spring.ai.embedding.transformer.tokenizer.uri=classpath:onnx/tokenizer.json — 之前创建的分词器文件路径。
• spring.ai.embedding.transformer.onnx.modelOutputName=token_embeddings — 用于生成嵌入的输出节点名称。
• docs.path=/Path/To/FinancialDocs — 加载财务文档的目录。
• gemfire.region.docsMetadata= - 用于存储 GemFire Vector DB 中每份文档元数据的区域。

配置 GemFire 集群连接

此示例目前尝试连接到运行于 localhost:10334 的 GemFire 集群。如果你的集群运行在其他位置：

1. 打开 GemfireMcpServerDemoApplication.java。
2. 找到 ClientCache 配置 @Bean。
3. 更新定位器主机/端口，使其与你的环境匹配。

构建 MCP 服务

./gradlew clean build

---

GemFire 集群设置

确保你已下载 GemFire 10.x 或更高版本，以及 GemFire Vector DB 扩展，下载地址：Broadcom Customer Support Portal

1. 解压 GemFire 并打开该目录。

2. 找到你从 Broadcom Support Portal 下载的 GemFire Vector DB .gfm 文件，并将其移入 GemFire 安装目录的 extensions 目录。
   此文件不包含在 GemFire 主下载包中，你必须单独下载。

   例如：

   vmware-gemfire-10.1.3/extensions/vmware-gemfire-vectordb-1.2.0.gfm
   

3. Open a terminal, navigate to the bin folder in the GemFire directory, and start GFSH:

   ./gfsh
   

4. In GFSH, confirm that the Vector DB extension is installed:

   version --full
   

   You should see output similar to:

   gfsh>version --full
   ----------------------------------------
   Tanzu GemFire
   ----------------------------------------
   Build-Java-Vendor: BellSoft
   GemFire-Source-Date: 2025-03-20 13:29:10 -0700
   Build-Platform: Linux 4.18.0-553.el8_10.x86_64 amd64
   Build-Java-Version: 1.8.0_442
   GemFire-Source-Revision: 62f20538984ebd92beee00874104d8706c6e4719
   Build-Id: gemfire 2511
   Product-Name: Tanzu GemFire
   GemFire-Version: 10.1.3
   GemFire-Source-Repository: support/10.1
   ----------------------------------------
   Tanzu GemFire Vector DB
   ----------------------------------------
   GemFire-Vector-DB-Source-Repository: HEAD
   GemFire-Vector-DB-Source-Date: 2025-04-10 09:22:32 -0700
   GemFire-Vector-DB-Version: 1.2.0
   GemFire-Vector-DB-Source-Revision: 9ad01268475449c40fd58491b373b30ce3c91522
   

5. Start a locator with the HTTP service enabled:

   start locator --name locator1 --http-service-port 7070
   

6. Start a second server with a different HTTP service port:

   start server --name server1 --http-service-port 7071
   

7. Create a region matching the name used in your gemfire.region.docsMetadata property. For example:

   create region --name=FinancialDocumentsMetadata --type=PARTITION
   

The GemFire cluster is now ready to accept documents.

---

Claude Desktop Setup

The GemFire MCP Server will appear as a Tool in Claude Desktop once configured.

1.Download Claude Desktop 2. Start Claude Desktop and open the Developer settings: Claude -> Settings -> Developer 3. Click on Edit Config 4. Open the claude_desktop_config.json file. 5. Add or update the mcpServers section as follows:

{
   "mcpServers": {
      "filesystem": {
         "command": "npx",
         "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "/Path/To/financialDocs"
         ]
      },
      "gemfire-mcp-demo": {
         "command": "java",
         "args": [
            "-jar",
            "/Path/To/GEMFIRE/MCP/JAR"
         ]
      }
   }
}

这会注册两个 MCP 服务，它们将作为工具显示在 Claude Desktop 中：

• Filesystem 工具 — 允许 Claude Desktop 访问指定目录中的文件。请确保 /Path/To/financialDocs 与应用配置中 docs.path= 属性的值一致。

• GemFire MCP 服务 — 允许 Claude Desktop 与 GemFire 集群交互。JAR 路径必须指向前文提到的 ./gradlew clean build 命令的输出。

6. 重启 Claude Desktop。
7. 重启后，点击工具选择按钮（位于 + 按钮旁边），确认两个工具均可用（版本 0.9.3）。

8. 确保 financialDocuments 目录中有文档。此演示使用了 Eli Lilly 2024 10K 和 Eli Lilly May 1, 2025 10Q 文档。

---

使用工具

在 Claude Desktop 中点击 gemfire-mcp-demo，即可查看三个可用工具：

• add_financial_doc
  Claude 会在 financialDocs 目录中查找指定文档，并将其发送到 MCP 服务。该服务会为文档生成向量嵌入，将其存储在 GemFire Vector DB 中，并将关联的元数据添加到元数据区域。

• list_available_financial_docs
  Claude 会向 MCP 服务请求可用文档列表。该服务会查询 GemFire 元数据区域，并返回文档列表。

• search_financial_docs
  可以向 Claude 提出以下问题： “总结这份财务文档，并告诉我有哪些新趋势。” Claude 会向 MCP 服务发送语义搜索请求，由该服务从 GemFire Vector DB 中检索相关内容并作出相应回答。

示例

添加文档

列出可用文档

总结指定文档

列出可用文档——多于 1 份

总结两份文档