{"id":50313058,"url":"https://github.com/alias8818/enoch-mcp","last_synced_at":"2026-05-28T22:02:31.870Z","repository":{"id":355107228,"uuid":"1226764732","full_name":"alias8818/enoch-mcp","owner":"alias8818","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-26T13:09:44.000Z","size":129,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T15:15:15.166Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alias8818.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T20:06:16.000Z","updated_at":"2026-05-26T13:10:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alias8818/enoch-mcp","commit_stats":null,"previous_names":["alias8818/enoch-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alias8818/enoch-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alias8818%2Fenoch-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alias8818%2Fenoch-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alias8818%2Fenoch-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alias8818%2Fenoch-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alias8818","download_url":"https://codeload.github.com/alias8818/enoch-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alias8818%2Fenoch-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33627951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-28T22:02:31.770Z","updated_at":"2026-05-28T22:02:31.861Z","avatar_url":"https://github.com/alias8818.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# enoch-mcp\n\n\u003c!-- mcp-name: io.github.alias8818/enoch --\u003e\n\n`enoch-mcp` is a local [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) stdio server for the Enoch FastAPI control-plane API. It lets MCP clients such as Claude Desktop, Cursor, Copilot, and Windsurf inspect and operate a running Enoch instance through tools.\n\nThis MCP server is built for the Enoch project: [`alias8818/enoch-agentic-research-system`](https://github.com/alias8818/enoch-agentic-research-system).\n\nThis package is a thin HTTP bridge. It does not reimplement Enoch business logic.\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 \u003ctoken\u003e` to every API request.\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\n  allowlisted SSH diagnostics.\n\n## What it does not do\n\n- It does not run shell commands.\n- It does not expose a raw shell tool, even when SSH worker probes are configured.\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 add telemetry or analytics.\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 '\u003ctoken\u003e'\n```\n\nOr configure with environment variables:\n\n```bash\nexport ENOCH_API_URL='http://localhost:8787'\nexport ENOCH_API_TOKEN='\u003ctoken\u003e'\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 '\u003ctoken\u003e'\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\n`ENOCH_WORKER_PROBES_FILE` is configured. This keeps the default package a thin\ncontrol-plane bridge. When configured, the MCP exposes named diagnostics for\nworker truth: API health, wake-gate dashboard status, active process markers,\nbounded 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  \"gb10\": {\n    \"api_url\": \"http://127.0.0.1:18789\",\n    \"api_token\": \"worker-api-token\",\n    \"ssh_host\": \"100.92.44.26\",\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 wake-gate base URL. Used first for `/healthz`,\n  `/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 wake-gate log paths that may be tailed.\n\nSSH probes only run fixed diagnostic commands. They do not accept arbitrary shell\ninput from the MCP client. User-supplied IDs are limited to safe run/project\nidentifier characters, log output is bounded, SSH uses batch mode and no stdin,\nand the recommended deployment is a read-only worker user or forced-command\npolicy.\n\n## MCP client setup\n\n### Claude Desktop\n\nAdd an entry like this to `claude_desktop_config.json`:\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 Claude Desktop 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\n### Cursor\n\nAdd an MCP server entry that runs the same stdio command:\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\nUse the equivalent MCP server settings for other clients that support local stdio MCP servers.\n\n### Codex on the Enoch workstation\n\nFor this workstation, use the repo wrapper so Codex does not store the Enoch\nbearer token directly. The wrapper starts or reuses an SSH tunnel to\n`enoch-core.exe.xyz`, reads the control-plane token on the remote host, and then\nruns this checkout over stdio:\n\n```toml\n[mcp_servers.enoch]\ncommand = \"/home/jeremy/Desktop/projects/enoch-release/enoch-mcp/scripts/run_codex_mcp.sh\"\nstartup_timeout_sec = 60.0\n```\n\nThe wrapper honors these optional environment overrides:\n\n- `ENOCH_MCP_SSH_HOST` default `enoch-core.exe.xyz`\n- `ENOCH_MCP_LOCAL_PORT` default `18787`\n- `ENOCH_MCP_REMOTE_PORT` default `8787`\n- `ENOCH_MCP_ENABLE_WORKER_PROBES` default `1`\n- `ENOCH_MCP_WORKER_BASE_PORT` default `18788`\n\nWhen worker probes are enabled, the wrapper reads configured Enoch\n`worker_targets` on `enoch-core`, opens local SSH tunnels for each worker API,\nand exports `ENOCH_WORKER_PROBES_JSON` for this MCP process. The Codex config\nstill does not store the control-plane or worker bearer tokens.\n\n## Tools\n\n### Read-only tools\n\nThese tools are registered with `readOnlyHint=true`.\n\n| Tool | Endpoint | Purpose |\n| --- | --- | --- |\n| `enoch_status` | `GET /control/api/status` | Full control-plane status, dispatch safety, counts, warnings, and conflicts. |\n| `enoch_queue_health` | `GET /control/api/queue-health` | Queue health, worker freshness, alert findings, and recent events. |\n| `enoch_overview` | `GET /control/api/v1/overview` | Bounded operator overview: counts, active work, paper pipeline, top actions, and recent events. |\n| `enoch_automation_readiness` | `GET /control/api/v1/automation-readiness` | Canonical long-haul readiness check for “can I leave this running?” |\n| `enoch_research_quality` | `GET /control/api/v1/research-quality` | Latest research quality readiness report. |\n| `enoch_intake_status` | `GET /control/api/intake/ideas` | Current control-plane idea intake status. |\n| `enoch_lanes` | `GET /control/api/v1/lanes` | Bounded worker-lane state and lane-aware next candidate. |\n| `enoch_probe_worker` | worker API / allowlisted SSH | Optional direct worker truth: health, wake-gate status, active process markers, matching run presence, disk, and telemetry. |\n| `enoch_worker_logs` | allowlisted SSH only | Optional bounded tail for `service`, `wake_gate`, or `active_run` logs. |\n| `enoch_worker_artifacts` | worker API / allowlisted SSH | Optional expected artifact presence check for one project/run. |\n| `enoch_queue_list` | `GET /control/api/queues/{status}` | Queue rows for `active`, `queued`, `blocked`, or `paused`. |\n| `enoch_v1_queue` | `GET /control/api/v1/queue` | Cursor-paginated Dashboard V1 queue rows. |\n| `enoch_projects` | `GET /control/api/v1/projects` | Cursor-paginated project list. |\n| `enoch_project_detail` | `GET /control/api/v1/projects/{project_id}` | Project detail with related rows and events. |\n| `enoch_runs` | `GET /control/api/v1/runs` | Cursor-paginated run list. |\n| `enoch_run_detail` | `GET /control/api/v1/runs/{run_id}` | Run detail with related rows and events. |\n| `enoch_papers_list` | `GET /control/api/papers` | Paginated paper listing. |\n| `enoch_paper_detail` | `GET /control/api/papers/{paper_id}` | Paper detail with related project, run, events, and warnings. |\n| `enoch_paper_artifact` | `GET /control/api/papers/{paper_id}/artifact/{field}` | Artifact content served by the Enoch API. |\n| `enoch_reviews_list` | `GET /control/api/paper-reviews` | Publication review queue. |\n| `enoch_review_next` | `GET /control/api/paper-reviews/next` | Next review candidate. |\n| `enoch_events` | `GET /control/api/v1/events` | Cursor-paginated Dashboard V1 event log query. |\n| `enoch_core_health` | `GET /enoch-core/health` | Enoch core health and mode. |\n| `enoch_core_queue_projection` | `GET /enoch-core/projections/queue` | Core queue projection. |\n| `enoch_core_paper_candidates` | `GET /enoch-core/candidates/paper-draft` or `/paper-polish` | Next draft or polish candidate. |\n\n### Mutating tools\n\nThese tools are registered as non-read-only and include `userApproval` metadata. MCP annotations and metadata are hints to clients; confirmation behavior depends on the MCP client.\n\n| Tool | Endpoint | Safety behavior |\n| --- | --- | --- |\n| `enoch_dispatch` | `POST /control/dispatch-next` | Defaults to `dry_run=true`. |\n| `enoch_dispatch_one` | `POST /control/dispatch-one` | Explicit single-project dispatch; defaults to `dry_run=true`. |\n| `enoch_queue_alert_check` | `POST /control/api/alerts/queue-check` | Queue alert/stale-active check; defaults to `dry_run=true`. |\n| `enoch_reconcile_stale_lane` | `POST /control/api/alerts/queue-check` | Focused stale-lane explanation/reconcile wrapper; defaults to `dry_run=true`. |\n| `enoch_research_run_cycle` | `POST /control/api/research/run-cycle` | One bounded research autopilot cycle; defaults to `dry_run=true`. |\n| `enoch_launch_followup` | `POST /control/api/v1/followups/launch-next` | Launch next bounded follow-up candidate; defaults to `dry_run=true`. |\n| `enoch_pause` | `POST /control/pause` | Requires an explicit reason. |\n| `enoch_resume` | `POST /control/resume` | Requires an explicit tool call. |\n| `enoch_preflight` | `POST /control/worker/preflight` | Checks worker health; does not dispatch by itself. |\n| `enoch_intake_notion` | `POST /control/intake/notion-ideas` | Legacy compatibility path; defaults to `dry_run=true`. |\n| `enoch_intake_ideas` | `POST /control/intake/ideas` | Current control-plane idea intake; defaults to `dry_run=true`. |\n| `enoch_review_claim` | `POST /control/api/paper-reviews/{paper_id}/claim` | Claims a review. |\n| `enoch_review_checklist` | `POST /control/api/paper-reviews/{paper_id}/checklist/{item_id}` | Updates one checklist item. |\n| `enoch_review_status` | `POST /control/api/paper-reviews/{paper_id}/status` | Updates review status. |\n| `enoch_draft_paper` | `POST /control/papers/draft-next` | Checks or requests next paper draft; defaults to `dry_run=true`. |\n| `enoch_rewrite_draft` | `POST /control/api/paper-reviews/{paper_id}/rewrite-draft` | Requests draft rewrite. |\n\n## Live smoke test\n\nA live smoke script is included for checking a running Enoch instance before publishing or changing client configuration:\n\n```bash\nENOCH_API_TOKEN='\u003ctoken\u003e' uv run python scripts/live_smoke.py --api-url http://localhost:8787\n```\n\nThe script:\n\n- verifies that the expected tools are registered;\n- verifies approval metadata on mutating tools;\n- calls read-only tools against the configured Enoch API;\n- reads one paper detail and one artifact when available;\n- calls direct worker probes only when worker probe config is present;\n- calls only safe mutating paths by default: dispatch dry-runs, queue alert dry-run,\n  stale-lane reconcile dry-run, research cycle dry-run, follow-up dry-run,\n  worker preflight, idea intake dry-run, legacy Notion intake dry-run when\n  enabled, and paper draft dry-run.\n\nIt does not print the bearer token.\n\n## Development\n\n```bash\nuv sync --dev\nuv run ruff check .\nuv run pytest\nuv build\n```\n\nRun the MCP server from a checkout:\n\n```bash\nuv run enoch-mcp --api-url http://localhost:8787 --api-token '\u003ctoken\u003e'\n```\n\nThe server uses stdio transport, so it waits for MCP protocol messages on standard input.\n\n## Error handling\n\n- HTTP 4xx/5xx responses from Enoch are returned as MCP tool errors that include the status code and response body.\n- Network failures are returned as transport errors.\n- Missing bearer tokens are reported before a request is sent.\n\n## Security notes\n\n- Treat `ENOCH_API_TOKEN` like any other credential.\n- Treat `ENOCH_WORKER_PROBES_JSON` like a credential when it includes worker API tokens.\n- Prefer environment variables or your MCP client's secret storage over hard-coded tokens.\n- Do not expose an Enoch API endpoint to networks or users that should not operate the control plane.\n- Mutating tool approval prompts are MCP-client dependent; review your client behavior before enabling mutating workflows.\n- Worker SSH diagnostics are named probes with fixed commands, not a general\n  remote shell. Use a dedicated read-only/forced-command SSH identity when\n  possible.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falias8818%2Fenoch-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falias8818%2Fenoch-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falias8818%2Fenoch-mcp/lists"}