vibemap-mcp

@vibemap.ai/mcp-server

通过 Model Context Protocol，将 IDE Agent 连接到 VibeMap。将项目规范加载到任何兼容 MCP 的 AI 编码 Agent 中，或将现有代码库反向工程为结构化的 VibeMap 资源。

快速开始

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

前往 vibemap.ai → Account → Developer → API Keys 生成 API 密钥。

功能说明

导出（VibeMap → IDE）： 将完整的项目上下文——功能、用户故事、验收标准、角色、页面和数据库架构——加载到 IDE Agent 中。Agent 按照规范构建，并在工作过程中实时更新 VibeMap 看板。

导入（IDE → VibeMap）： 将服务指向现有代码库，VibeMap 的 AI 会对其进行反向工程，生成一组结构化的功能、用户故事和验收标准。

要求

• Node.js ≥ 18
• 一个 VibeMap 账户

IDE 设置

Claude Desktop

配置文件：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %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"
      }
    }
  }
}

保存后，完全退出并重启 Claude Desktop。确认消息框中出现 🔨 锤子图标。

Cursor

打开 Settings → MCP 并添加：

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

Windsurf

格式与 Cursor 相同。将其添加到 Windsurf MCP 设置文件并重启。

环境变量

变量	说明	默认值
VIBEMAP_API_KEY	你的个人访问令牌（vm_...）	必填
VIBEMAP_BASE_URL	VibeMap 实例 URL	http://localhost:3000

工具

该服务通过 vibemap_ 前缀提供 55 个工具。

项目与上下文

工具	说明
vibemap_list_projects	列出你的所有项目
vibemap_create_project	创建新项目（在使用 analyze_codebase 前调用）
vibemap_get_project_context	将完整项目规范加载到 Agent 上下文中
vibemap_get_atomic_blueprint	获取整个项目的代码形态蓝图（内容较多；用于脚手架和审计，不适用于构建单个任务：此时请使用 vibemap_get_criterion_context）
vibemap_list_access_rules	列出表级和页面级访问规则（包含 op_conditions），用于 RLS + 身份验证
vibemap_get_page_source	获取页面及其各部分的源代码

角色与页面（规范编写）

工具	说明
vibemap_create_persona	创建详细的用户角色（人口统计信息、目标、痛点等）
vibemap_create_page	在项目的页面清单中创建页面或屏幕
vibemap_create_schema	一次调用即可保存数据库架构（表 → 列 → 关系）

对话式 Agent（托管、计量）

工具	说明
vibemap_agent	驱动 VibeMap 的完整对话式 Agent 完成一轮交互（与应用内聊天使用相同的核心逻辑）。按量计费——使用 VibeMap 令牌。破坏性操作会返回计划和 operationId，需在第二次调用中批准；耗时较长的生成任务会在后台运行（轮询 get_generation_status）

功能

工具	说明
vibemap_list_features	按筛选条件列出功能
vibemap_create_feature	创建新功能
vibemap_update_feature	更新功能字段或状态（会验证状态转换）。仅用于编写规范：构建过程中请使用 vibemap_propose_spec_change

用户故事

工具	说明
vibemap_list_user_stories	按项目或功能列出用户故事
vibemap_create_user_story	创建用户故事
vibemap_update_user_story	更新用户故事字段或状态（会验证状态转换）。仅用于编写规范：构建过程中请使用 vibemap_propose_spec_change

验收标准

工具	描述
vibemap_list_acceptance_criteria	获取 BDD 验收标准
vibemap_create_acceptance_criterion	创建 BDD 验收标准
vibemap_update_acceptance_criterion	更新标准内容（Given/When/Then、描述）。此处不能写入状态：请使用下方的生命周期工具。仅用于编写规格：构建期间请使用 vibemap_propose_spec_change

看板 — 看板与 Agent 生命周期

