内容
# EverSpring MCP
[](https://github.com/alpeerkaraca/everspring-mcp/actions/workflows/docker-publish.yml)
## 快速开始
### 选项 A: 适用于用户（推荐 - Docker，零配置）
正常插入和播放使用不需要设置 Python 环境和 AWS 密钥。
1. **构建镜像**
```bash
docker build -t everspring-mcp:latest .
```
2. **运行 MCP 服务器（`xslim` 层级）**
```bash
docker run --name everspring-xslim --rm -i -e EVERSPRING_MODEL_TIER=xslim -e EVERSPRING_DATA_DIR=/home/everspring/.everspring -v everspring-data-xslim:/home/everspring/.everspring everspring-mcp:latest python -m everspring_mcp.main serve --tier xslim --transport stdio
```
### 选项 B: 适用于开发者（使用 uv）
1. **安装依赖**
```bash
uv sync
```
2. **下载预构建的精简快照**
```bash
uv run python -m everspring_mcp.main sync --mode snapshot-download --snapshot-tier slim --snapshot-model BAAI/bge-base-en-v1.5
```
3. **启动 MCP 服务器**
```bash
uv run python -m everspring_mcp.main serve --tier slim
```
## ⚠️ 首次运行的重要注意事项（防止超时）
在第一次运行中，容器可以自动从 S3 下载 ChromaDB/SQLite 快照（根据层级/模型，大约 **750MB 到 1.5GB**）。这可能比某些客户端严格的 60 秒 MCP 启动超时窗口更长。
为了避免连接超时，请在终端中手动运行 Docker 命令，让初始快照下载完成，然后从 Claude/Copilot 配置/启动 MCP 服务器。
EverSpring MCP 是一个 Spring 文档摄取、索引和检索系统，具有 MCP 服务器接口。
主要 CLI 入口点：`python -m everspring_mcp.main`.
## `main.py` 的功能
`main.py` 提供了操作命令：
- **scrape**: 发现/爬取 Spring 文档并将原始工件上传到 S3
- **sync**: 清单同步和快照上传/下载
- **status**: 本地同步状态报告
- **index**: 分块 + 嵌入 + 插入到 Chroma
- **search**: 查询本地索引
- **serve**: 启动 MCP stdio 服务器
- **client**: 交互式终端客户端
- **model-cache**: 预取嵌入模型工件
它还包括：
- 层级感知模型默认值（`main`、`slim`、`xslim`）
- 层级/模型感知的默认 Chroma 目录命名
- `index/search/serve` 的启动快照自动刷新
---
## 高级架构流程
```text
Scrape -> Sync -> Index -> Retrieve -> MCP Serve
```
1. **Scrape**: Spring 文档被发现、解析并上传到 S3（`raw-data` 布局）。
2. **Sync**: 本地 `docs` + `metadata.db` 被同步（清单模式）或从快照中恢复。
3. **Index**: 本地文档被分块、嵌入并写入 Chroma（批量）。
4. **Retrieve**: 查询时间检索运行层级感知搜索逻辑。
5. **Serve**: MCP 服务器通过 stdio 公开文档搜索工具。
---
## 安装
```bash
uv sync --dev
```
适用于 AMD ROCm 工作流（如果您使用项目额外功能）：
```bash
uv sync --extra amd
export HSA_OVERRIDE_GFX_VERSION=12.0.1
```
---
## 层级默认值
| 层级 | 默认嵌入模型 | 默认块大小（`max_tokens`） | 默认重叠（`overlap_tokens`） |
| --- | --- | ---: | ---: |
| `main` | `BAAI/bge-m3` | 2048 | 200 |
| `slim` | `BAAI/bge-base-en-v1.5` | 512 | 50 |
| `xslim` | `BAAI/bge-small-en-v1.5` | 384 | 40 |
注意：
- 默认 Chroma 目录模式：`~/.everspring/chroma-{tier}-{model_slug}`
- 当前检索行为：
- `tier=main`：密集/模型原生路径（BM25 构建/检查跳过）
- `tier!=main`：混合路径（密集 + BM25）
---
## MCP 服务器构建/运行说明
1. **安装依赖**
```bash
uv sync --dev
```
2. **准备本地数据**（同步快照或运行完整的抓取/同步/索引流程）
3. **启动 MCP 服务器**
```bash
uv run python -m everspring_mcp.main serve --tier main
```
4. **可选本地终端客户端**
```bash
uv run python -m everspring_mcp.main client
```
---
## 全局 CLI 参数（`main.py`）
| 参数 | 必需 | 值 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `--log-level` | 否 | `DEBUG`、`INFO`、`WARNING`、`ERROR` | `INFO` | 控制台/文件日志级别 |
| `--log-file` | 否 | 路径 | `None` | 可选的额外日志文件 |
---
## 命令参考（参数、值、默认值）
## `scrape`
| 参数 | 必需 | 值 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `--entry-url` | 条件* | URL | `None` | 发现入口 URL |
| `--module` | 条件* | Spring 模块枚举值 | `None` | 目标 Spring 模块 |
| `--version` | 条件* | 版本字符串（`4.0.5`） | `None` | 目标版本 |
| `--submodule` | 否 | 字符串 | `None` | 可选子模块 |
| `--content-type` | 否 | 内容类型枚举值 | `reference` | 文档内容类型 |
| `--registry-path` | 否 | 文件路径 | `None` | 子模块注册表 JSON |
| `--concurrency` | 否 | 整数 | `5` | 并行抓取并发度 |
| `--s3-bucket` | 否 | 字符串 | `None` | S3 存储桶覆盖 |
| `--s3-region` | 否 | 字符串 | `None` | S3 区域覆盖 |
| `--s3-prefix` | 否 | 字符串 | `None` | S3 前缀覆盖 |
| `--no-hash-check` | 否 | 标志 | `false` | 禁用内容哈希检查 |
| `--json` | 否 | 标志 | `false` | JSON 输出 |
\* `entry-url`、`module`、`version` 必须一起提供。
## `sync`
| 参数 | 必需 | 值 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `--mode` | 否 | `manifest`、`manifest-prime`、`snapshot-upload`、`snapshot-download` | `manifest` | 同步操作模式 |
| `--module` | 条件 | 字符串 | `None` | 非 `--all` 清单同步的模块 |
| `--version` | 条件 | 字符串 | `None` | 非 `--all` 清单同步的版本 |
| `--submodule` | 否 | 字符串 | `None` | 可选子模块 |
| `--all` | 否 | 标志 | `false` | 从矩阵同步所有目标 |
| `--force` | 否 | 标志 | `false` | 强制清单/清单主要操作 |
| `--parallel-jobs` | 否 | 整数（`>=1`） | `5` | 并行工作线程 |
| `--snapshot-model` | 否 | 模型名称 | `None` | 快照命名空间模型覆盖 |
| `--snapshot-tier` | 否 | `main`、`slim`、`xslim` | `None` | 快照命名空间层级覆盖 |
| `--s3-bucket` | 否 | 字符串 | `None` | S3 存储桶覆盖 |
| `--s3-region` | 否 | 字符串 | `None` | S3 区域覆盖 |
| `--s3-prefix` | 否 | 字符串 | `None` | S3 前缀覆盖 |
| `--data-dir` | 否 | 路径 | `None` | 本地数据目录覆盖 |
| `--json` | 否 | 标志 | `false` | JSON 输出 |
快照命名空间路径格式：
`s3://<bucket>/<prefix>/db-snapshots/{model_slug}-{tier}/...`
## `status`
| 参数 | 必需 | 值 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `--module` | 否 | 字符串 | `None` | 模块过滤器 |
| `--version` | 否 | 字符串 | `None` | 版本过滤器 |
| `--submodule` | 否 | 字符串 | `None` | 子模块过滤器 |
| `--all` | 否 | 标志 | `false` | 显示所有本地清单目标的状态 |
| `--data-dir` | 否 | 路径 | `None` | 本地数据目录覆盖 |
| `--json` | 否 | 标志 | `false` | JSON 输出 |
## `index`
| 参数 | 必需 | 值 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `--limit` | 否 | 整数 | `50` | 要处理的未索引文档的最大数量 |
| `--tier` | 否 | `main`、`slim`、`xslim` | `main` | 嵌入层级 |
| `--embed-model` | 否 | 模型名称 | 层级默认值 | 嵌入模型覆盖 |
| `--batch-size` | 否 | 整数 | 配置默认值 | 嵌入批量大小 |
| `--chunk-workers` | 否 | 整数 | 配置默认值 | CPU 分块准备工作线程 |
| `--upsert-batch-size` | 否 | 整数 | 配置默认值 | Chroma 插入批量大小 |
| `--max-tokens` | 否 | 整数 | 层级默认值 | 块令牌限制覆盖 |
| `--overlap-tokens` | 否 | 整数 | 层级默认值 | 块重叠覆盖 |
| `--build-bm25` | 否 | 标志 | `false` | 构建 BM25（跳过 `tier=main`） |
| `--reindex` | 否 | 标志 | `false` | 重置索引标志并重建向量 |
| `--module` | 否 | 字符串 | `None` | `--reindex` 的过滤器 |
| `--version` | 否 | 整数 | `None` | `--reindex` 的主要版本过滤器 |
| `--submodule` | 否 | 字符串 | `None` | `--reindex` 的子模块过滤器 |
| `--data-dir`、`--db-filename`、`--docs-subdir`、`--chroma-dir`、`--collection` | 否 | 路径/字符串 | `None` | 本地/索引存储覆盖 |
| `--json` | 否 | 标志 | `false` | JSON 输出 |
## `search`
| 参数 | 必需 | 值 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `--query`、`-q` | **是** | 字符串 | — | 搜索查询 |
| `--top-k`、`-k` | 否 | 整数 | `3` | 结果数量 |
| `--module` | 否 | 字符串 | `None` | 模块过滤器 |
| `--version` | 否 | 整数 | `None` | 主要版本过滤器 |
| `--build-index` | 否 | 标志 | `false` | 在搜索前重建 BM25（`tier!=main`） |
| `--no-dedup` | 否 | 标志 | `false` | 禁用 URL 去重 |
| `--tier` | 否 | `main`、`slim`、`xslim` | `main` | 搜索层级/模型 |
| `--json` | 否 | 标志 | `false` | JSON 输出 |
## `serve`
| 参数 | 必需 | 值 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `--transport` | 否 | `stdio` | `stdio` | MCP 传输 |
| `--tier` | 否 | `main`、`slim`、`xslim` | `main` | 服务层级/模型 |
| `--json` | 否 | 标志 | `false` | 发出启动状态 JSON |
## `client`
| 参数 | 必需 | 值 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `--no-progress` | 否 | 标志 | `false` | 禁用进度显示 |
## `model-cache`
| 参数 | 必需 | 值 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| `--embed-model` | 否 | 模型名称 | 配置默认值 | 模型覆盖 |
| `--batch-size` | 否 | 整数 | 配置默认值 | 批量大小覆盖 |
| `--json` | 否 | 标志 | `false` | JSON 输出 |
---
## 环境变量
## 必需（按工作流程）
| 变量 | 必需条件 | 描述 |
| --- | --- | --- |
| `EVERSPRING_S3_BUCKET` | `scrape`（如果没有明确的 `--s3-bucket` 覆盖） | 用于抓取上传的 S3 存储桶 |
| AWS 凭证（`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`，可选会话令牌） | 任何 S3 操作（`scrape`、`sync` 快照/清单） | S3 认证 |
## 可选（配置覆盖）
| 变量 | 默认值 | 使用者 |
| --- | --- | --- |
| `EVERSPRING_S3_BUCKET` | `everspring-mcp-kb` | 同步/抓取 |
| `AWS_REGION` | `eu-central-1`（同步），`us-east-1` 在抓取配置中作为后备 | 同步/抓取 |
| `EVERSPRING_S3_PREFIX` | `spring-docs`（同步），`spring-docs/raw-data`（抓取环境配置） | 同步/抓取 |
| `EVERSPRING_DATA_DIR` | `~/.everspring` | 同步/向量 |
| `EVERSPRING_MODEL_TIER` | `main` | 快照命名空间同步 |
| `EVERSPRING_EMBED_MODEL` | 层级默认值 | 向量 + 快照命名空间模型 |
| `EVERSPRING_CHROMA_DIR` | `~/.everspring/chroma`（由 CLI 层级/模型动态覆盖） | 向量 |
| `EVERSPRING_CHROMA_COLLECTION` | `spring_docs` | 向量 |
| `EVERSPRING_EMBED_TIER` | `main` | 向量 |
| `EVERSPRING_INDEX_CHUNK_WORKERS` | 自动（基于 `cpu_count`） | 向量索引 |
| `EVERSPRING_CHROMA_UPSERT_BATCH_SIZE` | `512` | 向量索引 |
| `EVERSPRING_INDEX_PREFETCH_BATCHES` | `3` | 向量索引预取 |
---
## 操作示例
## `bge-m3-main` 的快照上传/下载
```bash
python -m everspring_mcp.main sync \
--mode snapshot-upload \
--snapshot-model BAAI/bge-m3 \
--snapshot-tier main \
--json
python -m everspring_mcp.main sync \
--mode snapshot-download \
--snapshot-model BAAI/bge-m3 \
--snapshot-tier main \
--json
```
## 层级索引/搜索/服务（main 层级）
```bash
python -m everspring_mcp.main index --tier main --build-bm25 --json
python -m everspring_mcp.main search --tier main --query "security filter chain" --json
python -m everspring_mcp.main serve --tier main
```
---
## 注意
- `index/search/serve` 对活动模型 + 层级执行启动快照新鲜度检查；如果应用了更新的远程快照，则进程在一次性完成重启。
- 在 `sync`、`index` 和 `search/serve` 之间保持 `data_dir` 一致，以避免“文档存在但数据库为空”的不匹配。
---
## 🔌Claude 桌面集成（`claude_desktop_config.json`）
```json
{
"mcpServers": {
"everspring-main": {
"command": "docker",
"args": [
"run",
"--name",
"everspring-main",
"--rm",
"-i",
"-e",
"EVERSPRING_MODEL_TIER=main",
"-e",
"EVERSPRING_DATA_DIR=/home/everspring/.everspring",
"-v",
"everspring-data-main:/home/everspring/.everspring",
"everspring-mcp:latest",
"python",
"-m",
"everspring_mcp.main",
"serve",
"--tier",
"main",
"--transport",
"stdio"
]
},
"everspring-slim": {
"command": "docker",
"args": [
"run",
"--name",
"everspring-slim",
"--rm",
"-i",
"-e",
"EVERSPRING_MODEL_TIER=slim",
"-e",
"EVERSPRING_DATA_DIR=/home/everspring/.everspring",
"-v",
"everspring-data-slim:/home/everspring/.everspring",
"everspring-mcp:latest",
"python",
"-m",
"everspring_mcp.main",
"serve",
"--tier",
"slim",
"--transport",
"stdio"
]
},
"everspring-xslim": {
"command": "docker",
"args": [
"run",
"--name",
"everspring-xslim",
"--rm",
"-i",
"-e",
"EVERSPRING_MODEL_TIER=xslim",
"-e",
"EVERSPRING_DATA_DIR=/home/everspring/.everspring",
"-v",
"everspring-data-xslim:/home/everspring/.everspring",
"everspring-mcp:latest",
"python",
"-m",
"everspring_mcp.main",
"serve",
"--tier",
"xslim",
"--transport",
"stdio"
]
}
}
}
```
> **卷隔离很重要：** 每个层级必须使用不同的 Docker 卷（例如 `everspring-data-slim` vs `everspring-data-xslim`），以防止 Chroma/SQLite 冲突。
>
> **STDIO 安全：** 不要在 MCP 配置的 Docker 参数中添加 `-t`（TTY）。保留 `-i` 即可。
连接后，使用以下命令调用 `search_spring_docs`：
- `query`（必需）
- `top_k`（默认值：`3`）
- `module`（可选）
- `version_major`（可选）
---
## 🛠 高级用法：自定义模型和企业 S3
### 自带模型（BYOM）
1. **仅同步原始 Markdown 语料库**
```bash
uv run python -m everspring_mcp.main sync --mode manifest
```
2. **使用自定义嵌入模型构建本地向量数据库**
```bash
uv run python -m everspring_mcp.main index --embed-model "custom/model"
```
### 企业私有 S3
将管道指向您自己的 S3 存储桶，覆盖：
```bash
export EVERSPRING_S3_BUCKET=your-enterprise-bucket
```
## 🚀 CI/CD 和基础设施设置
该项目在完全自动化的持续集成和持续部署（CI/CD）管道上运行。基础设施已使用以下技术现代化，以确保安全和高性能的环境：
### 🛠️ 部署架构
- **环境：** 无根 Podman（一种不需要 root 权限的容器运行时，增强安全性）。
- **应用服务器：** Granian（高性能 Python HTTP 服务器）。
- **资源管理：** 为每个容器应用严格的 **4GB RAM** 和 **2 CPUs** 硬限制，特别是为了适应 BGE-M3 嵌入模型的内存需求。
- **数据持久性：** 使用 `everspring-data-[tier]` 卷将应用程序数据安全地存储在主机上。
### ⛓️ CI/CD 管道流程
1. **GitHub Actions：** 将代码推送到 `main` 分支会触发 Docker 镜像构建，然后将镜像推送到 **GHCR（GitHub 容器注册表）**。
2. **Webhook：** 构建成功后，会发送 Webhook 有效负载以自动触发 Jenkins 服务器。
3. **Jenkins 管道：** 执行 `Jenkinsfile` 中定义的步骤，Jenkins：
- 拉取 GHCR 中的最新镜像。
- 停止并清理现有容器。
- 部署新镜像，并具有严格的资源限制和动态环境变量（层级、工作线程、线程）。
### 🔐 安全性和权限
- **用户命名空间映射：** 在 `/etc/subuid` 和 `/etc/subgid` 中配置 ID 映射（范围 `100000-165535`），允许 `jenkins` 用户管理无根 Podman 层。*（有关主机设置和配置的详细说明，请参阅 [docs/setup.md](docs/setup.md)。*
- **基于矩阵的安全性：** 在 Jenkins 上通过矩阵授权强制实施项目隐私：
- **管理员：** 完全访问。
- **匿名：** 限制为 `Job/Read` 访问（仅允许 GitHub 提取和显示构建状态徽章）。
- **SSH 凭证：** 使用存储在 Jenkins 凭证商店中的 SSH 密钥在 Jenkins 和 GitHub 之间安全地处理通信。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器