AI导哈

自动化文档搜索服务器

为B&R Automation Studio帮助文档提供关键词和混合搜索功能的服务器，支持本地和API嵌入模式。

  • by BRDK-Public
  • Python
  • 本地部署
  • 11 星标
  • 更新于
在 GitHub 查看 BRDK-GitHub/as-help-mcp

使用说明

AS帮助MCP服务器

用于B&R Automation Studio帮助文档搜索的MCP服务器。默认情况下，使用LanceDB的原生全文搜索（FTS）提供关键字搜索，并在配置嵌入API时，使用倒数排名融合（RRF）提供可选的混合语义+关键字搜索。

特性

  • 关键词搜索 （默认）：使用LanceDB的原生FTS进行快速全文搜索——没有外部依赖关系
  • 混合搜索 （可选）：启用嵌入时向量相似度和关键字匹配的RRF融合
  • 基于API的嵌入：适用于任何与OpenAI兼容的端点（Ollama、OpenAI、Azure OpenAI、GitHub Models、LiteLLM）——不需要本地ML模型
  • 智能排名：查询类型检测在FTS和向量（标识符如 MC_MoveAbsolute 赞成精确匹配；自然语言倾向于语义相似性）
  • 类别过滤和分层浏览
  • 自动生成的B&R在线帮助链接（AS4/AS6）
  • 上下文相关帮助集成的HelpID查找
  • 增量重新索引——只重新处理更改的页面
  • 两阶段构建：在后台构建嵌入的同时，几分钟内即可进行关键字搜索

先决条件

  • 已安装B&R Automation Studio（附带帮助文档）
  • 带有GitHub Copilot扩展的VS代码
  • 对于独立二进制文件： 下载 as-help-server.exe 从 发布 --不需要Python或Docker
  • 对于紫外线： Python 3.12+ 紫外线
  • 对于Docker： Docker 桌面版
  • 可选的 （用于混合搜索）：与OpenAI兼容的嵌入API（例如。， 奥拉玛 和 nomic-embed-text)

演示

https://github.com/user-attachments/assets/b4df6bc7-ed7c-471f-93b8-db84b0110ac3

快速入门（VS代码）

添加 .vscode/mcp.json 在您的工作空间中：

选项1：独立二进制（推荐）

没有Python，没有Docker——只需下载 .exe 从 发布 然后把它放进去 %APPDATA%\as-help-mcp\.

{
  "servers": {
    "as-help": {
      "command": "${env:APPDATA}\\as-help-mcp\\as-help-server.exe",
      "args": [
        "--help-root",
        "C:\\Program Files (x86)\\BRAutomation\\AS6\\Help-en\\Data",
        "--db-path",
        "${env:APPDATA}\\as-help-mcp\\data\\as6\\.ashelp_lance",
        "--metadata-dir",
        "${env:APPDATA}\\as-help-mcp\\data\\as6\\.ashelp_metadata",
        "--as-version",
        "6"
      ]
    }
  }
}

更新 --help-root 要匹配您的AS安装：

  • AS 4.x： C:\\BRAutomation\\AS412\\Help-en\\Data
  • AS 6.x： C:\\Program Files (x86)\\BRAutomation\\AS6\\Help-en\\Data

选项2:Docker

{
  "servers": {
    "as-help": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "C:\\Program Files (x86)\\BRAutomation\\AS6\\Help-en\\Data:/data/help:ro",
        "-v", "ashelp-data:/data/db",
        "-e", "AS_HELP_VERSION=6",
        "-e", "AS_HELP_FORCE_REBUILD=false",
        "ghcr.io/brdk-public/as-help-mcp:latest"
      ]
    }
  }
}

更新卷路径以匹配AS安装：

  • AS 4.x： C:\\BRAutomation\\AS412\\Help-en\\Data:/data/help:ro
  • AS 6.x： C:\\Program Files (x86)\\BRAutomation\\AS6\\Help-en\\Data:/data/help:ro
  • WSL中的AS 6.x： /mnt/c/Program Files (x86)/BRAutomation/AS6/Help-en/Data:/data/help:ro

