VibeShare MCP Server

@vibeshare/mcp 是 VibeShare 的 stdio MCP Server 和本地 CLI。它是纯客户端实现，不新增 VibeShare 后端 endpoint；业务 tools 通过 Authorization: Bearer vbs_pat_xxx 调用现有 API，token 可来自 env 或本机设备登录绑定。

Tools

• list_my_apps：列出当前 API Token 用户的作品。
• get_app：读取指定作品详情。
• get_build_status：查询指定作品的静态构建 / 发布状态。
• get_demo_guide：返回「把带后端的项目改造成纯前端 mock 体验版」的配方 markdown，零网络依赖。
• publish_static_web_app：按 Phase 1 状态机诊断并发布本地静态目录；成功时返回 PublishResult，未满足条件时返回 NEEDS_BUILD / NEEDS_LOGIN / NO_ARTIFACT / BLOCKED_SENSITIVE。
• upload_static_web_app：打包本地静态目录并上传发布。

publish_static_web_app 和 upload_static_web_app 会优先用本机 Chrome / Edge / Chromium 渲染静态产物首屏并截取 PNG 作为封面；如果未找到浏览器或截图失败，会附带 warning 并回退到内置最小 PNG 封面。上传会优先使用 presigned upload，服务端返回 presigned disabled 时自动降级到 multipart /uploads/static-web。

作品阶段 stage（概念验证 Demo）

两个上传工具和 CLI publish 均支持可选 stage 字段：released（成品，默认）/ demo（概念验证体验版）。项目带后端时，建议先调用 get_demo_guide 获取改造配方，生成 mock 数据的纯前端体验版后以 stage:"demo" 上传，先验证想法是否有人需要。CLI 用法：vibeshare publish . --stage demo。

Phase 1 新发布契约：

• CLI 目标表面：vibeshare mcp、vibeshare setup、vibeshare login、vibeshare doctor、vibeshare publish .。
• MCP 目标发布工具：publish_static_web_app，输入 / 输出 schema 已在 src/contracts.ts 中定义，当前已注册可用。
• 当前兼容上传工具 upload_static_web_app 仍保留并继续可用；成功输出已升级为 PublishResult。
• 当前 CLI 已实现 setup、doctor 与 publish .。

环境变量

VIBESHARE_API_URL=https://api.sunchen.top
VIBESHARE_API_TOKEN=vbs_pat_xxx

• VIBESHARE_API_URL 可选，默认 https://api.sunchen.top，必须是合法 http(s) URL。
• VIBESHARE_API_TOKEN 可选，必须以 vbs_pat_ 开头；设置后优先级高于本机 store。
• VIBESHARE_CHROME_PATH 可选，用于指定生成封面截图的 Chrome / Edge / Chromium 可执行文件路径；不设置时会自动查找常见安装位置和 PATH。
• API Token 只应放在本机 MCP config、shell 环境变量或安全 secret store；不要提交到 Git、README、日志或公开 issue。

未设置 env token 时，vibeshare-mcp 会读取本机 store。默认路径：

• Windows：%APPDATA%\VibeShare\mcp-auth.json
• macOS：~/Library/Application Support/VibeShare/mcp-auth.json
• Linux：${XDG_CONFIG_HOME:-~/.config}/VibeShare/mcp-auth.json

token 优先级：VIBESHARE_API_TOKEN env > 本机 store > 未绑定时提示运行 vibeshare login。

配置错误和登录/status/logout 提示只写 stderr；stdout 仅用于 MCP JSON-RPC。

npm / npx 使用

发布到 npm 后可直接使用：

npx -y @vibeshare/mcp@latest setup
npx -y @vibeshare/mcp@latest mcp

本仓库本地开发：

cmd /c npm run mcp-server:build
node packages/mcp-server/dist/bin/vibeshare-mcp.js mcp

不带命令启动仍会进入 MCP stdio server；serve 是旧入口，等价于 mcp，仅用于兼容。 Phase 1 默认 MCP 配置目标使用 @vibeshare/mcp@latest。

设备登录

无 env token 时可先运行：

node packages/mcp-server/dist/bin/vibeshare-mcp.js login

命令会打印授权地址和授权码。去网页完成授权后，CLI 会轮询 /mcp/device/poll，成功后把 token 写入本机 store，并只显示脱敏前缀。

node packages/mcp-server/dist/bin/vibeshare-mcp.js status
node packages/mcp-server/dist/bin/vibeshare-mcp.js logout

CLI setup

node packages/mcp-server/dist/bin/vibeshare-mcp.js setup .
node packages/mcp-server/dist/bin/vibeshare-mcp.js setup . --dry-run
node packages/mcp-server/dist/bin/vibeshare-mcp.js setup . --tool cursor --yes
node packages/mcp-server/dist/bin/vibeshare-mcp.js setup . --tool claude --yes
node packages/mcp-server/dist/bin/vibeshare-mcp.js setup . --tool codex --yes
node packages/mcp-server/dist/bin/vibeshare-mcp.js setup . --tool trae --yes