工具	描述
vibemap_get_kanban_board	获取实时看板视图
vibemap_get_execution_plan	构建顺序：按依赖顺序分组到冲刺中的标准及其状态
vibemap_get_next_ready_criterion	获取下一个待处理标准、其故事包，以及没有可领取项时的 reason
vibemap_claim_story	一次性领取某个故事的所有可领取标准；为每项返回上下文包
vibemap_claim_criterion	领取一个标准（ready → in_progress）
vibemap_get_criterion_context	构建一个标准所需的全部信息，约几千个 token（请使用此工具，而非整个蓝图）
vibemap_report_progress	使用当前 phase 发送心跳，并可附带计划、文件和测试数量
vibemap_submit_for_review	提交标准以供审查，并提供已更改的文件和用于验证的测试名称（→ in_review）
vibemap_get_criterion_evidence	标准的提交历史：每次尝试的文件、测试和判定结果
vibemap_rework_criterion	将审查未通过的标准退回 ready，以便重新构建
vibemap_resolve_review	处理审查（passed / failed）；需要 CI 审查令牌或已登录用户
vibemap_block_criterion	使用类别和原因阻塞一个标准
vibemap_ask_user	规格不明确时向项目所有者提问（在获得答复前会阻塞该标准）
vibemap_get_answers	收集问题的答复
vibemap_unblock_criterion	提供解决方案并解除标准阻塞
vibemap_propose_spec_change	代码必须有所不同步时，提议规格变更供所有者审查；绝不会编辑规格
vibemap_list_kanban_events	看板状态转换历史（用于增量同步）
vibemap_update_kanban_status	⚠️ 已弃用 — 请使用上述生命周期工具

版本控制

工具	描述
vibemap_list_changesets	列出变更集（你的写入操作和历史记录）及操作数量；使用 includeOps 获取差异，使用 sinceSeq 作为游标
vibemap_get_spec_delta	查看规格自某个序列号以来的变更，以及受影响的标准
vibemap_get_release_work_list	按新增、修改和移除分组列出某个版本的工作（附带要删除的代码路径）
vibemap_get_release_diff	查看某个版本相对于其基线的原始差异
vibemap_sync_changes	报告自上次同步以来变更的路径，以便 VibeMap 标记规格偏差

代码库

工具	描述
vibemap_scan_codebase	遍历本地目录
vibemap_analyze_codebase	对代码库进行逆向工程，生成 VibeMap 资产
vibemap_submit_code_map	提交结构化代码映射（节点/边），以便在项目的 Codebase 选项卡中呈现
vibemap_get_code_map	获取项目当前的代码映射（状态、节点/边、同步锚点及偏差）
vibemap_get_generation_status	轮询 AI 生成任务状态

导入现有代码库

结构会在你的机器上读取，不使用模型，也不会发起网络调用。传到 VibeMap 的内容是结构事实（表、列、策略和路由定义及其文件路径），以及 Agent 编写的规格文本。文件内容绝不会离开你的机器。

工具	描述
vibemap_extract_repo_facts	在本地读取仓库的表、策略、路由和文件集群；不会发送任何内容
vibemap_import_facts	发送事实：VibeMap 会创建架构、访问规则，并为每条路由创建一个页面，每个页面都链接到对应文件
vibemap_import_semantic	发送 Agent 编写的功能、故事和标准，每项都注明其来源文件
vibemap_finalize_import	传入已导入的标准（未经验证），锁定 MVP1 并开启 MVP2
vibemap_resync	在当前提交中应用结构变更，并标记受变更文件影响的规格
vibemap_resolve_drift	从漂移报告中清除已处理的文件、映射单元或标准
vibemap_resolve_code_drift_proposal	应用或驳回一项已暂存的代码漂移提案

提示词（斜杠命令）

该服务还会提供提示词——可调用的工作流，IDE 会将其显示为斜杠命令（在 Claude Code 中为：/mcp__vibemap__<name>）。每个提示词的正文会在调用时从 VibeMap 服务端展开，因此你调用的是工作流，而不是粘贴一段冗长指令。除用于创建项目的 new_project 外，每个提示词都需要 projectId；面向代码的提示词还接受可选的 localPath。

