{
  "markdown": "# @vibemap.ai/mcp-server\n\nConnect your IDE agent to [VibeMap](https://vibemap.ai) via the [Model Context Protocol](https://modelcontextprotocol.io). Load project specs into any MCP-compatible AI coding agent, or reverse-engineer an existing codebase back into structured VibeMap assets.\n\n## Quick Start\n\n```json\n{\n  \"mcpServers\": {\n    \"vibemap\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vibemap.ai/mcp-server\"],\n      \"env\": {\n        \"VIBEMAP_API_KEY\": \"vm_your_token_here\",\n        \"VIBEMAP_BASE_URL\": \"https://vibemap.ai\"\n      }\n    }\n  }\n}\n```\n\nGenerate your API key at [vibemap.ai → Account → Developer → API Keys](https://vibemap.ai/account).\n\n## What It Does\n\n**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.\n\n**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.\n\n## Requirements\n\n- Node.js ≥ 18\n- A [VibeMap](https://vibemap.ai) account\n\n## IDE Setup\n\n### Claude Desktop\n\nConfig file: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows)\n\n```json\n{\n  \"mcpServers\": {\n    \"vibemap\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@vibemap.ai/mcp-server\"],\n      \"env\": {\n        \"VIBEMAP_API_KEY\": \"vm_your_token_here\",\n        \"VIBEMAP_BASE_URL\": \"https://vibemap.ai\"\n      }\n    }\n  }\n}\n```\n\nFully restart Claude Desktop after saving. Confirm the 🔨 hammer icon appears in the chat input.\n\n### Cursor\n\nOpen **Settings → MCP** and add:\n\n```json\n{\n  \"vibemap\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"@vibemap.ai/mcp-server\"],\n    \"env\": {\n      \"VIBEMAP_API_KEY\": \"vm_your_token_here\",\n      \"VIBEMAP_BASE_URL\": \"https://vibemap.ai\"\n    }\n  }\n}\n```\n\n### Windsurf\n\nSame format as Cursor. Add to your Windsurf MCP settings file and restart.\n\n## Environment Variables\n\n| Variable | Description | Default |\n|---|---|---|\n| `VIBEMAP_API_KEY` | Your Personal Access Token (`vm_...`) | **Required** |\n| `VIBEMAP_BASE_URL` | VibeMap instance URL | `http://localhost:3000` |\n\n## Tools\n\nThe server exposes **36 tools** via the `vibemap_` prefix.\n\n**Projects & context**\n\n| Tool | Description |\n|---|---|\n| `vibemap_list_projects` | List all your projects |\n| `vibemap_create_project` | Create a new project (use before `analyze_codebase`) |\n| `vibemap_get_project_context` | Load full project specs into agent context |\n| `vibemap_get_atomic_blueprint` | Get the code-shaped atomic blueprint for LLM generation |\n| `vibemap_list_access_rules` | List table- and page-level access rules (with `op_conditions`) for RLS + auth |\n| `vibemap_get_page_source` | Retrieve a page and its section source code |\n\n**Personas & pages (spec authoring)**\n\n| Tool | Description |\n|---|---|\n| `vibemap_create_persona` | Create a rich user persona (demographics, goals, pain points, …) |\n| `vibemap_create_page` | Create a page/screen in the project's page inventory |\n| `vibemap_create_schema` | Persist the database schema (tables → columns → relationships) in one call |\n\n**Conversational agent (Engine B — hosted, metered)**\n\n| Tool | Description |\n|---|---|\n| `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`) |\n\n**Features**\n\n| Tool | Description |\n|---|---|\n| `vibemap_list_features` | List features with filtering |\n| `vibemap_create_feature` | Create a new feature |\n| `vibemap_update_feature` | Update feature fields or status (validates transitions) |\n\n**User stories**\n\n| Tool | Description |\n|---|---|\n| `vibemap_list_user_stories` | List stories by project or feature |\n| `vibemap_create_user_story` | Create a user story |\n| `vibemap_update_user_story` | Update story fields or status (validates transitions) |\n\n**Acceptance criteria**\n\n| Tool | Description |\n|---|---|\n| `vibemap_list_acceptance_criteria` | Fetch BDD criteria |\n| `vibemap_create_acceptance_criterion` | Create a BDD acceptance criterion |\n| `vibemap_update_acceptance_criterion` | Update or mark criteria passed/failed (validates transitions) |\n\n**Kanban — board & agentic lifecycle**\n\n| Tool | Description |\n|---|---|\n| `vibemap_get_kanban_board` | Get a real-time board view |\n| `vibemap_get_next_ready_criterion` | Get the highest-priority criterion ready to work on |\n| `vibemap_claim_criterion` | Claim a criterion (`ready` → `in_progress`) |\n| `vibemap_report_progress` | Append a progress event to a criterion |\n| `vibemap_submit_for_review` | Submit a criterion for review (→ `review_pending`) |\n| `vibemap_resolve_review` | Resolve a review (`passed` / `failed`) |\n| `vibemap_block_criterion` | Block a criterion with a category and reason |\n| `vibemap_unblock_criterion` | Unblock a criterion with a resolution |\n| `vibemap_list_kanban_events` | Kanban transition history (for incremental sync) |\n| `vibemap_update_kanban_status` | ⚠️ Deprecated — use the lifecycle tools above |\n\n**Version control**\n\n| Tool | Description |\n|---|---|\n| `vibemap_list_changesets` | List changesets (your writes + history) with op counts; `includeOps` for diffs |\n| `vibemap_sync_changes` | Report changed paths since the last sync so VibeMap can flag spec drift |\n\n**Codebase**\n\n| Tool | Description |\n|---|---|\n| `vibemap_scan_codebase` | Walk a local directory |\n| `vibemap_analyze_codebase` | Reverse-engineer a codebase into VibeMap assets |\n| `vibemap_submit_code_map` | Submit a structural code map (nodes/edges) rendered on the project's Codebase tab |\n| `vibemap_get_code_map` | Fetch the project's current code map (status, nodes/edges, sync anchor + drift) |\n| `vibemap_get_generation_status` | Poll AI generation task status |\n\n## Prompts (slash commands)\n\nThe 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`.\n\n| Prompt | Args | Description |\n|---|---|---|\n| `new_project` | — | Guided interview that creates a new VibeMap project. Start here |\n| `author_spec` | `projectId`, `localPath?` | Author the full spec graph from your local codebase (bring-your-own-agent, code-first) |\n| `author_idea` | `projectId` | Author the full spec graph from the project idea (bring-your-own-agent, idea-first) |\n| `author_personas` | `projectId` | Stage 1 of 5 — author just the personas |\n| `author_features` | `projectId` | Stage 2 of 5 — author just the features |\n| `author_stories` | `projectId` | Stage 3 of 5 — author just the user stories |\n| `author_criteria` | `projectId` | Stage 4 of 5 — author just the acceptance criteria |\n| `author_pages` | `projectId` | Stage 5 of 5 — author just the pages |\n| `author_schema` | `projectId`, `localPath?` | Author the database schema — tables, columns, relationships |\n| `sync_changes` | `projectId`, `localPath?` | Detect and reconcile spec drift since the last sync |\n| `code_map` | `projectId`, `localPath?` | Build and submit a structural code map |\n| `load_context` | `projectId` | Load the project's spec context into your agent |\n| `kanban` | `projectId` | Show the project's kanban board |\n\n### `gen_*` — run VibeMap's own generators\n\nThe `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`).\n\n| Prompt | Args | Description |\n|---|---|---|\n| `gen_personas` | `projectId` | Generate personas — who you're building for |\n| `gen_features` | `projectId` | Generate features — the set every story, page and table hangs off |\n| `gen_stories` | `projectId` | Generate user stories from your features |\n| `gen_criteria` | `projectId` | Derive acceptance criteria from features and stories |\n| `gen_pages` | `projectId` | Generate the page architecture from features and stories |\n| `gen_schema` | `projectId` | Generate the database schema — tables and relationships |\n| `gen_sync_criteria_from_pages` | `projectId` | Cross-check acceptance criteria against your page layouts |\n\n## Documentation\n\nFull docs at [vibemap.ai/docs/developer-docs/mcp-server/introduction](https://vibemap.ai/docs/developer-docs/mcp-server/introduction)\n\n## License\n\nMIT\n",
  "bytes": 9061,
  "sha": "bf58deef7196a76205ef929d3dee26bf770eca07d0d78944590789b00ea0af53",
  "repo_slug": "ashmet/vibemap-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ashmet_vibemap_mcp_f9f66134/readme"
}