方案3:UV（地方发展）

{
  "servers": {
    "as-help": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/as-help-mcp",
        "as-help-server",
        "--help-root",
        "C:\\Program Files (x86)\\BRAutomation\\AS6\\Help-en\\Data",
        "--db-path",
        "..\\data\\as6\\.ashelp_lance",
        "--metadata-dir",
        "..\\data\\as6\\.ashelp_metadata",
        "--as-version",
        "6"
      ]
    }
  }
}

更新 --directory 指向克隆的存储库并根据需要调整路径。

重新启动VS Code，然后在Copilot Chat中进行测试： “搜索地图运动的AS帮助”

第一轮需要2-3分钟 构建关键字搜索索引。启用嵌入后，完整的混合构建需要15-20分钟（在后台构建嵌入时，可以立即进行关键字搜索）。后续启动是即时的（~3s）。

启用混合搜索（可选）

默认情况下，服务器使用仅关键字搜索（FTS）。若要启用混合语义+关键字搜索，请配置与OpenAI兼容的嵌入API。

示例：Ollama（本地，免费）

  1. 安装 奥拉玛 并拉取嵌入模型：
ollama pull nomic-embed-text
  1. 添加 --create-embeddings true 并将环境变量嵌入到MCP配置中：
{
  "servers": {
    "as-help": {
      "command": "${env:APPDATA}\\as-help-mcp\\as-help-server.exe",
      "args": [
        "--help-root", "C:\\Program Files (x86)\\BRAutomation\\AS6\\Help-en\\Data",
        "--db-path", "${env:APPDATA}\\as-help-mcp\\data\\as6\\.ashelp_lance",
        "--metadata-dir", "${env:APPDATA}\\as-help-mcp\\data\\as6\\.ashelp_metadata",
        "--as-version", "6",
        "--create-embeddings", "true"
      ],
      "env": {
        "EMBEDDING_API_ENDPOINT": "http://localhost:11434",
        "EMBEDDING_API_KEY": "ollama",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "EMBEDDING_DIMENSIONS": "768",
        "EMBEDDING_BATCH_SIZE": "100",
        "EMBEDDING_MAX_CHARS": "4000"
      }
    }
  }
}

任何与OpenAI兼容的端点都可以工作——OpenAI、Azure OpenAI、GitHub Models、LiteLLM等。只需相应地更新端点、键、模型和尺寸。

混合搜索的工作原理

启用嵌入后，服务器使用 互易秩融合（RRF） 以组合四个搜索信号：

信号 NL重量 ID重量 描述
标题向量 2.0 0.5 查询与标题的语义相似度+面包屑嵌入
内容向量 1.0 0.5 查询与面包屑的语义相似度+内容嵌入
FTS关键字 1.5 3.0 Lance原生全文搜索标题+面包屑+内容
标题匹配 3.0 4.0 页面标题中查询的精确/子字符串匹配

查询类型检测 自动选择权重：标识符查询（例如。， MC_MoveAbsolute, X20DI9371)转向FTS+冠军赛；自然语言查询更倾向于向量相似性。

要深入了解RAG架构——分块策略、两阶段构建、RRF融合、嵌入模型选择和考虑的替代方案——请参阅 RAG.md.

地方发展设置

选项1：紫外线（推荐）

# Clone and install
git clone <repository-url>
cd as-help-mcp
uv sync --extra test --extra dev

# Run server with command line arguments (precedence over .env)
uv run as-help-server --help-root "C:\BRAutomation\AS412\Help-en\Data" --db-path "data\.ashelp_lance" --metadata-dir "data\.ashelp_metadata"

# Or use relative paths (automatically resolved)
uv run as-help-server --db-path ./data/lance_index --metadata-dir ./data

选项2：环境变量（.env）

您还可以创建 .env 根目录中的文件。命令行参数将覆盖这些值（如果提供）。

AS_HELP_ROOT=C:\Program Files (x86)\BRAutomation\AS6\Help-en\Data
AS_HELP_VERSION=6

CLI参数

