{
"markdown": "# enoch-mcp\n\n\n\n\n\n**`enoch-mcp` is a local Model Context Protocol stdio server for a configured Enoch FastAPI control-plane API.** It lets MCP clients inspect and operate Enoch through typed tools without exposing a raw shell or reimplementing Enoch business logic.\n\n
\n\n## What it does\n\n- Registers MCP tools for Enoch control-plane, Dashboard V1, and core endpoints.\n- Sends requests to a configured Enoch API URL.\n- Adds `Authorization: Bearer ` to API requests using the configured token.\n- Returns Enoch API responses to the MCP client.\n- Marks read-only tools with MCP read-only annotations.\n- Marks mutating tools as non-read-only and adds approval metadata.\n- Keeps safe defaults for dry-run operations.\n- Optionally probes configured CPU/GPU workers directly through worker APIs or allowlisted SSH diagnostics.\n\n## What it does not do\n\n- It does not expose a raw shell tool.\n- It does not accept arbitrary SSH commands.\n- It does not read or write local artifact files directly.\n- It does not call language models.\n- It does not cache, retry, queue, or schedule work.\n- It does not bypass Enoch authentication or authorization.\n\n## Requirements\n\n- Python 3.11 or newer\n- A running Enoch API, normally at `http://localhost:8787`\n- An Enoch API bearer token\n- An MCP client that can run local stdio servers\n\n## Installation\n\nRun from PyPI with `uvx`:\n\n```bash\nuvx enoch-mcp --api-url http://localhost:8787 --api-token ''\n```\n\nOr configure with environment variables:\n\n```bash\nexport ENOCH_API_URL='http://localhost:8787'\nexport ENOCH_API_TOKEN=''\nuvx enoch-mcp\n```\n\nFor local development from a checkout:\n\n```bash\ngit clone https://github.com/alias8818/enoch-mcp.git\ncd enoch-mcp\nuv sync --dev\nuv run enoch-mcp --api-url http://localhost:8787 --api-token ''\n```\n\n## Configuration\n\n| Option | Environment variable | Default | Description |\n| --- | --- | --- | --- |\n| `--api-url` | `ENOCH_API_URL` | `http://localhost:8787` | Base URL for the Enoch API. |\n| `--api-token` | `ENOCH_API_TOKEN` | none | Bearer token for the Enoch API. |\n| `--worker-probes-json` | `ENOCH_WORKER_PROBES_JSON` | none | Optional JSON map for direct worker diagnostics. |\n| `--worker-probes-file` | `ENOCH_WORKER_PROBES_FILE` | none | Optional path to a JSON map for direct worker diagnostics. |\n\nThe token is required. If it is missing, tool calls fail before making an HTTP request.\n\n## Optional worker probes\n\nWorker probes are disabled unless `ENOCH_WORKER_PROBES_JSON` or `ENOCH_WORKER_PROBES_FILE` is configured. This keeps the default package a thin control-plane bridge. When configured, the MCP exposes named diagnostics for worker truth: API health, worker-gate dashboard status, active process markers, bounded log tails, disk space, and expected artifact presence.\n\nExample:\n\n```json\n{\n \"cpu\": {\n \"api_url\": \"http://127.0.0.1:18788\",\n \"api_token\": \"worker-api-token\",\n \"service_name\": \"enoch-control-plane\",\n \"project_root\": \"/srv/enoch/projects\"\n },\n \"gpu\": {\n \"api_url\": \"http://127.0.0.1:18789\",\n \"api_token\": \"worker-api-token\",\n \"ssh_host\": \"worker-gpu.example.internal\",\n \"ssh_user\": \"enoch\",\n \"service_name\": \"enoch-control-plane\",\n \"project_root\": \"/srv/enoch/projects\",\n \"log_paths\": [\"/var/log/enoch-control-plane.log\"]\n }\n}\n```\n\nSupported fields per lane:\n\n- `api_url`: worker-gate base URL. Used first for `/healthz`, `/dashboard/api`, `/dashboard/api/run/{run_id}`, and `/project-status/{project_id}`.\n- `api_token`: worker bearer token. Treated as secret.\n- `ssh_host`, `ssh_user`, `ssh_port`: optional SSH fallback/debug target.\n- `service_name`: systemd unit name for service checks and journal tails.\n- `project_root`, `state_dir`: fixed worker roots used for disk and artifact checks.\n- `log_paths`: fixed worker-gate log paths that may be tailed.\n\nSSH probes only run fixed diagnostic commands. They do not accept arbitrary shell input from the MCP client. User-supplied IDs are limited to safe run/project identifier characters, log output is bounded, SSH uses batch mode and no stdin, and the recommended deployment is a read-only worker user or forced-command policy.\n\n## MCP client setup\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"enoch\": {\n \"command\": \"uvx\",\n \"args\": [\"enoch-mcp\"],\n \"env\": {\n \"ENOCH_API_URL\": \"http://localhost:8787\",\n \"ENOCH_API_TOKEN\": \"replace-with-token\"\n }\n }\n }\n}\n```\n\nFor local development, point the MCP client at the checkout:\n\n```json\n{\n \"mcpServers\": {\n \"enoch\": {\n \"command\": \"uv\",\n \"args\": [\"--directory\", \"/path/to/enoch-mcp\", \"run\", \"enoch-mcp\"],\n \"env\": {\n \"ENOCH_API_URL\": \"http://localhost:8787\",\n \"ENOCH_API_TOKEN\": \"replace-with-token\"\n }\n }\n }\n}\n```\n\nUse the equivalent local stdio-server settings for Cursor, Copilot, Windsurf, or other MCP clients.\n\n## Development\n\n```bash\nuv sync --dev\nuv run pytest -q\ngitleaks detect --no-git --redact\n```\n\n## Public-safety note\n\nThis package is public. Examples must use placeholders and local URLs only. Do not publish private hostnames, LAN/Tailscale IPs, operator paths, or live tokens.\n",
"bytes": 5501,
"sha": "eba0ac6d9ea8d1860f45f11115f55d90dfd81d58ec53facb6e25412291182388",
"repo_slug": "alias8818/enoch-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_alias8818_enoch_4e3f27fb/readme"
}