muziyuyang/linux_handler_mcp repository overview

⁠Linux Agent MCP 规格说明书 · 极简版 v2.0

⁠1. 产品概述

Docker 交付的 MCP Server + Web 管理端。Agent 通过 2 个 MCP 工具在局域网 Linux 主机上远程执行命令；管理员通过 Web 控制台管理主机、实时查看执行流、为敏感命令输入密码。

设计基调：面向个人局域网服务器运维，克制复杂度、不做迁移、安全适当放宽。

⁠2. 裁剪对照表（相对 v0.5 全量版）

⁠3. 功能需求（as-built）

⁠4. 命令状态机

PENDING ──→ RUNNING ──→ SUCCESS | FAILED | TIMEOUT
                │
                └─→ WAITING_SECRET_INPUT ──(Web 提交)──→ RUNNING
                         │
                         └─(120s 未提交)──→ FAILED(SECRET_INPUT_EXPIRED)
PENDING ──→ WAITING_APPROVAL ──(Web 批准)──→ RUNNING | WAITING_SECRET_INPUT
                    │               └─(Web 拒绝)──→ REJECTED
                    └─(300s 未审批)──→ APPROVAL_EXPIRED

• 挑战提交为一次性：过期/已消费的 challengeId 提交返回错误，密码不落库、不回显、不出现在任何执行记录。

⁠5. 接口清单（as-built）

MCP 工具（2 个）：linux.execute_command、linux.help_info（Streamable HTTP /mcp，X-API-Key 或 Bearer 鉴权）。

Web 页面：/login、/console（实时命令）、/console/hosts（主机管理）；未登录访问控制台 303 → /login。

Web API：/api/hosts（GET/POST）、/api/hosts/{id}（PATCH/DELETE）、/api/hosts/{id}/test、/api/hosts/{id}/toggle、/api/hosts/backup（GET，下载 JSON）、/api/hosts/restore（POST，UploadFile）、/api/commands/recent、/api/console/stream（SSE）、/api/challenges/{id}（POST）、/api/approvals/{id}（POST，action=approve/reject）、/login、/logout、/health。

⁠6. 非功能约定

• 输出单值上限 65,536 字符（超出截断并标记 truncated）
• 敏感输入挑战有效期 120s（CHALLENGE_EXPIRE_SECONDS），过期惰性翻转；密码错误可重试，最多 3 次
• 高风险审批有效期 300s（APPROVAL_EXPIRE_SECONDS），审批单一次性消费，拒绝/过期均为终态
• 执行记录保留 500 条 FIFO；SSE 监控窗口 30 条
• DB 只初始化不迁移：schema 变更须删库重建（数据宽松原则）
• 打包约束：pyproject.toml package-data 必须含 web/*.html，改页面后须跑一次 wheel 构建核验

⁠7. 验收标准（与 .scratch/smoke_v2.py 32 项对齐）

⁠8. 决策记录

• D-1（决策 1）= 选项 A：完全移除高风险拦截与确认令牌。
• D-2（决策 2）= 选项 A：移除 host_info 工具。
• D-3（决策 3）= 选项 B：敏感输入采用 Web 弹窗实时输入，不预置 sudo 密码（体验基准：linux-handler-python-mcp）。
• D-3+：应用户要求新增 linux.help_info 工具，承载参数说明与动态主机清单。
• D-4（2026-09-05 16:40）：控制台拆分为「主机管理」与「实时命令」双页面，顶部导航切换，功能不变；/console 保留为实时命令页。
• D-5（2026-09-05 17:00）：修复 _sudo_stdin_command 复合命令缺陷——原实现只改写行首第一个 sudo，sudo -k; sudo whoami 中第二个裸 sudo 改写后无法获得 stdin 密码通道。现改为行首及 ;/&/|/换行分隔后的每个 sudo 段均改写 sudo -S（已含 -S 的段跳过）；risk.py 的 SUDO_PATTERN 同步支持换行分隔以保持识别/改写一致。已知边界：单条命令内多个都需要密码的 sudo 段，第二个起仍会因 stdin 密码已被消费而失败（stdin 单次注入机制限制），建议拆分执行。
• D-6（2026-09-06 20:39）：高风险命令人工审批回归（v2.1）。以 Web 人工审批方式替代 D-1 移除的 v1 BLOCKED/confirm 令牌机制（不复引入 confirm MCP 工具，工具数保持 2 个）；新建 approval_challenges 表（应用户确认，项目无历史数据包袱）；审批先于密码挑战（复合命令先审批、批准后再输密码）；审批价值定位为防 Agent 误判/幻觉命令，静态规则库按"宁少拦不误拦"原则持续迭代。

⁠9. 原待确认项落地结果

⁠10. 变更记录

docker run -d \
  --name "${CONTAINER_NAME}" \
  --restart unless-stopped \
  --user "$(id -u):$(id -g)" \
  -p "${HOST_PORT}:${CONTAINER_PORT}" \
  -v "${DATA_VOLUME_HOST}:/app/data" \
  -e HOST="${HOST}" \
  -e PORT="${PORT}" \
  -e LOG_LEVEL="INFO" \
  -e LOG_JSON="true" \
  -e API_KEY="${API_KEY}" \
  -e CREDENTIAL_ENCRYPTION_KEY="oK7EKqEJkcOQ-uC71Yz2ioLw65LP_JV-l0v_SPhPydA=" \
  -e DATABASE_PATH="./data/linux_agent.db" \
  -e HOST_CONCURRENCY_LIMIT="3" \
  -e SESSION_IDLE_TIMEOUT_SECONDS="1800" \
  -e SESSION_COOKIE_SECURE="false" \
  -e CHALLENGE_EXPIRE_SECONDS="180" \
  -e APPROVAL_EXPIRE_SECONDS="300" \
  -e MCP_ALLOWED_HOSTS="192.168.100.120:*" \
  -e DEBUG="false" \
  "linux_handler_mcp"

call me: [email protected]⁠