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 5.1 — MCP server overview to get the server installed first.

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 / minute per API key.

// 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_machine": {
        "field": "status",
        "states": ["draft", "submitted", "verified"],
        "transitions": [{ "from": "draft", "to": "submitted", "trigger": "diver submits log" }],
        "confidence": "low"
      }
    }
  ],
  "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"
    }
  }
}

_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 Development 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_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.

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 6 — Kanban tracker 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.

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_get_generation_status

Poll a generation task started by vibemap_analyze_codebase.

// 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.