Skip to main content
Glama
@vibemap.ai/mcp-server
by AshMet

@vibemap.ai/mcp-server

Connect your IDE agent to VibeMap via the Model Context Protocol. Load project specs into any MCP-compatible AI coding agent, or reverse-engineer an existing codebase back into structured VibeMap assets.

Quick Start

{
  "mcpServers": {
    "vibemap": {
      "command": "npx",
      "args": ["-y", "@vibemap.ai/mcp-server"],
      "env": {
        "VIBEMAP_API_KEY": "vm_your_token_here",
        "VIBEMAP_BASE_URL": "https://vibemap.ai"
      }
    }
  }
}

Generate your API key at vibemap.ai → Account → Developer → API Keys.

Related MCP server: CodeLocal

What It Does

Outbound (VibeMap → IDE): Load your full project context — features, user stories, acceptance criteria, personas, pages, and DB schema — into your IDE agent. The agent builds to spec and updates your VibeMap kanban in real time as it works.

Inbound (IDE → VibeMap): Point the server at an existing codebase and VibeMap's AI will reverse-engineer it into a structured set of features, user stories, and acceptance criteria.

Requirements

IDE Setup

Claude Desktop

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "vibemap": {
      "command": "npx",
      "args": ["-y", "@vibemap.ai/mcp-server"],
      "env": {
        "VIBEMAP_API_KEY": "vm_your_token_here",
        "VIBEMAP_BASE_URL": "https://vibemap.ai"
      }
    }
  }
}

Fully restart Claude Desktop after saving. Confirm the 🔨 hammer icon appears in the message box.

Cursor

Open Settings → MCP and add:

{
  "vibemap": {
    "command": "npx",
    "args": ["-y", "@vibemap.ai/mcp-server"],
    "env": {
      "VIBEMAP_API_KEY": "vm_your_token_here",
      "VIBEMAP_BASE_URL": "https://vibemap.ai"
    }
  }
}

Windsurf

Same format as Cursor. Add to your Windsurf MCP settings file and restart.

Environment Variables

Variable

Description

Default

VIBEMAP_API_KEY

Your Personal Access Token (vm_...)

Required

VIBEMAP_BASE_URL

VibeMap instance URL

http://localhost:3000

Tools

The server exposes 55 tools via the vibemap_ prefix.

Projects & context

Tool

Description

vibemap_list_projects

List all your projects

vibemap_create_project

Create a new project (use before analyze_codebase)

vibemap_get_project_context

Load full project specs into agent context

vibemap_get_atomic_blueprint

Get the code-shaped blueprint of the whole project (large; for scaffolds and audits, not for building a single ticket: use vibemap_get_criterion_context there)

vibemap_list_access_rules

List table- and page-level access rules (with op_conditions) for RLS + auth

vibemap_get_page_source

Retrieve a page and its section source code

Personas & pages (spec authoring)

Tool

Description

vibemap_create_persona

Create a rich user persona (demographics, goals, pain points, …)

vibemap_create_page

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

vibemap_create_schema

Persist the database schema (tables → columns → relationships) in one call

Conversational agent (hosted, metered)

Tool

Description

vibemap_agent

Drive VibeMap's full conversational agent for one turn (same brain as the in-app chat). Metered — uses VibeMap tokens. Destructive turns return a plan + operationId to approve in a second call; long generations run in the background (poll get_generation_status)

Features

Tool

Description

vibemap_list_features

List features with filtering

vibemap_create_feature

Create a new feature

vibemap_update_feature

Update feature fields or status (validates transitions). For spec authoring only: while building, use vibemap_propose_spec_change

User stories

Tool

Description

vibemap_list_user_stories

List stories by project or feature

vibemap_create_user_story

Create a user story

vibemap_update_user_story

Update story fields or status (validates transitions). For spec authoring only: while building, use vibemap_propose_spec_change

Acceptance criteria

Tool

Description

vibemap_list_acceptance_criteria

Fetch BDD criteria

vibemap_create_acceptance_criterion

Create a BDD acceptance criterion

vibemap_update_acceptance_criterion

Update a criterion's content (Given/When/Then, description). Status is not writable here: use the lifecycle tools below. For spec authoring only: while building, use vibemap_propose_spec_change

Kanban — board & agentic lifecycle

Tool

Description

vibemap_get_kanban_board

Get a real-time board view

