内容
# BSP 文档 MCP
MCP 服务器允许 Codex 在“1С: 标准子系统库” （BSP）文档中搜索推荐的方法， 而不仅仅是精确的词语匹配。搜索结合了 OpenRouter 的嵌入式模型和本地 SQLite FTS5 全文索引。
本说明适用于 Windows 10/11 和 Codex。 不需要 Python、Git 和 MCP 的知识。
## 已包含内容
- 初始 BSP 文档 `3.1.11`；
- 已准备好的索引 `data/indexes/3.1/index.sqlite`；
- 索引的嵌入式模型 `qwen/qwen3-embedding-8b`；
- 用于确定 BSP 版本、搜索和读取找到的章节的 MCP 工具。
通常不需要重新构建索引。 OpenRouter 仅用于将新的搜索查询转换为向量。
如果需要重新下载与 ITS 的 HTML 并获取 `manifest.json`，请使用 [docs/crawler.md](./docs/crawler.md)。如果 HTML 已经下载并需要仅将其分解为最终目录结构，请使用 [docs/exporter.md](./docs/exporter.md)。
版本 `3.1.11.155` 、 `3.1.12.1` 等 `3.1.x.x` 使用索引系列 `3.1`。选择索引时，平台模板版本号的最后两部分不被考虑。
## 所需内容
1. Windows 10 或 Windows 11。
2. 已安装 Codex。
3. Python 3.12 来自 [Python 官方网站](https://www.python.org/downloads/windows/)。安装时请勾选 **Add Python to PATH**。
4. OpenRouter API 密钥。在 [OpenRouter Keys](https://openrouter.ai/settings/keys) 部分创建密钥。
5. 安装依赖和执行新搜索查询时需要互联网连接。
在任意 PowerShell 窗口中检查 Python：
```powershell
py -3.12 --version
```
期望类似 `Python 3.12.10` 的字符串。如果找不到命令，请安装 Python 3.12 并重新打开 PowerShell。
## 快速安装
### 步骤 1. 下载项目
推荐使用 Git。如果尚未安装 Git，请下载 [Git for Windows](https://git-scm.com/download/win)，使用默认设置安装，然后打开新的 PowerShell 窗口。
可以在任何 PowerShell 目录中运行以下命令：
```powershell
git config --global core.longpaths true
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\mcp" | Out-Null
git clone https://github.com/VVi3ard/bsp-docs-mcp.git "$env:TEMP\bsp-docs-mcp"
Set-Location "$env:TEMP\bsp-docs-mcp"
```
`core.longpaths` 是因为某些 BSP 文档文件的名称很长。
如果不想使用 Git：
1. 打开 [GitHub 项目页面](https://github.com/VVi3ard/bsp-docs-mcp)。
2. 点击 **Code → Download ZIP**。
3. 创建一个名为 `C:\bsp-docs-mcp` 的短目录，并将 ZIP 解压到其中。
4. 打开包含 `README.md` 和 `install.ps1` 的目录。
5. 点击文件夹路径，输入 `powershell` 并按 Enter。
### 步骤 2. 运行安装程序
命令必须在包含 `install.ps1` 的下载目录中执行：
```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```
安装程序：
- 将服务器复制到 `%USERPROFILE%\.codex\mcp\bsp-docs-mcp`；
- 创建独立的 Python 环境 `.venv`；
- 安装工作依赖项；
- 检查是否已准备好索引。
安装程序不请求或保存 API 密钥。
安装成功后，可以删除临时目录：
```powershell
Set-Location $env:TEMP
Remove-Item -Recurse -Force "$env:TEMP\bsp-docs-mcp"
```
如果使用了 ZIP，安装后可以删除 `C:\bsp-docs-mcp`。
## 手动安装
本节是必要的，如果自动安装程序以错误结束或您想了解每个步骤。
### 带有 Git 的选项
命令可以在任何 PowerShell 目录中运行：
```powershell
git config --global core.longpaths true
$InstallDir = Join-Path $env:USERPROFILE ".codex\mcp\bsp-docs-mcp"
New-Item -ItemType Directory -Force (Split-Path $InstallDir) | Out-Null
git clone https://github.com/VVi3ard/bsp-docs-mcp.git $InstallDir
Set-Location $InstallDir
```
### 使用下载的 ZIP 文件的选项
将 ZIP 解压到 `C:\bsp-docs-mcp`。然后打开此目录中的 PowerShell 并确保 `pyproject.toml` 文件可见：
```powershell
Get-ChildItem .\pyproject.toml
```
然后执行：
```powershell
$InstallDir = Join-Path $env:USERPROFILE ".codex\mcp\bsp-docs-mcp"
New-Item -ItemType Directory -Force $InstallDir | Out-Null
Copy-Item -Path ".\*" -Destination $InstallDir -Recurse -Force
Set-Location $InstallDir
```
### 创建 Python 环境
在已安装的目录 `%USERPROFILE%\.codex\mcp\bsp-docs-mcp` 中执行以下命令：
```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --disable-pip-version-check -e .
```
记录 `-e .` 表示“从当前目录安装软件包”。 命令 `pip install -e ".[dev]"` 对普通用户不必要：它额外安装了开发人员和测试工具。
## OpenRouter API 密钥设置
实际密钥存储在 Windows 用户环境变量中。不需要将其写入存储库或 `config.toml`。
在任意 PowerShell 窗口中执行以下命令，用您的密钥替换 `<ВАШ_КЛЮЧ_OPENROUTER>`：
```powershell
[Environment]::SetEnvironmentVariable(
"OPENROUTER_API_KEY",
"<ВАШ_КЛЮЧ_OPENROUTER>",
"User"
)
```
关闭 PowerShell 和 Codex 以使更改生效。新的进程将看到变量，而已打开的进程则不会。
在新的 PowerShell 中，可以通过以下方式检查变量是否存在：
```powershell
if ([string]::IsNullOrWhiteSpace($env:OPENROUTER_API_KEY)) {
"OPENROUTER_API_KEY 未找到"
} else {
"OPENROUTER_API_KEY 已配置"
}
```
## 连接到 Codex
打开文件 `%USERPROFILE%\.codex\config.toml`。可以通过以下方式快速打开：
```powershell
notepad "$env:USERPROFILE\.codex\config.toml"
```
在文件末尾添加：
```toml
[mcp_servers.bsp_docs]
command = "powershell.exe"
args = [
"-NoProfile",
"-NonInteractive",
"-Command",
"& \"$env:USERPROFILE\\.codex\\mcp\\bsp-docs-mcp\\.venv\\Scripts\\python.exe\" -m bsp_docs_mcp serve"
]
env_vars = ["OPENROUTER_API_KEY"]
startup_timeout_sec = 20
tool_timeout_sec = 120
```
字符串 `env_vars = ["OPENROUTER_API_KEY"]` 留下不替换。这里指定了 MCP 服务器将从中接收密钥的系统变量名称。密钥本身不能写入 `config.toml`。
配置不依赖于 Windows 用户名： `$env:USERPROFILE` 将自动变为，例如 `C:\Users\ivanov`。
不要添加参数 `cwd`。然后相对路径 `src/Configuration/ParentConfigurations.bin` 将从 Codex 打开的项目目录解析。
完全关闭并重新启动 Codex。
## 安装验证
### 验证文件和 Python
命令可以在任何 PowerShell 目录中运行：
```powershell
$McpDir = Join-Path $env:USERPROFILE ".codex\mcp\bsp-docs-mcp"
Test-Path "$McpDir\.venv\Scripts\python.exe"
Test-Path "$McpDir\data\indexes\3.1\index.sqlite"
& "$McpDir\.venv\Scripts\python.exe" -c "import bsp_docs_mcp; print('bsp_docs_mcp installed')"
```
前两个命令应输出 `True`，最后一个命令应输出 `bsp_docs_mcp installed`。
### 在 Codex 中验证 MCP
重启 Codex 后，打开新的对话框并请求：
> 通过 MCP bsp_docs 显示可用的 BSP 文档版本。
Codex 应调用 `list_bsp_versions` 并显示 `3.1` 系列。
要验证搜索，请打开具有文件 `src/Configuration/ParentConfigurations.bin` 的 1C 项目并请求：
> 确定项目的 BSP 版本并为长时间操作找到推荐的编程接口。
## MCP 工具
### `detect_bsp_version(parent_configurations_path = "src/Configuration/ParentConfigurations.bin")`
从 `ParentConfigurations.bin` 获取 BSP 版本:
```json
{"full_version":"3.1.11.155","index_family":"3.1"}
```
### `search_bsp(version, query, limit=8)`
执行混合搜索。 版本是必需的； 可以传递完整的项目版本，例如 `3.1.11.155`。 默认情况下，查询由模型 `qwen/qwen3-embedding-8b` 转换为向量。
### `get_bsp_section(version, section_id)`
按 `search_bsp` 获得的 `section_id` 返回章节的完整文本。
### `list_bsp_versions()`
返回已安装的索引系列和文档信息。
## 代理如何选择 BSP 版本
1. 为打开的项目的 `src/Configuration/ParentConfigurations.bin` 调用 `detect_bsp_version`。
2. 将获得的完整版本传递到 `search_bsp` 和 `get_bsp_section`。
3. 如果 `ParentConfigurations.bin` 不存在，请询问用户 BSP 版本而不是默默选择索引。
## OpenRouter 消耗
OpenRouter 用于：
- 在索引编制过程中 - 为文档的每个片段创建嵌入式模型；
- 在搜索过程中 - 为用户的新查询创建一个嵌入式模型。
已准备好的索引包含 3761 个片段，来自 2673 个 HTML 文件，约 497 万个字符。 其初始构建大约需要 1-200 万个嵌入式令牌；确切的数字取决于模型的标记。
通常，包含 2-3 个句子的查询会给出一个小的嵌入式 API 调用。 查询的精确重复从本地 `index.sqlite` 中的 `query_cache` 表中获取，无需再次调用 OpenRouter。
OpenRouter 的费率会发生变化，因此在重新索引之前，请在 OpenRouter 网站上检查所选嵌入式模型的当前价格。
## 添加文档和重新索引
这些命令对普通用户来说是不必要的。它们在目录 `%USERPROFILE%\.codex\mcp\bsp-docs-mcp` 中执行。
无需 OpenRouter 费用即可解析 HTML：
```powershell
.\.venv\Scripts\python.exe -m bsp_docs_mcp inspect `
--version 3.1.11 `
--source ".\data\sources\3.1.11"
```
使用 OpenRouter 费用构建索引：
```powershell
.\.venv\Scripts\python.exe -m bsp_docs_mcp index `
--version 3.1.11 `
--source ".\data\sources\3.1.11"
```
索引构建到临时文件，只有在成功获取所有嵌入式模型后才会替换工作索引。
要添加其他文档：
1. 将 HTML 文件放在 `data/sources/<完整版本>` 中。
2. 运行 `inspect` 并检查已解析的页面数量。
3. 使用相同的完整版本运行 `index`。
4. 重新启动 Codex。
### 更改嵌入式模型
文档向量和查询向量必须由同一模型创建。因此，在更改 `BSP_EMBEDDING_MODEL` 后，必须完全重新构建索引。
在 Windows 中设置其他模型的示例：
```powershell
[Environment]::SetEnvironmentVariable(
"BSP_EMBEDDING_MODEL",
"<OPENROUTER_MODEL_ID>",
"User"
)
```
同时，在 `config.toml` 中将字符串更改为：
```toml
env_vars = ["OPENROUTER_API_KEY", "BSP_EMBEDDING_MODEL"]
```
之后，打开新的 PowerShell 窗口，重新构建所有必要的索引并重新启动 Codex。使用的模型写入 `index.sqlite` 元数据。
## 典型错误
### `py` 或 Python 3.12 未找到
从官方网站安装 Python 3.12，启用 **Add Python to PATH**，然后打开新的 PowerShell 窗口。
### `running scripts is disabled on this system`
使用本手册中的说明中的 `-ExecutionPolicy Bypass` 参数运行安装程序。它仅适用于此 PowerShell 启动。
### Git 报告 `Filename too long`
执行并重复下载：
```powershell
git config --global core.longpaths true
```
### Codex 看不到 `OPENROUTER_API_KEY`
完全关闭 Codex，在新的 PowerShell 中检查变量并再次启动 Codex。
### MCP 未启动
执行本节中的三个命令。然后检查 `config.toml` 中是否已添加 `[mcp_servers.bsp_docs]` 块。
### 未找到指定版本的索引
该套件中仅包含 `3.1` 系列。对于其他系列，请添加相应的文档并构建新索引。
## 开发和测试
本节仅适用于开发人员。命令在克隆存储库的根目录中执行：
```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m compileall -q src
```
