Keelen MCP Server

Read a project's current product goal (the outcome work is aimed at). READ THIS BEFORE YOU CALL `set_product_goal`: the setter REPLACES the whole document rather than appending to it, so writing without reading first silently discards whatever the user already recorded. To add a line, read the current text, edit it, and set the full result back. Returns {project_id, product_goal_md, updated_at}. `product_goal_md` is None when no goal has been set. Tenant-scoped: a project not in the caller's workspace 404s.

Read a project's current product vision (what the product is for). READ THIS BEFORE YOU CALL `set_product_vision`: the setter REPLACES the whole document rather than appending to it, so writing without reading first silently discards whatever the user already recorded. To add a line, read the current text, edit it, and set the full result back. Returns {project_id, product_vision_md, updated_at}. `product_vision_md` is None when no vision has been set. Tenant-scoped: a project not in the caller's workspace 404s.

Set the outcome to aim at right now, so work is prioritised toward one thing. `goal_md` is free-form markdown and must be non-empty. Tenant-scoped: a project not in the caller's workspace 404s. Returns {project_id, product_goal_md, updated_at, next_step}.

Say what this product is for, so every run knows what it is building toward. `vision_md` is free-form markdown and must be non-empty. Tenant-scoped: a project not in the caller's workspace 404s. Returns {project_id, product_vision_md, updated_at, next_step}.

Start, pause, or resume a project's autonomous work. `action` is one of: "enable" | "disable" | "resume" | "process_now". - enable/disable flip scheduler_enabled (the loop dispatches only enabled, status='active' projects). - resume clears a pause (peak/backoff/manual) so the project dispatches again. - process_now durably prioritizes and immediately attempts the next intake batch, independent of the dev scheduler switch. A gate returns a typed reason and recovery step instead of a spawn promise. Returns the resulting scheduler state.

Read a project's security-control observations and review boundaries. The result groups records by evidence class without a total or an overall framework outcome. Read `not_determinable` and `outside_review_scope` before describing any observation. An empty group does not establish that a control is in place, and `disclaimer_md` must reach the user. `limit` defaults to 25 (max 100). `include_all` includes resolved, dismissed, and out-of-scope records. This read-only tool has no compute quota and remains available after the trigger closes for a project.

Start a source-bound security control gap review for one project. The review records bounded engineering observations under the user's selected Cyber Essentials or CMMC Level 1 or Level 2 context. It does not determine framework standing, and it does not make changes. The `disclaimer_md` field must be repeated to the user before any observation is summarised. The project needs a saved framework profile, an eligible plan, and a place on the operator allowlist. Billable; one review is allowed in flight per project. Refusals return `ok: false` with a next step and do not start work. Rate-limited per workspace.

Start building something new: creates a GitHub repo and begins work on it. Use this ONLY when the user wants a NEW repo scaffolded. If they already have a repo, use import_project(repo_full_name) instead — this tool would create a second, empty one beside theirs (list_github_repos() browses what the workspace can see). Scaffolds a new GitHub repo, a bootstrap-mode project, and submits `build_description` as the project's first Roadmap Request. `name` is a concise GitHub short repo slug (no owner); `project_kind` is REQUIRED and one of library | node_library | python_library | service | cli | web_app | godot_game | roblox_game; `preview_command` is required iff `project_kind == 'web_app'`. `engine` is OPTIONAL — one of claude_code | codex | glm | kimi | grok (defaults to claude_code); codex, glm, kimi, and grok require the workspace to have a matching connected credential. `org` is OPTIONAL — a GitHub organization login to create the repo inside (e.g. your company org); omit it to land the repo on a member's personal account. `private` defaults to True. `ci_runs_on` is OPTIONAL — the CI runner labels for the scaffolded workflow, e.g. ["self-hosted", "linux", "x64", "my-fleet"]. Omit it to inherit the workspace default (ubuntu-latest if unset). Labels no registered org runner carries are rejected, because GitHub would queue such a job forever rather than fail it. `framework` is OPTIONAL and `web_app`-only — one of vite | next (defaults to vite). It picks the scaffolded frontend rails: `vite` a vanilla-TypeScript SPA, `next` a Next.js app-router app. Passing it with any other `project_kind` is an error. The repo is created on the GitHub account of a workspace member with repo-create OAuth access (this path has no specific caller user), so the returned `repo` owner is whichever member's token resolved (or the chosen `org`). If no member has repo-create access — or the resolving member can't create in `org` — the call returns an actionable error. Returns {project_id, repo, thread_id, next_action, poll_after_seconds, next_step}; follow next_step (poll get_request_status with the returned thread_id). On the rare arm where the first Request failed to submit, next_action is "call_tool" with next_tool="submit_request".