vibemap_get_execution_plan

The build order: criteria grouped by sprint in dependency order, with state

vibemap_get_next_ready_criterion

Get the next criterion to work on, its story bundle, and a reason when nothing is claimable

vibemap_claim_story

Claim every claimable criterion of a story at once; returns a context pack for each

vibemap_claim_criterion

Claim a criterion (ready → in_progress)

vibemap_get_criterion_context

Everything needed to build one criterion in a few thousand tokens (use instead of the whole blueprint)

vibemap_report_progress

Heartbeat with the current phase, plus optional plan, files and test counts

vibemap_submit_for_review

Submit a criterion for review with the changed files and the named tests that prove it (→ in_review)

vibemap_get_criterion_evidence

Submission history of a criterion: files, tests and verdict per attempt

vibemap_rework_criterion

Send a criterion that failed review back to ready to build it again

vibemap_resolve_review

Resolve a review (passed / failed); needs a CI-review token or a signed-in user

vibemap_block_criterion

Block a criterion with a category and reason

vibemap_ask_user

Ask the project owner a question when the spec is unclear (blocks the criterion until answered)

vibemap_get_answers

Collect the answers to your questions

vibemap_unblock_criterion

Unblock a criterion with a resolution

vibemap_propose_spec_change

Propose a spec change for the owner to review when the code must differ; never edits the spec

vibemap_list_kanban_events

Kanban transition history (for incremental sync)

vibemap_update_kanban_status

⚠️ Deprecated — use the lifecycle tools above

Version control

Tool

Description

vibemap_list_changesets

List changesets (your writes + history) with op counts; includeOps for diffs, sinceSeq as a cursor

vibemap_get_spec_delta

What changed in the spec since a sequence number, and which criteria that affects

vibemap_get_release_work_list

A release's work grouped as new, modified and removed (with the code paths to delete)

vibemap_get_release_diff

A release's raw diff against its baseline

vibemap_sync_changes

Report changed paths since the last sync so VibeMap can flag spec drift

Codebase

Tool

Description

vibemap_scan_codebase

Walk a local directory

vibemap_analyze_codebase

Reverse-engineer a codebase into VibeMap assets

vibemap_submit_code_map

Submit a structural code map (nodes/edges) rendered on the project's Codebase tab

vibemap_get_code_map

Fetch the project's current code map (status, nodes/edges, sync anchor + drift)

vibemap_get_generation_status

Poll AI generation task status

Import an existing codebase

The structure is read on your machine with no model and no network call. What reaches VibeMap is the structural facts (table, column, policy and route definitions with their file paths) and the spec text your agent writes. File contents never leave your machine.

Tool

Description

vibemap_extract_repo_facts

Read the repository's tables, policies, routes and file clusters locally; sends nothing

vibemap_import_facts

Send the facts: VibeMap creates the schema, access rules and a page per route, each linked to its file

vibemap_import_semantic

Send the features, stories and criteria your agent wrote, each citing its source files

vibemap_finalize_import

Pass the imported criteria (unverified), lock MVP1 and open MVP2

vibemap_resync

Apply the structural changes at your current commit and flag the specs the changed files touch

vibemap_resolve_drift

Clear handled files, map units or criteria from the drift report

vibemap_resolve_code_drift_proposal

Apply or dismiss one staged code-drift proposal

Prompts (slash commands)

The server also exposes prompts — invocable workflows your IDE surfaces as slash commands (in Claude Code: /mcp__vibemap__<name>). The body of each prompt is expanded from VibeMap's server at call time, so you invoke a workflow rather than paste a long instruction. Every prompt takes a projectId except new_project, which is the one that creates a project; the code-oriented ones also accept an optional localPath.

Prompt

Args

Description

new_project

—

Guided interview that creates a new VibeMap project. Start here

author_spec

projectId, localPath?

Author the full spec graph from your local codebase (bring-your-own-agent, code-first)

author_idea

projectId

Author the full spec graph from the project idea (bring-your-own-agent, idea-first)

author_personas

projectId

Stage 1 of 5 — author just the personas

author_features

projectId

Stage 2 of 5 — author just the features

author_stories

projectId

Stage 3 of 5 — author just the user stories

author_criteria

projectId

Stage 4 of 5 — author just the acceptance criteria

author_pages

projectId

Stage 5 of 5 — author just the pages

author_schema

