Server Control MCP

自托管的 Linux 服务器控制集成：让远程 MCP 客户端通过持久化 OAuth 调用文件、补丁、命令、终端会话、Git 和图片工具，并可订阅定向事件。

状态：0.1.0，首个提取版本。 目标平台 Linux / Python 3.11+。 执行核心来自 coding-tools-mcp 0.3.0，保持原样安装；本项目提供持久化认证网关、事件适配和部署集成。 不是上游官方发行版，也不是独立实现的执行引擎。

English · 部署 · 事件 · 安全边界 · 来源与差异

环境要求

• Linux，Python 3.11+（CI 覆盖 3.11 / 3.12 / 3.13）

• 自己的 HTTPS 反向代理或隧道（本服务不签发 TLS 证书）

• 可选：Docker Compose（Linux host 网络）或 systemd

Related MCP server: MCP Ops Toolkit

提供什么

工具列表（上游 18 项）

启用事件后，网关额外提供 server/discover 与 events/*（见下文）。

OAuth 只解决调用者认证；所有授权客户端仍共用一个操作系统账号和工作目录。 适用于自己管理的客户端，不用于互不信任的租户。

快速开始

以下命令在本项目根目录执行，使用普通用户：

python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/server-control-mcp init
mkdir -p workspace

编辑生成的 .env：将 CODING_TOOLS_MCP_SERVER_URL 改为自己的 HTTPS 源站地址， 例如 https://mcp.example.com，不加 /mcp；按需修改 SCM_WORKSPACE。 保留自动生成的密码和签名密钥，将 .env 放在工作目录之外。 该文件使用字面量 KEY=value 格式，不要加引号或 shell 表达式。

.venv/bin/server-control-mcp --env-file .env serve

默认执行端是 127.0.0.1:28766，OAuth 网关是 127.0.0.1:28767。 通过你自己的 HTTPS 反向代理或隧道将网关对外提供服务。 两者都不直接绑定公网。更完整的部署方法见 部署说明。

在支持远程 MCP OAuth 的客户端中添加：

https://mcp.example.com/mcp

使用生成配置里的专用密码登录。支持动态注册的客户端通常不需要预填 Client ID / Secret。 客户端是否支持令牌刷新、实验性 Events，取决于客户端自身；本版本没有逐个平台重新验收。

配置

init 生成的 .env 包含以下键（完整说明见 部署说明）：

权限模式

由上游 coding-tools-mcp 0.3.0 执行：

dangerous 等同于以服务账号身份不受限执行，仅在隔离环境中使用。 实际生效情况请用 server_info / check_exec_environment 确认。

可选事件

设置 SCM_EVENTS_ENABLED=1 并重启后，支持实验性 MCP Events 的客户端可订阅 server.changed。本地业务系统按该客户端的 OAuth client_id 定向投递：

.venv/bin/server-control-mcp --env-file .env emit \
  --recipient YOUR_OAUTH_CLIENT_ID --kind task.assigned

回调只含事件编号、类型和时间，不含任务正文，也不代表任务已处理。 事件说明包含订阅格式、签名验证、去重和业务适配边界。

Docker 与 systemd

• Linux Docker：.env 需在宿主机上生成（compose 会覆盖其中的状态与工作目录为命名卷）：

  python3 -m venv .venv && .venv/bin/python -m pip install .
  .venv/bin/server-control-mcp init          # 生成 .env
  # 编辑 .env 中的 CODING_TOOLS_MCP_SERVER_URL
  docker compose up -d --build

  示例用普通容器用户（UID 10001）和命名卷，采用 Linux host 网络；HTTPS 入口仍由你配置。

• 长期运行：参考 systemd 模板，调整目录后安装。

• 不依赖任何特定云厂商、个人令牌或个人域名。

验证与打包

python -m unittest discover -s tests -v
python scripts/smoke.py
python scripts/release.py --check-only
python scripts/release.py

Smoke 在临时目录和随机端口启动真实执行端及网关，跑 OAuth 登录、文件与命令调用、 重启持久化、刷新与撤销；不会连接生产服务器或公开端口。 发布脚本按白名单创建源码 ZIP，拒绝常见凭据格式，并可从未纳入版本控制的本地 .release-denylist 文件读取额外正则（每行一个）。 验证结果和未覆盖部分见 VALIDATION.md。

许可证与来源

Apache-2.0，保留 LICENSE 和 NOTICE。上游执行包固定为 0.3.0，未复制其核心源码。 我们曾将它与官方 PyPI 发布 wheel 做逐文件比较，核心 15 个 Python 文件一致。 扩展提取来源和公开版改动见 provenance.md。