ZeroWidth Compass MCP Server

Replace a change's effects: for each step it reaches (workflowPageId + nodeId from compass_workflow_steps — a sub-workflow's steps included), one of eliminate, automate (reviewMinutes: what a person still spends checking), parallelize (its wait comes off the critical path), relax_gate (keepShare: share of the wait left, default 0.25), assist (keepShare: share of hands-on time left, default 0.5), reassign (toSubjectPageId). Eliminating or automating every step of a sub-workflow collapses the step that is that sub-workflow. Then project with compass_workflow_rollup changeIds. May return `needs_confirmation`.

Create or update up to 100 changes in one call, each matched by `url` — the GitHub issue, Linear or Jira ticket, PR or doc it mirrors. A url already linked to a change updates that change (label, description, status, tags, experiment, workflow — omitted fields are left alone); any other url creates a change with that link. Run it again with the same urls to keep Compass in step; nothing duplicates. Statuses are by name (compass_statuses_list). Returns one result per item — created / updated with the change's key, or failed with why; a failed item doesn't stop the rest. Summarize what you're about to bring in before calling. May return `needs_confirmation` — one approval covers the whole batch.

Records something you don't yet know — the gap registry is your working memory, so use it liberally while mapping or interviewing. Give one clear question, WHY it matters (what answering it unblocks), and how you'd resolve it (ask the user / interview a specific person / connect a source). No approval needed — noting your own uncertainty isn't acting on the user's behalf. Attach it to a subject (subjectType/subjectId) when it's ABOUT a specific page or person.

Lists the workspace's open questions — the gap registry: what the map doesn't know yet. Defaults to OPEN gaps. This is where you keep your head — check it before asking the user something you may already have flagged, and compose interview briefs from a subject's open questions.

Closes a gap once you've learned the answer (ANSWERED, with the resolution) or decided it doesn't matter (DISMISSED). Keep the registry honest — resolve gaps as their answers land (from an interview, a doc, or the user) so it always reflects what's still unknown. Gaps you raised close without a card; a question a person wrote needs their approval.

Edits an open question's wording, rationale, or suggested resolution — for sharpening a vague question or fixing one you phrased badly. Closing a gap is compass_gaps_resolve, not this. Gap ids come from compass_gaps_list. May return `needs_confirmation`.

The Compass Inbox in one read: finished interviews awaiting review (transcript in, not yet turned into pages), AI-proposed opportunities awaiting accept / dismiss, and the caller's pending approval cards for Compass writes. THE place to answer 'what needs me?' for the map. Next moves: compass_interviews_get to read a transcript, then propose pages from it with compass_pages_create; compass_opportunities_accept or compass_opportunities_delete for a proposal.

Emails the guest link for an existing interview, framed as coming from the REQUESTING USER (their name signs it; replies go to them). Author `message` in their voice — short, human, says why THEIR knowledge matters and that it takes ~15 minutes, no account needed. The approval card shows the exact subject + message before anything sends. Limit: the invite plus ONE reminder; a third ask is the user's conversation to have. Completion arrives as a notification with draft-page counts — don't poll.

Ranks the PEOPLE the map says know about a page (workflow, system, pain point): `owns` links first, then `involved_in`, then weaker edges. Each target carries contact email + role from their PERSON page and their latest interview (skip someone who just gave one — interview fatigue is real). Empty result = the map doesn't know an owner: ASK THE USER who runs this, create the PERSON page + owns link from the answer, and the map gets smarter. Use before compass_interviews_create to pick the interviewee.

