5.2 — Tools reference

Every tool the @vibemap.ai/mcp-server package exposes, grouped by category. Each tool is callable directly by your IDE agent as a function — your agent picks the right one based on what you ask it to do.

If you're new here, start with MCP server overview to get the server installed first.

The server exposes 48 tools and 22 prompts (plus the ci-report command, which runs in CI rather than in your agent).

One distinction runs through this whole page. Almost every tool below is unmetered: vibemap_create_feature, vibemap_list_user_stories and friends are plain reads and writes, so your agent does the thinking, on your tokens, and VibeMap runs no model. The exceptions are the two tools that ask VibeMap's own brain to do the work — vibemap_agent and vibemap_analyze_codebase — and those are metered against your VibeMap token budget.

Prompts (slash commands)

Beyond tools, the server exposes a set of prompts — invocable workflows your IDE surfaces as slash commands (in Claude Code they appear as /mcp__vibemap__<name>). Instead of pasting a long instruction, you run the command and your agent receives the full, up-to-date workflow expanded from VibeMap's server. Every prompt except new_project takes a projectId; the code-oriented ones also accept an optional localPath (otherwise they target the repo you have open).

Start with new_project. It is the only prompt that needs no projectId, because it is the one that creates the project — everything else is scoped to a project that already exists.

Whole-graph or stage-by-stage — same standard, your choice of pacing. author_idea authors all five stages in one run; the author_personas → … → author_pages chain authors one stage per command and stops so you can review before the next stage builds on it. The coverage floors, criticality weighting, scope guardrails and BDD rules are single-sourced, so neither route applies a weaker standard — the only difference is where you get to intervene. Each stage prints the next command when it finishes.

All of these are unmetered: they drive the vibemap_create_* tools, so your agent does the thinking on your own tokens and VibeMap runs no model.

The prompt bodies live on VibeMap's server, single-sourced with the in-app copy-paste flow, and are available on every plan — same as the tools. MCP is not plan-gated; what a plan gates is which server-side generations VibeMap will run for you. See What your plan gets you.

Metered generation prompts (gen_*)

The prompts above are bring-your-own-agent — VibeMap runs no model. The server also exposes VibeMap's own generation commands as prompts, mirroring the in-app /gen-* slash commands. Unlike the author_* prompts, these run VibeMap's own models and draw down your VibeMap token budget — exactly as if you'd typed the command in the app. Each takes a projectId.

Because they spend your token budget, these are subject to the same plan gates as any server-side generation — see What your plan gets you. (gen_business_case is intentionally not exposed while the Research phase is gated off for MVP1; it appears once that flag flips on.)

Project management

vibemap_list_projects

List all projects owned by the authenticated user. Returns project IDs, names, descriptions, and status. No parameters.

// Result
[{ "id": "uuid", "name": "My SaaS App", "description": "...", "created_at": "..." }]

vibemap_create_project

Create a new project. When starting from an existing codebase, create the project first, then call vibemap_analyze_codebase with the returned project ID.

vibemap_get_project_context

Retrieve the full context of a project — features, user stories, personas, pages, and database schema — in one call. Use the include* flags to trim the payload.

vibemap_get_atomic_blueprint

Returns a single, code-shaped projection of the entire project — entities, interactions, page auth rules, and state machines synthesised from spec data, with PM-narrative fields stripped.

It is the whole project, and large projects can run to about 150K tokens. Use it for one-off whole-project work such as an initial scaffold or an audit. While building a ticket, do not fetch it: call vibemap_get_criterion_context for the criterion you are on, which returns only what that criterion needs.

Rate limit: 60 calls per minute, shared with vibemap_list_access_rules, vibemap_get_review_plan, and vibemap_list_changesets. The budget is keyed to your account, not to the key, so two PATs on the same account share it.

