Codex ServerOps MCP

ServerOps

通过日常对话，从 Codex 或 Claude Code 操作你选择的 Linux 服务端，无需在其上安装 ServerOps Agent。

ServerOps 会在操作间保留实用的 Bash 状态，返回结构化证据，并在 OpenSSH 或 sudo 需要输入时打开可见的本地窗口。它面向自由职业者、代理机构、支持团队、项目所有者和运维人员，帮助他们可靠地处理服务端工作，而不必一直待在 SSH 终端中。

三项承诺

轻松上手

轻量的 Codex 和 Claude Code 插件连接到同一个 ServerOps 核心。引导式本地助手会创建明确的服务端配置，不会将凭据放入聊天中。

轻松操作

用日常语言描述你想要的结果。ServerOps 会在持久的 Bash 会话中保留工作目录和 shell 环境，支持交互式终端操作，并返回有界的结构化结果，而不是失控的终端文本墙。

结果至关重要时依然可靠

会话归本地 Broker 管理的工作进程所有，而非临时的 MCP 进程。如果远程变更的结果不确定，ServerOps 会报告 outcome_unknown，绝不会自动重试。Linux 权限、明确的配置、可见的身份验证、受控的权限提升、哈希前置条件，以及经过脱敏的本地审计，共同构成信任层。

查看实际效果

以下是适用于当前提供的八种工具的真实提示词：

List my ServerOps profiles. Do not connect to a server or change anything.

Use the customer-web profile. Start read-only, identify the host and current user, then explain
why the service is unhealthy. Narrow the diagnosis with evidence instead of dumping every log.

Open the project profile, enter /srv/my-app, inspect the current Git and Compose state, and keep
the session open so we can continue from the same directory.

Read /srv/my-app/.env.example with the structured file tool. Propose a minimal change and show me
the observed SHA-256, but do not apply anything until I approve it.

查看分步的可复现演示，了解预期证据和安全边界。

当前提供的功能

• 明确的配置，以及可见的本地配置助手。
• 由 Broker 管理的有状态 Bash 会话，支持已完成命令和交互式终端模式。
• 安装可选的托管 Broker 任务后，如果 Broker、工作进程和 Bash 仍在运行，则 MCP 客户端重启后可重新发现会话。
• 明确报告结果未知的错误，不会自动重试结果不确定的变更。
• 在已配置的根目录内进行有界的结构化 UTF-8 文本操作，编辑时可选用 SHA-256 前置条件。
• 可见的本地 OpenSSH 身份验证和主机密钥决策，并提供引导式 sudo 和可选的 root 会话。
• 经过脱敏的本地 JSONL 审计事件，不包含远程输出或文件内容。
• 一个包含八种工具的 MCP 核心，以及轻量的 Codex 和 Claude Code 封装。
• 首次启动 MCP 时自动执行幂等的本地引导。
• 除 Codex 外，还提供原生 Claude Code Marketplace 和插件。
• 不会在 Linux 服务端安装 ServerOps Agent 或守护进程。

当前运行时优先支持 Windows，并使用 Windows OpenSSH 连接 Linux。详细的工具参考定义了准确的操作和架构。

Codex 快速入门

安装仓库 Marketplace 和插件。固定版本的 0.1.1 MCP 会在首次启动时创建自己的本地状态；无需预先运行设置命令：

codex plugin marketplace add cyyprezz/codex-serverops-mcp
codex plugin add codex-serverops-mcp@serverops-codex

启动新的 Codex 任务。使用此插件时，不要额外添加用户级 [mcp_servers.serverops] 配置块。如果先前的安装程序创建了这个替代配置块，请先用 serverops-install codex-config --remove 预览删除操作，然后仅在审核后使用 --apply 执行。这会保留配置和审计数据。开始时先不要连接服务端：

List my ServerOps profiles. Do not create, edit, remove, test, or connect to a profile. If no
suitable profile exists, wait for me to provide non-secret suggestions before opening the visible
profile assistant. Credentials and host-key decisions belong only in the local ServerOps window.

Claude Code 快速入门

Claude Code 封装使用相同的固定版本 0.1.1 运行时和与客户端无关的技能：

claude plugin marketplace add cyyprezz/codex-serverops-mcp
claude plugin install serverops@serverops-claude

