Vibemap Mcp

io.github.AshMetPublished by GitHub account AshMetv2.8.1Updated Oct 26, 2026

Load & create VibeMap product specs from your coding agent; sync build progress.

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

VibeMap MCP server that loads product specs into a coding agent and syncs build progress back to VibeMap's kanban.

What you can do
  • List, create and load projects, project context, blueprints, access rules and page source
  • Author personas, pages, database schemas, features, user stories and BDD acceptance criteria
  • Work the kanban lifecycle: claim criteria, report progress, submit for review, rework, block, ask the owner questions and propose spec changes
  • Track version control: changesets, spec deltas, release work lists and diffs, and sync changed paths
  • Scan and analyze a local codebase, extract repo facts, import them, submit or fetch a code map, and resolve drift
  • Drive VibeMap's hosted conversational agent and poll generation status; prompts expose guided workflows such as new_project, author_*, gen_* and build_sprint
When to use it
Use it when you build software from a VibeMap spec and want the IDE agent to read the spec, claim work and report progress, or when you want to reverse-engineer an existing codebase into VibeMap features, stories and criteria.
Requirements
Runs locally over stdio via npx, so Node.js 18 or newer is needed. A VibeMap account and an API key in VIBEMAP_API_KEY are required; VIBEMAP_BASE_URL optionally points at another instance. The CI reporting command needs VIBEMAP_CI_TOKEN, a CI-review scoped token.
Before you install
The API key in VIBEMAP_API_KEY is a personal access token and should be kept out of shared configs. Many tools write to your VibeMap project: creating and updating specs, claiming and resolving criteria, importing codebase facts, and resolving drift. The hosted agent and gen_* prompts are metered and draw down the owner's VibeMap token budget. Destructive agent turns return a plan and operationId that must be approved separately. Codebase extraction is described as local, but structural facts…

Installation

In SourceWeft

  1. Open Vibemap Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@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

json
{  "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.

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)

