mcp-bsl-platform-help-context: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server (Python) that gives AI assistants access to 1C:Enterprise platform API documentation. Reads binary .hbk help files or pre-exported JSON, parses HTML pages into structured domain entities, and exposes MCP tools for fuzzy, semantic, and hybrid search. Python port of mcp-bsl-platform-context (Kotlin).

Commands

pip install -e .              # Install in dev mode
pip install -e ".[dev]"       # Install with pytest
pip install -e ".[local]"     # Install with local embedding models (sentence-transformers, torch)

pytest -v                     # Run all tests (359)
pytest -v tests/test_search_engine.py           # Single test module
pytest -v tests/test_search_engine.py::test_name  # Single test

# Run the server — YAML config (recommended)
mcp-bsl-context -c config.yml                                  # Full config from YAML
mcp-bsl-context -c config.yml -p /opt/1cv8/x86_64              # YAML + CLI override

# Run the server — CLI options (env vars MCP_BSL_* also work)
mcp-bsl-context -p /opt/1cv8/x86_64                            # Auto-detect latest version
mcp-bsl-context -p /opt/1cv8/x86_64 --platform-version 8.3.20  # Closest to 8.3.20
mcp-bsl-context -p /path -m streamable-http --port 8080         # Streamable HTTP transport
mcp-bsl-context -p /path --data-source json --json-path /path   # JSON source

# Docker
docker compose up                      # CPU + API providers
docker compose --profile gpu up        # GPU + local models
docker compose --profile json up       # JSON data source

Configuration

YAML config file (config.yml) is the primary configuration method. See config.example.yml for all options.

Priority: YAML < env vars (MCP_BSL_*) < CLI arguments.

Key sections: server, platform, search, embeddings, reranker, storage, index, docs.