Mints a stakeholder-interview invite: a no-account guest link where the person talks to an interviewer agent briefed by your focusPrompt, and the transcript flows back into Compass as reviewable draft pages. THE KNOWLEDGE-GAP MOVE: when caliper_flow_performance shows failures clustered on missing company facts (the judge says the flow invented a policy, missed a rule, didn't know who owns something), the fix is usually not a prompt edit — it's asking the human who actually knows. Write a focusPrompt that names the SPECIFIC gaps (cite the eval run id), pick the owner of the relevant workflow as interviewee when the map knows one, and hand the user the invite link to forward. May return `needs_confirmation` — tell the user who you want to interview and why, then wait.

One interview in full — metadata plus the transcript of what the guest actually said. Read this before summarizing an interview or drafting pages from it: the transcript is the source you work from, and your compass skill has the rules for typing and splitting what's in it. Ids come from compass_interviews_list or compass_inbox_list.

Every stakeholder interview in the workspace, newest first: who was invited, status (INVITED / IN_PROGRESS / COMPLETED), focus, message count, whether the transcript was already reviewed (documentPageId set), and the invite URL while the link is still live. Check this before inviting someone again — interview fatigue is real — and to answer 'who have we already asked?'. Read one in full with compass_interviews_get.

Kills an interview's invite link — the guest's next visit sees that the link is no longer active. Use when an invite went to the wrong person, the user changed their mind, or the link leaked. Idempotent. Ids come from compass_interviews_list. May return `needs_confirmation`.

Creates a typed, directed edge between two pages — the knowledge graph's connective tissue. Canonical directions: PERSON or ROLE owns WORKFLOW/SYSTEM, PERSON or ROLE involved_in WORKFLOW, PERSON holds ROLE, WORKFLOW uses SYSTEM, SYSTEM uses SYSTEM, PAIN_POINT affects WORKFLOW/SYSTEM/PERSON/ROLE, DOCUMENT documents anything, relates_to as fallback. Prefer attaching responsibilities to the ROLE and linking the PERSON to it with holds — the role outlasts whoever is in it. Pass validFrom / validTo when the source says when it was true ('took over approvals in March'), and sourceKind + sourceId for who said so (the interview or page you learned it from). Idempotent on an open (from, to, kind) edge — re-creating one returns it. May return `needs_confirmation`; tell the user what you're proposing, wait for their approval, then re-call with the approvalId.

Deletes one edge from the graph (the pages stay). Use only when a connection was never true — the system isn't used by that workflow, it was recorded by mistake. When a relationship WAS true and has stopped (the person left the team, moved roles), end it with compass_links_update `validTo` instead, so the history stays. Link ids come from compass_page_links_list. Re-creating the same edge later revives it. May return `needs_confirmation`.

Edits an existing edge between two pages: its `kind` (how the two relate), its `note`, and/or when it was true (`validFrom` / `validTo`). Use kind to CORRECT a connection typed wrongly — 'Dana doesn't own billing, she's involved in it'. Use validTo to END one that used to be true — 'Dana handed approvals to Sam in March' ends Dana's edge in March (then create Sam's from March); the old edge stays as history. Don't delete a relationship that ended; end it. Link ids come from compass_page_links_list. Fails with conflict when the new reading already exists between the same two pages (delete this one instead). May return `needs_confirmation`.

Renders the workspace's visual map to an image and returns it so you can SEE it the way the user does: an isometric drawing where every page is a structure whose shape is its type — people are figures, audiences are crowds, workflows are gears lying on the ground, systems are database drums, offerings are price tags, pain points are warning signs, documents are standing sheets of paper, values are shields, priorities are flags — sized by how many other pages connect to them, placed near what they link to, with pages connected to nothing parked to one side, and routes drawn between linked pages. A coloured ring on the ground around a page shows the changes touching it by stage (blue undecided, amber not started, green in progress, violet done; thicker = more), with a key in the top-left corner. Use this when the user asks about the shape of their map, where the problems are, what connects to what, or anything spatial. The text part counts the pages of each type, the links, and how many pages are unconnected, plus `mapUrl`. The image is for you to look at; do NOT put it in your reply as a markdown image (the chat can't show it). When the user should see the map, link `mapUrl` — e.g. `[Open your map](mapUrl)` — and describe what you saw.

The review verb for the Inbox: promotes an AI-PROPOSED opportunity (from compass_opportunities_propose or the opportunity scout) into the workspace's own pipeline. compass_opportunities_set_status does NOT do this — a proposal stays in the Inbox until accepted. Optional `status` decides its lane in the same step (BACKLOG to park it, EXPERIMENTING to start it); omitted, it lands in NEW. Fails with not_proposed when the row isn't an AI proposal. Ids come from compass_inbox_list / compass_opportunities_list. May return `needs_confirmation` — name the proposal and wait.

Record a change — a fix, a chore, a new step, or an experiment worth trying. Anchor it to a workflow page when one fits (compass_pages_list); leave unanchored otherwise. It lands in the board's first status unless you name another (compass_statuses_list). Set `experiment` only when the user wants it measured against the Ledger. May return `needs_confirmation` — summarize and wait for approval.

Removes an opportunity from the pipeline (soft delete). For an AI proposal the user doesn't want, this is the dismiss verb; for a captured experiment that was a duplicate or a mistake, the remove verb. To conclude a real experiment without evidence, prefer compass_opportunities_set_status REJECTED — that keeps the record. Ids come from compass_opportunities_list. May return `needs_confirmation`.