如果 GitHub 简写需要尚未配置的 SSH 密钥，请改用 HTTPS 添加市场：

claude plugin marketplace add https://github.com/cyyprezz/codex-serverops-mcp.git

启动新的 Claude Code 会话（或重新加载插件），并使用相同的安全首条提示词。

自动本地引导

版本 0.1.1 无需单独的设置命令即可启动。MCP、broker、设置、检查、Doctor 和更新共用一个幂等引导流程，仅准备由 ServerOps 管理的本地状态：当前用户的应用、配置、运行时、审计、迁移和状态路径。

引导流程不会编辑 Codex 或 Claude 配置、安装计划任务、创建配置文件、联系服务器、请求管理员权限，也不会覆盖非托管文件。可见的配置文件助手仍是首次联系服务器的唯一可能入口。

显式的 serverops-install setup 命令仍兼容且幂等，可用于维护和预览可选的 broker 任务；它不再是插件的前置条件。

可选安装程序和 broker 任务

固定版本的安装程序可检查共享运行时或客户端路径：

uvx --from "codex-serverops-mcp==0.1.1" serverops-install check --client core
uvx --from "codex-serverops-mcp==0.1.1" serverops-install doctor --client claude

doctor --client codex 也会检查由替代安装程序管理的用户配置。因此，仅安装插件的 Codex 可能会提示缺少此可选配置块；该警告并不能证明插件无法正常工作。

仅当 MCP 客户端进程重启后需要可靠地重新发现活动会话时，才安装由当前用户管理的 broker 任务。先预览，再明确应用：

uvx --from "codex-serverops-mcp==0.1.1" serverops-install setup --broker-task
uvx --from "codex-serverops-mcp==0.1.1" serverops-install setup --broker-task --apply

该任务不会请求管理员权限，也不会存储密码。它不能让会话在 Windows 重启或 broker 崩溃后继续运行；当前 broker 不会接管孤立的工作进程。

典型工作流

客户服务器检查

选择指定的客户配置文件，从只读操作开始，确认目标和身份，仅检查相关服务证据，并分别报告事实、假设、缺口和任何更改。

远程项目工作

进入项目目录一次，在多次调用间保留其 shell 环境，运行有界命令，并对已配置路径使用结构化文件读取或带前置条件的文本编辑。

交互式或长时间运行的工作

只有当命令确实需要交互、增量输出、中断、调整大小或保留终端状态时，才使用终端。已完成的命令最长可运行配置的 3600 秒，并返回退出代码、持续时间、CWD 和截断状态。

已配置的远程文件

在配置文件指定的根目录内，对 UTF-8 文本路径执行列出、检查、搜索、读取、哈希、写入、修补、重命名、创建或删除操作。这些根目录限制结构化文件工具的范围；它们不会限制 shell 命令，也不能替代备份。

身份验证和 sudo

密码、密钥口令、主机密钥决策和交互式 sudo 输入均保留在单独且可见的本地窗口中。ServerOps 可以使用现有 OpenSSH 行为，也可以指导受控的密钥迁移。Sudo 仍受服务器的 PAM 和 sudoers 策略约束。

一次性 SSH 命令还是 ServerOps？

需求	ssh host "command"	ServerOps
执行一条独立命令	最简直接方案	可以使用，但通常没有必要
保留当前工作目录和 Shell 环境	每次都要重新构建	保存在一个持续运行的 Bash 会话中
交互式终端控制	需要终端工作流	光标读取、输入、中断、调整大小、状态
结构化文本文件	解析并引用 Shell 输出	有界结果和可选的哈希前置条件
身份验证提示	由终端处理	独立的可见本地窗口
结果不确定的远程变更	操作者必须根据传输中断情况判断	明确返回结果未知；不会自动重试
MCP 重启后继续操作	执行新的 SSH 命令	只要进程仍在运行，就可通过可选的代理任务重新发现

ServerOps 不会取代 SSH。它使用 OpenSSH，并为由 AI 主导的操作增加有状态、结构化的边界，让反复执行的一次性命令不再脆弱或难以审查。

架构

flowchart LR
    C["Codex plugin"] --> M["Shared ServerOps MCP core"]
    A["Claude Code plugin"] --> M
    M --> B["Local per-user broker"]
    B --> W["One worker per live session"]
    W --> S["Windows OpenSSH"]
    S --> L["Configured Linux server<br/>Bash + common utilities"]
    W -. "visible local prompts" .-> U["Operator"]
    M --> F["Local profiles + redacted audit"]