projectId, localPath?

Author the database schema — tables, columns, relationships

sync_changes

projectId, localPath?

Detect and reconcile spec drift since the last sync

code_map

projectId, localPath?

Build and submit a structural code map

load_context

projectId

Load the project's spec context into your agent

kanban

projectId

Show the project's kanban board

import

projectId, localPath?

Import an existing codebase as a locked MVP1: extract locally, import the facts, write the spec per cluster, finalize

resync

projectId, localPath?

Bring an imported project up to date and stage drift proposals for review

build_sprint

projectId

Build the ready work test first while the board follows live; CI verifies, the agent never marks anything done

release_next

projectId

Build the next release: new and modified items, and delete what was removed

gen_* — run VibeMap's own generators

The author_* prompts above run on your model: your agent does the thinking and VibeMap just stores the result. The gen_* prompts are the other half — they run VibeMap's hosted generation pipelines, the same ones behind the app's /gen-… slash commands. They are metered (they draw down the project owner's VibeMap token budget) and asynchronous (you get a sessionId back and poll vibemap_get_generation_status).

Prompt

Args

Description

gen_personas

projectId

Generate personas — who you're building for

gen_features

projectId

Generate features — the set every story, page and table hangs off

gen_stories

projectId

Generate user stories from your features

gen_criteria

projectId

Derive acceptance criteria from features and stories

gen_pages

projectId

Generate the page architecture from features and stories

gen_schema

projectId

Generate the database schema — tables and relationships

gen_sync_criteria_from_pages

projectId

Cross-check acceptance criteria against your page layouts

Reporting test results from CI

ci-report turns a test run into review results. Tag each test name with the acceptance criterion it proves, for example [AC-042] rejects an empty title. After the run, post the report:

VIBEMAP_CI_TOKEN=... npx @vibemap.ai/mcp-server ci-report \
  --junit junit.xml --project <project-id>

Every criterion that is in review and mentioned by the report is resolved from its own tests: passed when all of them passed, failed when any failed (the failing test names go back to the agent). Criteria that are not in review, or are unknown, are listed and left alone.

  • Formats: --junit (JUnit XML), --vitest and --playwright (each tool's JSON reporter). Pass several to combine them.

  • VIBEMAP_CI_TOKEN must be a CI-review token (Account, Developer, scope "CI review"). An agent token is refused.

  • The run URL and commit are picked up automatically on GitHub Actions; otherwise pass --run-url and --sha.

  • Exit codes: 0 reported, 1 the server rejected the report or could not be reached, 2 bad usage, 3 no tagged tests with --strict.

  • --dry-run prints the request without sending it.

Documentation

Full docs at vibemap.ai/docs/developer-docs/mcp-server/introduction

License

MIT

Available Tools

32 tools
vibemap_analyze_codebaseA

Scan a local codebase and submit it to VibeMap for AI-powered reverse engineering. The server-side generation persists FEATURES from the code digest. It does NOT persist user stories or acceptance criteria — after the features task completes (poll vibemap_get_generation_status), create those yourself with vibemap_create_user_story and vibemap_create_acceptance_criterion, using your full codebase access for accuracy. Returns a sessionId to poll.

Inputs: localPath (required), projectId (required), depth, taskTitle.

vibemap_block_criterionA

Mark a criterion as blocked. Transitions any-active-status → blocked. Use this when external dependency, ambiguity, or environmental issue prevents progress.

Inputs: reason (required), category (required), criterionId (required).

vibemap_claim_criterionA

Atomically claim an acceptance criterion for implementation. Transitions ready → in_progress. Returns 409 (race) if another agent already claimed it.

Inputs: criterionId (required).

vibemap_create_acceptance_criterionA

Create a new acceptance criterion for a user story in BDD format (Given/When/Then). Use this to flesh out what 'done' means for a story before or during implementation. You can call this multiple times to add multiple scenarios (happy path, error cases, edge cases) to the same story.

Inputs: storyId (required), whenAction (required), thenOutcome (required), givenCondition (required), +3 more.

vibemap_create_featureA

Create a new feature in a VibeMap project. Use this when reverse-engineering a codebase to register discovered capabilities.

Inputs: name (required), projectId (required), effort, category, +4 more.

vibemap_create_projectA

Create a new VibeMap project. Use this when starting from an existing codebase — create the project first, then call vibemap_analyze_codebase with the returned project ID.

Inputs: name (required), description (required).

vibemap_create_user_storyC

Create a new user story inside a VibeMap feature. Provide the user role, action, and expected outcome.

Inputs: title (required), featureId (required), description (required), soThat, +4 more.

vibemap_get_atomic_blueprintA
Read-only

Retrieve a code-shaped atomic blueprint of a VibeMap project — relationships hydrated, Kanban metadata stripped, with synthesized interactions and entity state machines. Designed for LLM coders building the application end-to-end. Prefer this over vibemap_get_project_context when generating code; the blueprint omits PM narrative and process metadata to maximise signal-per-token.

Inputs: projectId (required).

vibemap_get_code_mapA
Read-only

Fetch the project's current code map (status draft|confirmed, nodes/edges, sync anchor incl. any drift report). Use before re-submitting to preserve the user's hidden-node curation where possible.

Inputs: projectId (required).

vibemap_get_generation_statusA
Read-only

Poll the status of a VibeMap AI generation task (e.g., reverse engineering or spec generation). Use the sessionId returned by vibemap_analyze_codebase.

Inputs: sessionId (required).

vibemap_get_kanban_boardA
Read-only

Get a real-time kanban board view of a project grouped by status columns. Shows features with their stories nested underneath. Ideal for an IDE agent to understand what's planned, in progress, and done.

Inputs: projectId (required), includeCriteria.

vibemap_get_next_ready_criterionA
Read-only

Get the highest-priority acceptance criterion in ready status for the given project. Returns the criterion to work on next, or null if nothing is ready.

Inputs: projectId (required).

vibemap_get_page_sourceA
Read-only

Retrieve a VibeMap page's generated source code so you can pull it straight into a repo. Returns the page's own source_code plus the source_code of each of its sections. Use this to export a generated page into your codebase instead of copy-pasting.

Inputs: pageId (required), projectId (required).

vibemap_get_project_contextA
Read-only

Retrieve the full context of a VibeMap project including features, user stories, personas, pages, and database schema. Use this before building a feature to understand all the specs.

Inputs: projectId (required), includePages, includeSchema, includeStories, +2 more.

vibemap_list_acceptance_criteriaB
Read-only

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

Inputs: limit, offset, status, storyId, +2 more.

vibemap_list_access_rulesA
Read-only

List a VibeMap project's access-control rules: table-level rules (per persona/role, with can_select/insert/update/delete and structured op_conditions predicates like "own rows only") and page-level rules (can_view/create_content/edit/delete with predicates), plus an advisory reconciliation summary flagging page↔table drift. Use this to generate correct RLS policies and route/UI authorization — the atomic blueprint only carries page-level conditions, so call this for table-level (RLS) access control.

Inputs: projectId (required).

vibemap_list_changesetsA
Read-only

List a VibeMap project's version-control changesets (most recent first) with a per-changeset op count. Every write you make through this server is wrapped in a changeset, so use this to see the changesets your own edits produced, audit who/what changed the project, or review recent edit history. Pass includeOps=true to inline each changeset's individual operations (entity_type, op, diff).

Inputs: projectId (required), limit, includeOps.

vibemap_list_featuresA
Read-only

List features for a VibeMap project. Supports filtering by status, priority, category, and search. Returns paginated results.

Inputs: projectId (required), limit, offset, search, +3 more.

vibemap_list_kanban_eventsA
Read-only

List kanban transition events for a project, newest first. Use since to fetch only events after a timestamp (for reconnect-backfill).

Inputs: projectId (required), limit, since.

vibemap_list_projectsA
Read-only

List all VibeMap projects for the authenticated user. Returns project IDs, names, descriptions, and status.

Inputs: no named parameters.

vibemap_list_user_storiesA
Read-only

List user stories for a project or feature. Filter by status, priority. Returns paginated results with full story detail.

Inputs: limit, offset, search, status, +3 more.

vibemap_report_progressA

Append a progress event to the criterion timeline without changing its status. Used to surface intermediate work for visibility.

Inputs: summary (required), criterionId (required).

vibemap_resolve_reviewA

Resolve a criterion in review. Transitions in_review → passed | failed. NOTE: agents (env_token:agent) cannot self-resolve their own work — this tool requires a CI-scoped token (env_token:ci) or a session user.

Inputs: outcome (required), criterionId (required), notes, testRunUrl.

vibemap_scan_codebaseA
Read-only

Scan a local directory and return a formatted tree view plus file statistics. Use this to explore and understand an existing codebase before syncing to VibeMap.

Inputs: localPath (required), depth.

vibemap_submit_code_mapA

Submit a structural code map of the user's codebase to VibeMap (rendered on the project's Codebase tab). Build it yourself from your codebase access: one node per meaningful unit (page/route, API endpoint, data model, service, module, config), edges for imports/routes/reads/writes. 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 project's map and resets it to draft for the user to re-confirm.

Inputs: map (required), projectId (required), anchor.

vibemap_submit_for_reviewA

Submit completed work for review. Transitions in_progress → in_review. Requires a git SHA and a diff URL as evidence.

Inputs: gitSha (required), diffUrl (required), criterionId (required), notes.

vibemap_sync_changesA

Report codebase changes since the last sync so VibeMap can flag spec drift. Workflow: 1) call vibemap_get_code_map and read anchor.commitSha; 2) run git diff --name-only <commitSha>..HEAD (plus untracked files from git status --porcelain); 3) call this tool with the changed paths and your current HEAD sha. The response lists affected map units and features — update the stale specs with vibemap_update_feature / vibemap_update_user_story / vibemap_update_acceptance_criterion (all changeset-audited), then re-submit the code map with vibemap_submit_code_map to clear the drift.

