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.

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.

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 — designed for LLM coders that need to understand the full app before writing any code. Strips PM-narrative fields and synthesises entities, interactions, page auth rules, and state machines from spec data.

Use this tool at the start of a coding session instead of assembling context from multiple calls.

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",
      "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"
    }
  }
}

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.

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 status or content. Use status passed when your code satisfies the criterion, failed when it does not (criterionId required).

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 highest-priority criterion in ready status (or null if nothing is ready). Read-only — the standard entry point for an implementation loop.

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_report_progress

Append a progress note to the criterion timeline without changing status. Use it to surface intermediate work for visibility.

vibemap_submit_for_review

Transition in_progress → in_review. Requires evidence — a git SHA and a diff URL.

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, ambiguity, or environmental issue prevents progress.

vibemap_unblock_criterion

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

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.

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, then re-submit the map to clear the drift.

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.