// Result shape
{
  "project": {
    "id": "uuid",
    "name": "ScubaLife",
    "description": "...",
    "tech_stack": ["nextjs", "supabase"],
    "core_capabilities": ["dive log", "booking"],
    "key_differentiators": ["offline-first"]
  },
  "roles": [
    {
      "id": "uuid",
      "name": "Diver",
      "permissions": [{ "page_path": "/dashboard", "verbs": ["view"] }]
    }
  ],
  "entities": [
    {
      "name": "dive_logs",
      "columns": [
        { "name": "id", "type": "uuid", "primary_key": true, "nullable": false, "unique": true, "default": null },
        { "name": "status", "type": "text", "primary_key": false, "nullable": true, "unique": false, "default": "draft" }
      ],
      "relationships": [{ "to": "users", "via": "diver_id", "type": "many-to-one" }],
      "state_machines": [
        {
          "field": "status",
          "states": ["draft", "submitted", "verified"],
          "initial_state": "draft",
          "terminal_states": ["verified"],
          "transitions": [
            {
              "from": "draft",
              "to": "submitted",
              "trigger": "diver submits log",
              "guard": "all required dive fields are filled"
            }
          ],
          "confidence": "high"
        }
      ]
    }
  ],
  "interactions": [
    {
      "id": "uuid",
      "actor": "Diver",
      "trigger": "submits offline log",
      "precondition": "log is in draft",
      "operation": { "type": "create", "entity": "dive_logs", "fields": [] },
      "post_state": "log queued for sync",
      "ui_surface": "/logs/new",
      "story_id": "uuid",
      "feature_id": "uuid",
      "section_id": "uuid",
      "element_key": "primary-cta",
      "scenario": "happy_path",
      "confidence": "low"
    }
  ],
  "pages": [
    {
      "id": "uuid",
      "name": "Dive Log Form",
      "path": "/logs/new",
      "page_type": "form",
      "auth_required": true,
      "allowed_roles": ["Diver"],
      "sections": [],
      "data_dependencies": [],
      "api_endpoints": [],
      "ui_states": null
    }
  ],
  "navigation": {
    "header": [{ "name": "Top Nav", "nav_links": ["/dashboard", "/logs"] }],
    "footer": [],
    "flows": []
  },
  "_meta": {
    "generated_at": "2026-04-30T12:00:00.000Z",
    "blueprint_version": 1,
    "missing": [],
    "synthesis_confidence": {
      "interactions": "low",
      "state_machines": "low"
    }
  }
}

interactions[].section_id / element_key — present on every interaction, though either may be null: the page section and the specific UI element the interaction is bound to. Both come from the element-contract layer, which lets a criterion or interaction target one element on a page rather than the page as a whole.

entities[].state_machines — every lifecycle machine declared on the table, ordered by field. A table can carry more than one (e.g. status and escrow_status), so this is an array; the key is omitted entirely when the table has no machine.

• initial_state — the state a new row starts in, or null when never captured. Always null for synthesised machines (confidence: "low") — the heuristic does not guess it.
• terminal_states — derived, not stored: states with incoming transitions but no outgoing ones. A self-transition counts as both, so a self-looping state is never terminal. Always [] for synthesised machines.
• transitions[].guard — the precondition that must hold for the transition to fire, or null when unconditional/unknown. Always null for synthesised machines.
• transitions are deduplicated and returned in a derived canonical order (source lifeline, then forward/self/back, then target, then trigger, then guard) — the same order the State Machines tab draws. It is not the insertion order, and it is stable across regenerations even though every transition UUID churns.

Deprecated: entities[].state_machine (singular) is still emitted and equals state_machines[0]. It will be removed one release after state_machines ships. Migrate now: on a table with two machines the singular key exposes only one of them, chosen by field-name order rather than by intent — which is the data-loss bug the array replaces.

_meta.synthesis_confidence — "low" means the field was synthesised heuristically from acceptance-criteria text. "high" means the field is backed by an LLM-authored row in a dedicated table (interactions in the interactions table; state machines in entity_state_machines + entity_state_transitions). Confidence flips to "high" after the user runs Prepare for Dev on the project (Pro+ only) — it triggers four parallel pipelines (interactions / state machines / permissions / data contracts) that populate these tables. Until then, "low" is expected: use the blueprint as authoritative structure but validate edge-case transitions during implementation.

_meta.missing — lists any blueprint sections that couldn't be populated (e.g., "entities" when the schema hasn't been generated yet). An empty array means the blueprint is complete.

vibemap_list_access_rules

List the project's access rules (which roles can do what, per page/entity) — the same rules the App Builder compiles into RLS policies.

vibemap_get_review_plan

What stands between the project and being ready to build, in the order it should be tackled — the same walkthrough the Prepare map shows the user, and the same one the in-app agent's briefs are built from.

