内容
# Bitrix MCP
[中文文档](./zh.README.md)
一个本地的、无需令牌的 [MCP](https://modelcontextprotocol.io) 服务器，用于索引您的 **Bitrix 框架 / 1C-Bitrix** 项目 —— PHP 源代码、模板、模块、安装资产和文档 —— 以便 AI 助手可以搜索实际的项目符号和文档。无需安装 Bitrix 模块，无需运行时更改，无需 API 令牌。
与任何支持 MCP 的助手兼容：Cursor、Claude Code、Claude Desktop、PhpStorm/JetBrains AI、VS Code / GitHub Copilot、Windsurf、Cline、Roo Code、Continue、Gemini CLI、OpenAI Codex 和 Kilo Code。
## 它能做什么
- **实时 API 和符号搜索** —— 在您的项目和 Bitrix 核心中查找函数、类、方法、事件、组件、常量和模块包含/检查用法。
- **项目、模板和核心索引** —— 分别索引您自己的代码、模板/组件和 Bitrix 核心，并增量更新。
- **文档搜索** —— 本地 Bitrix 框架文档作为 MCP 资源，使用 SQLite 全文搜索（可选的语义搜索通过 Python 服务）。
- **依赖图和影响半径** —— 查询 Bitrix 感知的事件、处理程序、模块、代理、ORM 实体、组件、IBlock、选项和继承图；查看更改的影响。
- **本地和私有** —— 无需令牌或 Bitrix 身份验证；访问仅限于您公开的本地文件夹。
## 要求
- Node.js **22.12+** （使用 `node:sqlite`）和 npm **10+**。
- Linux、macOS 或 Windows。
- 您要索引的 Bitrix 项目的磁盘访问权限。
- 首次文档索引的网络访问权限（克隆官方 Bitrix 文档；可以禁用）。
- 仅用于可选的语义搜索的 Python **3.11+**。
## 安装
```bash
npm install -g @mb4it/bitrix-mcp
# 或在不安装的情况下运行：
npx @mb4it/bitrix-mcp init
```
### Windows / PowerShell
如果 PowerShell 拒绝使用 `cannot be loaded because running scripts is disabled on this system`（`UnauthorizedAccess` / `PSSecurityException`）运行全局 `bitrix-mcp` 命令，则是 Windows 脚本**执行策略**阻止了 npm 的 `bitrix-mcp.ps1` shim —— 这不是此软件包的问题。请选择以下解决方案之一：
```powershell
# 推荐：为您的用户允许本地/签名脚本（永久，一次性）
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
# 或在不安装/不更改策略的情况下绕过：
npx @mb4it/bitrix-mcp init
# 或显式调用 .cmd shim（在限制策略下有效）：
bitrix-mcp.cmd init
```
这仅影响您自己输入的一次 `init`。`init` 编写的 MCP 服务器配置已经通过 `cmd /c` 在 Windows 上启动服务器，因此您的 MCP 客户端（Cursor、Claude Code、...）在没有任何策略更改的情况下启动它。
## 快速入门
从您的 Bitrix 项目根目录：
```bash
# 配置您的 MCP 客户端并构建初始索引。
# 客户端本身启动服务器，因此 init 不会启动它。
npx @mb4it/bitrix-mcp init --agent cursor
```
`init` 选择当前目录作为项目根目录，配置选定的客户端（s），写入指导/规则文件，并索引您的项目、模板、Bitrix 核心（如果存在本地 `bitrix/`）和文档。交互式运行以选择多个客户端，或传递 `--agent <id>` / `--all-agents` / `--yes`。
然后打开您的 AI 客户端，并要求它使用 Bitrix MCP。一个好的第一个提示：
```text
使用 Bitrix MCP 检查索引状态，然后查找该项目如何注册销售模块事件处理程序。
```
## 常用命令
```bash
bitrix-mcp index-all # 重新索引所有内容：项目、模板、核心、安装、文档
bitrix-mcp index-code # 仅重新索引代码（不包括文档）
bitrix-mcp serve # 启动 MCP 服务器（您的客户端通常会执行此操作）
bitrix-mcp status # 索引计数器和数据库路径
bitrix-mcp doctor # 健康检查和解析路径
```
仅索引特定的 Bitrix 核心模块以加快运行速度：
```bash
bitrix-mcp index-bitrix --modules=main,iblock,sale,catalog
```
跳过官方文档下载（离线 / CI / 首次运行演示）：
```bash
BITRIX_MCP_OFFICIAL_DOCS_ENABLED=0 bitrix-mcp index-all
```
→ 完整的命令列表、标志和进度选项： **[docs/cli.md](./docs/cli.md)**。
## AI 代理如何使用它
将非空的 MCP 结果视为项目符号、框架 API、事件处理程序、ORM 实体和文档的权威信息。当 MCP 返回结果为空、报告索引过期或您要求手动检查时，请退回到手动 `grep` / 文件读取。这可以节省令牌并避免部分文件扫描产生的幻觉。（`init` 自动将此指导写入每个客户端的规则文件中。）
推荐流程：`bitrix_index_status` → `bitrix_project_overview` → `bitrix_liveapi_search` / `bitrix_docs_search` → `bitrix_read_file_context` / `bitrix_read_symbol_context`。
## MCP 工具
分组概述（完整参考包含参数和示例，见 **[docs/tools.md](./docs/tools.md)**）：
- **索引 / 状态** —— `bitrix_index_project`、`bitrix_index_template`、`bitrix_index_all`、`bitrix_index_docs`、`bitrix_index_status`
- **符号和 LiveAPI 搜索** —— `bitrix_liveapi_search`、`bitrix_event_search`、`bitrix_module_usage_search`、`bitrix_inheritance_search`
- **源代码上下文** —— `bitrix_read_file_context`、`bitrix_read_symbol_context`
- **组件和 ORM** —— `bitrix_component_search`、`bitrix_component_context`、`bitrix_orm_search`、`bitrix_orm_entity_map`、`bitrix_orm_usage_search`
- **IBlock / HLBlock / 选项 / 代理 / 邮件** —— `bitrix_iblock_usage_search`、`bitrix_hlblock_usage_search`、`bitrix_option_search`、`bitrix_agent_search`、`bitrix_mail_event_search`
- **图和影响** —— `bitrix_relation_search`、`bitrix_graph_neighbors`、`bitrix_graph_traverse`、`bitrix_impact_radius`、`bitrix_detect_changes`
- **文档** —— `bitrix_docs_search`、`bitrix_docs_for_symbol`、`bitrix_explain_api_usage`，以及可选的 `bitrix_semantic_docs_search`
- **概览 / 自动加载** —— `bitrix_project_overview`、`bitrix_autoload_search`
## 配置
常见的设置是环境变量 —— 路径、Bitrix 根目录、官方文档和语义搜索。`init` 将客户端需要的变量写入其 MCP 配置中。
```bash
BITRIX_ROOT # Bitrix 项目根目录，用于核心索引
BITRIX_MCP_DATA_DIR # 索引存储位置（默认为 .bitrix-mcp）
BITRIX_MCP_OFFICIAL_DOCS_ENABLED # 0 以跳过官方文档仓库
BITRIX_MCP_SEMANTIC_ENABLED # 1 以启用语义文档搜索
```
→ 所有变量、每个客户端的配置表、`init` / `configure` 标志和故障排除： **[docs/configuration.md](./docs/configuration.md)**。
## 文档
- **[CLI 参考](./docs/cli.md)** —— 每个命令、Bitrix 核心索引、标志、进度。
- **[配置](./docs/configuration.md)** —— 环境变量、客户端设置、故障排除。
- **[MCP 工具](./docs/tools.md)** —— 参数、示例、结果格式、限制。
- **[索引](./docs/indexing.md)** —— 范围和存储。
- **[依赖图](./docs/graph.md)** —— 关系、邻居、遍历、影响半径。
- **[检测更改](./docs/detect-changes.md)** —— 审查工作流程。
- **[Bitrix 事件](./docs/bitrix-events.md)** · **[ORM](./docs/orm.md)** · **[组件](./docs/components.md)** —— 每个主题的工作流程。
- **[文档搜索和嵌入](./docs/embeddings.md)** —— FTS 和可选的 Python 服务。
- **[安全](./docs/security.md)** —— 本地数据、路径限制、网络说明。
- **[示例提示](./docs/examples.md)** —— 可复制的提示。
## 开发
```bash
npm test
npm run typecheck
npm run build
```
## 许可证
[MIT](./LICENSE)
