Content
# BSP Documentation MCP
MCP server allows Codex to search for recommended methods in the "1C: Standard Subsystem Library" (BSP) documentation by meaning, not just by exact word match. The search combines OpenRouter embeddings and a local SQLite FTS5 full-text index.
The instructions below are designed for Windows 10/11 and Codex. No knowledge of Python, Git, or MCP is required.
## What's Included
- Original BSP documentation `3.1.11`;
- Ready-made index `data/indexes/3.1/index.sqlite`;
- Index embedding model `qwen/qwen3-embedding-8b`;
- MCP tools for determining BSP version, searching, and reading found sections.
For normal use, rebuilding the index is not necessary. OpenRouter is only needed to convert a new search query into a vector.
If you need to download HTML from ITS and get `manifest.json`, use [docs/crawler.md](./docs/crawler.md). If HTML is already downloaded and you only need to lay it out in the final directory structure, use [docs/exporter.md](./docs/exporter.md).
Versions `3.1.11.155`, `3.1.12.1`, and other `3.1.x.x` use the `3.1` index family. The last two parts of the platform template number are not considered when choosing an index.
## Requirements
1. Windows 10 or Windows 11.
2. Installed Codex.
3. Python 3.12 from the [official Python website](https://www.python.org/downloads/windows/). When installing, mark the **Add Python to PATH** option.
4. OpenRouter API key. Create a key in the [OpenRouter Keys](https://openrouter.ai/settings/keys) section.
5. Internet connection when installing dependencies and performing new search queries.
Check Python in any PowerShell window:
```powershell
py -3.12 --version
```
A string like `Python 3.12.10` is expected. If the command is not found, install Python 3.12 and reopen PowerShell.
## Quick Installation
### Step 1. Download the Project
The recommended option is Git. If Git is not installed, download [Git for Windows](https://git-scm.com/download/win), install it with default settings, and open a new PowerShell window.
The following commands can be run from any PowerShell directory:
```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` is needed due to long names of some BSP documentation files.
If you don't want to use Git:
1. Open the [project page on GitHub](https://github.com/VVi3ard/bsp-docs-mcp).
2. Click **Code → Download ZIP**.
3. Create a short directory `C:\bsp-docs-mcp` and unzip ZIP into it.
4. Open the directory where `README.md` and `install.ps1` are located.
5. Click the address bar in Explorer, type `powershell`, and press Enter.
### Step 2. Run the Installer
The command must be executed in the downloaded directory where `install.ps1` is located:
```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
```
The installer:
- copies the server to `%USERPROFILE%\.codex\mcp\bsp-docs-mcp`;
- creates an isolated Python environment `.venv`;
- installs working dependencies;
- checks for a ready index.
The installer does not request or save the API key.
After successful installation, the temporary directory can be deleted:
```powershell
Set-Location $env:TEMP
Remove-Item -Recurse -Force "$env:TEMP\bsp-docs-mcp"
```
If ZIP was used, after installation, you can delete `C:\bsp-docs-mcp`.
## Manual Installation
This section is needed if the automatic installer completed with an error or you want to understand each step.
### Option with Git
Commands are run from any PowerShell directory:
```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
```
### Option with Downloaded ZIP
Unzip ZIP into `C:\bsp-docs-mcp`. Then open this directory in PowerShell and make sure that `pyproject.toml` is visible in the current directory:
```powershell
Get-ChildItem .\pyproject.toml
```
After that, execute:
```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
```
### Creating a Python Environment
The following commands in both options are executed already in the installed directory `%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 .
```
The `-e .` record means "install the package from the current directory". The command `pip install -e ".[dev]"` is not needed for an ordinary user: it additionally installs developer and testing tools.
## Configuring OpenRouter API Key
The real key is stored in the user's Windows environment variable. It does not need to be written to the repository or `config.toml`.
Execute in any PowerShell window, replacing `<YOUR_OPENROUTER_KEY>` with your key:
```powershell
[Environment]::SetEnvironmentVariable(
"OPENROUTER_API_KEY",
"<YOUR_OPENROUTER_KEY>",
"User"
)
```
Close PowerShell and Codex after executing the command. New processes will see the variable, but open ones will not.
You can check the presence of the variable without outputting the key itself in a new PowerShell:
```powershell
if ([string]::IsNullOrWhiteSpace($env:OPENROUTER_API_KEY)) {
"OPENROUTER_API_KEY not found"
} else {
"OPENROUTER_API_KEY configured"
}
```
## Connecting to Codex
Open the file `%USERPROFILE%\.codex\config.toml`. You can quickly open it from PowerShell:
```powershell
notepad "$env:USERPROFILE\.codex\config.toml"
```
Add to the end of the file:
```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
```
Leave the line `env_vars = ["OPENROUTER_API_KEY"]` without replacement. Here, the name of the system variable is specified, from which Codex will pass the key to the MCP server. You cannot write the key itself in `config.toml`.
The configuration does not depend on the Windows user name: `$env:USERPROFILE` will automatically become, for example, `C:\Users\ivanov`.
Do not add the `cwd` parameter. Then the relative path `src/Configuration/ParentConfigurations.bin` will be resolved from the directory of the open Codex project.
Completely close and restart Codex.
## Installation Verification
### Check Files and Python
Commands are run from any PowerShell directory:
```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')"
```
The first two commands should output `True`, the last one - `bsp_docs_mcp installed`.
### Check MCP in Codex
After restarting Codex, open a new dialog and ask:
> Show available BSP documentation versions via MCP bsp_docs.
Codex should call `list_bsp_versions` and show the `3.1` family.
To verify the search, open a 1C project with the file `src/Configuration/ParentConfigurations.bin` and ask:
> Determine the BSP version of the project and find the recommended software interface for long-term operations.
## MCP Tools
### `detect_bsp_version(parent_configurations_path = "src/Configuration/ParentConfigurations.bin")`
Gets the BSP version from `ParentConfigurations.bin`:
```json
{"full_version":"3.1.11.155","index_family":"3.1"}
```
### `search_bsp(version, query, limit=8)`
Performs hybrid search. Version is required; you can pass the full project version, for example, `3.1.11.155`. By default, queries are converted to a vector using the `qwen/qwen3-embedding-8b` model.
### `get_bsp_section(version, section_id)`
Returns the full text of the section by `section_id` obtained from `search_bsp`.
### `list_bsp_versions()`
Returns installed index families and documentation information.
## How the Agent Chooses the BSP Version
1. Call `detect_bsp_version` for `src/Configuration/ParentConfigurations.bin` of the open project.
2. Pass the obtained full version to `search_bsp` and `get_bsp_section`.
3. If `ParentConfigurations.bin` is missing, ask the user for the BSP version instead of silently selecting an index.
## OpenRouter Usage
OpenRouter is used:
- when building the index — embeddings are created for each fragment of documentation;
- when searching — one embedding is created for a new user query.
The finished index contains 3761 fragments from 2673 HTML files, about 4.97 million characters. Its initial construction required approximately 1–2 million embedding tokens; the exact number depends on the model's tokenization.
A typical query of 2–3 sentences gives one small embeddings API call. The exact repetition of the query is taken from the `query_cache` table in the local `index.sqlite` without a new call to OpenRouter.
OpenRouter rates change, so check the current price of the selected embedding model on the OpenRouter website before reindexing.
## Adding Documentation and Reindexing
These commands are not needed for an ordinary user. They are executed in the `%USERPROFILE%\.codex\mcp\bsp-docs-mcp` directory.
Parse HTML without OpenRouter expenses:
```powershell
.\.venv\Scripts\python.exe -m bsp_docs_mcp inspect `
--version 3.1.11 `
--source ".\data\sources\3.1.11"
```
Build an index with OpenRouter expenses:
```powershell
.\.venv\Scripts\python.exe -m bsp_docs_mcp index `
--version 3.1.11 `
--source ".\data\sources\3.1.11"
```
The index is built into a temporary file and replaces the working one only after successfully receiving all embeddings.
To add other documentation:
1. Place HTML files in `data/sources/<full-version>`.
2. Run `inspect` and check the number of parsed pages.
3. Run `index` with the same full version.
4. Restart Codex.
### Changing the Embedding Model
Document vectors and query vectors must be created by the same model. Therefore, after changing `BSP_EMBEDDING_MODEL`, you need to completely rebuild the index.
Example of setting another model for a Windows user:
```powershell
[Environment]::SetEnvironmentVariable(
"BSP_EMBEDDING_MODEL",
"<OPENROUTER_MODEL_IDENTIFIER>",
"User"
)
```
In `config.toml`, change the line to:
```toml
env_vars = ["OPENROUTER_API_KEY", "BSP_EMBEDDING_MODEL"]
```
After that, open a new PowerShell window, rebuild all necessary indexes, and restart Codex. The used model is recorded in the `index.sqlite` metadata.
## Typical Errors
### `py` or Python 3.12 not found
Install Python 3.12 from the official website, enable **Add Python to PATH**, and open a new PowerShell window.
### `running scripts is disabled on this system`
Run the installer with the command from these instructions with the `-ExecutionPolicy Bypass` parameter. It applies only to this PowerShell launch.
### Git reports `Filename too long`
Execute and repeat the download:
```powershell
git config --global core.longpaths true
```
### Codex does not see `OPENROUTER_API_KEY`
Completely close Codex, check the variable in a new PowerShell with the command from the key setup section, and launch Codex again.
### MCP does not start
Execute three commands from the "Check files and Python" section. Then check that the `[mcp_servers.bsp_docs]` block is added to `%USERPROFILE%\.codex\config.toml` exactly once.
### Index for version not found
The kit includes only the `3.1` family. For another family, add the corresponding documentation and build a new index.
## Development and Tests
This section is intended only for developers. Commands are executed in the root of the cloned repository:
```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
```
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available