Inputs: projectId (required), changedFiles (required), headSha.

vibemap_unblock_criterionB

Unblock a criterion. Transitions blocked → prior_status (recorded when block was set; defaults to ready).

Inputs: resolution (required), criterionId (required).

vibemap_update_acceptance_criterionB
Idempotent

Update an acceptance criterion's status or content. Use status 'passed' when your code satisfies the criterion, 'failed' when it does not.

Inputs: criterionId (required), status, whenAction, description, +3 more.

vibemap_update_featureB
Idempotent

Update an existing feature's fields or status in VibeMap.

Inputs: featureId (required), name, effort, status, +5 more.

vibemap_update_kanban_statusA
Idempotent

[DEPRECATED — use the typed transition tools (claim, report_progress, submit_for_review, resolve_review, block, unblock) instead. This tool will be removed in a future release.] Atomically advance or update the kanban status of a feature, user story, or acceptance criterion. Validates allowed state transitions and prevents invalid moves. Call this when you start or finish implementing something.

Feature stages: draft → open → in_progress → completed Story stages: draft → has_criteria → open → in_progress → completed Criterion stages: draft → pending → passed | failed

Inputs: entityId (required), newStatus (required), entityType (required), notes.

vibemap_update_user_storyC
Idempotent

Update an existing user story's fields or status in VibeMap.