The workspace's changes — fixes, chores, new steps, experiments. Each carries `statusName` (the workspace's own word for where it is) and `statusCategory` (TRIAGE undecided, BACKLOG not started, ACTIVE in progress, DONE, CANCELED dropped), plus the older lane key in `status`. `experiment: true` marks a change measured against the Ledger: `ledgerEntryId` null means no expectation registered; `ledger.verdict` carries confirmed/missed after settlement. Scores (value/feasibility/risk) and a workflow anchor are optional. Filter by lane key in `status` or by workflowPageId; compass_statuses_list has the status names.

The measurement window's boundary: when the user says the experiment's change actually shipped / went live / rolled out, record the landing date. Readings before it are baseline; after it, evidence of effect. Recorded once — it cannot move afterward, so confirm the date. Attaches to the linked Ledger entry as evidence. May return `needs_confirmation`.

File an AI-PROPOSED opportunity into the workspace's review queue — the scouting verb (the opportunity-scout routine's main move). Unlike compass_opportunities_create this needs NO approval: the proposal itself is the human gate — it lands in the Compass Inbox and the cockpit's Needs-you for accept/dismiss. Check compass_opportunities_list first so you never duplicate an idea. Anchor to a workflow page when one fits; score value/feasibility/risk 1–5.

The honesty mechanism: write what the experiment is expected to change BEFORE evidence exists. Creates a Ledger decision entry and links it to the opportunity — never backfill an expectation to match an outcome. Bind a metric (ledger_metrics_list) + comparator + target when the expectation is measurable; readings then land on the entry as evidence automatically. One expectation per opportunity — revise by superseding in Ledger. May return `needs_confirmation`.

Move a change to one of the workspace's statuses, by name (compass_statuses_list has them — e.g. "In review"). The old lane keys (NEW / QUALIFYING / BACKLOG / EXPERIMENTING / SETTLED / REJECTED) still work and land on that lane's default status. Only changes marked as experiments follow the Ledger: when an experiment enters an In progress status with no registered expectation, offer compass_opportunities_register_expectation; when it enters Done with its Ledger entry still open, offer ledger_entries_settle. Other changes just move. May return `needs_confirmation`.

Corrects an opportunity's content: label, description, priority, what done means, the 1–5 value / feasibility / risk scores, the owner (a PERSON page), notes, tags, workflow anchor, external link, visibility. Fields you omit are untouched; the lane is NOT here — move it with compass_opportunities_set_status. Opportunity ids come from compass_opportunities_list. May return `needs_confirmation` — say what you're changing and wait.

All typed edges touching one page, both directions, each hydrated with the other endpoint's page summary. Use this to understand a subject's neighborhood before adding to it. Current connections only, unless includeEnded — then also relationships that have ended (validTo in the past), for questions like who handled this before.

Creates a typed page in the workspace's Compass compendium. Check `compass_pages_list` first — don't create a page for a subject the map already has; link to it instead. May return `needs_confirmation` — if so, tell the user what you're proposing, wait for their approval, then re-call with the approvalId. Only record what the human has actually told you.

Moves a page to the trash (soft delete — its connections and anchored opportunities go with it, and compass_pages_restore brings the whole set back). Use this to REMOVE a page you or an extraction created wrongly, or one the user says no longer belongs on the map; to fix a wrong title or body, use compass_pages_update instead. Page ids come from compass_pages_list / compass_pages_search. May return `needs_confirmation` — name the page and wait for approval.

Fetches one Compass page by id, including its full Markdown body, header fields, and any attached Napkin sketches — view an attached sketch's actual drawing with `napkin_boards_view` (its boardId) before discussing it.

Lists pages in the active workspace's Compass compendium. Optional `type` filter narrows to one node type (WORKFLOW, PERSON, ROLE, SYSTEM, PAIN_POINT, DOCUMENT, VALUE, PRIORITY, AUDIENCE, OFFERING). Returns summaries, 50 at a time (`limit` / `offset`, `total` and `nextOffset` in the result) — fetch one with `compass_pages_get` for the full body. When you know what you're looking for, `compass_pages_search` is the better first call.

Puts a trashed page back on the map, together with exactly the connections and opportunities its delete took. Use when the user wants a deleted page back (the pageId from the earlier compass_pages_delete, or from the Compass trash). Fails with not_found when the page is already live or never existed. May return `needs_confirmation`.

