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.

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

vibemap_get_project

Get full project details including features, personas, and stories.

// Result
{ "id": "uuid", "name": "...", "features": [...], "personas": [...], "user_stories": [...] }

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_create_project

Create a new project and trigger initial AI generation.

Features

(For features, user stories, ACs, etc., your agent will usually call vibemap_get_atomic_blueprint once and then operate from that. The individual list/get tools below are for when you need fresh, fine-grained reads.)

vibemap_list_features

List features for a project with story and criteria counts.

// Result
[{ "id": "uuid", "name": "Auth", "story_count": 3, "criteria_count": 12 }]

vibemap_get_feature

Get a single feature with all nested user stories and acceptance criteria.

User Stories

vibemap_list_user_stories

List user stories filtered by feature or project.

At least one filter parameter is required.

vibemap_get_user_story

Get a single user story with its acceptance criteria.

// Result
{
  "id": "uuid",
  "title": "As a user, I can log in with Google",
  "acceptance_criteria": [
    { "id": "uuid", "description": "Google OAuth button is visible", "status": "pending" }
  ]
}

Acceptance Criteria

vibemap_list_acceptance_criteria

List acceptance criteria for a user story.

vibemap_update_acceptance_criteria

Mark a criterion as passed, failed, or pending.

// Example
{ "criteriaId": "uuid", "status": "passed" }

Kanban Tracking

vibemap_get_kanban_board

Get the current kanban board state for a project.

// Result
{
  "columns": {
    "backlog": [{ "id": "uuid", "title": "...", "type": "feature" }],
    "in_progress": [...],
    "done": [...]
  }
}

vibemap_move_kanban_item

Move an item between kanban columns.

Codebase Analysis

vibemap_submit_codebase

Submit code for reverse-engineering into VibeMap specs.

Returns a session ID for tracking analysis progress.

vibemap_get_analysis_status

Poll the progress of a codebase analysis.

// Result
{ "status": "processing", "progress_percentage": 45, "message": "Analysing components..." }

Generation

vibemap_trigger_generation

Start an AI generation task for a project.

Returns a session ID for progress tracking.

vibemap_get_generation_status

Check the progress of a generation task.

// Result
{ "status": "completed", "progress_percentage": 100, "message": "Generated 6 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.