Findings on their own are an unordered set. Call this rather than deriving your own priority: the ordering is deterministic, so you and the UI always agree on what comes first.

Steps are grouped by finding kind — 40 stories missing criteria is one step, not 40 — and ordered so a fix never invalidates earlier work: access → data → surfaces → behaviour → detail → reconcile. Reconciliation runs last because every earlier tier can create fresh staleness.

// Result shape
{
  "project_id": "uuid",
  "ready_to_build": false,
  "blocking_steps": 2,
  "total_findings": 17,
  "sources_failed": [],
  "steps": [
    {
      "position": 1,
      "id": "review:page-no-access",
      "kind": "page-no-access",
      "tier": "access",
      "title": "Decide who can open these pages",
      "why": "Pages with no access rule are unreachable for every role...",
      "severity": "warning",
      "blocking": true,
      "count": 3,
      "finding_ids": ["page-no-access:page:<uuid>"],
      "messages": ["Page \"Dashboard\" has no access rule — no role can reach it."],
      "node_ids": ["page:<uuid>"],
      "action": {
        "kind": "generate",
        "pipeline": "permissions",
        "endpoint": "/api/projects/<uuid>/prepare-for-dev",
        "body": { "pipelines": ["permissions"] },
        "label": "Generate access rules"
      }
    }
  ]
}

action.kind is how the step is resolved in-product. There are five, and the one dimension worth branching on is whether a human is required:

node_ids carries the blueprint-map nodes the step concerns, for pages, features, roles and tables alike.

sources_failed — a non-empty list means some checks did not run, so their findings are missing. An empty steps array alongside a non-empty sources_failed is not a clean bill of health; say so rather than reporting the project as ready.

Read-only. Reporting a gap is not the same as being entitled to fix it — the generations behind action.fixKey stay gated at their own execution seams.

vibemap_list_changesets

List the project's version-control changesets (most recent first) with a per-changeset op count. Every write made through this server is wrapped in a changeset, so use this to audit what an agent session actually changed.

vibemap_get_page_source

Retrieve a page's generated source code (the page's own source_code plus each of its sections') so you can pull it straight into a repo.

The VibeMap agent

vibemap_agent

Runs one turn of VibeMap's own conversational agent — the same Supervisor behind the agent panel in the app — entered through MCP instead of the browser. Where the create_* tools let your agent do the work, this hands the work to VibeMap's: it plans, asks for confirmation when a change is destructive, executes across the spec graph, and can kick off background generation pipelines.

That makes it the one metered authoring tool on this page. It reserves against your VibeMap token budget before the turn and commits the real usage after, and it answers 402 with code: "TOKEN_BUDGET_EXCEEDED" when there isn't budget left. The granular create_* / list_* tools run no VibeMap model and cost you nothing.

// Result
{
  "success": true,
  "response": "I'll remove the Subscriptions feature and its 3 user stories…",
  "confirmationRequired": true,
  "operationId": "…",
  "plan": { "…": "human-readable plan" },
  "clarificationNeeded": null,
  "executionResults": [],
  "sessionId": "…"
}

Confirmation is a two-call flow. MCP has no interactive button, so a destructive change can't pop a dialog. Instead:

1. Send { projectId, message: "delete the subscriptions feature" }. The agent replies with confirmationRequired: true, an operationId, and a plan describing exactly what it intends to do. Nothing has been changed yet.
2. Call back with { projectId, approveOperationId: "<the id>" } to execute it. { approve: true } resolves the latest pending operation instead, and a bare { message: "yes" } works too — but approveOperationId is the one that can't approve the wrong thing when two operations are pending.

Show the user the plan between those two calls. That's what it's for.

The conversation threads itself. MCP calls are stateless, so the server derives a deterministic session ID from your user ID and the project ID: the same person on the same project always lands on the same thread, and multi-turn history works without your IDE tracking anything. Pass an explicit sessionId only if you want a separate thread.

When the turn starts a generation, the reply carries generationStarted: true and the matching entry in executionResults is marked queued. Where that entry carries a sessionId, poll it with vibemap_get_generation_status. Background pipelines are metered separately under their own generation type and are capability-gated like any other generation: a plan that can't generate schema still can't get it this way.

Personas & pages