Soft-delete a project (the harder option) — frees a slot and hides it. Stops any in-flight machine, then flips the project to `deleted`: it disappears from `list_projects`, drops out of the project cap, and the loop stops dispatching it. The row is retained for audit but there is NO in-tool restore (unlike `archive_project`) — re-import the repo to reconnect it as a fresh project. Idempotent. Owner-scoped; a project not in the workspace 404s.

Check how a project is doing: what is in flight, what shipped, what is stuck. Returns lifecycle status, open task count, queued roadmap item count, runs today, verification pass rate, open blockers, pause state, and freshness. Zero `open_tasks` does not mean an empty roadmap: `queued_roadmap_items` counts planned work awaiting expansion, including work held while the scheduler is disabled. Use list_roadmap to inspect those items. `glm_peak_paused` is NOT a fault and sets no pause columns: it is the ephemeral GLM peak-hours skip. True means clean PRs hold and runs stop until `glm_peak_resumes_at`. It is an intentional cost gate, so report it as "waiting for off-peak", never as a failure.

Read a project's legal exposure findings, worst exposure first. Returns each finding as an OBSERVATION plus the obligation commonly cited over that pattern, its citation, the date the citation was last checked, and whether counsel has reviewed the registry entry (`counsel_reviewed`, false today for every entry). `exposure_order` is an ORDER, never a score: there is no grade, no percentage, and no overall state in this output. Read `not_determinable` before you summarise: those are checks that could not reach a verdict, and leaving them out would turn a partial review into a clean answer. The `disclaimer_md` field must reach the user. `limit` defaults to 25 (max 100). `include_all` adds resolved, dismissed, and out-of-scope rows to the default actionable set. Read-only, no compute, no rate limit; it works even while the trigger is closed for the project.

Find where a codebase creates legal exposure (privacy, consent, data handling). Spawns a one-shot review machine that reads the checkout offline and maps what the code DOES onto commonly cited legal obligations, filtered by the project's saved compliance profile (jurisdictions plus eleven product facts). Findings land on the project's Legal page for a human to triage, and you read them with get_legal_exposure_findings. No change is ever applied automatically. THIS IS NOT LEGAL ADVICE AND IT IS NOT A LEGAL CLEARANCE. The result carries a `disclaimer_md` field: repeat it to the user before you summarise anything. The review is not exhaustive, so an empty result is never proof that anything is in order. Requires a saved compliance profile (409-shaped refusal without one), a plan that carries the feature, and the project on the operator allowlist. Billable; one review in flight per project. Every refusal comes back as `ok: false` with an actionable `next_step`, and starts nothing. Rate-limited per workspace.

Acknowledge a handled ask only when no blocked task becomes invisible. `decision_md` is a required short note (why/how it was resolved), appended to the escalation's detail_md as an audit trail. Resolving a project_pause / orphan_pause RESUMES the project (clears the pause). A blocked task's final task_block/operator_action cannot be acknowledged: use its typed retry, platform-policy resolution, replan, close, or supersede operation instead. Idempotent. Accepts a real escalation UUID or a synthetic `orphan:<project_id>`.

Resolve a platform-policy dead-end with a structured plan decision. ``decision`` is one of ``reuse_existing_evidence``, ``split_task``, ``raise_project_cap``, or ``remove_scenario``. ``raise_project_cap`` also requires ``project_cap`` (6..32). The decision becomes a new task-plan section; the same task lineage is requeued before the escalation resolves.

Answer a thread's clarifying questions (status must be awaiting_answers). `answers` is a list of {"idx": <int from get_request_status>, "answer_md": <str, 1..2000 chars>}. Answer EVERY question exactly once. Flips the thread back to intake_pending; poll get_request_status again.

Archive a project (reversible shelve) — frees a project slot in-tool. Stops any in-flight machine, then flips the project to `archived`: it drops out of the per-tier project cap (freeing a slot for a new project) and the loop stops dispatching it, but the project + its history are kept and can be restored from the dashboard project page. Idempotent. Prefer this over `delete_project` unless you specifically want the project gone. Owner-scoped (an MCP key is owner-only); a project not in the workspace 404s.

