JinDaGe - as-help-mcp MCP Details

article

README

🚀 AS Help MCP Server

AS Help MCP Server是一个用于贝加莱（B&R）Automation Studio帮助文档搜索的MCP服务器。它借助SQLite FTS5和BM25排名算法，实现了对所有帮助页面的全文搜索。

🚀 快速开始

VS Code 配置

在工作区的 .vscode/mcp.json 文件中添加以下内容：

选项 1：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

选项 2：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\\search.db",
        "--metadata-dir",
        "..\\data\\as6\\.ashelp_metadata",
        "--as-version",
        "6"
      ]
    }
  }
}

请将 --directory 指向你克隆的仓库，并根据需要调整路径。

重启VS Code，然后在Copilot Chat中测试："Search AS help for mapp Motion"。

首次运行需要5 - 10分钟 来构建搜索索引，后续启动则是即时的。

✨ 主要特性

基于BM25排名的全文搜索
类别过滤和分层浏览
自动生成指向贝加莱在线帮助（AS4/AS6）的链接
支持通过HelpID查找，实现上下文相关帮助集成
通过MD5哈希在帮助目录发生变化时自动重新索引
多线程并行索引

📦 安装指南

前提条件

安装贝加莱Automation Studio（包含帮助文档）
安装并运行Docker Desktop
安装带有GitHub Copilot扩展的VS Code

本地开发设置

选项 1：UV（推荐）

# 克隆并安装
git clone <repository-url>
cd as-help
uv sync --extra test --extra dev

# 使用命令行参数运行服务器（优先级高于.env）
uv run as-help-server --help-root "C:\BRAutomation\AS412\Help-en\Data" --db-path "data\.ashelp\search.db" --metadata-dir "data\.ashelp_metadata"

# 或者使用相对路径（自动解析）
uv run as-help-server --db-path ./data/ashelp.db --metadata-dir ./data

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

你也可以在根目录创建一个 .env 文件。如果提供了命令行参数，它们将覆盖这些环境变量的值。

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

命令行参数

运行 uv run as-help-server --help 可获取完整详细信息。 | 参数 | 环境变量等效项 | 描述 | |------|----------------|------| | --help-root | AS_HELP_ROOT | AS帮助数据文件夹的路径 | | --db-path | AS_HELP_DB_PATH | SQLite数据库文件的路径 | | --metadata-dir | AS_HELP_METADATA_DIR | 索引元数据目录的路径 | | --as-version | AS_HELP_VERSION | 在线帮助的AS版本（4 或 6） | | --force-rebuild | AS_HELP_FORCE_REBUILD | 强制完全重建索引 |

选项 3：Docker Compose

# 本地构建
docker compose build

# 挂载你的帮助文件运行
docker compose run --rm \
  -v "C:\Program Files (x86)\BRAutomation\AS6\Help-en\Data:/data/help:ro" \
  as-help-local

使用MCP Inspector进行测试

MCP Inspector提供了一个Web UI来测试工具和提示：

# 使用UV
uv run mcp dev src/server.py

# 在浏览器中打开 http://localhost:5173

注意：在Windows上，请使用VS Code的运行和调试面板（Inspector存在标准输入输出传输问题）。

VS Code调试

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

Rebuild BR Help Index - 首次运行以构建索引
Run BR Help MCP Server - 正常启动服务器
Test BR Help Indexer - 快速XML解析测试

📚 详细文档

环境变量和命令行参数

服务器支持通过环境变量和命令行参数进行配置。命令行参数优先。相对路径会自动解析为绝对路径。 | 命令行参数 | 环境变量 | 默认值 | 描述 | |------------|----------|--------|------| | --help-root | AS_HELP_ROOT | /data/help | AS帮助数据文件夹的路径 | | --as-version | AS_HELP_VERSION | 4 | 在线帮助的AS版本（4 或 6） | | --force-rebuild | AS_HELP_FORCE_REBUILD | false | 强制重建索引 | | --db-path | AS_HELP_DB_PATH | {root}/.ashelp_search.db | 数据库位置 | | --metadata-dir | AS_HELP_METADATA_DIR | {root}/.ashelp_metadata | 元数据目录 |

工具

| 工具 | 描述 | |------|------| | search_help | 基于BM25排名的全文搜索，支持可选的类别过滤 | | get_categories | 列出用于过滤的顶级类别 | | browse_section | 分层浏览帮助树 | | get_page_by_id | 获取完整页面内容 | | get_page_by_help_id | 通过数字HelpID检索页面 | | get_breadcrumb | 获取导航路径 | | get_help_statistics | 获取内容统计信息 |

提示

| 提示 | 描述 | |------|------| | help_search | 结构化搜索，包含页面ID、面包屑和HelpID | | help_details | 深度研究，综合多个页面的内容 | | search_hardware | 过滤条件：X20模块、PLC、驱动器、电机 | | search_motion | 过滤条件：ACOPOS、mapp Motion、MC_* 块 | | search_visualization | 过滤条件：mapp View、小部件、HMI | | search_safety | 过滤条件：SafeLOGIC、安全功能 | | search_vision | 过滤条件：mapp Vision、智能相机 | | search_communication | 过滤条件：POWERLINK、OPC UA、Modbus | | search_programming | 过滤条件：IEC 61131-3、C/C++、库 | | search_mapp_services | 过滤条件：AlarmX、Recipe、UserX |

资源

| URI | 描述 | |-----|------| | help://page/{page_id} | 纯文本内容 | | help://html/{page_id} | 原始HTML内容 |

多个AS版本支持

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

演示

点击查看演示

as-help-mcp