Planner — provable "done" for AI agents MCP Server

Add an assumption to a goal edge (parent→this goal). An assumption is an explicit premise: "why does completing this goal contribute to the parent?" Requires the goal to have a parent (root goals have no edge). Text must pass quality linter (testable, precise, discrete, signposted). Type (cause_effect/causal_link) is auto-classified by LLM.

Append an acceptance criterion to a goal. The text must describe an observable check over an artifact (e.g. "GET /api/health returns 200 with {status:ok}"), not a subjective approval. Grove mode: AC can only be added while goal is in backlog (frozen once started), quality linter blocks high-severity issues. Standard mode: AC editable until goal is closed, linter is advisory. Returns criterion id, position, text, and any quality findings.

SUBORDINATE / supplementary path — does NOT close an acceptance criterion. Adds a text-only note (URL to a permanent external source like CI run / GitHub commit / issue, or a description of a manual scenario) as extra context alongside the real proof. The path that actually covers an AC and closes a Grove goal is goal-attach-evidence — use that one for every criterion. Plain evidence NEVER counts toward AC coverage no matter how many you add; it is only a complement to an attached file. NOT for bytes — screenshots, logs, API responses, exports all go through goal-attach-evidence. NOT for filesystem paths — those need goal-attach-evidence with the actual file.

Add a free-form note (markdown supported) to a goal — decisions taken, dead ends hit, context worth carrying into the next session. Notes are NOT evidence: they hang off the goal rather than an acceptance criterion and never count toward AC coverage or closing a Grove goal — use goal-attach-evidence for proof. Notes are visible in the goal detail panel and returned by goal-get under notes[].

Attach text evidence to an assumption and judge it. The judge evaluates whether the evidence supports or challenges the assumption and automatically transitions its status: supports → supported, first challenges → challenged, second (repeat) challenges → invalidated. Invalidated is terminal — further evidence no longer moves the status. Judge infra failures fail open (errored verdict, no status change).

PRIMARY path to close a Grove goal: this is the ONLY tool that covers an acceptance criterion. Attach binary evidence (screenshot, log dump, API response, export) to an AC — call it once per criterion to satisfy the close gate. The subordinate goal-add-evidence-text only adds context for proofs with NO bytes (URLs to permanent external sources, manual repro descriptions) and does NOT cover an AC. Caption is optional but strongly recommended: state what the file captures and the reproduction conditions (URL/commit/session/inputs) so a third reviewer can reproduce. ⚠ PICK THE RIGHT TRANSPORT BEFORE YOU CALL THIS TOOL ⚠ • BEST for ANY file > ~1 KB raw — and the ONLY no-token path, so use it in a claude.ai / hosted-agent session that has no raw X-Auth-Token → call the sibling MCP tool `goal-request-upload` with this same criterionId. It returns a one-time {uploadUrl, expiresAt}; then stream the raw bytes with a single PUT: `curl -sS --fail --upload-file "/abs/path/to/file.png" "<uploadUrl>"` (optionally add -H "X-Content-Sha256: <hex sha256>" so corruption fails fast). No base64, no token — the signed ?t= ticket in the URL is the only credential, single-use, criterion-scoped. The PUT response is the same evidence JSON this tool returns. • ALTERNATIVELY, if you DO have the raw X-Auth-Token in your shell → the `planner-attach.sh` helper (zero-install bash, binary-safe). The MCP base64 path below is unreliable for non-trivial files: long string arguments get truncated or whitespace-corrupted on the agent side BEFORE the JSON-RPC request is sent. Measured 2026-05-20 on prod: a 4 KB PNG arrived at the server as 1874 decoded bytes (file_hash_mismatch); a 2 KB payload arrived with stray whitespace (failed base64_decode). The server itself accepts up to 25 MiB raw — the bottleneck is the agent-side serialisation of contentBase64, NOT the server. planner-attach.sh COPY-PASTE RECIPE (replace 3 placeholders, run in your shell): curl -sS https://planner.monopoly-gold.com/api/cli/planner-attach.sh \ | PLANNER_TOKEN="<same X-Auth-Token you use for MCP>" bash -s -- \ --criterion-id "<CRITERION_UUID>" \ --file "/abs/path/to/file.png" \ --caption "what is captured and the repro conditions" \ --created-by "<your agent id>" Where to get each value: - PLANNER_TOKEN: the very same token that is already in your MCP config under the X-Auth-Token header for the `planner` server. NOT a separate credential. - CRITERION_UUID: the AC id you got from goal-get / goal-list. Same UUID you would pass to this MCP tool. - file path: absolute path on YOUR (agent) machine — the script reads it locally and streams multipart. The planner server never sees your filesystem. The helper computes SHA-256 itself and ships it as `contentSha256`, so any in-flight corruption fails fast with HTTP 400 instead of poisoning the evidence row. Output on stdout is the same JSON shape this MCP tool returns; non-zero exit means HTTP ≥ 400 (stderr explains). Without curl/bash? Fall back to raw multipart: POST https://planner.monopoly-gold.com/api/criteria/<id>/evidence/file, header X-Auth-Token, form fields file=@..., contentSha256=..., caption, createdBy. • File ≤ ~1 KB raw → this MCP tool is fine. ALWAYS pass `contentSha256` (hex SHA-256 of raw bytes BEFORE base64). Without it, a silently truncated PNG looks valid to the MIME sniffer; the server cannot distinguish a truncated 4 KB PNG from a valid 1 KB one and the vision judge burns ~30s on broken bytes. With the hash, the server fast-fails with error=file_hash_mismatch and points back here at the multipart endpoint. Validates MIME whitelist (png/jpeg/webp/gif/pdf/txt/json/zip), per-file size cap (ATTACHMENTS_MAX_FILE_BYTES, default 25 MiB), per-project attachments quota. Returns evidence record + file URL + serverSha256.

