MCP La Telecommande

遥控器

        

查看正在运行的遥控器

Click to watch the demo on YouTube

作者

卢卡斯·杜波特 • 阿尔芒·布林 • 阿瑟·库塞尔 • Samy Yacef • 弗拉维安·杰弗里

什么是遥控器？

遥控器 （法语为“The Remote”）将Mistral转变为真正的DevOps副驾驶，解决了现代基础设施管理中最持久的挑战之一： 人类意图和机器执行之间的复杂性障碍.

我们解决的问题

无论你是管理数百个虚拟机的DevOps工程师，还是偶尔害怕命令行的开发人员，基础设施管理都是一样的：乏味、容易出错、耗时。你知道你想要实现什么，但实现这一目标意味着记住无数命令，处理不同的操作系统发行版，管理SSH密钥，最糟糕的是——一次一台机器，按顺序完成所有事情。

如果你能简单地用自然语言描述你想要什么，并在整个基础设施中立即执行，那会怎么样？

我们的解决方案

La Télécommand是一个基于SSH的模型上下文协议（MCP）服务器，它弥合了自然语言和基础设施操作之间的差距。它将Le Chat转变为您基础设施的实际运营商，使您能够：

• 配置服务器 有简单的提示
• 安装程序包 在任何发行版或操作系统上（是的，甚至是Arch Linux！）
• 获取监控见解 即时生成地表日志
• 协调部署 同时跨多台机器
• 并行执行命令 --在几秒钟内部署到整个舰队，而不是几个小时

核心创新：自然语言→ 基础设施行动

原理非常简单：

1. 设置机器访问权限 通过我们的MCP服务器配置
2. 描述你的意图 以自然语言进入Le Chat
3. Le Chat理解 并使用我们的MCP工具执行操作
4. 命令并行运行 自动跨越您的基础架构

为每个人打造

这不仅仅适用于核心DevOps专业人士。得益于我们的自然语言界面，经验丰富的基础设施工程师和喜欢避免命令行的开发人员都可以同样轻松地管理基础设施——只需提出问题并描述他们想要实现的目标。

La Télécommand使MCP客户端的远程操作变得非常简单，同时保持访问控制的透明性和配置优先性，确保您的基础设施在规模上保持安全和可管理性。

______________________________________________________________________

亮点

• 通过Paramiko进行SSH并键入结果
• YAML优先配置：虚拟机、用户、组
• 选择加入权限模型（如果没有用户/组，则默认关闭）
• 使用HTTP和stdio传输清理FastMCP引导
• 强而友好的错误消息：“API密钥无效或不允许VM”
• Weave的跟踪和可观测性（按权重和偏差）
• Qdrant+Mistral嵌入技术支持的语义日志搜索和洞察

快速启动

前提条件

• Python 3.13+
• macOS/Linux与zsh/bash

1. 创建一个虚拟环境并安装deps（通过uv）

curl -sSL https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate
uv pip install -r pyproject.toml

1. 配置虚拟机

• 复制 config_examples.yaml 向 config.yaml 以及编辑主机/密钥/用户。
• 设置 CONFIG 如果不使用默认路径，则使用环境变量指向您的YAML文件。

1. 跑

source .venv/bin/activate
fastmcp dev main.py

默认情况下 fastmcp dev 使用stdio传输。跑步 python main.py （或 fastmcp run)将使用中配置的流式HTTP传输 main.py.

可选：HTTP传输

MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=8000 fastmcp dev main.py

然后用客户端或curl访问服务器（路径将取决于您的MCP客户端）。

配置

把你的配置放在YAML中。最小值：VM列表。可选择添加组和用户以启用权限。

示例（参见 config_examples.yaml):

vms:
  - name: vm1
    host: 192.168.1.10
    user: ubuntu
    port: 22
    key: |
      -----BEGIN OPENSSH PRIVATE KEY-----
      ...
      -----END OPENSSH PRIVATE KEY-----

groups:
  - name: dev
    vms: [vm1]

users:
  - name: alice
    api_key: "alice-secret"
    groups: [dev]

备注

• 如果 users 或 groups 完全省略，权限被禁用，所有VM都是可访问的。
• 根据黑客马拉松的要求，密钥以明文形式存储；不要泄露真正的秘密。

环境