When authoring a spec with your own agent (bring-your-own-agent generation), personas come first — they are the cast of users the rest of the spec is written for — and pages come last, once the feature set is stable. Existing personas and pages are visible via vibemap_get_project_context, so enrich rather than duplicate.

vibemap_create_persona

Create a user persona. All parameters are camelCase; the nested blocks mirror the depth VibeMap's own generator produces, so an agent-authored persona is as rich as a hosted one (and is indexed for semantic search).

vibemap_create_page

Create a page/screen in the project's page inventory.

Schema

The database schema is authored as its own step, after the rest of the spec is stable (run the author_schema prompt). Existing schema is visible via vibemap_get_project_context (dbSchema); the persist step keyed-reconciles, so re-running is safe.

vibemap_create_schema

Persist a project's database schema — tables, columns, and relationships — in one call. All parameters are camelCase (this is VibeMap's SchemaJSON, so no snake_case conversion). Give every table an id primary key plus created_at/updated_at; express foreign keys via each column's foreignKey, and relationships auto-derive from them (so relationships is usually unnecessary). Table- and page-level access rules are handled by the separate access-rules flow, not here — VibeMap seeds sensible RLS from the foreign keys you set.

Features

(For broad reads, your agent will usually call vibemap_get_atomic_blueprint or vibemap_get_project_context once and operate from that. The tools below are for fine-grained reads and writes.)

vibemap_list_features

List features for a project. Supports filtering by status, priority, category, and search; paginated via limit/offset.

vibemap_create_feature

Create a feature — used heavily when reverse-engineering a codebase to register discovered capabilities.

vibemap_update_feature

Update an existing feature's fields or status. For spec authoring only: while building a ticket, use vibemap_propose_spec_change so a person reviews the change.

User stories

vibemap_list_user_stories

List user stories for a project or feature (at least one of projectId/featureId). Filter by status, priority, search; paginated.

vibemap_create_user_story

Create a user story inside a feature.

vibemap_update_user_story

Update an existing story's fields or status (storyId required; same optional fields as create, plus status).

Acceptance criteria

vibemap_list_acceptance_criteria

List criteria for a story, feature, or project (at least one filter). Returns BDD-formatted criteria (Given/When/Then) with status.

vibemap_create_acceptance_criterion

Create a criterion in BDD format. Call it repeatedly to flesh out what "done" means for a story.

vibemap_update_acceptance_criterion

Update a criterion's content (Given/When/Then, description, scenario category). Status is not writable here: claim the criterion and submit it for review instead, and CI (or a person) decides whether it passes. For spec authoring only: while building a ticket, use vibemap_propose_spec_change.

Kanban tracking

The kanban tools implement a typed agent workflow: get next → claim → report progress → submit for review → resolve. See Kanban tracker: step-by-step user guide for the full lifecycle.

vibemap_get_kanban_board

Real-time board view grouped by status columns; features with stories nested underneath. Read-only.

vibemap_get_next_ready_criterion

Returns the next criterion to work on, plus the other ready criteria of the same story (bundle) so the whole story can be built together. Read-only — the standard entry point for an implementation loop.

When nothing can be claimed, criterion is null and reason says why: awaiting_approval, awaiting_review, failed_needs_rework, blocked, dep_cycle, sprint_complete, release_complete, reserved or in_progress. blocking lists the criteria behind it, and skipped_sprints lists earlier sprints whose leftovers are waiting on a person or CI.

vibemap_get_execution_plan

The build order for a project: criteria grouped by sprint in dependency order, each with its state. Call it once at the start of a build session. Read-only.

vibemap_claim_criterion

Atomically claim a criterion (ready → in_progress). Returns a 409 if another agent won the race — call vibemap_get_next_ready_criterion again rather than retrying the same claim.

vibemap_claim_story

Claim every claimable criterion of a story in one call (the story is the ticket; each criterion is still verified on its own). The response lists what was claimed, what was skipped and why, and a context pack for each claimed criterion. All or nothing: if another agent wins a race, nothing is left claimed by the call.

vibemap_get_criterion_context

Everything needed to build one criterion in a few thousand tokens: the criterion, its story and feature, the pages and interactions it touches, data entities, access rules, related code and conventions (the test-name prefix, the commit trailer and the data-vm-ac element attribute). Carries a spec_seq to pass to vibemap_submit_for_review and an etag so re-checking is cheap. Read-only.

