MCP-远程控制服务器

Name: MCP-远程控制服务器
Author: Mistral-MCP-Hackathon-2025

作者：Mistral-MCP-Hackathon-20257 星标更新：2025-09-15

安装使用来源：spider==github.com

项目介绍

La Télécommande

观看La Télécommande演示

<div align="center">  <a href="https://www.youtube.com/watch?v=5K_iIvqFtFc" title="在YouTube上观看La Télécommande演示"> <img src="https://img.youtube.com/vi/5K_iIvqFtFc/hqdefault.jpg" alt="La Télécommande演示 — 点击观看YouTube视频" width="560" /> <br /> <sub>点击观看YouTube上的演示</sub> </a> </div>

作者

卢卡斯·杜波特 • 阿尔芒·布林 • 亚瑟·库塞尔 • 萨米·雅塞夫 • 弗拉维安·乔弗雷

</div>

La Télécommande是什么？

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

我们解决的问题

无论是管理数百台虚拟机的DevOps工程师，还是对命令行感到恐惧的偶尔开发者，基础设施管理总是同样的故事：繁琐、容易出错且耗时。你知道你想实现什么目标，但要达到这个目标意味着记住无数的命令，处理不同的操作系统发行版，管理SSH密钥，最糟糕的是——一次只能操作一台机器。

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

我们的解决方案

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

使用简单的提示配置服务器
在任何发行版或操作系统上安装软件包（是的，甚至Arch Linux！）
即刻获取监控洞察并显示日志
同时跨多台机器进行部署
并行执行命令——只需几秒钟即可部署到整个机群，而不是几个小时

关键创新：自然语言 → 基础设施行动

原理非常简单：

通过我们的MCP服务器配置设置机器访问
用自然语言向Le Chat描述你的意图
Le Chat理解并使用我们的MCP工具执行动作
命令自动并行运行于你的基础设施中

面向所有人

这不仅仅是针对硬核的DevOps专业人士。由于我们的自然语言界面，无论是经验丰富的基础设施工程师还是更喜欢避免命令行的开发者都可以同样轻松地管理基础设施——只需提问并描述他们想要完成的任务。

La Télécommande让远程操作对于MCP客户端来说变得极其简单，同时保持透明的访问控制和配置优先，确保你的基础设施在大规模下既安全又易于管理。

特点

带有类型结果的Paramiko SSH
YAML优先配置：VM、用户、组
选择加入权限模型（默认关闭，除非有用户/组）
清晰的FastMCP引导，带有HTTP和stdio传输
强大友好的错误消息：“API密钥无效或VM未被允许”
使用Weave（由Weights & Biases提供）进行跟踪和可观测性
使用Qdrant + Mistral嵌入进行语义日志搜索及洞察

快速开始

前置条件

Python 3.13+
macOS/Linux带zsh/bash

创建虚拟环境并安装依赖项（通过uv）

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

配置VM

复制config_examples.yaml到config.yaml并编辑主机/密钥/用户。
设置CONFIG环境变量指向你的YAML文件，如果未使用默认路径。

运行

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

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

可选：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：获取时发送的X-API-Key头部。
WANDB_API_KEY：Weights & Biases的API密钥；用于认证Weave跟踪。

启动行为

服务器启动时，如果没有设置CONFIG，则期望项目根目录中有一个名为<CONFIG_FILENAME>的文件。
如果该文件不存在，服务器将从${URL}/${VERSION}/${CONFIG_FILENAME}获取，使用头部X-API-Key: ${API_KEY}，并将文件保存到本地后再继续启动。
当需要获取而缺少URL、VERSION或API_KEY中的任何一个时，启动将失败并显示有用的错误信息。

认证与权限

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

客户端必须发送授权头部。支持的格式：
- Authorization: Bearer <API_KEY>
- Authorization: <API_KEY>（原始值）
授权决定了你可以看到和访问哪些VM。
错误故意使用单一消息以清晰表达：API密钥无效或VM未被允许。