• CONFIG （可选）：YAML文件的绝对或相对路径。如果设置，则将直接使用它，并跳过自动获取行为。
• CONFIG_FILENAME：在项目根目录下查找的文件名（默认值 config.yaml).
• VERSION：版本段附加到获取URL。
• URL：从中获取配置的基本URL。
• API_KEY：API密钥作为发送 X-API-Key 获取时使用header。
• WANDB_API_KEY：API权重和偏差键；用于验证Weave跟踪。

启动行为

• 在服务器启动时，如果 CONFIG 如果未设置，服务器需要一个名为的文件 `` 在项目的根。
• 如果该文件不存在，服务器将从 ${URL}/${VERSION}/${CONFIG_FILENAME} 带有标题 X-API-Key: ${API_KEY} 并在继续启动之前将其保存在本地。
• 如果有 URL, VERSION，或 API_KEY 当需要获取时，如果缺少这些信息，启动将失败，并显示一条有用的错误消息。

身份验证和权限

启用权限时（存在 users 列表）：

• 客户端必须发送授权标头。支持的格式：

- Authorization: Bearer - Authorization: （原始值）

• 授权决定了您可以看到和访问哪些虚拟机。
• 为清楚起见，错误故意使用单个消息： API key invalid or VM not permitted.

当权限被禁用时（否 users 按键）：

• 所有VM都是可见的，并且可以在没有任何Authorization标头的情况下调用。

MCP工具

所有工具定义见 src/SSH/tools.py 并由以下人员注册 src/server.py.

1. ssh_list_vms

• 目的：列出调用者可以访问的VM名称。
• 参数：无
• 退货： { vms: string[] }
• 错误： ValueError 当权限被启用并且API密钥丢失/无效时。

1. ssh_is_vm_up

• 目的：以粗略的延迟快速TCP探测VM的SSH端口。
• 参数： vm_name: string
• 退货： { vm, host, port, reachable, latency_ms, reason }
• 错误： ValueError 启用权限时授权失败。

1. ssh_vm_distro_info

• 用途：只读诊断：发行版、内核、init、pkg管理器、主机/用户基础知识。
• 参数： vm_name: string
• 退货： { vm, host, port, status, distro, platform, network, user, notes[] }
• 错误： ValueError 授权失败或SSH错误。

1. ssh_run_命令

• 目的：在允许的VM（bash-lc）上执行shell命令。
• 参数： command: string, vm_name: string
• 退货： { command, status: 'executed', stdout, stderr, return_code }
• 错误： ValueError 在授权失败、SSH/auth问题或非零退出（包括stderr）时。

1. ssh_search_logs

• 目的：跨SSH历史（命令、stdout、stderr）进行语义搜索。
• Args：

- query （字符串，必填）：自然语言（例如“oom杀手”、“scp备份失败”）。 - collection （字符串，可选）：其中之一 commands | stdout | stderr （默认值： commands). - host_filter （string | null，可选）：仅来自此主机。 - user_filter （string | null，可选）：仅来自此用户。 - time_hours （int|null，可选）：限制为最后N小时。 - limit （int，可选）：最大结果（默认值：10）。

• 退货： { query, total_found, results[] } 其中每个结果包含：

- relevance_score （浮动）， host （字符串）， command （字符串）， job_id （字符串）， timestamp （浮动）， formatted_time （字符串）， stdout （字符串）， stderr （字符串）， return_code （int | null）

• 例子：

- 查找最近的OOM错误： { "query": "oom killer", "collection": "stderr", "time_hours": 6 }

1. ssh_get_统计

• 目的：汇总SSH命令历史上的使用统计数据。
• Args：

- time_hours （int，可选）：回溯窗口（默认值：24） - user_filter （string | null，可选）：限制为一个用户 - host_filter （string | null，可选）：限制为一个主机

• 退货： { time_period_hours, commands_executed, successful_commands, failed_commands, most_used_hosts, most_common_commands, recent_errors[] }

- recent_errors[] 元素： { host, command, error, timestamp }

• 注：成功/失败基于 return_code == 0.

1. ssh_suggest_命令

• 目的：使用语义相似性从之前成功执行的命令中提出建议。
• Args：

- context （字符串，必填）：自然语言目标，例如“检查磁盘空间” - host （string | null，可选）：偏向特定主机 - limit （int，可选）：建议数（默认值：5）

• 退货： { context, host, total_suggestions, suggestions[] }

