内容
# 思杰Unicon管理侦察员
一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io) 服务器，暴露Unicorn Scout Board MDM REST API作为AI助手和Claude Desktop的工具。
通过自然语言管理设备、组织单位、应用程序、配置、标签、规则、计划、维护窗口和通知。
---
## 通过Docker MCP工具包安装（推荐）
如果您拥有启用了MCP工具包的 [Docker Desktop](https://www.docker.com/products/docker-desktop/)，请在 [hub.docker.com/mcp](https://hub.docker.com/mcp) 的目录中找到 **思杰Unicon管理侦察员** 并点击 **添加**。在UI中配置您的Scout Board网址、用户名和密码 - 不需要CLI。
---
## 手动安装
### 先决条件
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) - 或用于源安装的Node.js 20+
### 选项A - Docker（推荐）
```bash
docker pull mcp/scout-mcp
echo "" | docker run --rm -i \
-e SCOUT_BASE_URL=https://your-server:22160 \
-e SCOUT_USERNAME=admin@example.com \
-e SCOUT_PASSWORD=secret \
mcp/scout-mcp
```
将以下内容添加到您的MCP客户端配置（Claude Desktop、Claude Code等）中：
```json
{
"mcpServers": {
"scout": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env-file", "/path/to/.env",
"mcp/scout-mcp"
]
}
}
}
```
### 选项B - 从源代码构建
```bash
git clone https://github.com/mathiastornblom/ScoutMCP.git
cd ScoutMCP
npm install
npm run build
```
将以下内容添加到您的MCP客户端配置中：
```json
{
"mcpServers": {
"scout": {
"command": "node",
"args": ["/path/to/ScoutMCP/dist/index.js"],
"env": {
"SCOUT_BASE_URL": "https://your-server:22160",
"SCOUT_USERNAME": "admin@example.com",
"SCOUT_PASSWORD": "secret"
}
}
}
}
```
### 选项C - 从源代码构建Docker镜像
```bash
docker build \
--build-arg GIT_SHA=$(git rev-parse HEAD) \
--build-arg VERSION=$(node -p "require('./package.json').version") \
-t scout-mcp:latest \
-t scout-mcp:$(git rev-parse --short HEAD) \
.
```
---
## 配置
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `SCOUT_BASE_URL` | 是 | `https://your-server:22160` - 必须使用 `https://` |
| `SCOUT_USERNAME` | 是 | Scout Board登录用户名 |
| `SCOUT_PASSWORD` | 是 | Scout Board登录密码 |
| `SCOUT_DOMAIN` | 否 | 登录域（如果不需要，请留空） |
| `SCOUT_IGNORE_TLS` | 否 | `true` 以接受自签名证书 |
| `SCOUT_REQUEST_TIMEOUT_MS` | 否 | HTTP超时（毫秒）（默认值：30000） |
| `SCOUT_TEST_OU_PATH` | 仅限测试 | 集成测试的OU路径，例如 `/MCP-Test` |
| `SCOUT_ENV` | 仅限测试 | 设置 `test` 以限制破坏性操作到 `SCOUT_TEST_OU_PATH` |
| `SCOUT_ENABLE_PRIVATE_ENDPOINTS` | 否 | `true` 以暴露11个额外的私有端点工具（见下文） |
> **注意：** 您也可以在运行时使用 `scout_configure` 工具配置凭证 - 不需要 `.env` 文件。
> **警告：** `SCOUT_IGNORE_TLS=true` 禁用证书验证。仅在受控环境中使用自签名证书。
---
## 版本检查
每次MCP重新连接（每次 `docker run` 都是一个新的启动），服务器都会检查最新的GitHub版本并记录到stderr：
```
[scout-mcp] 版本 v1.5.1 是最新的。
# 或：
[scout-mcp] 有更新可用：v1.5.1 → v1.6.0. 请重建Docker镜像以获取最新版本。
```
不会自动采取任何操作 - 检查仅为信息目的。
---
## 资源
Scout MCP暴露可浏览的MCP资源，以便AI客户端可以读取Scout Board上下文而无需消耗工具调用。资源在查询时从实时连接的服务器构建。
| 资源URI | 类型 | 描述 |
| --- | --- | --- |
| `scout://ou-tree` | 具体 | 完整的OU层次结构快照（名称、路径、ID） |
| `scout://ou/<path>` | 具体（枚举） | 单个OU详细信息 - 树中的每个OU一个资源 |
| `scout://devices/{+ouPath}` | 模板 | OU中的设备。示例：`scout://devices/Enterprise/Germany/Berlin`。添加 `?includeSubOus=true` 以包含子OU。 |
**示例效率增益：** 与其调用 `ou_get(mode=structure)` 来了解您的环境，不如让AI客户端一次性读取 `scout://ou-tree` 作为环境上下文 - 零工具槽消耗。
---
## 可用工具（22个公共 + 11个私有）
### 核心工具
| 工具 | 描述 |
| --- | --- |
| `scout_configure` | 在运行时设置、检查或清除Scout Board凭证 |
| `scout_context` | 设置、检查或清除会话级别的工作OU默认值 |
| `health_check` | ping或身份验证系统状态检查 |
| `ou_get` | 读取OU - 单个、根、搜索、下属、结构、设备状态 |
| `ou_manage` | 添加、重命名、删除、移动OU；导出/导入OU结构 |
| `device_get` | 获取设备信息、在OU中搜索、运行时状态、配置来源； **`search_with_config` 模式** 获取每个匹配设备的配置部分 |
| `device_manage` | 添加、重命名、删除、移动设备 |
| `device_command` | 向设备/OU/组发送命令（重启、更新、恢复出厂设置等） |
| `device_diagnostics` | 异步诊断：`run` （自动触发→轮询→下载URL，带有进度），或手动 `trigger` → `poll` → `download_url` |
| `app_list` | 列出基本或OU范围的应用程序 |
| `app_manage` | 创建、删除、复制、移动应用程序；管理继承 |
| `config_get` | 读取配置部分 - 基本、OU或设备范围 |
| `config_update` | 写入配置部分 - 基本、OU或设备范围；传递 `deviceIds[]` 以并行更新多个设备 |
| `config_compare` | 为设备ID列表并行获取配置部分并按相同配置分组 - `uniform: true` 表示所有设备匹配，否则显示不同的组 |
| `label_manage` | CRUD标签用于动态设备配置 |
| `rule_manage` | CRUD规则、验证表达式、管理标签关联 |
| `schedule_manage` | 查看和管理OU和设备的计划命令 |
| `maintenance_window_manage` | CRUD维护窗口 |
| `notification_manage` | 设置和删除设备、OU和组的通知 |
| `scout_update` | 检查并应用服务器更新 |
### 车队工作流工具
这些工具将常见的多步骤操作压缩为单个调用。
| 工具 | 替换 | 描述 |
| --- | --- | --- |
| `onboard_branch` | `ou_manage(add)` + `ou_filter_manage(add)` | 创建一个新的OU分支并过滤器 |
| `move_devices_by_filter` | `device_get(search)` + N×`device_manage(move)` | 查找设备并根据搜索词移动它们 |
| `bulk_command` | `device_get(search)` + N×`device_command` | 查找设备并向它们发送命令 |
所有工作流工具都支持 `dryRun=true` （预览而不写入）和 `confirm=true` （对于大型/破坏性操作需要）。每批操作最多500个设备。
**典型的车队操作工作流：**
```
1. device_get mode=search_with_config ouRef=NorthCreek searchTerm=2603 searchFields=osVersion configSection=firmware
→ 返回每个匹配设备的配置部分
2. config_compare deviceIds=[48,43,55,59] section=firmware
→ 按相同配置对设备进行分组；uniform=false 显示哪些设备不同
3. config_update target=device section=firmware deviceIds=[55,59] body={...}
→ 并行将更正的配置应用于异常设备
```
### 私有端点工具（按需）
这些工具针对Scout Board内部端点 - 它们 **不是** 公共OpenAPI规范的一部分。启用 `SCOUT_ENABLE_PRIVATE_ENDPOINTS=true`。
> **警告：** 这些端点不受支持且未记录。它们可能会在未来Scout Board版本中更改或消失。
| 工具 | 操作 | 描述 |
| --- | --- | --- |
| `system_info` | `status_summary`, `device_count`, `device_distribution`, `device_image_files`, `recovery_settings`, `db_diags`, `system_check`, `tree_filter`, `missed_notifications`, `auth_user` | 只读系统状态和诊断数据 |
| `system_settings` | `get_logging` / `set_logging`, `get_discover` / `set_discover`, `get_retain_local_config` / `set_retain_local_config`, `get_device_name_options` / `set_device_name_options`, `get_recovery_settings` / `set_recovery_settings`, `set_device_password` | 读取和写入服务器范围的设置 |
| `predefined_commands` | `list`, `add`, `modify`, `delete`, `auth`, `list_templates`, `modify_templates` | 管理预定义设备命令 |
| `predefined_paths` | `list`, `add`, `delete` | 管理预定义固件更新路径 |
| `predefined_images` | `list_images`, `list_uefi` | 列出预定义IDF镜像和UEFI文件 |
| `license_manage` | `get`, `check_availability`, `reconfigure` | 读取和重新配置Scout Board许可 |
| `admin_manage` | `list`, `permissions`, `advanced_rights`, `configuration_rights`, `update_rights`, `add_admin`, `update_admin`, `delete_admin` | 读取和写入管理员帐户和UI权限 |
| `server_instances` | `list`, `modify`, `delete` | 管理Scout Board服务器实例 |
| `db_cleanup` | `list`, `delete` | 按筛选器列出和删除数据库记录 |
| `ou_filter_manage` | `get_settings`, `list`, `set_settings`, `add`, `modify`, `delete` | 管理OU筛选规则 - **子网筛选器** （IP网络，例如 `192.168.1.0/24` ）和**用户定义筛选器** （ELUX_* 属性表达式，参见下面的语法） |
| `new_device_options` | `get`, `set` | 读取或更新新设备注册选项 |
#### 用户定义筛选器语法（`custom_filter`）
确认适用于Scout 2605：
| 语法 | 示例 |
| --- | --- |
| 简单匹配 | `ELUX_HOSTNAME=NorthCreek` |
| 前缀匹配（内置） | `ELUX_HOSTNAME=North` - 匹配所有以“North”开头的名称 |
| AND | `ELUX_HOSTNAME=NorthCreek AND ELUX_OSVERSION=2603` |
| OR | `ELUX_HOSTNAME=NorthCreek OR ELUX_HOSTNAME=LiveStick` |
| 用括号分组 | `\(ELUX_HOSTNAME=NorthCreek OR ELUX_HOSTNAME=LiveStick\) AND ELUX_OSVERSION=2603` |
**注意：**
- `AND` / `OR` 必须大写
- 括号必须转义： `\(` 和 `\)`
- `=` 操作符是文档记录的比较运算符； `!=` `>` `<` 可能有效但不在官方Scout 2605文档中
- 没有显式通配符字符 - 内置前缀匹配
- 多个筛选器条目针对同一个OU在评估时进行AND运算
---
## 响应增强
包含数字OUID字段（例如 `device_get`, `device_manage` ）的工具响应会自动注释人类可读的 `_OUIDName` 和 `_OUIDPath` 兄弟节点，以便AI具有完整的上下文而无需后续的 `ou_get` 调用：
```json
{ "Name": "Thin01", "OUID": 42, "_OUIDName": "Berlin Office", "_OUIDPath": "/Enterprise/Germany/Berlin", "Status": "active" }
```
增强功能是尽力而为 - 如果无法获取OU树，则返回原始响应不变。OU映射缓存5分钟，并在任何 `ou_manage` 变更后自动失效。
---
## 404上的模糊建议
当 `ou_get` 或 `ou_manage` 调用返回HTTP 404时，错误会自动包含排名靠前的“您是否想到了？”列表：
```
ou_get failed: OU not found at path "/Enterprise/Germany/Berln" (HTTP 404)
Did you mean one of these OUs?
• "Berlin Office" → /Enterprise/Germany/Berlin
• "Berlin HQ" → /Enterprise/Germany/BerlinHQ
```
按以下顺序匹配：精确 → 前缀 → 子字符串 → 编辑距离相似度。当 `device_get` 或 `device_manage` 返回404时，错误包括提示使用 `device_get mode=search` 通过部分名称定位设备。
---
## 工作OU（会话上下文）
设置一次会话的默认OU，并在后续调用中省略它：
```
scout_context action=set_ou path=/Enterprise/Germany/Berlin
→ 工作OU设置为“Berlin Office”（/Enterprise/Germany/Berlin）
device_get mode=search searchTerm=thin* # 不需要ouPath
ou_get mode=subordinate # 不需要路径
device_manage action=add newDeviceName=Thin99 newDeviceMac=AA:BB:CC:DD:EE:FF
```
工作OU是会话范围（内存中，重启后清除）。使用 `scout_context action=get_ou` 检查和 `action=clear_ou` 取消设置。
**尊重工作OU默认值的工具：** `device_get mode=search` 和 `mode=search_with_config` ， `ou_get mode=subordinate` 和 `mode=device_status` ， `device_manage action=add` 和 `action=move`。
---
## MCP提示（工作流模板）
通过MCP `prompts/list` 和 `prompts/get` 端点公开了五个预建的工作流模板：
| 提示 | 描述 | 关键参数 |
| --- | --- | --- |
| `scout_connect` | 连接到服务器并准备会话 | `base_url`, `username`, `ou_path` （可选） |
| `onboard_device` | 将新设备添加到Scout Board | `device_name`, `mac_address`, `ou_path` （可选） |
| `audit_ou` | 列出和总结OU中的设备健康状况 | `ou_path` （可选）， `include_sub_ous` （可选） |
| `mass_command` | 向OU中的所有设备发送命令 | `command`, `ou_path` （可选）， `confirm` （可选） |
| `move_devices` | 查找设备并移动它们 | `search_term`, `target_ou`, `source_ou` （可选） |
---
## 破坏性操作防护
- `device_command` 带有 `factoryreset` 或 `halt` 需要 `confirm: true`
- `bulk_command` 和 `move_devices_by_filter` 需要 `confirm: true` 以影响多个设备
- 当 `SCOUT_ENV=test` 时，所有写入操作仅限于 `SCOUT_TEST_OU_PATH`
---
## 身份验证
Scout Board使用JWT身份验证。客户端将凭证发送到 `POST /rest/api/v1/user/login` 并接收一个存储在内存中的令牌。该令牌作为 `Cookie: ScoutBoardAuthJWT=<token>` 头部在每个请求中发送。在401响应时，客户端重新身份验证一次并自动重试。
---
## 运行测试
测试需要一个实时Scout Board服务器。所有写入操作仅限于 `SCOUT_TEST_OU_PATH`。
```bash
cp .env.example .env # 填写您的值
npm test
```
如果未设置 `SCOUT_TEST_OU_PATH`，测试套件将立即中止。
---
## 架构
```
src/
index.ts MCP服务器入口点 - 启动身份验证、版本检查、工具调度
client.ts ScoutClient - JWT cookie身份验证、undici TLS控制
session.ts 运行时凭证存储和~/.scout-mcp.json持久化
types.ts 共享帮助程序：ok（）、fail（）、buildQuery（）
enricher.ts 用人类可读的OU名称/路径注释OUID字段（5分钟缓存）
fuzzy.ts 404响应上的排名“您是否想到了？”建议
resolver.ts 为自然语言输入解析OU名称/部分名称为ID
resources.ts MCP资源 - 实时OU树 + 设备库存
progress.ts ProgressReporter - 将server.sendLoggingMessage连接到长时间运行的工具
tools/ 每个功能组一个文件
catalog/
server.yaml Docker MCP注册表提交元数据
tools.json 用于注册表构建验证的静态工具列表
.github/
workflows/
update-mcp-registry.yml 每次推送到main时自动更新注册表PR
cleanup-runs.yml 自动删除失败的工作流运行
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器