setup 会检测 Claude Code / Cursor / Codex / Trae、打印 MCP 配置计划、备份已有配置，并在确认后写入。默认 --tool auto 会配置检测到的 Claude Code、Codex CLI 或 Codex App 配置目录，并写入项目 .cursor/mcp.json 作为 Cursor 项目配置；Trae 需要显式 --tool trae 或 --tool all 才写入，非交互环境必须使用 --yes 或 --dry-run。

Claude Code 走原生 claude mcp add；Cursor 写入 mcp.json；Codex 写入 config.toml；Trae 写入项目级 .trae/mcp.json。Codex 默认写项目 .codex/config.toml，只有在项目已被 Codex 信任后才会加载；--scope user 会写入 ~/.codex/config.toml。Trae 项目级配置需要在 Trae 设置中启用 Project MCP，或手动粘贴同一段 JSON。

{
  "mcpServers": {
    "vibeshare": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vibeshare/mcp@latest", "mcp"]
    }
  }
}

Codex config.toml 形态：

[mcp_servers."vibeshare"]
command = "npx"
args = ["-y", "@vibeshare/mcp@latest", "mcp"]

Windows 原生环境下，setup --tool codex 会写入 cmd /c npx 包装，避免 MCP 客户端直接启动 npx 时命中 PowerShell 脚本策略。

Trae 项目级 .trae/mcp.json 形态：

{
  "mcpServers": {
    "vibeshare": {
      "command": "npx",
      "args": ["-y", "@vibeshare/mcp@latest", "mcp"]
    }
  }
}

Windows 原生环境下，setup --tool trae 会写入 cmd /c npx 包装。若 Trae 客户端已能直接启动 npx，也可以在 Trae 的 MCP 手动配置里使用上面的跨平台 JSON。

CLI doctor / publish

node packages/mcp-server/dist/bin/vibeshare-mcp.js doctor .
node packages/mcp-server/dist/bin/vibeshare-mcp.js doctor . --json
node packages/mcp-server/dist/bin/vibeshare-mcp.js publish . --title "我的小工具"
node packages/mcp-server/dist/bin/vibeshare-mcp.js publish . --json

doctor 会检查 Node 版本、API/Web/user-content 基准 URL、登录态、候选静态产物、敏感文件阻断，以及 Claude Code / Cursor / Codex / Trae 的本机命令和配置候选路径。 publish 复用 publish_static_web_app 的 shared core：成功时返回 PublishResult；未满足条件时返回 NEEDS_BUILD、NEEDS_LOGIN、NO_ARTIFACT 或 BLOCKED_SENSITIVE，不会自行运行 build。

Claude Code MCP config 示例

Claude Code 当前 CLI 支持优先使用原生命令添加 MCP：

claude mcp add vibeshare -- npx -y @vibeshare/mcp@latest mcp

Windows 原生环境下，Claude Code 官方建议给 npx 加 cmd /c 包装：

claude mcp add vibeshare -- cmd /c npx -y @vibeshare/mcp@latest mcp

本地仓库构建产物：

{
  "mcpServers": {
    "vibeshare": {
      "command": "node",
      "args": ["E:/py/平台/packages/mcp-server/dist/bin/vibeshare-mcp.js", "mcp"],
      "env": {
        "VIBESHARE_API_URL": "https://api.sunchen.top"
      }
    }
  }
}

npx：

{
  "mcpServers": {
    "vibeshare": {
      "command": "npx",
      "args": ["-y", "@vibeshare/mcp@latest", "mcp"],
      "env": {
        "VIBESHARE_API_URL": "https://api.sunchen.top"
      }
    }
  }
}

上传目录规则

publish_static_web_app / upload_static_web_app 会按以下顺序决定实际打包目录：

1. 显式 artifactPath（仅 publish_static_web_app 支持）。
2. 输入目录直接包含 index.html：打包输入目录。
3. 输入目录包含 dist/index.html：打包 dist。
4. 输入目录包含 build/index.html：打包 build。
5. 输入目录包含 out/index.html：打包 out。
6. 未找到产物但检测到 package.json 的 scripts.build：返回 NEEDS_BUILD，由 Agent 在自身权限体系里执行构建后重试。
7. 未找到产物且无构建脚本：返回 NO_ARTIFACT。

候选上传集若命中 .env*、*.pem、*.key、id_rsa*、.aws/、带 token 的 .npmrc 或 VibeShare 本机凭证，会返回 BLOCKED_SENSITIVE。打包时仍跳过 node_modules、.git、.next、隐藏文件 / 目录和 .DS_Store；本地默认打包上限为 20MB，与当前 API 默认 MAX_STATIC_ZIP_BYTES 保持一致。若部署方调大 API 上限，需要同步调整 MCP 打包上限。