Loading ToolBench
MCP server for Poke: Cursor + OpenCode sessions + Next dashboard
poke-agents defines 15 tools with generally clear naming (verb_noun pattern: adapters, sessions, session, control_plan, control_agent, etc.) and detailed descriptions (avg ~180 chars, well above 10-char minimum). However, input schemas are partially visible but incomplete: many tools lack explicit type definitions in the provided source excerpts. Output schemas are documented in descriptions but not formally declared. Error handling is present but generic ('ok: false' + 'error' field). Security is reasonable (no secrets in params, read-only risk annotations), but parameter validation rules are not explicit. Composition is strong, tools chain well (sessions → session → control_chat_*) and follow single-responsibility principle. Major gap: tool annotations (readOnlyHint, destructiveHint) are absent from registration, forcing LLMs to infer from descriptions.
**No parameters.** Always lists **cursor**, **opencode**, **codex**, and **claude** disk adapters first (with **`available`** / **`detail`** / **`server_enabled`**), then any other editors in **`POKE_AGENTS_EDITORS`**. **`server_enabled: false`** means that id is not merged into **`sessions`** until you add it to the env and restart. Call **before `sessions`** when debugging empty lists.
**`action`:** **`list`** (merged built-ins + custom, `built_in_ids`, `has_local_override`), **`upsert`** (requires **`template`** object), **`delete`** (requires **`delete_id`**). Storage: **`~/.poke-agents/agent-templates.json`** or **`POKE_AGENTS_TEMPLATES_PATH`** — survives **`npx`** and upgrades. Upsert with same **`id`** as a built-in = local override. Delete on built-in id = remove override only.
Runs the configured headless CLI (**`POKE_AGENTS_CONTROL`**: `cursor` = Cursor `agent -p`, `opencode` = OpenCode `agent`, `codex` = Codex `agent`, `claude` = Claude CLI `agent`). Spawns a subprocess, returns **`run_id`** immediately (non-blocking). Use **`control_run_status`** to poll. **`cwd`** defaults to MCP server's cwd; use absolute path to run in a user repo. **`prompt`** is the agent instruction (required). **`resume_uuid`** (optional) resumes a prior CLI session (Cursor/OpenCode/Codex/Claude uuid, **not** disk **`session.id`**). **`auto_create_cli_chat`** (default true) auto-creates a new CLI chat if **`resume_uuid`** is missing. **`format`** (default `text`) controls output: `text` = plain, `json` = JSON lines. **`env`** (optional) merges into subprocess env. **`timeout_seconds`** (optional, default 3600) kills the process if it exceeds the limit. Returns **`ok: true`** + **`run_id`** on spawn success; **`ok: false`** + **`error`** on validation or spawn failure.
Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are absent from tool registration. LLMs must infer risk from descriptions, increasing misuse likelihood.
Input schemas are incomplete or not visible in source. adapters and control_plan claim 'no parameters' but lack explicit empty schema definitions. Many tools show parameter descriptions but not formal JSON Schema type/required arrays.
Inferred effective spec: 2025-06-18+.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 57 | 2025-06-18+ | v2 |
Probe the configured headless CLI (**`POKE_AGENTS_CONTROL`**: cursor, opencode, codex, or claude) for availability, version, and auth status. Specify **`cwd`** (optional, defaults to MCP server's cwd) to run the probe in a specific folder. Returns backend, cwd, binary path, about (version), and status (auth/login info).
Fetch messages around a specific index in a disk session. Specify **`id`** (from **`sessions`**), **`index`** (message index), **`before`** (default 5), and **`after`** (default 5). Returns the surrounding slice, session metadata, total count, and truncation flag.
Fetch a slice of messages from a disk session. Specify **`id`** (from **`sessions`**), **`offset`** (default 0), and **`limit`** (default 50). Returns the slice, session metadata, total count, and truncation flag.
Fetch the last N messages from a disk session. Specify **`id`** (from **`sessions`**) and **`limit`** (default 30). Returns the tail slice, session metadata, total count, and truncation flag.
Convert a disk **`sessions[].id`** to the corresponding CLI session uuid (Cursor workspace uuid, OpenCode session uuid, Codex session uuid, or Claude CLI chat uuid). Specify **`id`** (from **`sessions`**). Returns the CLI uuid and source. Use this uuid with **`control_agent.resume_uuid`** to resume the session in a headless agent run.
**No parameters.** Read-only: no CLI, no disk heavy reads. Returns **`active_control`** (which backend **`control_agent`** uses), binary paths, per-provider notes, **`session_ids`** legend (disk vs resume vs **run_id**), echoed **env** hints, **`orchestration`** (why **502** / timeouts happen and how to poll), and **`session_stop`** (in-flight runs are not cancellable via MCP). Call at **session start** or when switching machines.
Fetch a slice of stdout or stderr from a **`run_id`**. Specify **`stream`** (`stdout` or `stderr`), **`offset`** (default 0), and **`limit`** (default 8000 bytes). Returns the slice, total length, next offset, and truncation flag.
Poll a **`run_id`** from **`control_agent`**. Returns status, timestamps, backend, cwd, prompt preview, resume uuid, auto-created CLI chat uuid, pid, exit code, signal, timeout flag, stdout/stderr lengths, format, and optional error. Use **`control_run_output_slice`** to fetch output.
Fetch metadata for a disk session: id, source, title, project_path, last_updated_at, and optional editor-specific fields (e.g. Cursor workspace uuid, OpenCode session uuid). Specify **`id`** (from **`sessions`**).
Returns long-form markdown (same as MCP **resources** `poke-agents://guide/...`) for clients that cannot **`resources/read`**. Use **`topic`** to avoid loading everything: **`overview`** = index + quick start; **`read`** / **`control`** / **`session_ids`** / **`streaming`** / **`tunnel`** / **`templates`** / **`prompts`**; **`all`** = full manual (large). Unknown **`topic`** → **`overview`**.
Loads the **full** message list for one **`sessions[].id`**. **Risk:** huge threads hold the MCP request open and can cause **HTTP/proxy timeouts** (e.g. poke tunnel). Prefer **`control_chat_slice`**, **`control_chat_tail`**, or **`control_chat_around`** for pagination. On parse/unknown id, **`ok: false`** + **`error`**.
Merged list of **saved** chats on disk (not live CLI runs). Newest first. Each **`id`** is opaque — copy **exactly** into **`session`** or **`control_chat_*`**. Use **`editor`** / **`folder`** / **`limit`** to narrow; omit filters to browse. Does **not** return headless **`run_id`** or CLI resume ids.
Output schemas are documented in descriptions but not formally declared in tool registration. LLMs cannot parse expected response structure from schema alone.
Error handling is generic ('ok: false' + 'error' field). No categorization of retryable vs fatal errors, no recovery guidance, no invalid-value echoing for self-correction.
Parameter constraints (enums, ranges, patterns) are documented in descriptions but not enforced in JSON Schema. LLMs may pass invalid values; validation happens server-side without clear feedback.