Keyword search over page titles, bodies, and tags (case-insensitive substring match), paginated. The fast way to check whether a subject already has a page before creating or linking. Returns summaries with a 300-char body snippet — fetch full text with `compass_pages_get`.

Edits an existing page's title, description, body, tags, header fields, or visibility — use this to FIX what you (or an extraction) got wrong instead of creating a duplicate. Fetch the current page with `compass_pages_get` first and preserve what the human wrote; title / body / tags replace the field wholesale, while `headerFields` MERGES over the current ones (send only the keys you're changing — 'set the owner' leaves status alone). Page ids come from compass_pages_list. May return `needs_confirmation` — tell the user what you're changing, wait for approval, then re-call with the approvalId.

Returns the Napkin diagram that holds a WORKFLOW page's steps, creating it when the page has none. If the page body has a ```mermaid block, it moves into the diagram verbatim (node ids kept, so changes anchored to a step still point at it) and leaves the body. Then edit the steps with napkin_diagrams_update using the returned diagramId. One diagram per workflow holds every step anyone has described — when two people describe the same process differently, add the steps to this one diagram rather than making a second. A step that is itself a workflow is a node whose meta ref is { type: 'page', id: <that workflow's page id> }. compass_pages_get returns processDiagramId when one exists. May return `needs_confirmation`.

Changes whose effects reach a WORKFLOW's steps — or any nested workflow's — plus changes anchored to it with no effects yet, each with what it does per step. Pass their ids to compass_workflow_rollup's changeIds to project the workflow after them.

The statuses this workspace's changes move through, in board order — the names people use. Each sits in a group: Undecided (TRIAGE), Not started (BACKLOG), In progress (ACTIVE), Done (DONE), Dropped (CANCELED). Groups are stable across workspaces; names aren't, so use the names when talking to people and the groups when reasoning about progress. Move a change with compass_opportunities_set_status.

Every claim about a WORKFLOW's steps, oldest first: the step (nodeId; null = the workflow as a whole), the role or person (subject), the relation, who says so (sourceKind + sourceLabel), when it was true (validFrom/validTo), and origin — AI_PROPOSED claims are waiting for a person to review. Claims that disagree coexist; each keeps its source.

