mcp-trmm

TRMM MCP 服务

专为 TRMM 风格的远程管理操作打造的精简 MCP 服务。

该项目提供一组精选的 MCP 工具，用于执行常见的 IT 运维任务，例如：

• 查找和控制 Agent
• 检查项
• 脚本
• 服务
• 软件
• Windows 更新
• 报告
• 警报
• 自动化
• 任务

该服务专为本地或较小的模型设计，因为这些模型不擅长构建原始 API 路径、HTTP 方法或 JSON 负载。

该服务不会暴露一个通用的“调用任意端点”工具，而是提供名称明确、参数精简的小型工具。后端会将这些参数转换为有效的 API 请求。

为什么要开发这个项目

较小的本地模型往往难以做到以下事项：

• 选择正确的端点
• 选择正确的 HTTP 方法
• 构建有效的 JSON 负载
• 正确区分 ID 和对象类型
• 避免破坏性操作或范围过大的操作

该服务通过为模型提供以下内容来解决这些问题：

• 精简的工具集
• 明确的工具名称
• 简单的参数
• 由后端负责请求转换
• 一致的结果处理

简而言之，模型决定要做什么，后端决定如何调用实际 API。

---

架构

项目分为四个主要层：

server.py

托管 FastAPI 应用，并在 /mcp 挂载 MCP ASGI 应用。

还包括：

• MCP 路由的 bearer token 保护
• 简单的 /healthz 端点

rmm_tools.py

定义向模型公开的 MCP 工具。

模型应只看到这些函数。

示例：

• list_agents()
• get_agent(agent_id)
• reboot_agent(agent_id, mode="normal")
• run_agent_command(agent_id, command, shell="cmd")

translator.py

将适合模型使用的参数转换为实际的 API 请求。

此层负责处理：

• 选择端点
• 选择方法
• 构建 JSON 请求体
• 规范化参数
• 简单的操作映射

示例：

• 模型调用 reboot_agent(agent_id="abc", mode="force")
• 转换器将其转换为 PATCH /agents/{agent_id}/reboot/，并附上正确的请求体

api_client.py

向上游 TRMM/PAI API 发送最终的 HTTP 请求，并返回规范化的结果对象。

此层负责处理：

• 身份验证标头
• 超时
• JSON 解析
• 状态处理
• 结构化错误报告

---

设计目标

该 MCP 服务有意采用明确的设计取舍。

1. 精简的工具集

该服务仅包含实用工具，而非上游架构中的所有端点。

2. 适合模型使用的工具

每个工具的设计都便于较小的模型正确调用。

3. 优先读取

只要可行，模型都应先检查，再执行操作。

4. 请求格式由后端负责

模型不应负责构建原始端点路径或请求负载。

5. 更安全的操作

破坏性操作或会改变状态的工具数量有限，且名称明确。

---

当前工具覆盖范围

Agent

• list_agents
• get_agent
• get_agent_history
• get_agent_notes
• create_agent_note
• get_agent_tasks
• create_agent_task
• reboot_agent
• shutdown_agent
• wake_agent
• run_agent_command
• run_agent_script
• get_agent_eventlog
• list_agent_processes
• get_agent_process
• kill_agent_process

检查项

• list_checks
• get_check
• list_agent_checks
• run_checks
• run_checks_for_agent
• reset_check
• reset_all_checks_for_agent

软件

• get_agent_software
• uninstall_agent_software
• list_choco_packages

Windows 更新

• get_agent_winupdates
• scan_agent_winupdates
• install_agent_winupdates

服务

• list_agent_services
• get_agent_service
• control_agent_service

脚本

• list_scripts
• get_script
• download_script
• test_script_on_agent

报告

• list_report_history
• run_report_history
• list_report_schedules
• get_report_schedule
• run_report_schedule

警报

• get_alert
• update_alert_status

自动化

• get_automation_policies_overview
• get_automation_policy
• list_automation_policy_checks
• list_automation_policy_tasks
• run_automation_task
• get_automation_task_status
• get_automation_check_status

任务

• list_tasks
• get_task
• run_task

---

有意不包含的内容

此服务不会尝试公开上游架构中的每个端点。

除非确有需要，否则会有意避免以下类型的端点：

• 每种对象类型的通用 CRUD
• 范围宽泛的管理变更端点
• 含义高度模糊的更新端点
• 原始透传 API 工具
• 需要大型请求正文、配置繁琐的端点
• 与现有清晰工具重叠过多的工具

这样可以避免模型不堪重负，并减少错误选择工具的情况。

---

工具行为示例

示例 1：按名称重启 Agent

模型应：

1. 调用 list_agents
2. 找到正确的 Agent
3. 调用 reboot_agent(agent_id, mode="normal")

示例 2：调查服务问题

模型应：

1. 找到 Agent
2. 调用 get_agent_service(...) 或 list_agent_services(...)
3. 检查结果
4. 仅在收到请求或明确合适时，才调用 control_agent_service(...)

示例 3：检查 Windows 更新

模型应：

1. 调用 get_agent_winupdates(agent_id)
2. 检查结果
3. 仅在收到请求时，才调用 scan_agent_winupdates(...) 或 install_agent_winupdates(...)

---

运行服务

使用 Uvicorn 启动 FastAPI 应用：

uvicorn server:app --host 0.0.0.0 --port 8000