当禁用权限（没有users键）时：

所有VM都可见且无需任何授权头部即可调用。

MCP工具

所有工具都在src/SSH/tools.py中定义，并由src/server.py注册。

ssh_list_vms

目的：列出调用者可以访问的VM名称。
参数：无
返回：{ vms: string[] }
错误：当启用权限且API密钥缺失或无效时抛出ValueError。

ssh_is_vm_up

目的：快速TCP探测VM的SSH端口，粗略估计延迟。
参数：vm_name: string
返回：{ vm, host, port, reachable, latency_ms, reason }
错误：当启用权限且授权失败时抛出ValueError。

ssh_vm_distro_info

目的：只读诊断：发行版、内核、初始化系统、包管理器、主机/用户基本信息。
参数：vm_name: string
返回：{ vm, host, port, status, distro, platform, network, user, notes[] }
错误：当授权失败或出现SSH错误时抛出ValueError。

ssh_run_command

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

ssh_search_logs

目的：在SSH历史记录中进行语义搜索（命令、stdout、stderr）。
参数：
- query（字符串，必需）：自然语言（例如："oom killer"，"failed scp to backup"）。
- collection（字符串，可选）：commands | stdout | stderr（默认：commands）。
- host_filter（字符串或null，可选）：仅来自此主机。
- user_filter（字符串或null，可选）：仅来自此用户。
- time_hours（整数或null，可选）：限制到最近N小时。
- limit（整数，可选）：最大结果数（默认：10）。
返回：{ query, total_found, results[] }，其中每个结果包含：
- relevance_score（浮点数），host（字符串），command（字符串），job_id（字符串），timestamp（浮点数），formatted_time（字符串），stdout（字符串），stderr（字符串），return_code（整数或null）
示例：
- 查找最近的OOM错误：{ "query": "oom killer", "collection": "stderr", "time_hours": 6 }

ssh_get_statistics

目的：聚合SSH命令历史记录的使用统计。
参数：
- time_hours（整数，可选）：回溯窗口（默认：24）
- user_filter（字符串或null，可选）：限制到一个用户
- host_filter（字符串或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。

ssh_suggest_commands

目的：根据先前成功的执行建议命令，使用语义相似性。
参数：
- context（字符串，必需）：自然语言目标，例如："检查磁盘空间"
- host（字符串或null，可选）：偏向特定主机
- limit（整数，可选）：建议的数量（默认：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（由Weights & Biases提供），初始化为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écommande可以记录每次SSH操作并将其索引用于语义搜索和分析。

工作原理

src/qdrant/log_manager.py使用Mistral Embed嵌入命令/stdout/stderr，并将其插入Qdrant。
集合在首次使用时自动创建（如果不存在），以及用于过滤的负载索引。
src/qdrant/tools.py中的工具查询Qdrant以支持搜索、统计和建议。

集合及负载模式

ssh_commands（向量大小1024，余弦）
- 负载：job_id（字符串），host（字符串），user（字符串），command（字符串），timestamp（浮点数），return_code（整数）
ssh_stdout（向量大小1024，余弦）
- 负载：基础字段+stdout（字符串）
ssh_stderr（向量大小1024，余弦）
- 负载：基础字段+stderr（字符串）

环境变量

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: "检查磁盘空间" }

故障排除

缺少包：确保已安装mistralai和qdrant-client（参见pyproject.toml）。
结果为空：验证SSH执行器是否调用了log_ssh_operation，并且环境变量指向您的Qdrant。
嵌入限制：stdout/stderr被截断至约30k字符以适应模型限制。

故障排除

fastmcp未找到：激活您的虚拟环境；确保已安装FastMCP。
Python版本错误：La Télécommande针对Python 3.13。
权限错误：确保发送正确的授权头部，并且您的API密钥属于具有包含VM的组的用户。
SSH错误