json
{  "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:

json
{  "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

VariableDescriptionDefault
VIBEMAP_API_KEYYour Personal Access Token (vm_...)Required
VIBEMAP_BASE_URLVibeMap instance URLhttp://localhost:3000

Tools

The server exposes 55 tools via the vibemap_ prefix.

Projects & context

ToolDescription
vibemap_list_projectsList all your projects
vibemap_create_projectCreate a new project (use before analyze_codebase)
vibemap_get_project_contextLoad full project specs into agent context
vibemap_get_atomic_blueprintGet 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_rulesList table- and page-level access rules (with op_conditions) for RLS + auth
vibemap_get_page_sourceRetrieve a page and its section source code

Personas & pages (spec authoring)

ToolDescription
vibemap_create_personaCreate a rich user persona (demographics, goals, pain points, …)
vibemap_create_pageCreate a page/screen in the project's page inventory
vibemap_create_schemaPersist the database schema (tables → columns → relationships) in one call

Conversational agent (hosted, metered)

ToolDescription
vibemap_agentDrive 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

ToolDescription
vibemap_list_featuresList features with filtering
vibemap_create_featureCreate a new feature
vibemap_update_featureUpdate feature fields or status (validates transitions). For spec authoring only: while building, use vibemap_propose_spec_change

User stories

ToolDescription
vibemap_list_user_storiesList stories by project or feature
vibemap_create_user_storyCreate a user story
vibemap_update_user_storyUpdate story fields or status (validates transitions). For spec authoring only: while building, use vibemap_propose_spec_change

Acceptance criteria

ToolDescription
vibemap_list_acceptance_criteriaFetch BDD criteria
vibemap_create_acceptance_criterionCreate a BDD acceptance criterion
vibemap_update_acceptance_criterionUpdate 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

ToolDescription
vibemap_get_kanban_boardGet a real-time board view
vibemap_get_execution_planThe build order: criteria grouped by sprint in dependency order, with state
vibemap_get_next_ready_criterionGet the next criterion to work on, its story bundle, and a reason when nothing is claimable
vibemap_claim_storyClaim every claimable criterion of a story at once; returns a context pack for each
vibemap_claim_criterionClaim a criterion (ready → in_progress)
vibemap_get_criterion_contextEverything needed to build one criterion in a few thousand tokens (use instead of the whole blueprint)
vibemap_report_progressHeartbeat with the current phase, plus optional plan, files and test counts
vibemap_submit_for_reviewSubmit a criterion for review with the changed files and the named tests that prove it (→ in_review)
vibemap_get_criterion_evidenceSubmission history of a criterion: files, tests and verdict per attempt
vibemap_rework_criterionSend a criterion that failed review back to ready to build it again
vibemap_resolve_reviewResolve a review (passed / failed); needs a CI-review token or a signed-in user
vibemap_block_criterionBlock a criterion with a category and reason
vibemap_ask_userAsk the project owner a question when the spec is unclear (blocks the criterion until answered)
vibemap_get_answersCollect the answers to your questions
vibemap_unblock_criterionUnblock a criterion with a resolution
vibemap_propose_spec_changePropose a spec change for the owner to review when the code must differ; never edits the spec
vibemap_list_kanban_eventsKanban transition history (for incremental sync)
vibemap_update_kanban_status⚠️ Deprecated — use the lifecycle tools above

Version control

ToolDescription
vibemap_list_changesetsList changesets (your writes + history) with op counts; includeOps for diffs, sinceSeq as a cursor
vibemap_get_spec_deltaWhat changed in the spec since a sequence number, and which criteria that affects
vibemap_get_release_work_listA release's work grouped as new, modified and removed (with the code paths to delete)
vibemap_get_release_diffA release's raw diff against its baseline
vibemap_sync_changesReport changed paths since the last sync so VibeMap can flag spec drift

Codebase

ToolDescription
vibemap_scan_codebaseWalk a local directory
vibemap_analyze_codebaseReverse-engineer a codebase into VibeMap assets
vibemap_submit_code_mapSubmit a structural code map (nodes/edges) rendered on the project's Codebase tab
vibemap_get_code_mapFetch the project's current code map (status, nodes/edges, sync anchor + drift)
vibemap_get_generation_statusPoll 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.

ToolDescription
vibemap_extract_repo_factsRead the repository's tables, policies, routes and file clusters locally; sends nothing
vibemap_import_factsSend the facts: VibeMap creates the schema, access rules and a page per route, each linked to its file
vibemap_import_semanticSend the features, stories and criteria your agent wrote, each citing its source files
vibemap_finalize_importPass the imported criteria (unverified), lock MVP1 and open MVP2
vibemap_resyncApply the structural changes at your current commit and flag the specs the changed files touch
vibemap_resolve_driftClear handled files, map units or criteria from the drift report
vibemap_resolve_code_drift_proposalApply 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.

PromptArgsDescription
new_project—Guided interview that creates a new VibeMap project. Start here
author_specprojectId, localPath?Author the full spec graph from your local codebase (bring-your-own-agent, code-first)
author_ideaprojectIdAuthor the full spec graph from the project idea (bring-your-own-agent, idea-first)
author_personasprojectIdStage 1 of 5 — author just the personas
author_featuresprojectIdStage 2 of 5 — author just the features
author_storiesprojectIdStage 3 of 5 — author just the user stories
author_criteriaprojectIdStage 4 of 5 — author just the acceptance criteria
author_pagesprojectIdStage 5 of 5 — author just the pages
author_schemaprojectId, localPath?Author the database schema — tables, columns, relationships
sync_changesprojectId, localPath?Detect and reconcile spec drift since the last sync
code_mapprojectId, localPath?Build and submit a structural code map
load_contextprojectIdLoad the project's spec context into your agent
kanbanprojectIdShow the project's kanban board
importprojectId, localPath?Import an existing codebase as a locked MVP1: extract locally, import the facts, write the spec per cluster, finalize
resyncprojectId, localPath?Bring an imported project up to date and stage drift proposals for review
build_sprintprojectIdBuild the ready work test first while the board follows live; CI verifies, the agent never marks anything done
release_nextprojectIdBuild 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).

PromptArgsDescription
gen_personasprojectIdGenerate personas — who you're building for
gen_featuresprojectIdGenerate features — the set every story, page and table hangs off
gen_storiesprojectIdGenerate user stories from your features
gen_criteriaprojectIdDerive acceptance criteria from features and stories
gen_pagesprojectIdGenerate the page architecture from features and stories
gen_schemaprojectIdGenerate the database schema — tables and relationships
gen_sync_criteria_from_pagesprojectIdCross-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:

bash
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

Source: README.md at commit ca84444

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v2.8.1LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.