io.github.AshMet/vibemap-mcp

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.

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

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

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.

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

Create a page/screen in a VibeMap project's page inventory. Author pages after features, stories, and criteria to capture the app's screens and routes. Existing pages are visible via vibemap_get_project_context — enrich, don't duplicate.

Create a user persona in a VibeMap project. Personas are the cast of users the spec is written for — author them FIRST, then reference each persona's role (userRole) when writing user stories. Match the depth VibeMap's own generator produces: fill the structured blocks so the persona is rich and semantically searchable, not just a name. Existing personas are visible via vibemap_get_project_context — enrich, don't duplicate. All params are camelCase.

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.

Persist a VibeMap project's database schema — tables, columns, and relationships — in one call. Author this LAST, after the rest of the spec exists, grounded on the spec (idea-first) or the codebase's models/migrations (code-first). One table per domain entity; give every table an `id` primary key and created_at/updated_at; set real Postgres column types + constraints; express foreign keys via each column's `foreignKey` (relationships auto-derive from these, so `relationships` is optional); add junction tables for many-to-many. All params are camelCase (this IS VibeMap's SchemaJSON). Existing schema is visible via vibemap_get_project_context (dbSchema) — the server keyed-reconciles, so re-running is safe. Table/page access rules are handled by the separate access-rules flow, not here.

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

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.

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.

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

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.

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.

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.

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.

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

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.

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

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

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

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

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

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

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.

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.

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.

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

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.

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

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

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

[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

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