# io.github.AshMet/vibemap-mcp (npm · @vibemap.ai/mcp-server)

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

- Trust score: 64/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@vibemap.ai/mcp-server`: 64/100 (this document), [markdown](https://verifymcp.io/servers/ashmet-vibemap-mcp/vibemap-ai-mcp-server.md), [page](https://verifymcp.io/servers/ashmet-vibemap-mcp/vibemap-ai-mcp-server)

## Channel facts

- Registry: `npm`
- Package: `@vibemap.ai/mcp-server`
- Version: `2.8.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (100 of 104), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (100 of 104), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 3 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 80/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 3820 tokens (~109/item across 35 items; 35 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 81/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 43% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### Claude

```bash
claude mcp add ashmet-vibemap-mcp -- npx -y @vibemap.ai/mcp-server
```

### Codex

```bash
codex mcp add ashmet-vibemap-mcp -- npx -y @vibemap.ai/mcp-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ashmet-vibemap-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@vibemap.ai/mcp-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add ashmet-vibemap-mcp --command npx --arg -y --arg @vibemap.ai/mcp-server
```

### Hermes

```yaml
mcp_servers:
  ashmet-vibemap-mcp:
    command: "npx"
    args: ["-y", "@vibemap.ai/mcp-server"]
```

### Other

```json
{
  "mcpServers": {
    "ashmet-vibemap-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@vibemap.ai/mcp-server"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 64, +32)

- [security improvement] Malware scan: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Schema quality: unverified → good

### 2026-08-01 (score 32, +3)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Capabilities: pass → unverified
- [functional improvement] License: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional] Licence: MIT

### 2026-07-31 (score 29, +23)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 6)

First indexed and scored.

## MCP tools (35)

### `vibemap_list_projects` (~32 tokens)

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

### `vibemap_create_project` (~85 tokens)

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.

Input parameters:

- `description` (string, required): Detailed project description (50+ characters). The more detail, the better the AI analysis.
- `name` (string, required): Project name (3-100 characters)

### `vibemap_get_project_context` (~102 tokens)

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.

Input parameters:

- `includeFeatures` (boolean)
- `includePages` (boolean)
- `includePersonas` (boolean)
- `includeSchema` (boolean)
- `includeStories` (boolean)
- `projectId` (string, required): The VibeMap project ID

### `vibemap_get_atomic_blueprint` (~95 tokens)

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.

Input parameters:

- `projectId` (string, required): The VibeMap project ID

### `vibemap_list_access_rules` (~124 tokens)

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.

Input parameters:

- `projectId` (string, required): The VibeMap project ID

### `vibemap_list_changesets` (~151 tokens)

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

Input parameters:

- `includeOps` (boolean): Inline each changeset's individual ops + diffs (default false)
- `limit` (number): Max changesets to return (1-200, default 50)
- `projectId` (string, required): The VibeMap project ID

### `vibemap_get_page_source` (~92 tokens)

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.

Input parameters:

- `pageId` (string, required): The page ID to export
- `projectId` (string, required): The VibeMap project ID

### `vibemap_create_persona` (~261 tokens)

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.

Input parameters:

- `avatarDescription` (string): Brief visual description
- `communicationPreferences` (object): How to reach them
- `demographics` (object): Who they are
- `goalsAndNeeds` (object): What they are trying to achieve
- `name` (string, required): Persona's first name
- `narrative` (object): Their voice
- `painPoints` (object): What frustrates or blocks them
- `productSpecific` (object): How they relate to this product
- `projectId` (string, required)
- `psychographics` (object): What drives them
- `tagline` (string): Brief one-line descriptor
- `userRole` (string): Canonical role this persona represents (e.g. 'admin', 'diver'). User stories reference this role.

### `vibemap_create_page` (~115 tokens)

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.

Input parameters:

- `description` (string): What this page is for
- `name` (string, required): Page name (e.g. 'Dashboard')
- `path` (string): Route path (e.g. '/dashboard')
- `projectId` (string, required)
- `status` (string)

### `vibemap_create_schema` (~240 tokens)

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.

Input parameters:

- `projectId` (string, required)
- `relationships` (array): Optional — foreign keys on columns auto-derive relationships. Provide only for relationships not expressed by a column FK.
- `tables` (array, required): One entry per table (snake_case, plural names).

### `vibemap_list_features` (~86 tokens)

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

Input parameters:

- `category` (string)
- `limit` (number)
- `offset` (number)
- `priority` (string)
- `projectId` (string, required)
- `search` (string)
- `status` (string)

### `vibemap_create_feature` (~93 tokens)

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

Input parameters:

- `business_value` (string)
- `category` (string)
- `complexity` (string)
- `description` (string)
- `effort` (string)
- `name` (string, required)
- `priority` (string)
- `projectId` (string, required)

### `vibemap_update_feature` (~88 tokens)

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

Input parameters:

- `business_value` (string)
- `category` (string)
- `complexity` (string)
- `description` (string)
- `effort` (string)
- `featureId` (string, required)
- `name` (string)
- `priority` (string)
- `status` (string)

### `vibemap_list_user_stories` (~102 tokens)

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

Input parameters:

- `featureId` (string): Filter by specific feature
- `limit` (number)
- `offset` (number)
- `priority` (string)
- `projectId` (string): Filter by project (use featureId for more specific results)
- `search` (string)
- `status` (string)

### `vibemap_create_user_story` (~118 tokens)

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

Input parameters:

- `description` (string, required)
- `estimatedEffort` (number)
- `featureId` (string, required)
- `iWantTo` (string): What the user wants to do
- `priority` (string)
- `soThat` (string): The benefit / outcome
- `title` (string, required)
- `userRole` (string): e.g., 'admin', 'developer', 'guest'

### `vibemap_update_user_story` (~95 tokens)

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

Input parameters:

- `description` (string)
- `estimatedEffort` (number)
- `iWantTo` (string)
- `priority` (string)
- `soThat` (string)
- `status` (string)
- `storyId` (string, required)
- `title` (string)
- `userRole` (string)

### `vibemap_list_acceptance_criteria` (~86 tokens)

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

Input parameters:

- `featureId` (string)
- `limit` (number)
- `offset` (number)
- `projectId` (string)
- `status` (string)
- `storyId` (string)

### `vibemap_create_acceptance_criterion` (~160 tokens)

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.

Input parameters:

- `description` (string): Optional plain-text summary
- `givenCondition` (string, required): Precondition / context ('Given …')
- `scenarioCategory` (string)
- `status` (string)
- `storyId` (string, required): ID of the user story this criterion belongs to
- `thenOutcome` (string, required): Expected result ('Then …')
- `whenAction` (string, required): Action performed ('When …')

### `vibemap_update_acceptance_criterion` (~96 tokens)

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

Input parameters:

- `criterionId` (string, required)
- `description` (string)
- `givenCondition` (string)
- `scenarioCategory` (string)
- `status` (string)
- `thenOutcome` (string)
- `whenAction` (string)

### `vibemap_update_kanban_status` (~187 tokens)

[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

Input parameters:

- `entityId` (string, required): ID of the feature, story, or criterion
- `entityType` (string, required): Type of item to update
- `newStatus` (string, required): Target kanban status
- `notes` (string): Optional context about why this transition was made

### `vibemap_get_kanban_board` (~75 tokens)

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.

Input parameters:

- `includeCriteria` (boolean): Include acceptance criteria counts per story
- `projectId` (string, required)

### `vibemap_get_next_ready_criterion` (~55 tokens)

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.

Input parameters:

- `projectId` (string, required): Project UUID

### `vibemap_claim_criterion` (~51 tokens)

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

Input parameters:

- `criterionId` (string, required): Acceptance criterion UUID

### `vibemap_report_progress` (~55 tokens)

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

Input parameters:

- `criterionId` (string, required)
- `summary` (string, required): Short progress note (1-2000 chars)

### `vibemap_submit_for_review` (~95 tokens)

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

Input parameters:

- `criterionId` (string, required)
- `diffUrl` (string, required): URL to view the diff (PR link or compare URL)
- `gitSha` (string, required): 7+ char commit SHA
- `notes` (string): Optional notes for the reviewer (max 2000 chars)

### `vibemap_resolve_review` (~93 tokens)

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.

Input parameters:

- `criterionId` (string, required)
- `notes` (string)
- `outcome` (string, required)
- `testRunUrl` (string)

### `vibemap_block_criterion` (~70 tokens)

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

Input parameters:

- `category` (string, required)
- `criterionId` (string, required)
- `reason` (string, required): Human-readable explanation (1-2000 chars)

### `vibemap_unblock_criterion` (~61 tokens)

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

Input parameters:

- `criterionId` (string, required)
- `resolution` (string, required): How the blocker was resolved (1-2000 chars)

### `vibemap_list_kanban_events` (~87 tokens)

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

Input parameters:

- `limit` (number): Max events to return (default 200, max 1000)
- `projectId` (string, required)
- `since` (string): ISO timestamp; only events strictly after this are returned

### `vibemap_scan_codebase` (~69 tokens)

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.

Input parameters:

- `depth` (number): Max directory depth to traverse
- `localPath` (string, required): Absolute path to the local project directory

### `vibemap_analyze_codebase` (~146 tokens)

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.

Input parameters:

- `depth` (number)
- `localPath` (string, required): Absolute path to the local project directory
- `projectId` (string, required): The VibeMap project to populate with discovered specs
- `taskTitle` (string)

### `vibemap_submit_code_map` (~234 tokens)

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.

Input parameters:

- `anchor` (object): Optional sync anchor: { commitSha?, scannedAt? } (git rev-parse HEAD)
- `map` (object, required): { nodes: [{id,label,kind,path,layer,summary?}], edges: [{source,target,kind}], stats?: {totalFiles,scannedAt} }
- `projectId` (string, required): VibeMap project to attach the map to

### `vibemap_get_code_map` (~59 tokens)

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.

Input parameters:

- `projectId` (string, required)

### `vibemap_sync_changes` (~200 tokens)

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.

Input parameters:

- `changedFiles` (array, required): Repo-relative paths changed since anchor.commitSha (max 2000)
- `headSha` (string): Current HEAD commit sha (git rev-parse HEAD)
- `projectId` (string, required): VibeMap project id

### `vibemap_get_generation_status` (~62 tokens)

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

Input parameters:

- `sessionId` (string, required): Session ID from vibemap_analyze_codebase

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/ashmet-vibemap-mcp/vibemap-ai-mcp-server#diagnostics

## Score history

- 2026-08-03: 64
- 2026-08-02: 64
- 2026-08-01: 32
- 2026-07-31: 29
- 2026-07-30: 6

## Links

- npm package: https://www.npmjs.com/package/@vibemap.ai/mcp-server
- Socket report: https://socket.dev/npm/package/@vibemap.ai/mcp-server
- Repository: https://github.com/AshMet/vibemap-mcp
- Changelog RSS feed: https://verifymcp.io/servers/ashmet-vibemap-mcp/vibemap-ai-mcp-server/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/ashmet-vibemap-mcp/vibemap-ai-mcp-server/changelog.json
- HTML version of this page: https://verifymcp.io/servers/ashmet-vibemap-mcp/vibemap-ai-mcp-server