vibemap_report_progress

The live heartbeat for a criterion you have claimed. It does not change status; it tells the board what you are doing. Call it at every phase change and at least every 3 minutes.

vibemap_submit_for_review

Transition in_progress → in_review. Requires evidence: the commit SHA, the files you changed and the named tests that prove the criterion. Each test name should start with the criterion's code, for example [AC-042] rejects an empty title. A local pass does not finish the criterion; only a passing CI run marks it verified (see CI review driver).

vibemap_get_criterion_evidence

The submission history of a criterion: every attempt with its files, named tests and verdict, newest first. Read-only. Use it after a failure to see which tests failed.

vibemap_rework_criterion

Send a criterion that failed review back to ready so you can build it again. Only the agent that built it can do this. The failing review's feedback is attached to the event; read it with vibemap_get_criterion_evidence, then claim the criterion again.

vibemap_resolve_review

Transition in_review → passed | failed. Agents cannot self-resolve their own work — this tool requires a CI-scoped token or a signed-in user, not the agent token that submitted the work.

vibemap_block_criterion

Mark a criterion blocked (any active status → blocked) when an external dependency or an environmental issue prevents progress. For an unclear spec use vibemap_ask_user, which also files a question for a person to answer.

vibemap_unblock_criterion

Unblock a criterion — restores the status recorded when it was blocked, defaulting to ready.

vibemap_ask_user

Ask the project's owner a question when the spec is unclear. Blocks the criterion (spec_unclear) and shows the question on the board, with your suggested options if you give any. Keep working on other ready criteria while you wait. Once a person answers, the criterion is unblocked automatically; collect the reply with vibemap_get_answers.

vibemap_get_answers

The answers to questions you asked with vibemap_ask_user, read from the criterion's own questions (newest 50). Returns each answer, and waiting: true while a question is still open. Read-only.

vibemap_get_spec_delta

What changed in the spec since a sequence number (the spec_seq in your context pack), and which criteria that affects. requires_rebuild lists affected criteria that are already in progress, in review or passed. If has_more is true, call again with sinceSeq set to the returned to_seq. Read-only.

vibemap_propose_spec_change

Propose a change to the spec when the code has to differ from it. The proposal is staged; it does not edit the spec. The review screen for staged proposals is coming: until it ships, the owner will not see a staged proposal in the app, so also list it in your final summary. Identical pending proposals (same entity and field set) are returned rather than duplicated, a project holds at most 50 pending proposals, and each person can stage 10 per minute. While building, always use this instead of the update_* tools.

vibemap_get_release_work_list

A release's work list grouped as new, modified and removed. Each item has its material field changes, the commit it was last built at and its code paths; for removed items the code paths are the files to delete. Read-only. Needs a plan with release management.

vibemap_get_release_diff

The raw diff of a release against its baseline: every listed item with its baseline row and field changes. Prefer the work list for acting on; use this when you need a removed item's baseline detail. Read-only. Needs a plan with release management.

vibemap_list_kanban_events

List transition events for a project, newest first. Read-only. Use since for reconnect-backfill after a dropped realtime connection.

vibemap_update_kanban_status — DEPRECATED

Legacy free-form status setter for features, stories, and criteria (entityType, entityId, newStatus, optional notes). Deprecated — use the typed transition tools above instead (claim, report_progress, submit_for_review, resolve_review, block, unblock); this tool will be removed in a future release.

The build loop

The build_sprint prompt drives these tools in order, so you rarely call them by hand:

1. vibemap_get_execution_plan once, then vibemap_get_next_ready_criterion.
2. vibemap_claim_story; work from the context packs it returns. Do not fetch the whole-project blueprint inside the loop.
3. Per criterion: vibemap_report_progress (planning), write the test first (name starts [AC-042]), report writing_test, implement and report implementing (tag interactive elements with data-vm-ac), run the tests and report running_tests, then commit with a Spec-Ref: AC-042 trailer.
4. vibemap_submit_for_review with the changed files and named tests, then report waiting_ci. The agent never marks anything done: a passing CI run does, via ci-report.
5. On failed: vibemap_get_criterion_evidence, vibemap_rework_criterion, claim again.
6. When the spec is unclear: vibemap_ask_user, carry on with other ready work, collect the reply with vibemap_get_answers. When the code must differ: vibemap_propose_spec_change.
7. A heartbeat at every phase change and at least every 3 minutes.