- 建议有： { command, relevance_score, host, last_used, success_rate }

• 注：仅来源于历史 return_code == 0；通过命令删除重复项。

使用流程（推荐）

• 呼叫 ssh_list_vms 首先发现允许的VM。
• 可选呼叫 ssh_is_vm_up 到飞行前连接。
• 使用 ssh_vm_distro_info 用于诊断。
• 使用 ssh_run_command 用于实际的远程执行。

例子

可达性

tool: ssh_is_vm_up
args: { "vm_name": "vm1" }
→ { vm, host, port, reachable, latency_ms, reason }

区域和平台信息

tool: ssh_vm_distro_info
args: { "vm_name": "vm1" }
→ { vm, host, port, status, distro, platform, network, user, notes }

运行命令

tool: ssh_run_command
args: { "vm_name": "vm1", "command": "uname -a" }
→ { command, status: 'executed', stdout, stderr, return_code }

发展

• 棉绒/格式：Ruff（配置于 pyproject.toml).
• 跟踪：Weave（按权重和偏差）初始化为 la-telecommande.
• 入口点： main.py （默认情况下为HTTP）， src/server.py （FastMCP实例，工具注册）。

模块布局

• src/SSH/tools.py：SSH的公共MCP工具。仅限精简编排层。
• src/SSH/remote_executor.py：基于Paramiko的SSH客户端包装器。
• src/SSH/utils/:

- auth.py：授权标头解析帮助程序。 - masking.py：日志记录的安全屏蔽（避免秘密泄露）。 - network.py：TCP可达性和延迟检查实用程序。 - osinfo.py：分发解析和包管理器检测。 - types.py：工具的共享TypedDict结果合同。

配置和权限

• src/config/manager.py：加载YAML、索引VM、公开助手。
• src/config/permissions.py：可选用户/组模型和检查。
• src/config/credentials.py：键入VM凭据容器。

语义日志搜索（Qdrant+Mistral）

La Télécommand可以记录每个SSH操作并对其进行索引，以便进行语义搜索和分析。

运作原理

• src/qdrant/log_manager.py 使用Mistral Embed嵌入命令stdout/stderr，并将其插入Qdrant。
• 首次使用时会自动创建集合（如果缺少），以及用于过滤器的有效载荷索引。
• 工具在 src/qdrant/tools.py 查询Qdrant以增强搜索、统计数据和建议。

集合和有效载荷模式

• ssh_commands （矢量大小1024，余弦）

- 有效载荷： job_id （str）， host （str）， user （str）， command （str）， timestamp （浮动）， return_code （int）

• ssh_stdout （矢量大小1024，余弦）

- payload：相同的基字段+ stdout （str）

• ssh_stderr （矢量大小1024，余弦）

- payload：相同的基字段+ stderr （str）

环境变量

• QDRANT_URL：例如。 http://localhost:6333 或托管端点
• QDRANT_API_KEY：如果您的Qdrant实例需要身份验证
• MISTRAL_API_KEY：用于嵌入

启用日志记录

• SSH执行器通过以下方式调用日志记录 log_ssh_operation(job_id, host, user, command, result).
• 如果只运行核心SSH工具而从不调用记录器，Qdrant集合将保持为空。

查询示例

• 搜索最近12小时失败的命令： ssh_search_logs { query: "failed", collection: "commands", time_hours: 12 }
• 获取主机的使用统计数据： ssh_get_statistics { host_filter: "vm1", time_hours: 72 }
• 建议进行常见的磁盘检查： ssh_suggest_commands { context: "check disk space" }

故障排除

• 丢失的包：确保 mistralai 和 qdrant-client 已安装（请参见 pyproject.toml).
• 空结果：验证SSH执行器正在调用 log_ssh_operation env变量指向你的Qdrant。
• 嵌入限制：stdout/stderr被截断为约30k个字符，以适应模型限制。

故障排除

• 未找到fastmcp：激活您的venv；确保安装了FastMCP。
• Python版本错误：远程目标Python 3.13。
• 权限错误：请确保发送正确的授权标头，并且您的API密钥属于包含VM的组的用户。
• SSH错误：在YAML中验证VM的主机、用户、端口和密钥材料。

致谢

创建于2025年Mistral AI MCP服务器黑客马拉松期间。感谢组织者、导师、合作伙伴以及围绕FastMCP、Paramiko和Weave的开源社区。