Airlock MCP
Provides read-only Git repository inspection in the remote workspace via git-status and git-diff operations, allowing agents to view working tree status and diffs.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Airlock
A capability airlock for agents. Narrow, auditable SSH channels to a server — only registered operations pass, and every pass is logged.
给 agent 的「能力气闸」:通往服务器的窄通道。模型只能执行登记过的操作,拿不到任意 shell。 两个通道,方向相反:
通道 | 方向 | 用途 |
| 读写服务器上的工作区 | 让 agent 看代码、改文件、跑预注册的检查 |
| 本地构建产物 → 服务器 | 发版、切版本、失败自动回滚 |
它是什么
两台机器之间只跑一条 SSH 连接,stdin/stdout 接一个 JSON Lines 协议。请求侧说得越少, 能被滥用的面就越小:
remote-dev只开放 12 个固定 op:读(status/list/read/git-status/git-diff)、 写(lease-acquire/lease-release/apply)、执行(check/job-status/job-cancel)、 交接(release-request)。另有host-runtime端口:4 个服务槽位 + 3 个动作(restart/reload/status), 请求侧只能给槽位 id,不能给命令或单元名。deploy只认「应用 id + 版本号 + 归档」:启停命令、健康检查、目录结构全部来自服务器本地配置, 本机传不了命令进服务器。
Related MCP server: permission-aware-mcp
它不是什么
不是 SSH 的替代品,不是 Ansible,不是通用运维通道。
不执行任意命令、不提供交互式 PTY、不管理数据库、不
tail -f日志。不托管凭据:私钥在本机 ssh agent 或受保护文件里,profile 只存路径。
不负责构建:
deploy推的是已经构建好的目录,构建是调用方的事。
架构
agent / MCP client 本地
│ stdio (MCP) │
▼ │ npm run build(你自己)
bin/airlock-mcp.mjs ──┐ │
bin/airlock.mjs ──────┤ ssh -T -o BatchMode=yes
bin/airlock-deploy.mjs┘ │
│ │
▼ │
sshd (restrict + ForceCommand) │
│ stdin/stdout │
▼ │
bin/airlock-broker.mjs 或 │
bin/airlock-deployer.mjs │
├─ JSON Lines 协议(版本不符直接拒) │
├─ 路径白名单 + realpath 校验 │
├─ 版本目录 + current 链接 │
└─ 状态、日志、数据快照 │快速开始
需要 Node.js ≥ 24:直接运行 TypeScript,靠内置类型剥离,没有构建步骤。
git clone https://github.com/XneoZero/airlock.git && cd airlock
npm install
npm test # 78 个测试,不连服务器、不读 config/
npm run typecheck不想 clone:下 Releases 里的 airlock-0.1.0.tgz,
npm i -g ./airlock-0.1.0.tgz 直接装。
想先看界面:双击 airlock-ui.cmd(或 ./airlock-ui.sh),见 控制台。
还没有档案时它不会空转退出,而是打开「接入第一台服务器」的引导页——顺序是
先由人 RDP 进目标机把 SSH 打开(agent 进不去没有 SSH 的机器),再把页面上那段提示词交给 agent。
通道一:remote-dev(改服务器上的文件)
服务器侧配置 broker.json:
{
"profileId": "prod",
"serverId": "srv-prod01",
"workspaceId": "ws-app",
"root": "/opt/airlock/workspace",
"stateDir": "/opt/airlock/state",
"releaseInbox": "/opt/airlock/inbox",
"writable": true,
"tasks": {
"test": { "command": "npm", "args": ["test"], "timeoutMs": 600000 },
"build": { "command": "npm", "args": ["run", "build"], "timeoutMs": 600000 }
}
}root 是唯一可读写的工作区;stateDir 与 releaseInbox 必须在工作区之外。
tasks 里没登记的名字,check 一律拒绝。完整示例见 examples/broker.example.json。
本机 profile:
{
"default": "dev",
"profiles": {
"dev": {
"serverId": "srv-dev01",
"host": "ssh.example.com",
"user": "airlock-dev",
"identityFile": "~/.ssh/airlock-dev",
"brokerCommand": "node /opt/airlock/bin/airlock-broker.mjs --config /opt/airlock/config/broker.json",
"hostKeyChecking": "yes"
}
}
}profile 只放连接信息,不放私钥内容。完整示例见 examples/remote-profiles.example.json。
node bin/airlock.mjs status
node bin/airlock.mjs list --path src
node bin/airlock.mjs read --path package.json
node bin/airlock.mjs apply --path src/a.ts --expected-hash <hash|none> --operation-id op-0001 --content-file a.ts
node bin/airlock.mjs check --task testMCP(暴露 10 个 remote_* 工具):
node bin/airlock.mjs mcp通道二:deploy(本地构建产物 → 服务器)
npm run build # 先自己验证
airlock-deploy release --app web --source ./dist # 打包 → 上传 → 切版本 → 重启 → 探活
airlock-deploy rollback --app web # 切回上一版,起不来会自己退回来
airlock-deploy status --app web --probe # 现在跑的是哪版、健康不健康
airlock-deploy status --app web --server staging # 同一份代码,换台机器查服务器侧目录:
/srv/apps/web/
├── releases/<版本>/ 每次发布一个目录,解压后原样保存
├── current -> releases/… 正在跑的版本(Linux 符号链接 / Windows junction)
├── backups/<版本>.tar.gz 发布前数据快照(配置了 backupPaths 才有)
├── state.json 当前版本 + 历史
└── deploy.log 每次切版本、启停都记一行三条纪律:请求侧只提交「应用 id + 版本号 + 归档」;包解压后在服务器重算摘要,对不上整包作废;
切换前后都落 state.json 与日志,失败如实写 failed 并自动回退到上一版。
配置、回滚语义、数据备份细节见 docs/DEPLOY.md; 从零接入一台新服务器见 docs/ONBOARDING.md(Windows)或 docs/ONBOARDING-LINUX.md(Linux)。
控制台
不想敲命令时,直接用仓库根目录的启动入口:
平台 | 入口 |
Windows | 双击 |
macOS / Linux |
|
也可以用命令:
airlock-deploy ui --app web # 全局安装后
node bin/airlock-deploy-ui.mjs # 或直接跑仓库里的入口控制台是本地服务端渲染的单页,没有
index.html可以双击打开: 页面由src/deploy/ui/page.ts在请求时生成,一次性 token 也在那时下发。 上面的两个脚本就是入口。
纯本地服务(只绑 127.0.0.1,一次性 token 进 URL),一个页面做四件事:
切项目 / 切服务器:同一份代码可以推到测试机和正式机,不用配两份档案。 下拉只列真实存在的服务器;选择会记在浏览器本地,下次打开回到上次的项目与服务器。 切换项目时服务器跟着该项目的默认目标机走。
看:本地 git 提交、服务器上的版本历史、
deploy.log发:选本地构建产物目录(自动探测
dist/build/out等)→ 发布退:点某个版本回退,或改服务器上的发布落点
落点(root)可以直接在控制台改:点「落点」后面的「改」,走服务器端目录浏览器,
默认停在管理员桌面。改完下一次请求就生效,旧目录里的版本不会自动搬过去。
Windows 上的默认落点就是管理员桌面:C:\Users\Administrator\Desktop\<应用id>。
scripts\provision-windows.ps1 在 deployer.json 缺省时按这个位置生成配置,
并顺手把 ACL 授给部署组——部署账号读不到别人的 profile 目录,不授权第一次发布就会失败。
新机器生成的配置用 "layout": "mirror":服务器落点就是本地发布目录的副本,内容与目录结构
和本地一致,不掺 releases/、current、state.json。版本信息留在本地 git,回退就是
git checkout <旧版本> 再发一版。
想换回「root 是链接 → 当前版本」的老结构,把 layout 改成 flat(root 是链接)或删掉
(nested,root 下带 releases/current)。
mirror 下默认会「按本地对齐」——源里没有的文件会被删掉。上传目录、数据库这类运行时数据
必须显式保护:sharedPaths(换成链接,数据挪到 .airlock/<应用id>/shared/)或
preservePaths(只跳过,目录结构不变)。两者分工见 docs/DEPLOY.md。
多项目与多服务器
档案分三层:
{
"default": "web-prod",
"servers": {
"prod": { "host": "ssh.example.com", "user": "airlock-deploy", "identityFile": "~/.ssh/k1",
"serverId": "srv-prod01", "deployerCommand": "node /opt/airlock/bin/airlock-deployer.mjs --config /etc/airlock/deployer.json" },
"staging": { "host": "10.0.0.12", "user": "deploy", "identityFile": "~/.ssh/k2",
"serverId": "srv-stage01", "deployerCommand": "..." }
},
"profiles": {
"web-prod": { "server": "prod", "app": "web", "workspace": "~/work/my-web" },
"api-prod": { "server": "prod", "app": "api", "workspace": "~/work/my-api" },
"web-staging": { "server": "staging", "app": "web", "workspace": "~/work/my-web" }
}
}servers 是机器清单,profiles 是项目。控制台右上角的服务器下拉就是 servers 的键;
命令行用 --server <名字>,和控制台是同一套解析:只换机器,app 与本地目录跟着项目走。
名字写错会直接报错,不会退回默认那台。
档案每个请求前都会重读,所以运行中改了档案,回控制台刷新就能看到新服务器,不用重启。
档案查找顺序:--profiles > AIRLOCK_DEPLOY_PROFILES_FILE > AIRLOCK_DEPLOY_PROFILES(内联 JSON)
~/.airlock/deploy-profiles.json与./config/deploy-profiles.json合并(同名以项目内为准)。 前三项是「只读这一份」,会关掉合并——项目内配的项目会看不见,所以一般不要设。 老格式(把host直接内联在 profile 里)仍然可用。
接入新机器
Windows 上一条命令(在目标机的管理员 PowerShell 里跑,源码先按 docs/TRANSFER.md 弄上去):
.\scripts\bootstrap-windows.ps1 -PublicKey 'ssh-ed25519 AAAA... ag-ssh-deploy' -AppId demo它依次做:下载源码(GitHub 被 reset 就自动换国内镜像)→ 装 Node 24(npmmirror)→
解到 C:\airlock 并 npm ci --omit=dev → 建部署账号 + 密钥 + sshd 门禁 →
在管理员桌面生成默认落点配置与启停脚本并授权。加 -DryRun 可以先看它要做什么。
不想用脚本、或目标是 Linux,按 docs/ONBOARDING.md(Windows)/ docs/ONBOARDING-LINUX.md(Linux)一步步来。 国内云主机拿不到 GitHub、或 agent 只剩发布通道时怎么办,见 docs/TRANSFER.md。
控制台顶部「+ 服务器」会把这一整套写成一段提示词,复制给 agent 就行——里面带了本机实际路径、
每步的验证要求和几个已知的坑(Windows 防火墙规则、AllowGroups 白名单、profile 目录带机器后缀、ACL 别一刀切)。
平台相关的路径和措辞按运行控制台的操作系统生成,Windows / macOS / Linux 各按各的写。
配合 agent 使用
仓库带一份 DSH 技能:skills/airlock-deploy/SKILL.md。
装到本机技能目录后,agent 遇到「发版 / 回滚 / 接新服务器」会自动加载它——里面是完整的
操作流程、配置要点、失败模式对照表(13 类报错 → 原因 → 处理)和交付前自检清单。
mkdir -p ~/.dsh/skills/airlock-deploy
cp skills/airlock-deploy/SKILL.md ~/.dsh/skills/airlock-deploy/在每个使用 airlock 的项目里也要落一份,否则那个项目的 agent 读不到规范——
技能文件躺在 node_modules/airlock/skills/ 下,不在 agent 的扫描路径里:
airlock-deploy skill install --profile web-prod # 写 <项目>/.dsh/skills/airlock-deploy/SKILL.md生成的文件 = 通用规范 + 自动填好的「本项目」小节(profile、服务器、app、落点、布局、
sharedPaths / preservePaths)。首行带 <!-- airlock:generated --> 标记,重复执行会刷新;
遇到手写的同名文件不覆盖,除非加 --force。release 发现项目还没落规范时会提示一行。
技能里刻意不写死任何路径和 IP,改用「先查再答」:status 返回的 root、where airlock-deploy、
档案的实际来源。这样换机器、换账号都不用改技能。
安全模型
路径:先过语法白名单(拒绝绝对路径、
..、NUL),再resolve+ 带分隔符的前缀比较, 最后对落点realpath——挡住指向工作区外的符号链接。并发:
apply必须持有效租约;expectedHash不匹配就HASH_MISMATCH,不会覆盖别人的修改。幂等:
operationId落在stateDir,重启后同一次重试不会产生第二次写入。执行:
check只认预注册任务名,shell:false,参数数组固定,输出有上限。失败:只回错误码,不回堆栈;未预期异常一律
INTERNAL。发布落点:只认服务器配置里的
root,客户端不能在请求里临时指定;改落点要走set-root并拒绝盘根与系统目录。控制台:只绑
127.0.0.1,所有 API 都要 URL 里的 token,防其它网页撞进来发版。
与 ssh-mcp 类项目的关系
社区主流是「把 shell 交给模型」,再用正则白名单或审批做补救。Airlock 反过来: 默认没有 shell,能力面由 op 决定,策略在服务器侧强制执行,不在模型侧拦截。 代价是表达力——没预注册的排障要等人扩任务。这是有意的取舍。
目录结构
src/contracts/ 协议契约(zod schema、错误码)
src/transports/remote-dev/ Broker / client / 协议 / 工作区 / 任务 / MCP
src/transports/host-runtime/ systemd / Windows service 的预注册动作
src/deploy/ 发布通道:归档校验、版本状态、启停探活、落点管理
src/deploy/ui/ 本地控制台(node:http + 单页 HTML,无前端构建)
bin/ CLI、MCP 入口、服务器侧 Broker 与 deployer
docs/ 发布通道与接入流程
examples/ 各类配置示例,含 Minecraft 服务端模板
test/ 隔离测试(临时目录 + 本机 node 进程)开发与测试
npm install
npm test # node --test,全部隔离
npm run typecheck # tsc --noEmit测试不连服务器、不读 config/、不发消息。改代码时约定:
注释和提交信息用中文,代码标识符用英文。
报错信息写「为什么错 + 怎么办」,不要只回一个错误码。
不猜默认值:任何会影响服务器上真实文件的参数要么必填,要么有明确回退理由。
状态
已用隔离测试覆盖:协议编解码、Broker 路径 / CAS / 租约 / 任务白名单、客户端超时与错误码、
工作区写入原子性、宿主动作白名单、打包与摘要一致性、路径穿越、协议行与二进制混读、
install / activate / rollback、激活失败自动回退、数据备份恢复、落点校验与写回。
已用真实服务器端到端跑通:Windows + OpenSSH ForceCommand 的部署通道、版本切换与自动回滚、
多服务器切换、有状态服务(Minecraft Fabric 服务端:世界数据放在 releases/ 之外,用 junction 持久化)。
未验证:Linux 服务器上的完整链路、多客户端并发、慢链路下的大包传输稳定性、 带数据库迁移的回滚、macOS 作为控制台宿主。
许可
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Scoped, audited SSH exec, sessions, and SFTP on your saved servers without exposing credentials
Manage remote servers, SSH terminals, files, databases and proxies with scoped access and approvals.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables secure remote workspace management over SSH, supporting file operations, shell commands, and profile configuration for agent-safe remote code environments.-
- FlicenseAqualityDmaintenanceEnables secure file system operations (read, write, delete) and simulated command execution with server-enforced permission policies, risk assessment, and human-in-the-loop approval.5-
- FlicenseAqualityBmaintenanceEnables coding agents to perform workspace-confined file operations, read-only Git inspection, and structured shell commands, while requiring out-of-band human approval for mutations and external executions and maintaining an audit trail.143-
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to securely inspect and edit approved code, use semantic code intelligence, run builds/tests, supervise bounded processes, inspect Git, and execute owner-approved SSH commands on engineering workstations.2Apache 2.0