Codebase analysis

vibemap_scan_codebase

Scan a local directory and return a formatted tree view plus file statistics — read-only, nothing leaves your machine. Use it to explore before syncing to VibeMap.

vibemap_analyze_codebase

Scan a local codebase and submit a digest (directory tree + key file contents, ~20k-token budget) to VibeMap for AI-powered reverse engineering.

Prefer local-first authoring. If your agent is capable, skip this tool and author features directly with vibemap_create_feature (then stories and criteria). Your agent sees the whole repo, whereas this tool only submits a ~20-file digest to a server LLM — so locally-authored features are better grounded. analyze_codebase is the one-click fallback for weaker agents, and it still only bootstraps features.

What actually gets persisted: the server-side generation persists features only. It does not create user stories or acceptance criteria. After the task completes, create those yourself with vibemap_create_user_story and vibemap_create_acceptance_criterion — your agent has full codebase access, so its stories/criteria will be more accurate than anything derived from the digest — or run the story/criteria generations in the VibeMap app.

Returns a sessionId to poll with vibemap_get_generation_status.

vibemap_submit_code_map

Submit a structural code map of the user's codebase. It renders on the project's Codebase page, where the user reviews it, hides irrelevant units, and confirms it before map-grounded spec generation. Build the map from your own codebase access — one node per meaningful unit, edges for the relations between them.

Taxonomy: node kinds page | api | model | service | module | config; layers ui | api | data | services | shared; edge kinds imports | routes | reads | writes. Use repo-relative paths as node ids. Max 500 nodes — aggregate small files into their module. Re-submitting replaces the map and resets it to draft.

Available on all plans (the Codebase map is not Pro-gated; generating specs from it is).

Once the user confirms the map, the Codebase page can run the full map-grounded generation chain (features → user stories → acceptance criteria) through VibeMap's server-side pipelines, then link each feature to the code units it came from (spec_code_links provenance, shown as "Implements" chips on map nodes). Agents don't drive that chain — submit a good map and the app takes it from there.

vibemap_get_code_map

Fetch the project's current code map: status (draft or confirmed), nodes/edges (including user-hidden units), and the sync anchor — including any drift report. Call before re-submitting to preserve the user's curation.

vibemap_sync_changes

Report codebase changes since the last sync so VibeMap can flag spec drift on the Codebase page (banner, amber rings on affected units, affected-features list).

Workflow: read anchor.commitSha via vibemap_get_code_map → git diff --name-only <commitSha>..HEAD (plus untracked files) → call this tool. The response lists affected map units and features; update the stale specs with the changeset-audited update tools. The drift report stays on the project until the flagged items are resolved or dismissed in VibeMap; re-submitting the map does not clear it. While you are building a ticket, send spec changes through vibemap_propose_spec_change rather than editing the spec.

vibemap_get_generation_status

Poll a generation task started by vibemap_analyze_codebase, or one a vibemap_agent turn kicked off.

// Result
{ "status": "completed", "progress_percentage": 100, "message": "Generated 12 features" }

Error handling

All tools return errors in a consistent format:

{ "error": "Project not found", "code": "NOT_FOUND" }

Common error codes: NOT_FOUND, UNAUTHORIZED, VALIDATION_ERROR, RATE_LIMITED, INTERNAL_ERROR.

Common pitfalls:

• RLS-blanked reads with PAT auth — if list tools return empty for a project you own, your vm_ personal access token may be missing or malformed; the server then falls back to anonymous reads that RLS blanks out.
• 409 on claim — expected under multi-agent concurrency; re-poll for the next ready criterion rather than retrying the same claim.
• resolve_review 403 for agent tokens — by design; reviews resolve via a CI-scoped token.
• 402 from vibemap_agent — that surface is metered. TOKEN_BUDGET_EXCEEDED means you're out of token budget for the window; PLAN_UPGRADE_REQUIRED means a pipeline the turn tried to start isn't on your plan. The unmetered create_* / list_* tools never return either.
• vibemap_agent did nothing — check confirmationRequired. A turn that returns a plan and an operationId has changed nothing yet; you have to call back to approve it.