Propose claims about who does what in a WORKFLOW, from what someone said. Each claim names a step (nodeId from compass_workflow_steps), a ROLE or PERSON page (subjectPageId), and a relation: owns (accountable for it), does (does the work), approves (signs off), consulted (asked for input), does_not_do (says they don't do it — an answer, not a gap). Claims land as proposals for a person to accept in Compass; they don't count until then. Always say who said it: sourceKind 'interview' + the interview id, or 'page' + the DOCUMENT or PERSON page id. Prefer the ROLE when the person speaks for their role, the PERSON when it's specific to them. Record a disagreement as its own claim rather than skipping it. When someone says a step happens that isn't in the diagram, add the step with napkin_diagrams_update first. Re-proposing an existing claim from the same source returns it.

Propose estimates from what someone said, as ranges — people know "20 minutes to an hour", not "37 minutes"; when they give one number, use it for both ends. Each item is either a `measure` or a `gate` on a step (nodeId from compass_workflow_steps): - measure.metric `working`: hands-on minutes per run (low/high). - measure.metric `waiting`: minutes the work sits idle before or inside the step — ask about this separately; it's usually most of the waste. - measure.metric `hardCost`: money that isn't anyone's time (amount, currency, per run or month). - measure.metric `frequency` with nodeId null: how often the workflow runs (low/high per day, week, month, or year); with variantId, how often that variant runs. - gate: approval, handoff, rekey (typing the same data into another system), or rework, with returnRate (0–1) when they know how often it sends work back. Pass subjectPageId (a ROLE or PERSON) when the time is one person's or role's — it prices the time through that role's rate. Always say who said it. Proposals count once someone accepts them in Compass.

Builds a step suggestion the way Compass's Build button does: makes its change if it isn't one yet, then the thing in Workbench — a flow drafted from the step itself (who does it, its times, systems, write-up, attachments, interview notes) and its checklist; a shim named for the decision; or a task whose sentence is the steps. Use this, not workbench_flows_scaffold, whenever the work came from a step suggestion. Returns what was built and, for a flow, what the draft still needs. Fails if something's already built for it.

Your earlier read of a WORKFLOW's steps: for each suggestion, the steps it covers (nodeIds, labels), what could do them (proposal.doer: a flow and its mode, a shim, or a task), whether it does the step or helps (reach), why, and what it would take (checklist, each item met or not). state OPEN is waiting for a person; APPLIED made a change (opportunityId), and `built` is what was built for it in Workbench, if anything. Pass changeId instead of pageId to get the one suggestion a change came from. To build one, use compass_step_suggestions_build — not workbench_flows_scaffold.

Newest first: steps added to or dropped from the diagram (and by whom), and claims about who does what or what a step takes — said, corrected (with what they replaced), withdrawn, or accepted from a proposal — each with its source. This is when we LEARNED things; when they were true is each claim's validFrom/validTo. Use it to brief someone on what changed in the picture, or to see what an interview added.

Per run and per month: hands-on minutes, waiting minutes, labor cost (hands-on time priced through each role's hourly rate), and hard costs, each as a low–high range, with every step's share and its gates (approvals, handoffs, re-keying, rework). A step that is itself a workflow uses that workflow's roll-up unless it has its own estimate. `coverage` says how many steps are timed — always say how much of the total rests on estimates before quoting it, and never present a range as one number. `unpricedRoles` are roles doing timed work with no hourly rate; their time counts and its cost doesn't. Where the waiting dwarfs the hands-on time, or a gate rarely sends anything back, is usually where the improvement is. `at` reads the estimates as of a date; `variantId` rolls up one variant.

Every step in a WORKFLOW page's steps diagram, in diagram order, with its phase, whether it is itself a workflow (subWorkflowPageId), and who the map says owns, does, approves, is consulted on, or doesn't do it. `unknown: true` means nothing that counts has been said about the step — those are the questions worth asking in an interview. `disputed` lists roles or people with conflicting claims; ask about those rather than picking a side. `proposals` counts claims waiting for review. `variants` are named subsets of the steps ("rush job", "enterprise client"); each step lists the variants it belongs to. Returns no steps when the workflow has no diagram yet (compass_process_diagram_ensure makes one).

Posts a comment on a workspace entity — a new thread, or a reply when rootId is given. Use it to leave findings where the discussion already lives (an eval result on the flow being debated, a summary on a long thread). Mention people via mentionedUserIds (from workspace member ids) to ring their notification bell; never mention someone who didn't ask to be pulled in.

Lists the comment threads on one workspace entity (open first, then resolved) with authors and timestamps. Read this before weighing in on contested work — the threads are where disagreement lives before it becomes a decision.

Sets a comment thread's resolved state (rootId = the thread's root comment id). Resolve ONLY when the human asked or the thread's question is demonstrably settled — and say what settled it in a reply first. Reopening is for new evidence.

Without a tag: every tag in use across the workspace with how many entities carry it, most-used first — the vocabulary the team already organizes by. With a tag: everything filed under it across every tool, each with its kind, id, title, and path. Use it to reuse existing labels instead of inventing near-duplicates, and to answer 'show me everything about X' when X is a label.

Returns the tags on a batch of entities of one kind — the labels galleries organize by. Ids come from the kind's list/get tool or from search_workspace. Use it before entity_tags_set so you replace the full set knowingly, and to answer 'what is this filed under'. Entities the user can't see are omitted.

Replaces the FULL tag set on one entity (an empty list clears it). Read the current tags with entity_tags_get first and pass the merged list — this is not additive. Tags are lowercase letters, numbers, spaces, and hyphens; prefer labels already in use (entity_tags_browse) so the workspace's vocabulary stays small. The id comes from the kind's list/get tool or search_workspace.

Enumerate all available docs pages, optionally filtered by product (e.g. 'compass', 'legal', 'overview'). Use this to discover what slugs exist before calling `get_doc`. No authentication required.

Search ZeroWidth product documentation. Returns matching pages with title, slug, public URL, and a query-relevant snippet. Use this when the user asks about a ZeroWidth product (Compass, Workbench, Caliper, Prism, Ledger, Napkin, zv1), an API behavior, or a policy. No authentication required — the docs corpus is public.

Fetch the full Markdown body of a specific docs page by its slug. Use this after `search_docs` when the user needs the complete content of a page. No authentication required.

Finds entities across every tool by name in one call — Workbench flows, Compass pages, Caliper datasets, evals, rubrics, reviews, specs and sources (apps sending agent traces), Ledger entries, Napkin sketches and decks. Use it FIRST when the user names something without saying where it lives ('the onboarding flow', 'that invoice page'); reach for a tool's own list only when you already know the tool. Each hit carries its id, kind, and workspace-relative path, so the id feeds the matching *_get tool and the path makes a link. Results only include what the user can see, and only kinds this token may read.