跑 uv run as-help-server --help 了解全部细节。

参数 环境变量等价 描述
--help-root AS_HELP_ROOT AS帮助数据文件夹的路径
--db-path AS_HELP_DB_PATH LanceDB目录的路径
--metadata-dir AS_HELP_METADATA_DIR 索引元数据目录的路径
--as-version AS_HELP_VERSION AS版本用于在线帮助(4 或 6)
--force-rebuild AS_HELP_FORCE_REBUILD 强制进行完整索引重建
--create-embeddings CREATE_EMBEDDINGS 为混合搜索启用基于API的嵌入

嵌入配置（环境变量）

只有在以下情况下才需要这些 --create-embeddings true 已设置：

变量 默认值 描述
EMBEDDING_API_ENDPOINT （必填） 与OpenAI兼容的API的基本URL
EMBEDDING_API_KEY （必填） API密钥/承载令牌
EMBEDDING_MODEL （必填） 型号名称（例如。， nomic-embed-text, text-embedding-3-small)
EMBEDDING_DIMENSIONS （必填） 矢量维度（例如。， 768, 1536)
EMBEDDING_BATCH_SIZE 100 每个API调用的文本
EMBEDDING_MAX_CHARS 8000 将输入文本截断到此长度

选项3：Docker编写

# Local build
docker compose build

# Run with your help files mounted
docker compose run --rm \
  -v "C:\Program Files (x86)\BRAutomation\AS6\Help-en\Data:/data/help:ro" \
  as-help-local

MCP检验员测试

MCP检查器为测试工具和提示提供了一个web UI：

# With UV
uv run mcp dev src/server.py

# Opens browser at http://localhost:5173

注意：在Windows上，请改用VS Code的“运行和调试”面板（Inspector的stdio传输问题）。

VS代码调试

使用中的启动配置 .vscode/launch.json:

  1. 重建BR帮助索引 -首次运行以构建索引
  2. 运行BR Help MCP服务器 -正常服务器启动
  3. 测试BR帮助索引器 -快速XML解析测试

演出

操作 时间 备注
XML解析 ~2s 58K+页内存
首次索引构建（仅限FTS） ~2-3分钟 并行HTML提取+FTS索引
首次索引构建（混合） 15-20分钟 +通过API嵌入（可立即进行关键字搜索）
后续启动 ~3s 加载现有索引
搜索查询 10-50ms RRF混合或FTS关键字
内存使用量 10-30MB 索引加载后的运行时间

工具

工具 说明
search_help 具有RRF排名和可选类别过滤器的混合语义+关键字搜索
get_categories 列出用于筛选的顶级类别
browse_section 按层次导航帮助树
get_page_by_id 获取整页内容
get_page_by_help_id 通过数字帮助ID检索页面
get_breadcrumb 获取导航路径
get_help_statistics 获取内容和索引构建统计信息

提示

提示 描述
help_search 使用页面ID、面包屑和帮助ID进行结构化搜索
help_details 通过多页内容合成进行深入研究

多个AS版本

{
  "servers": {
    "as-help-4": {
      "command": "${env:APPDATA}\\as-help-mcp\\as-help-server.exe",
      "args": [
        "--help-root", "C:\\BRAutomation\\AS412\\Help-en\\Data",
        "--db-path", "${env:APPDATA}\\as-help-mcp\\data\\as4\\.ashelp_lance",
        "--metadata-dir", "${env:APPDATA}\\as-help-mcp\\data\\as4\\.ashelp_metadata",
        "--as-version", "4"
      ]
    },
    "as-help-6": {
      "command": "${env:APPDATA}\\as-help-mcp\\as-help-server.exe",
      "args": [
        "--help-root", "C:\\Program Files (x86)\\BRAutomation\\AS6\\Help-en\\Data",
        "--db-path", "${env:APPDATA}\\as-help-mcp\\data\\as6\\.ashelp_lance",
        "--metadata-dir", "${env:APPDATA}\\as-help-mcp\\data\\as6\\.ashelp_metadata",
        "--as-version", "6"
      ]
    }
  }
}

相关 MCP