提示词	参数	描述
new_project	—	通过引导式访谈创建新的 VibeMap 项目。从这里开始
author_spec	projectId、localPath?	根据本地代码库编写完整的规格图谱（自带 Agent、代码优先）
author_idea	projectId	根据项目构想编写完整的规格图谱（自带 Agent、构想优先）
author_personas	projectId	第 1 阶段，共 5 个阶段——仅编写角色画像
author_features	projectId	第 2 阶段，共 5 个阶段——仅编写功能
author_stories	projectId	第 3 阶段，共 5 个阶段——仅编写用户故事
author_criteria	projectId	第 4 阶段，共 5 个阶段——仅编写验收标准
author_pages	projectId	第 5 阶段，共 5 个阶段——仅编写页面
author_schema	projectId、localPath?	编写数据库架构——表、列和关系
sync_changes	projectId、localPath?	检测并协调自上次同步以来的规格漂移
code_map	projectId、localPath?	构建并提交结构代码映射
load_context	projectId	将项目的规格上下文载入 Agent
kanban	projectId	显示项目的看板
import	projectId、localPath?	将现有代码库导入为已锁定的 MVP1：在本地提取、导入事实、按集群编写规格，最后完成导入
resync	projectId、localPath?	更新已导入的项目，并暂存漂移提案以供审核
build_sprint	projectId	优先构建就绪的工作并进行测试，同时让看板保持实时更新；CI 负责验证，Agent 绝不会将任何事项标记为已完成
release_next	projectId	构建下一个版本：新增和修改的项目，并删除已移除的项目

gen_* — 运行 VibeMap 自带的生成器

上面的 author_* 提示词由你的模型运行：由你的 Agent 进行思考，VibeMap 只保存结果。gen_* 提示词则是另一部分——它们运行 VibeMap 托管的生成流程，也就是应用中 /gen-… 斜杠命令背后的流程。它们会计量用量（消耗项目所有者的 VibeMap 令牌额度），并且是异步的（会返回 sessionId，然后轮询 vibemap_get_generation_status）。

提示词	参数	描述
gen_personas	projectId	生成用户画像——你要为谁构建产品
gen_features	projectId	生成功能——每个故事、页面和表格所依托的功能集合
gen_stories	projectId	根据功能生成用户故事
gen_criteria	projectId	根据功能和故事推导验收标准
gen_pages	projectId	根据功能和故事生成页面架构
gen_schema	projectId	生成数据库架构——表和关系
gen_sync_criteria_from_pages	projectId	根据页面布局交叉核对验收标准

在 CI 中报告测试结果

ci-report 会将一次测试运行转换为评审结果。为每个测试名称标注其验证的验收标准，例如 [AC-042] rejects an empty title。测试运行结束后，提交报告：

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

报告中提及的每项处于评审中的标准，都会根据其对应的测试得出结果：全部测试通过则标记为通过，任一测试失败则标记为失败（失败的测试名称会反馈给 Agent）。不处于评审中或未知的标准会列出，但不会处理。

• 格式：--junit（JUnit XML）、--vitest 和 --playwright（各工具的 JSON 报告器）。可传入多个格式以合并结果。
• VIBEMAP_CI_TOKEN 必须是 CI 评审令牌（Account、Developer，范围为 "CI review"）。Agent 令牌会被拒绝。
• 在 GitHub Actions 中会自动获取运行 URL 和提交；否则请传入 --run-url 和 --sha。
• 退出代码：0 已报告，1 服务端拒绝报告或无法连接，2 用法错误，3 使用 --strict 时没有带标签的测试。
• --dry-run 会打印请求，但不发送。

文档

完整文档请参阅 vibemap.ai/docs/developer-docs/mcp-server/introduction

许可证

MIT