Add a blocker to a goal (blockers are additive — each call appends a new one, existing blockers are preserved). Sets status to blocked. Optionally create an inline resolver goal (resolverTitle) or link an existing one (linkedGoalId) — mutually exclusive. When the last active blocker is removed via goal-remove-blocker, the goal returns to its previous status.

Create a goal/task/milestone/habit in the planning tree. Two modes: grove (default) — enforces acceptance criteria gate on status transitions (AC required before in_progress, file-evidence per AC before done); standard — carries the same AC but without the evidence gate (advisory linting only). Returns the created goal with id, webUrl, mode, and nextStep hint. Every goal must belong to a project (pass projectId or inherit from parent).

IRREVERSIBLY delete a goal and all its descendants (children, evidence, blockers). Prefer goal-update status=cancelled to preserve history, or goal-block to mark an obstacle. Use delete only for erroneous/duplicate entries. Returns the deleted title and children_deleted count.

Dismiss the red-team finding that blocks a goal from starting, when you disagree with the verdict. Requires a reason of at least 80 characters explaining why the counterexample does not apply. The dismissal is recorded in goal history and surfaced in goal-get, so "agent overrode the gate" stays distinguishable from "no hole was found". Prefer fixing the acceptance criteria via goal-add-criterion — dismissing leaves the hole open.

Fetch full details of a single goal: title, description, status, priority, type, mode, children, acceptance criteria (with evidence coverage), blockers, tags, deadline, estimate, history log, and project. The primary drill-down tool after goal-list or goal-tree.

List goals with optional filters: projectId (UUID), status (backlog/in_progress/blocked/done/cancelled), type (goal/milestone/task/habit), parentId (UUID — direct children only). Returns up to limit results (default 50, no offset pagination). Sorted by priority ASC then createdAt DESC. Each entry has id, title, webUrl, status, priority, type, progress, parent_id, project_id.

Move a goal to a different parent or project. Pass newParentId=UUID to reparent (inherits project from new parent), newParentId=null to make root. Optional projectId=UUID overrides the target project when making root (cross-project move to root). Cascades project change to all descendants. Prevents cycles.

Pull-инбокс для «подхватить и довести» в неосновное окно. По одному проекту, за окно N дней, статусы для подхвата. Возвращает обогащённые записи (title/description-preview/parent/counts), чтобы выбрать без goal-get. Параметры: project (slug, required), withinDays (int, default 14), statuses (list, default ["backlog"]; допустимо {backlog,in_progress,blocked}), limit (int, default 10).

Remove an assumption from a goal edge.

Remove a blocker from a goal by blocker UUID. If it was the last active blocker, the goal automatically returns to its previous status (in_progress or backlog). Does not delete the linked resolver goal if one exists.

Remove an acceptance criterion from a goal. Grove mode: only while goal is in backlog (frozen once started). Standard mode: until goal is done. Cascades to all evidence on the criterion. Returns confirmation with removed criterion details.

Delete an evidence record by UUID. Forbidden if the owning goal is already done (evidence is frozen after close). Removes both the database record and the attached file (if any).

Remove a note from a goal by note UUID. Note ids come from goal-get (notes[].id). Deletes only the note — never touches acceptance criteria, evidence or blockers.

Set display order of sibling goals within the same parent and priority band. Pass an array of goal UUIDs in the desired order — each is assigned position = its array index. All goals must share the same parent and priority.

Request a change to an acceptance criterion that appears unreachable. Requires ≥3 failed evidence attempts (weak/mismatch) with 0 matches. An LLM judge evaluates the reason for substantiality. On pass, creates an escalation for the goal owner to resolve (edit AC text, split to sub-goal, drop AC without creating a child, or reject). Grove mode only, goal must be in_progress.

