内容
cepxion MCP一个使用 Python [Fast](https://github.com/jlowin/fastmcp服务器，暴露 Percepxion REST API 作为 MCP 工具。将其连接到 Claude Desktop、Claude Code 或任何兼容 MCP 的客户端，通过自然语言管理带外基础设施。
## 什么是 Percepxion？
Percepxion 是一个用于带外（OOB）网络设备管理的 SaaS 平台。它连接到控制台服务器、串口聚合器和远程访问设备，提供整个机队的可见性、配置管理、固件更新、CLI 访问和合规性报告，独立于主网络路径。
该 MCP 服务器为 AI 助手提供直接访问 Percepxion 的管理功能。
---
## 用例
- **库存发现**，查找组织中的所有设备，按型号或固件版本过滤
- **远程 CLI 执行**，在设备上运行命令，并通过 Perce 检索输出
- **配置管理**，推送单个属性更改或从参考设备克隆完整配置
- **固件合规性**，将机队固件与目标进行比较，并识别不符合要求的设备
- **固件更新**，上传固件并针对智能组进行协调发布
- **日志检索**，按需从设备拉取系统日志或访问日志
- **审计，按用户、时间范围或操作搜索平台审计记录 **租户管理**，列出组织并将限定为特定租户## 工作原理
服务器在本地运行，并通过 HTTPScepxion API 通信验证使用用户名/服务器交换会话令在进程生命周期内将其保存在内存中。
许多 Perion 操作都是异步的。触发设备操作的工具（CLI 命令、配置推送、固件更新、系统日志请求）会创建一个 Percepxion 作业组，并返回作业记录。使用 `search_job_groups` 或 `get_job_group` 来轮询状态和检索结果。
**响应信封，所有工具都结构：**
```json
{ "ok": true, "data": { ... }, "status_code": 200 }
```
```json
{ "ok": false, "error": "status_code":, "details": { }
```
---
## 先
- Python 3.11 或更高版本（推荐 3.12）
访问 Percepxion API 端点
- 具有的 Percepx名和密码
---
## 快速入门
### Linux 或
```bash
git clone https://github.com/Lantronix/percepxion-mcp-server.git
cd percepxion-mcp-server
python3 -m venv
source .venv/bin
pip install -e .
cp .env.example .env
# 编辑 .env，设置XION_USERNAME、PERCEPXION_PASSWORD
# 默认 API URL 为 https://pxion.ai/api
# Lantronix 员工：使用 https://api.gopercepxion.ai/api 进行内部沙盒
```
测试服务器启动：
```bash
python percepxion_mcp.py
```
服务器阻塞并等待 MCP 客户端连接。连接客户端后，调用 `login_with_env` 进行身份验证。
### Docker
```bash
docker build -t percepxion-server .
docker run --rm -it --env-file percepxion-mcp-server
```
---
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
---|
| `PERCEPXION_USERNAME` | 是 | | Percepxion 登录用户名 |
| `PERCEPXION_PASSWORD` | 是 | | Percepxion 登录密码 |
| `PERCEPXION_API_URL` | 否 | `https://api.percepxion.ai/api`cepxion API 基本 URL。对于 Lantron内部沙盒，请使用 `https://api.goperion.ai/api`。 |
| `PERCEPX_TENANT_ID 否 | | 默认租户 ID，用于调用者省略 `tenant_id` 时。租户部署。 |
| `PERCEPXION` | 否 | `45` | 秒为单位的 HTTP 超时时间。对于大型或慢速链接超时时间。 |
| `PERCEPXION_FIRMWARE_DIR` | 否 | | 如果设置，固件上传仅限于此目录中的文件。建议用于共享部署。 |
| `PERCEPXION_CREDENTIAL | 否 | ` | 凭证提供程序：`env`（默认vault` 或 `aws`。 |
将 `.env` 保存在版本控制之外。存储库包含 `.env.example`。
### CLI
`send_direct_cli_command` **默认情况下为只读**。仅允许 `、`get`、`ping`、`traceroute读命令。在 `.env` 中配置写访问和过滤：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `PERCEPXION_CLI_WRITE_ENABLED `false` | 设置true` 以允许（`set`` 等）。 |
| `XION_CLI_YOLO` | `false` | 设置为 `true` 以禁用所有命令过滤。请谨慎使用。 |
| `PERION_CLI_MAX_LENGTH` | `512` | 命令的最大长度（字符）。 |
| `PERCEP_CLI_DENY_COMMANDS` | | 除了内置默认项之外，还要阻止以逗号分隔的命令（`reload`、``、`write erase）。 |
| `PERCEPXION_CLI_PERMIT_COMMANDS` | | 以逗号分隔的显式允许列表。如果设置，则匹配的命令（及其子命令）。 |
### 凭证提供程序
默认情况下，从环境变量中读取凭证。提供了两个额外的后端：
**HashiCorp Vault：**
```
PERCEPXION_CREDENTIAL_PROVIDER=vault
VAULT_ADDR=https://vault.example.com
VAULT_TOKEN=hvs.XXXX
VAULT_SECRET_PATH=secret/data/percepxion
```
**AWS Secrets Manager：**
```
PERCEPXION_CREDENTIAL_PROVIDER=aws_SECRET_NAME=perion/credentials
=us-east-1
```
安装 AWS 额外组件：`pip install -[aws]"`
详情请参见 [`config/setup-instructions.md`](config/setup-instructions.md)。
---
## 连接 MCP 客户端
### Claude Code（推荐）
```bash
claude mcp add percepxion -- /path/to/percepxion-mcp-server/.venv/bin/python /path/to/percepxion-mcp-server/percepxion_mcp.py
```
或手动添加到 `~/.claude/settings.json
```json
{
"mcpServers": {
"percepxion": {
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/percepxion-mcp-server/percepxion_mcp.py"],
"env": {
"PYTHONED": "1",
"PERCEPXIONyour-email@example.com",
"PERCEPXION_PASSWORD": "your-password }
}
}
}
```
### Claude Desktop（Linux 或 macOS） `config/claude_des.example.json`，填写路径后放置在：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
### Claude Desktop（Windows + WSL）
使用 `config/claude_desktop_config.wsl_windows.example.json`。将符替换为 WSL 中此存储库。
### 首次连接检查
连接后：
1. 调用 `login_with_env`
2. 调用 `get_device_list`，并设置 `search_query: "*"`
如果 `get_device_list` 返回设备，则服务器正常工作。
---
## 工具参考
完整参考信息请参见 [`docs/tools.md`](docs)。下面是摘要 `login_with 前请先调用**。会话在进程生命周期内持续。遇到 401 响应时，请再次调用 `login_with_env`。
### 身份验证和凭证
| 工具 | 描述 |
|---|---|
| `login_with_env` | 使用配置的凭证提供程序进行身份验证。每个会话调用一次。 |
| `reconfigure_credentials`运行时切换凭证提供程序（`env`、`vaultaws`）并清除当前会话。 |
### 租户管理
工具 | 描述 |
---|
| `list` | 列出当前的组织。使用此 `tenant_id` |
### 设备库存工具 | 描述---|---|
| `_list` | 设备库存。 |
| `get_device_details` | 按 `device_id`serial_num` 获取属性。 |
|_devices_by_organization 列出指定租所有设备。 |
### 设备生命周期
| |
|---|---|
| `import_and_assign_devices` | 将设备分配给。 |
| `_devices` | 从租户中移除一个或。 |
| `_platform` |单个设备（便捷 |
### 智能组
||---|---|
| `create_smart_group` | 使用筛选查询或设备 ID 智能组。用于目标批量操作。 |
list_smart_groups 按名称列出。 |
| `delete_smart_group` | 删除智能组。 |
### CLI 命令
| | 描述 | |---|---|---|
send_direct_cli_command` | 向单个设备发送 CLI默认情况下为只参见上面的 CLI 命令会被审计日志记录。 | 是，使用 `get_job_group` |
### 设备配置
| 工具 | 描述 | 异步？ |
|---|---|---|
| `get_device_config` | 读取当前遥测配置，然后它。 | 否 `update_device_config` | 保存配置属性并立即应用它们。 | 如果 `apply_now=True`，则为异步 |
clone_device_config`模板将配置从复制到目标设备。 | 是，使用 `get_job_group` |
| ``出已保存的配置模板。 | 否 |
| `delete_template` | 按 ID 删除配置模板。 | 否 |
### 设备操作
| 工具 | 描述 | 异步？ |
|---|---|---|
| `reboot_device` | 通过 Percepxion 重启设备 是，使用 `_group` |
| `list_device_ports` | 列出设备上的串端口。返回端口名称、编号和连接状态设备标识，请使用 `get_security_te 或 `get_port_telemetry` 获取主机名序列号和 OS 版本。 | 否 |
固件管理 工具 | 描述 | 异步？ |
|| `get_device` | 获取单个设备的固件版本和状态 否 |
| `firmware_compliance_report`机队固件与预期版本进行比较。 |
| `list_firmware_content` | 列出 Percepxion 存储的固件包 否 |
| `update_firmware_by_smart_group固件并应用于一个或多个智能组中的设备。 | 是，使用 `get_job_group` 日志记录
| 工具 | 描述 | |
|---|---|---|
| `request_device_sys` | 触发设备将系统日志上传到pxion 存储。 | 是，使用 `get_job| `get_device_syslogs` | 查询的系统日志文件。 | 否 |
|_device_access_log` | 设备访问日志条目的。 | 否 |
| `download_device_access_log` | 下载单个设备的完整访问日志。 | 否 |
### 安全和审计
| 工具 | 描述 |
|---|---|
| `get_security_telemetry` | 检索完整的设备和每个端口的数据。托管设备库存的真实来源：端口的 `dp 记录，包括主机名、型号、序列号、OS 版本运行时间和 CPU/闪存使用情况包括控制台管理器固件状态探测和审计记录| `get_port` | 端口的遥测返回结构化的对象，仅限于该端口，相比 `get_security_telemetry` 更快捷、更经济。 |
| `investigate_audit_logs` | 按用户、时间范围或关键词搜索平台审计记录。 |
| `investigate_user_audit_logs` | 搜索用户记录每个用户的操作。作业跟踪
工具 | 描述 |
---|
| `search` | 按名称和轮询状态。 |
| `get_job_group` |组 ID 获取完整的和结果。 |
异步作业工作流工具创建作业立即返回作业
```
1操作工具（例如_command）
：{ "ok": true, "data "id": "jg-abc123", " "CLI_dev001_0000"2. 调用_group，传入 id → 返回：完整的、每个设备的和状态
```
包含 Unix 时间戳避免在同一设备多个作业时的冲突。
---
## 安全
网络基础设施上。请相应地对待**凭证：**
- 将 `.env`控制之外（gitignore` 中）。
- 设置文件权限chmod 600- 使用具有权限的专用 Perion 服务帐户。工作流帐户。
- 对于使用 Vault 或 Manager 提供程序，而不是纯文本 `.env`**CLI 命令策略： `send_direct` **默认情况下读**。识别的只读`show`、`、`ping` 等。
- 内列表阻止破坏性`reload`、`factory-reset`、`write erase`、`erase startup-config），即使启用写- 设置 `PERCEP_CLI=true` 以允许。所有调度的命令都会记录到 stderr，包含设备 ID 和命令- 设置 `PERCEPXION_CLI_DENS` 以添加的命令。设置CEPXION_CLI_PERMIT_COMMANDS` 以使用显式允许列表。
- `PERCEPXION_CLI_YOLO=true` 禁用所有过滤。仅在受信任的隔离环境中使用。
**固件上传：**
- `update_firmware_by_smart_group本地文件将其上传cepxion。
`PERCEP_FIRMWARE_DIR` 以限制上传目录。未设置时，服务器进程可以读取的任何文件。
**令：**
-验证令牌在内存中，绝磁盘。
401 ，会自动清除会话调用 `login` 以恢复。
- 没有自动令牌刷新。长期工作流程应处理 401 重新进行身份验证网络：**
仅通过 HTTPScepxion 通信 默认端 `api.perion.ai`。 内部是 `api.gpxion.ai`任何自动化上下文中，请验证 `ION_API_URL---
## 故障 症 可能原因 | |
|---|---|---|
未认证" |login_with 或令牌过期 | 调用 `login_with_env| 任意401` |中令牌 再次调用 `_env` |
|或超时 |CEPXION_API_URL` 错误 | 检查 `.env`，生产api.perce.ai`，沙为 `apipxion.ai| 日志下载 | 默认 45 秒超时时间太 设置 `PERCEP_REQUEST_TIMEOUT=120 固被拒绝 | 文件PERCEPXION_DIR` 移动文件到允许的目录或取消设置变量 |
| "禁用"策略处于模式 | 在` 中设置 `XION_CLI=true` |
| "命令在拒绝列表中" | 内置拒绝列表阻止命令 | 设置 `PERCEPXION_CLI_YOLO=true` 以绕过（谨慎使用） |
| 服务器立即退出 | Python 路径或虚拟环境问题 | 直接python perce_mcp查看---
## 该项目使用功能分支工作流：
```bash
git checkout -/your-feature
# 进行更改
gitu origin feat-feature
# 打开拉到 main在提交前运行件：
```bash
pip install -[dev]"
pytest -v
服务器上添加新工具的约定，请docs/adding-new-tools.md`](docs/adding.md)。
---
## 开发文档
- [`docs/tools.md`](docs)，完整的工具参考 API 端点- [`docs/-tools.md`](adding-new-tools.md服务器上添加
- [`-instructions.md-instructions.md 和凭证提供详细设置 [`docs/claude`](docs/cl.prompt)，Claude Desktop 会话的启动
---
## 更新日志
请参见 [``](CHANGELOG## 许可证参见 [`LICENSE`](