Billing status + a Stripe checkout link when a NEW subscription is needed. `plan` is one of starter | pro | agency (default starter). When the workspace has NO live subscription and needs one (open-signup unpaid, churned, or converting from a free/trial tier), returns a `checkout_url` with next_action "browser" — send it to the user to open in a browser (the one setup step that can't happen in chat). Compute unlocks automatically once payment completes (a Stripe webhook flips the workspace to active); you do not need to block on it. A past_due workspace gets NO checkout — the fix is a card update in the dashboard billing page (a new checkout would create a second subscription); follow next_step. Subscribed or suspended-with-subscription states return checkout_url=None with an explanatory next_step.

Cancel / close a single roadmap item (get its id from list_roadmap). Use this to close a DELIVERED or duplicate item that keeps re-parking: when the work already shipped, every expand produces no dev-ready tasks and files a recurring `roadmap_item_parked` escalation you have to keep acking. Cancelling drops the item out of the expand queue AND resolves any open expand-lane escalation for it. Idempotent for an already expanded/cancelled item; refuses (409) while the item is actively being expanded (retry once that iter ends). Returns {id, status, changed, next_step}.

Clear a queued roadmap item's horizon pin (now/next/later → none). A horizon pin dominates the queue sort, so `reorder_roadmap` cannot move a pinned item out of its band — a stale `now` pin on a delivered/duplicate item clogs the front of the queue. This unpins it and reprices the queue so the item follows plain priority order again (and reorder_roadmap can then move it). Only queued items carry a settable pin (in-flight / shipped items derive theirs), so this refuses (422) on a non-queued item — use cancel_roadmap_item to close a delivered item. Returns {id, previous_pin, horizon_pin, next_step}.

Close a task that should not be built — a duplicate, or work already shipped. Use this when a task on the board is obsolete: the change already landed in another PR, a sibling task covers it, or the user changed direction. The task is marked `cancelled` and keeps ALL of its history (acceptance criteria, QA steps, iterations) — nothing is deleted. `reason` is REQUIRED and is recorded on the audit trail; say why in one line. Pass `superseded_by_pr_number` (or `superseded_by_task_id`) when the work was genuinely delivered somewhere else — that records verified provenance instead of a bare abandon. Closing does NOT claim the content is on the default branch, so any task that declared a dependency on this one keeps waiting; deliver or re-plan those separately. Refuses with 409 while the task is being worked on by a running iteration (stop the machine first, or wait for it to finish). A task in another workspace 404s. Idempotent: closing an already-closed task changes nothing. The response echoes `open_tasks`: how many tasks are still open on the project, counted after the close commits. Check it — if it did not drop, the ticket was already closed and this call changed nothing. It is the same count `project_status` returns, and neither counts a closed task as open. Prefer this over leaving a dead task on the board: unfinished tasks count against the project's planning capacity, so stale duplicates quietly stop new roadmap items from being expanded.

Get the link that connects a GitHub account, so work can reach real repos. Returns an `install_url` — send it to the user to open in a browser. They pick the GitHub account/org, approve the install, and land on a "connected" page; then poll get_onboarding_status() until github_connected is true. The link expires in 10 minutes — call connect_github() again for a fresh one.

See what the work is stuck on and waiting for a human decision about. `project_status` only COUNTS open escalations; this returns each one with its kind, reason, detail_md, recommended_action, and (when task-scoped) the blocked task's title + PR url. A "forever-paused" project with no open `project_pause` row is surfaced as a synthetic `orphan:<project_id>` row. Each row carries a server-derived `task_retry_available` flag and an exact `next_tool`: eligible recovery blocks route to `retry_blocked_task`, roadmap parks to `rearm_roadmap_item`, platform conflicts to their structured resolver, stale work to `replan_task`, and only safe auxiliary cards to `resolve_escalation`.

List repos the workspace's GitHub connection can see (for import_project). Each entry has full_name, default_branch, private, language, pushed_at. Pass a `full_name` to import_project(repo_full_name) to connect it. Returns 409 if GitHub isn't connected yet — call connect_github() first.

Connect an EXISTING GitHub repo as a Keelen project. This is the counterpart of create_project: use THIS tool when the user already has a repo, and create_project only to scaffold a brand-new one. `repo_full_name` is "owner/repo" — it MUST be visible to the workspace's GitHub connection (list_github_repos() to browse; a non-visible repo 404s). `engine` is OPTIONAL — one of claude_code | codex | glm | kimi | grok (defaults to claude_code); codex/glm/kimi/grok require a matching connected credential. `build_description` is OPTIONAL but STRONGLY recommended — a plain-language "what should Keelen build first?" submitted as the project's first Request so the loop has work; an imported project with no Request sits idle until you call submit_request(project_id, ...). `project_kind` is OPTIONAL — one of library | node_library | python_library | service | cli | web_app | godot_game | roblox_game | unknown. Omit it and the kind is auto-detected. PASS IT when the repo is a MONOREPO (apps in subdirectories), a stack with no standard root manifest (Java, Ruby, PHP, .NET, Elixir), or when you want a classification detection cannot infer — in those cases detection yields "unknown", which BLOCKS the dev lane until someone overrides it. A value you pass is authoritative and is never overwritten by later auto-detection. `stack` is the OPTIONAL language axis (python | node | rust | go | cpp) for a language-agnostic kind. `preview_command` is REQUIRED when project_kind is "web_app" (the command that serves the app locally, e.g. "npm run dev") and optional otherwise, where it overrides the detected one. Re-importing the same repo is idempotent (returns the existing project with already_exists=True). On a plan with no scheduled-project allowance the project is still created but with the loop OFF — next_step then steers to get_billing(). Otherwise follow next_step and poll get_provisioning_status(project_id).

Check what is set up so far and what to do next to get building. Reports engine_connected / github_connected / project_count / payment_status and a `next_action` string you should follow VERBATIM, polling this tool between steps. `next_action` is "call_tool" (call the tool named in `next_tool`, following `next_step`) until onboarding is complete, then "done". (`next_action_detail` echoes the pre-2026-07-29 dict shape and is DEPRECATED — it is removed 2026-10-29; read next_action/next_tool instead.) - engine step: send the user the dashboard /login link. Engine subscriptions (Claude / Codex / GLM) are connected in the DASHBOARD for security — NEVER ask for or paste engine credentials in this chat. - github step: call connect_github() for an install link. - project step: create_project(...) for a new repo, or import_project(repo_full_name) for an existing one. - launch step: poll get_provisioning_status(project_id) until ready. Re-checking is YOUR job — the server does not push. Also returns a `usage` block (pool / daily / machine-hours counters + tier caps) for capacity-aware automation clients.

Get a one-click, pre-authenticated dashboard sign-in link for the owner. The engine-connect step — and any dashboard task (billing card update, a project page) — needs a signed-in browser. Because this server has already authenticated the workspace owner, this mints a single-use magic-link login token and returns a `/login?token=…` deep link: opening it signs the user straight into the dashboard (no email round-trip, no password) and lands them where onboarding left off. Send the user the returned `login_url`; it works once and expires in 15 minutes — call again for a fresh one.

List the projects in this workspace, with what each one is building.

Check whether a new project has finished setting up and is ready to build. Returns overall (provisioning | ready | errored), a 7-stage checklist, and a user-facing error_kind when a stage failed. next_action is "wait" with poll_after_seconds (~10s) while provisioning or errored, and "done" when overall is 'ready' (which also marks onboarding complete) — then steer the loop with submit_request(project_id, text). Tenant-scoped: a project not in the caller's workspace 404s.

Run the dashboard's idempotent same-item dependency re-arm. Pass an ``expand_produced_nothing`` or ``roadmap_item_parked`` escalation id. Keelen verifies delivered structural prerequisites, grants one bounded expand retry, preserves the roadmap item id and ``depends_on_item_ids``, and resolves the matching cards in one transaction.

Say what is wrong with what a request produced, and have it reworked. Status must be "done". `feedback_md` is 1..2000 chars. Moves the thread to refine_pending; poll get_request_status to see the revised items.

Change what gets built first. `ordered_ids` is the desired front-to-back order of queued roadmap-item ids (get them from list_roadmap). The first id becomes the highest priority — the cadence expands the lowest-priority_int queued item next. Horizon pins still dominate: a pinned-later item stays at the back and a pinned-now item at the front, regardless of position in `ordered_ids`. Ids that are unknown or no longer queued are skipped; duplicates are rejected. Returns {updated, queue, next_step}.

Replace an unretryable blocked task without losing its lineage. Creates a fresh, explicitly planned task under the same roadmap item and attempt lineage, transfers prerequisites and downstream dependents, and cancels the stale task with supersession provenance. The old PR, task, failures, criteria, and evidence remain in the audit history; nothing is marked delivered.

Check what happened to a request, and read any questions it asked back. Intake is async (~5min cadence) - poll periodically. Read `next_action`: "wait" (still processing), "answer_questions" (call answer_request with one answer per question), "done" (see generated_roadmap_item_ids), "cancelled" (terminal, no items), "failed" (see intake_failure_reason).

Grant one fresh attempt after fixing a recovery-budget task block. Pass the task_block id returned by ``list_escalations``. Eligibility, tenant, task, failure class, task status, and competing blockers are all derived server-side. This is distinct from ``resolve_escalation``, which remains acknowledgement-only for task blocks. Idempotent on replay.

Set this web_app project's ui-review scenario budget, or reset it. ``scenario_cap`` is an integer from 6 through 32, or ``null`` to reset to the platform default of 12. The screenshot cap derives from it and moves with it, so the two can never starve each other. Raising is always allowed, including from a completely full manifest. LOWERING is refused when the default branch already declares more scenarios or screenshots than the smaller budget allows, and is also refused when that manifest cannot be read — both caps are enforced when keelen pushes and not in your CI, so an over-cap manifest fails every push while CI stays green. Read ``project_status.ui_review`` first to see the live occupancy. Repeated calls with the same value change nothing.

See what is planned for a project and in what order. Queued rows also say whether the expand picker would elect them (`electable`) and, when not, why it skips them (`skip_reason`: crash_capped | noop_capped | crash_cooldown | noop_cooldown | awaiting_intake_thread | held_on_open_pr | other). A skipped item ahead of yours does not delay it.

Roll a Roblox project's place back to a previously-published version. For a `roblox_game` project, re-publishes the RETAINED build artifact for `version_number` (get published versions from the web Roblox Publishing card) — it never rebuilds from source, so rollback is fast + deterministic. This mints a NEW Roblox version pointing at the old build. Unknown version → 404; a version with no retained artifact → 422; a place open in Studio / rate-limited → 409 (retry); an invalid or unscoped Open Cloud key → 409 / 403. Returns {version_number, env, published_at, status, next_step}.

Find security problems in a repository: a deep, whole-codebase review. Spawns a one-shot audit that scans the repo across a kind-aware taxonomy (secrets + git history, vulnerable/abandoned deps, injection, SSRF, path traversal, deserialization, crypto, info-leak, plus web authz/session/CORS, library API-misuse, game client-trust, or infra/CI as applicable) and posts findings to the project's Security review for human triage. You review the findings, then send the ones worth fixing into the loop as Requests; no fix is applied automatically. Billable; one audit in-flight per project. (Triggering is disabled while the feature is hardened for production: a project not on the operator allowlist — empty by default — returns a message instead of spawning; earlier results stay visible.) Requires a paid plan; a free or trial workspace gets a message telling the user to upgrade.

Create a Keelen account (or start agent login) — emails a 6-digit code. UNAUTHENTICATED — the only tool besides verify_email that works before a bearer key is configured. `email` is where the code is sent. Flow: signup(email) -> the user reads the 6-digit code from their inbox -> verify_email(email, code) returns a reveal-once API key -> save it as this server's `Authorization: Bearer <api_key>` header in your MCP client config -> reconnect -> get_onboarding_status() to continue setup. The code expires in 15 minutes; call signup again to resend. Response is uniform whether or not the email already has an account (enumeration-safe), so signup doubles as agent LOGIN. Rate-limited per IP and per email. ASK THE USER for `email` in chat and WAIT for their answer before calling this. Do NOT infer it from your client profile, the logged-in account, git config, or any other ambient source; if you already hold a candidate, echo it back and get an explicit yes first. Because this call doubles as LOGIN, a guessed address signs the user in to whatever workspace owns it, and the rest of setup then mints an API key on, and creates a project in, an account they did not choose.

Ask for a change in plain English: a feature, a bug fix, or a new direction. Submit ONE feature or intent per call; split a multi-feature ask into separate requests. `text` must be under 16000 characters. Returns {thread_id, status, next_action, poll_after_seconds, next_step}; follow next_step (re-check get_request_status after poll_after_seconds).

Redeem the emailed 6-digit code for a reveal-once workspace API key. UNAUTHENTICATED. `email` + `code` must match a code issued by signup(email) within the last 15 minutes (5 attempts max). The returned `api_key` is shown exactly ONCE — store it ONLY in the MCP client config ("Authorization: Bearer <api_key>"), NEVER in a repo or a file you might commit. Then reconnect this server with the header set and call get_onboarding_status(). An invalid/expired/consumed code returns a uniform error — call signup(email) for a fresh one.