Enoch

enoch-mcp

enoch-mcp 是一个本地 Model Context Protocol stdio 服务，面向已配置的 Enoch FastAPI 控制平面 API。 它让 MCP 客户端能够通过类型化工具检查和操作 Enoch，而无需暴露原始 shell 或重新实现 Enoch 业务逻辑。

Enoch 系统仓库 · 文档 · MCP

功能

• 为 Enoch 控制平面、Dashboard V1 和核心端点注册 MCP 工具。
• 向已配置的 Enoch API URL 发送请求。
• 使用已配置的令牌，为 API 请求添加 Authorization: Bearer <token>。
• 将 Enoch API 响应返回给 MCP 客户端。
• 为只读工具添加 MCP 只读注解。
• 将修改类工具标记为非只读，并添加审批元数据。
• 为试运行操作保留安全默认值。
• 可选地通过工作器 API 或允许列表中的 SSH 诊断直接探测已配置的 CPU/GPU 工作器。

不提供的功能

• 不提供原始 shell 工具。
• 不接受任意 SSH 命令。
• 不会直接读取或写入本地工件文件。
• 不会调用语言模型。
• 不会缓存、重试、排队或安排工作。
• 不会绕过 Enoch 身份验证或授权。

要求

• Python 3.11 或更高版本
• 正在运行的 Enoch API，通常位于 http://localhost:8787
• Enoch API 持有者令牌
• 能够运行本地 stdio 服务的 MCP 客户端

安装

通过 uvx 从 PyPI 运行：

uvx enoch-mcp --api-url http://localhost:8787 --api-token '<token>'

或使用环境变量进行配置：

export ENOCH_API_URL='http://localhost:8787'
export ENOCH_API_TOKEN='<token>'
uvx enoch-mcp

从代码检出目录进行本地开发：

git clone https://github.com/alias8818/enoch-mcp.git
cd enoch-mcp
uv sync --dev
uv run enoch-mcp --api-url http://localhost:8787 --api-token '<token>'

配置

选项	环境变量	默认值	说明
--api-url	ENOCH_API_URL	http://localhost:8787	Enoch API 的基础 URL。
--api-token	ENOCH_API_TOKEN	无	Enoch API 的持有者令牌。
--worker-probes-json	ENOCH_WORKER_PROBES_JSON	无	用于直接诊断工作器的可选 JSON 映射。
--worker-probes-file	ENOCH_WORKER_PROBES_FILE	无	用于直接诊断工作器的 JSON 映射的可选路径。

令牌为必填项。如果缺少令牌，工具调用会在发出 HTTP 请求前失败。

可选的工作器探测

除非配置了 ENOCH_WORKER_PROBES_JSON 或 ENOCH_WORKER_PROBES_FILE，否则工作器探测处于禁用状态。这样可确保默认软件包只是一个轻量级控制平面桥接层。配置后，MCP 会公开用于核实工作器实际状态的命名诊断项：API 健康状态、worker-gate 仪表板状态、活动进程标记、有界日志尾部、磁盘空间以及预期工件是否存在。

示例：

{
  "cpu": {
    "api_url": "http://127.0.0.1:18788",
    "api_token": "worker-api-token",
    "service_name": "enoch-control-plane",
    "project_root": "/srv/enoch/projects"
  },
  "gpu": {
    "api_url": "http://127.0.0.1:18789",
    "api_token": "worker-api-token",
    "ssh_host": "worker-gpu.example.internal",
    "ssh_user": "enoch",
    "service_name": "enoch-control-plane",
    "project_root": "/srv/enoch/projects",
    "log_paths": ["/var/log/enoch-control-plane.log"]
  }
}

每个通道支持的字段：

• api_url：worker-gate 基础 URL。首先用于 /healthz、/dashboard/api、/dashboard/api/run/{run_id} 和 /project-status/{project_id}。
• api_token：工作器持有者令牌。视为机密。
• ssh_host、ssh_user、ssh_port：可选的 SSH 回退/调试目标。
• service_name：用于服务检查和 journal 尾部的 systemd 单元名称。
• project_root、state_dir：用于磁盘和工件检查的固定工作器根目录。
• log_paths：可读取尾部的固定 worker-gate 日志路径。

SSH 探测只会运行固定的诊断命令，不接受 MCP 客户端提供的任意 shell 输入。用户提供的 ID 仅限安全的运行/项目标识符字符，日志输出有长度限制，SSH 使用批处理模式且不接收标准输入；建议部署为只读工作器用户或强制命令策略。

MCP 客户端设置

Claude Desktop

{
  "mcpServers": {
    "enoch": {
      "command": "uvx",
      "args": ["enoch-mcp"],
      "env": {
        "ENOCH_API_URL": "http://localhost:8787",
        "ENOCH_API_TOKEN": "replace-with-token"
      }
    }
  }
}

进行本地开发时，将 MCP 客户端指向代码检出目录：

{
  "mcpServers": {
    "enoch": {
      "command": "uv",
      "args": ["--directory", "/path/to/enoch-mcp", "run", "enoch-mcp"],
      "env": {
        "ENOCH_API_URL": "http://localhost:8787",
        "ENOCH_API_TOKEN": "replace-with-token"
      }
    }
  }
}

对于 Cursor、Copilot、Windsurf 或其他 MCP 客户端，请使用等效的本地 stdio 服务设置。

开发

uv sync --dev
uv run pytest -q
gitleaks detect --no-git --redact

公共安全说明

此软件包是公开的。示例必须仅使用占位符和本地 URL。请勿发布私有主机名、局域网/Tailscale IP、操作员路径或有效令牌。