PREFERRED path to attach a LARGE binary evidence file (screenshot, log dump, PDF, session transcript — anything > ~1 KB) to an acceptance criterion. Returns a one-time {uploadUrl, expiresAt} scoped to this criterion. Then STREAM the raw file to it with a single PUT — no base64, no token: curl -sS --fail --upload-file "/abs/path/to/file.png" "<uploadUrl>" Optionally pass the hex SHA-256 of the file so the server fast-fails on any in-flight corruption: curl -sS --fail -H "X-Content-Sha256: <sha256>" --upload-file "/abs/path/to/file.png" "<uploadUrl>" The PUT response is the same evidence JSON that goal-attach-evidence returns (evidence id, serverSha256, judge verdict, criterion evidenceCount). A non-2xx PUT means the upload was rejected (expired/already-used/wrong-criterion/hash-mismatch) and NO evidence was created — request a fresh URL and retry. Use this instead of goal-attach-evidence for any non-trivial file. Use goal-add-evidence-text only for byte-less context (external URLs, manual repro notes) — it does NOT cover an AC.

Resolve a pending AC escalation. Owner decides: edit (provide new AC text), split (move AC to a child goal), drop (remove the AC outright, optionally with a linkedGoalId audit reference), or reject (agent must find another way). All prior evidence on the AC is deleted for edit/split/drop so the agent must submit fresh proof.

LLM generates suggested assumptions for a goal edge (parent→child). Returns 2-4 assumptions with signposts and type classification. Author should review, edit, and accept relevant ones via goal-add-assumption.

Aggregate statistics across all goals (or scoped to a projectId): total count, breakdown by status, root count, blocked count, and overdue count. Useful for daily standups and dashboard views.

Quick-capture a task or improvement idea into a project. Creates a backlog task with priority 4 (low) and auto-adds the "suggestion" tag. Resolves project by slug (falls back to the default project). Lightweight alternative to goal-create when you need minimal ceremony.

Fetch the full goal hierarchy as a nested tree. Optional filters: projectId (UUID) to scope to one project, rootId (UUID) to get a subtree. Each node includes id, title, status, priority, type, progress, and nested children array.

Partial update of a goal — only the fields you pass are changed; omitted fields are untouched. Updatable: title, status, priority (1-5), description, type, tags, deadline, estimate, mode. Status transitions are validated (backlog→in_progress→done|cancelled; blocked→in_progress). Grove mode enforces gates: in_progress requires ≥1 AC, done requires file-evidence on every AC + session_history. Returns the updated goal with all fields.

Update text or signpost of an assumption. Status cannot be changed manually — transitions happen only via evidence judge verdicts.

Update the text of an acceptance criterion. Grove mode: only while goal is in backlog (frozen once started), quality linter blocks high-severity issues. Standard mode: until goal is done, linter is advisory. Returns updated criterion details and any quality findings.

Declare that one project depends on another (depends-on relationship). Accepts UUID or slug for both sides. Idempotent: if the dependency already exists, returns it with already_existed=true. Self-references are rejected. No cycle detection — the caller is responsible for avoiding circular chains.

Create a new project container for goals. Requires title and a unique slug (lowercase a-z, 0-9, hyphens). Optional: description, status (active/archived/paused, default active), tags, icon (emoji), repositoryPath, repositoryUrl, isDefault. Returns the created project with id, slug, and webUrl. Slug must be unique — duplicates are rejected with existing slugs list.

Delete a project. If the project has goals, pass force=true to cascade-delete them all; without force, the call is rejected with the goals count. Returns deleted title, slug, and goals_deleted count.

Fetch full project details: title, slug, status, description, icon, tags, repository info, goals breakdown by status (backlog/in_progress/blocked/done/cancelled counts), and depends_on list of project dependencies.

List all projects with optional status filter (active/archived/paused). Returns id, title, slug, webUrl, icon, and goals_count for each project. Use project-get for full details with goals breakdown by status.

Remove a project dependency. Two lookup modes: pass dependency_id (UUID of the link itself), or pass both projectId and dependsOnProjectId (UUID or slug). Returns removed=true on success, removed=false if the dependency was not found.

Partial update of a project — only the fields you pass are changed; omitted fields are untouched. Updatable: title, slug, description, status (active/archived/paused), tags, icon (emoji), repositoryPath, repositoryUrl, isDefault, redTeamMode (optional/advisory/required), evidenceJudgeMode (off/optional/required), allowedGoalMode (any/grove_only), fmeaGenerationMode (off/on), escalationResolveTimeout (off/1h/4h/24h), escalationAutoResolveBy (none/planner-agent), escalationAutoResolveStrategy (suggest-edit/reject-default). Returns the updated project with all fields.

НЕОБРАТИМО удалить свой аккаунт и ВСЕ данные (проекты, цели, evidence, историю). Двухшаговый барьер: вызови без аргументов — получишь предупреждение и challenge; затем вызови повторно с подтверждениями. НЕ вызывай без явной просьбы пользователя.