Inputs: storyId (required), title, soThat, status, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 32 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, organized by resource type and action. However, the deprecated 'vibemap_update_kanban_status' overlaps with the newer transition tools, and 'vibemap_get_project_context' vs 'vibemap_get_atomic_blueprint' could be confused without careful reading.

    Naming Consistency5/5

    All tools follow a consistent 'vibemap_verb_noun' pattern (e.g., list_projects, create_feature, get_atomic_blueprint). No mixing of conventions or unpredictable names.

    Tool Count4/5

    32 tools is higher than the typical 3-15, but each tool serves a distinct purpose in the comprehensive project management and reverse engineering workflow. The count is justified, though it may feel heavy for simpler use cases.

    Completeness4/5

    The tool set covers CRUD for core entities (features, stories, criteria), kanban workflow, code analysis, and drift detection. However, missing deletion tools for projects, features, and stories, which is a minor gap.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Connects ChatGPT to a local developer workspace through MCP, enabling bounded repository analysis, file and image inspection, direct edits, command verification, and Git-aware review.
      22
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects MCP-compatible AI clients and agents to one durable Project Brain plus controlled access to authorized project folders on your own machine. Enables file editing, terminal and Git operations, project intelligence, browser automation, and local MCP server federation, all scoped to explicit workspace grants.
      55 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects ChatGPT and MCP clients to authorized local development environments, enabling secure file access, shell execution, persistent tasks, browser/desktop control, and remote management of projects.
      19
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects ChatGPT Web to a local development environment, enabling file reads and patches, shell execution, plan updates, and isolated worktree coordination through permissioned MCP tools.
      13
      MIT