MCP 进程提供八个工具。代理负责会话路由，每个工作进程只管理一个 SSH/Bash 进程，ServerOps 的任何组件都不会安装在远程端。请参阅架构和代理生命周期。

要求和实际限制

• 当前版本要求 Windows 10 或 11、Python 3.12、uv/uvx 和 Windows OpenSSH Client。
• 可通过 SSH 访问、带有 Bash 的 Linux 账户；结构化文件操作需要使用结构化远程文件中列出的常用工具。
• ServerOps 仍处于 alpha 阶段。请从一次性或非生产账户开始，并限制 Linux 权限。
• 有状态意味着由进程持有：不支持持久化任务、重启后恢复，也不支持在代理崩溃后接管工作进程。
• 结构化文件操作仅限有界 UTF-8 文本，不支持二进制或可恢复传输，也不是事务性文件系统。
• allowed_roots 仅限制结构化文件工具。Shell 命令仍保留 SSH 用户的实际权限。
• ServerOps 不保证恰好执行一次。交付后发生超时或连接丢失，可能导致操作效果未知，需要通过只读方式进行验证。
• 目前优先支持的客户端是 Codex 和 Claude Code。Claude Desktop、Cherry Studio 和其他桌面客户端的接入计划尚未发布。
• 目前还没有 ServerOpsSetup.exe；公开版本需要 Python 3.12 和 uvx。

功能状态

功能	状态	边界
配置档案、已完成的命令、交互式终端	可用	八工具 MCP 核心
由代理管理的有状态会话	可用	代理、工作进程和 Bash 均保持运行时
MCP 重启后重新发现	可用	要保证可靠性，需要可选的托管代理任务
结构化 UTF-8 文本文件	可用	已配置的根目录、有界数据、可选的 SHA-256 前置条件
可见身份验证、引导式 sudo、本地审计	可用	本地信任层；Linux 策略仍具有权威性
Codex 插件	在 0.1.1 中可用	精确固定到 0.1.1 运行时版本
Claude Code 插件	在 0.1.1 中可用	精确固定到 0.1.1 运行时版本
自动本地引导	在 0.1.1 中可用	无需预先设置；仅管理自身状态
ServerOpsSetup.exe 和独立 Windows 运行时	计划在 0.1.2 推出	发布后无需 Python/uv
持久化任务、回执、事件日志、日志、可恢复传输	计划在 0.2 推出	持久化操作状态，而非命令包装器
持久化调查和事件时间线	计划在 0.3 推出	基于操作存储构建
事务性变更和机群部署	计划在 0.4 推出	前置条件、验证、补偿；不保证恰好执行一次
备份保障和原生数据库适配器	计划在 0.5 推出	仅用于 Shell 提示不足以满足需求的场景

机器可读的功能契约让此表、证据路径、工具名称、市场身份标识和公开版本固定值都可供测试。

路线图

• 0.1.1A： Claude Code、中性品牌标识、自动本地引导、项目基础建设。
• 0.1.1B： 以证据为依据的产品展示和可复现演示。
• 0.1.1C： 同步版本固定、干净机器冷启动、生命周期回归测试、 与提交绑定的发布证据，以及发布强化。
• 0.1.2： 独立的 Windows 打包、图形化引导，以及明确确认的 桌面客户端集成。
• 0.2–0.5： 持久化运维、调查、适用于服务器集群的安全变更、备份保障，以及范围明确的 原生适配器。

请参阅 ROADMAP.md 了解各阶段的定义。计划中的项目尚不是可用功能。

文档和项目

• 快速入门和可复现演示
• 安装、更新、Doctor 和卸载
• 配置文件、工具和 故障排除
• 身份验证、权限提升、 结构化文件和安全模型
• 架构、ADR和 发布证据
• 0.1.1 版本说明、 迁移和回滚以及 发布检查清单
• 更新日志、制品计划和 贡献指南

如需支持，请提交 GitHub issue，但请勿附上 凭据、私钥、客户主机名或生产环境输出。请通过 SECURITY.md报告漏洞。ServerOps 采用 MIT 许可证。