Percepxion MCP Server

此存储库已存档。 该项目已转移到Lantronix官方组织： ****

Percepixion MCP服务器

Percepxion是什么？

Percepxion是一个用于带外（OOB）网络设备管理的SaaS平台。它连接到控制台服务器、串行端口聚合器和远程访问设备，以提供车队范围内的可见性、配置管理、固件更新、CLI访问和合规性报告，独立于主网络路径。

此MCP服务器使AI助手可以直接访问Percepixion的管理功能。

______________________________________________________________________

用例

• 库存发现：查找组织中的所有设备，按型号或固件版本过滤
• 远程CLI执行：在设备上运行命令并通过Percepixion检索输出
• 配置管理：推送单个属性更改或从参考设备克隆完整配置
• 固件合规性：将车队固件版本与目标进行比较，并识别不符合要求的设备
• 固件更新：上传固件并针对Smart Group进行协调部署
• 日志检索：按需从设备中提取系统日志或访问日志
• 审计调查：按用户、时间范围或操作搜索平台审计记录
• 租户管理：列出特定租户的组织和范围操作

______________________________________________________________________

运作原理

服务器在本地运行，并通过HTTPS与Percepxion API进行通信。身份验证使用用户名/密码，服务器将其交换为会话令牌，并在进程的整个生命周期内将其保存在内存中。

许多Percepixion操作都是异步的。触发设备操作（CLI命令、配置推送、固件更新、syslog请求）的工具会创建一个Percepxion作业组并返回作业记录。使用 search_job_groups 轮询作业状态并检索结果。

响应信封，所有工具返回此结构：

{ "ok": true, "data": { ... }, "status_code": 200 }

{ "ok": false, "error": "...", "status_code": 401, "details": { ... } }

______________________________________________________________________

先决条件

• Python 3.11或更高版本（推荐3.12）
• 网络访问您的感知API基础URL
• 具有适当权限的Percepixion用户名和密码

______________________________________________________________________

快速开始

Linux或WSL

git clone https://github.com/keelhaulin/percepxion-MCP-Server.git
cd percepxion-MCP-Server

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

cp .env.example .env
# Edit .env, set PERCEPXION_USERNAME, PERCEPXION_PASSWORD, PERCEPXION_API_URL

测试服务器是否启动：

python percepxion_mcp.py

服务器阻止并等待MCP客户端连接。连接客户端，然后呼叫 login_with_env 以进行身份验证。

码头工人

docker build -t percepxion-mcp-server .
docker run --rm -it --env-file .env percepxion-mcp-server

______________________________________________________________________

环境变量

保持 .env 脱离版本控制。回购包括 .env.example 作为一个起点。

______________________________________________________________________

连接MCP客户端

克劳德代码（推荐）

将服务器添加到您的Claude Code MCP配置中：

claude mcp add percepxion -- /path/to/percepxion-MCP-Server/.venv/bin/python /path/to/percepxion-MCP-Server/percepxion_mcp.py

或手动添加到 ~/.claude/settings.json:

{
  "mcpServers": {
    "percepxion": {
      "command": "/path/to/percepxion-MCP-Server/.venv/bin/python",
      "args": ["/path/to/percepxion-MCP-Server/percepxion_mcp.py"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

克劳德桌面（Linux或macOS）

复制 config/claude_desktop_config.example.json 填补你的道路。文件进入：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

克劳德桌面（Windows调用WSL）

使用 config/claude_desktop_config.wsl_windows.example.json.更换 带有此仓库的WSL路径（例如。 /home/youruser/percepxion-MCP-Server).

首次连接检查

连接后，验证集成：

1. 呼叫 login_with_env
2. 呼叫 get_device_list 随着 search_query: "*"

如果 get_device_list 返回设备，服务器正在工作。

______________________________________________________________________

工具参考

完整参考 docs/tools.md。快速总结如下。

会话必须与以下对象建立 login_with_env 在调用任何其他工具之前。

认证

租户管理

设备清单

设备生命周期

智能组

CLI命令

设备配置

固件管理

日志记录

安全和审计

工作追踪

作业跟踪工作流

当工具创建作业时，它会立即返回作业组记录。设备操作以异步方式继续。要获得结果：

1. Call the action tool (e.g. send_direct_cli_command)
   → Returns: { "ok": true, "data": { "job_group_id": "...", "name": "CLI_abc_1742900000" } }

2. Call search_job_groups with the job name or ID
   → Returns: job status, output, and per-device results

CLI命令示例：

{ "search_string": "CLI_abc", "job_type": "command", "subtype": "cli", "limit": 5 }

作业名称包含Unix时间戳后缀，以避免在同一设备上运行多个作业时发生冲突。

______________________________________________________________________

安全

此服务器在生产网络基础设施上执行操作。相应地对待它。

资格证书：

• 保持 .env 在版本控制之外。这 .gitignore 在这个回购中不包括它。
• 将文件权限设置为 600: chmod 600 .env
• 使用具有用例所需最低权限的专用Percepxion服务帐户。不要将管理员帐户用于自动化或代理驱动的工作流。

CLI命令执行：

• send_direct_cli_command 通过Percepxion向设备发送任意CLI命令。服务器中没有命令列表。使用此MCP工具的会话可以重新配置或重置设备。
• 通过服务器发送的所有CLI命令都会记录到stderr中，并带有设备ID和命令字符串，以供审计。
• 在生产或共享环境中，限制谁可以启动MCP服务器进程。

固件上传：

• update_firmware_by_smart_group 读取本地文件路径并将其上传到Percepxion。
• 集 PERCEPXION_FIRMWARE_DIR 限制上传到特定目录。没有这个变量，服务器进程可以读取的任何文件都可以上传。

令牌处理：

• 身份验证令牌仅存储在内存中，从不写入磁盘。
• 在401响应中，会话会自动清除。重新运行 login_with_env 以恢复会话。
• 没有自动令牌刷新。长时间运行的工作流应处理401响应并重新进行身份验证。

网络：

• 服务器仅通过HTTPS与Percepixion通信。
• 验证 PERCEPXION_API_URL 在任何自动化上下文中运行之前，指向正确的Percepixion实例。

______________________________________________________________________

故障排除

______________________________________________________________________

开发人员文档

• docs/tools.md，带有API端点映射的完整工具参考
• docs/adding-new-tools.md，向此服务器添加工具的约定
• docs/claude-example.prompt，Claude Desktop会话的启动系统提示

______________________________________________________________________

更新日志

看 CHANGELOG.md.

许可证

看 LICENSE.