vibecms

让你的 Agent 发布内容的 CMS：通过受限范围的 MCP 或 REST /api/v1 API 发布 Markdown 文章、管理版本和媒体——每篇文章都由你掌控。每次修改都会生成活动记录，重要的文章变更还会创建版本。

功能

• 简洁的托管博客仪表盘
• 公开博客页面
• Markdown 文章编辑器
• R2 媒体上传
• D1 数据库
• 活动历史记录
• 文章版本历史
• 受限范围、仅显示一次且带有 vc_live_ 前缀的 Agent 令牌
• 面向可信 Agent 的 MCP 端点
• 为托管版 vibecms Cloud 提供 Polar 计费
• 无需 Polar 的 SELF_HOSTED=true 模式

连接 MCP 客户端

vibecms 通过 Streamable HTTP 提供基于标准的 MCP。托管版 vibecms 使用 https://app.vibecms.dev；自托管用户使用自己的 API 主机。

在发现 MCP 或使用工具之前必须先登录：initialize、tools/list、server/discover 和旧版 notifications/initialized 均需身份验证。Claude 网页版、桌面版和 Code 等 OAuth 客户端会先显示 连接 或 登录。不带 bearer 的请求会收到带有 OAuth 资源元数据质询的 HTTP 401；现有 API 密钥用户仍可像以前一样发送 bearer 密钥。OAuth 元数据、可信 CIMD/公共客户端注册、静态服务器卡片和 HTTP Agent 技能文件仍公开可用。

使用 URL 连接 Claude Code，然后打开 /mcp 登录并批准访问：

claude mcp add --transport http vibecms https://app.vibecms.dev/mcp

如果客户端使用 Agent 密钥，请在仪表盘中打开 连接，创建一个受限范围的令牌，并复制一次。将其作为 bearer 凭据发送：

{
  "mcpServers": {
    "vibecms": {
      "type": "http",
      "url": "https://app.vibecms.dev/mcp",
      "headers": {
        "Authorization": "Bearer vc_..."
      }
    }
  }
}

安装与客户端无关的安全、写作和 SEO 技能（skills/ 中的所有技能）：

npx skills add https://vibecms.dev --skill '*'

运行 npx skills update 以保持更新。或者，使用 npx vibecms-cli skills get 将所有技能保存到 .agents/skills（传入技能名称以选择部分技能，使用 --dir <path> 选择文件夹，或使用 --force 覆盖现有文件），也可以让已连接的 Agent 调用 skills.list 和 skills.get MCP 工具。

使用托管服务的 Claude Code 用户可以将所有技能和 MCP 服务作为一个插件安装。该插件使用服务器 URL 连接；打开 /mcp 登录并通过 OAuth 批准访问：

claude plugin marketplace add moinulmoin/vibecms
claude plugin install vibecms@vibecms

目录列表文案和提交说明见 docs/directory-listings.md。

使用受保护的工具调用验证凭据是否能读取你的网站（tools/list 现在也需要身份验证，但只会列出凭据范围允许的工具）：

curl https://app.vibecms.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vc_..." \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"sites.get","arguments":{}}}'

有效令牌会在 structuredContent 中返回当前网站；无效或缺失的令牌会返回 401。发布前先审批的流程如下：

sites.get -> posts.format_guide -> draft -> posts.preview
  -> latest saved version -> explicit approval
  -> posts.publish(postId, expectedVersionNumber) -> returned URL

在请求批准发布之前，请先修复 SEO 检查结果中的 error 和 warn 项。 posts.preview 会包含确定性的 seo 检查结果。对于已保存的文章，请使用 posts.seo_check({postId, focusKeyword?}) 或 GET /api/v1/posts/{postId}/seo?focusKeyword=deployment。 这 31 条规则都是纯代码，并且在所有套餐中运行：其中 26 条针对搜索引擎 （元数据、标题、链接、内容、重复内容、索引、焦点关键词），5 条针对 AI 答案（首个标题前的简短开篇段落、带来源链接的数字、便于引用的简短章节、以列表呈现的步骤）。vibecms 不会对你的文章运行 AI 模型；你的 Agent 会使用自己的模型，根据 vibecms-seo 技能回答判断类问题。

REST /api/v1 API 与 MCP 工具相对应，具备完整的读写能力。文章列表返回的是摘要，不包含完整 Markdown，因此请通过 REST 或 MCP posts.get 获取单篇文章正文：

curl "https://app.vibecms.dev/api/v1/posts?limit=20&offset=0" \
  -H "Authorization: Bearer vc_..."

托管版 vibecms Cloud 会将 MCP 和 REST 请求计入同一工作区 API 配额。速率限制错误可供机器读取：REST 返回带有 RATE_LIMIT 的 429，MCP 则返回 JSON-RPC 速率限制错误。

许可证

vibecms 根据 AGPL-3.0-or-later 许可证授权。请参阅 LICENSE。

vibecms 名称和标志受 TRADEMARKS.md 中商标指南的约束。

脚本

pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build
pnpm public:audit
pnpm db:migrate:local
pnpm db:seed:local
pnpm dev

数据库迁移 SQL 位于 packages/db/drizzle/，由两个 Workers 共用。 本地 API 开发、Astro 渲染、迁移和种子命令共用根目录下的 .wrangler/state，因此两个 Workers 可以访问相同的 D1 和 R2 数据。

请参阅 plans/README.md 中的决策记录索引。

自托管模式

vibecms 现在支持真正的自托管开关：

SELF_HOSTED=true

在自托管模式下，Polar 为可选项，计费限制会被禁用，且默认不执行托管工作区 API 配额限制。注册并完成博客设置后，所有者会进入 /dashboard；发布、媒体上传、限定范围的 Agent 访问、活动历史记录和文章版本均使用自托管者的 Cloudflare D1/R2 资源。

该代码库在托管和自托管模式下部署相同的三 Worker 拓扑：

• apps/api/wrangler.jsonc、apps/public/wrangler.jsonc 和 apps/og/wrangler.jsonc 配置托管开发环境/生产环境。
• 根目录的 wrangler.jsonc 配置自托管的 Hono API + dashboard Worker。
• 根目录的 wrangler.public.jsonc 配置自托管的 Astro 公共博客 Worker。
• 根目录的 wrangler.og.jsonc 配置可选的自托管 OG Worker。
• pnpm deploy 会构建所有已配置的 Workers、应用 D1 迁移，然后按 API → OG → public 的顺序部署（先部署 OG，以便解析 public 的服务绑定）。

部署期间，请配置根目录下的 Wrangler 文件（wrangler.jsonc、 wrangler.public.jsonc，以及 wrangler.og.jsonc，除非根据 docs/self-hosting.md 省略 OG）。公共博客仅支持基于主机的模式 （租户身份由主机确定），因此 API/dashboard 和公共博客使用不同的 Worker 主机：

APP_URL=https://vibecms.<your-subdomain>.workers.dev
BETTER_AUTH_URL=https://vibecms.<your-subdomain>.workers.dev
PUBLIC_BLOG_DOMAIN=vibecms-public.<your-subdomain>.workers.dev
SELF_HOSTED=true

公共博客通过 PUBLIC_BLOG_DOMAIN 提供 /、/<post-slug> 和 /tag/<tag> 路径服务；不支持已移除的 /blog/<site-slug>/* 路径模式。

唯一必需的自托管密钥列于 .dev.vars.example：

BETTER_AUTH_SECRET=<generate with openssl rand -hex 32>
TOKEN_PEPPER=<generate with openssl rand -hex 32>

最简本地/自托管环境变量配置（本地 URL 不是公开的托管 URL）：

APP_URL=https://vibecms.example.workers.dev
BETTER_AUTH_URL=https://vibecms.example.workers.dev
PUBLIC_BLOG_DOMAIN=vibecms-public.example.workers.dev
SELF_HOSTED=true
BETTER_AUTH_SECRET=<generate with openssl rand -hex 32>
TOKEN_PEPPER=<generate with openssl rand -hex 32>

Cloudflare 自托管流程和部署按钮说明请参阅 docs/self-hosting.md。

上线说明

• 在生产部署前，在 apps/api/wrangler.jsonc 和 apps/public/wrangler.jsonc 中配置共享的 Cloudflare D1/R2 ID。
• 使用 Wrangler 设置 API Worker 密钥：BETTER_AUTH_SECRET、TOKEN_PEPPER、POLAR_ACCESS_TOKEN 和 POLAR_WEBHOOK_SECRET；AUTOSEOPILOT_INTERNAL_SECRET 为可选项，只有设置后才会启用托管的 AutoSEOPilot 路由。
• 在两个 Worker 配置文件中设置产品、URL 和主机变量。
• 使用 gh workflow run deploy-production.yml --ref main -f release_sha=<full sha> -f smoke_mode=authenticated 推广经过审核的提交；该命令会运行 pnpm deploy:prod：执行预检并构建生产产物、捕获备份元数据、迁移 D1、按 OG → public → API 的顺序部署，然后运行冒烟测试。Astro 会话已禁用（不使用 SESSION KV）。

对于自托管生产环境，请设置 SELF_HOSTED=true；密钥只需 BETTER_AUTH_SECRET 和 TOKEN_PEPPER。Polar 访问令牌/产品/ Webhook 密钥仅用于托管 SaaS。

开发部署

当前 Cloudflare 开发资源已在 apps/api/wrangler.jsonc 和 apps/public/wrangler.jsonc 中配置：

• API + 仪表板 Worker：vibecms-api-dev，地址为 https://app.basedui.dev
• 公共 Astro Worker：vibecms-public-dev，地址为 https://basedui.dev 和 *.basedui.dev
• 共享 D1 数据库：vibecms_dev
• 共享 R2 存储桶：vibecms-assets

运行完整的开发部署／测试流程：

pnpm install
pnpm typecheck
pnpm lint
pnpm db:seed:dev
pnpm deploy:dev

pnpm deploy:dev 会同步开发令牌 pepper、应用远程 D1 迁移、构建仪表板资源、部署 Hono API Worker、部署 OG Worker，然后构建并部署 Astro 公共 Worker。

对于 Polar 账单，请在 Polar 中创建沙盒产品并更新开发变量。 已提交的开发变量包含沙盒产品和启动折扣 ID；如果使用自己的 Polar 沙盒产品，请在 apps/api/wrangler.jsonc 的 env.development.vars 下设置以下全部四项—— POLAR_MONTHLY_PRODUCT_ID、POLAR_YEARLY_PRODUCT_ID、 POLAR_LAUNCH_DISCOUNT_MONTHLY_ID 和 POLAR_LAUNCH_DISCOUNT_YEARLY_ID。 结账流程会自动选择已配置的折扣，因此请创建期限为永久、优惠后价格为每月 $9 和每年 $75 的匹配折扣；或者移除两个折扣变量，以测试标价结账：

pnpm --filter @vc/api exec wrangler secret put POLAR_ACCESS_TOKEN
pnpm --filter @vc/api exec wrangler secret put POLAR_WEBHOOK_SECRET
pnpm deploy:dev

推荐的沙盒产品设置：

• 周期性订阅产品。
• 价格：标价为每月 $15；如果在 Polar 中创建年度产品／价格，则为每年 $150（启动优惠：通过折扣降至每月 $9、每年 $75）。
• 将月度产品设为 POLAR_MONTHLY_PRODUCT_ID。如果年度产品是单独的 Polar 产品，则将其设为 POLAR_YEARLY_PRODUCT_ID。同时设置两个启动折扣 ID，否则结账流程会发送已提交的沙盒折扣。
• 托管模式下，免费额度为 5 篇已发布文章、同时保留 5 篇草稿和 10 张图片——无需银行卡——免费博客会显示一个小型“由 vibecms 发布”链接；订阅可解锁不限文章数量、10 GB 媒体存储、分析和自定义域名，并移除该链接。自托管模式下，SELF_HOSTED=true 会完全绕过账单限制，且不会显示该链接。
• 启动版权益：1 个托管博客、不限文章数量、10 GB 媒体存储、范围受限的 Agent 访问权限（无每月请求上限，仅有每分钟和每日限制）、活动记录和版本历史，以及读者与 AI 发现分析。
• 应用强制执行的上传政策：仅允许 JPEG/PNG/WebP/GIF，图片大小上限为 10MB，不托管视频，不提供通用文件托管。

推荐的 Polar 组织访问令牌最低权限范围：

• checkouts:write，用于创建结账会话。
• customer_sessions:write，用于创建客户门户会话。

当前应用运行时不需要产品、订单、退款、文件、计量、Webhook 或订阅写入权限。Webhook 使用 POLAR_WEBHOOK_SECRET 验证，而不是 API 令牌。

在 Polar 中，将 Webhook 端点设置为：

https://app.vibecms.dev/api/polar/webhook

订阅以下 Webhook 事件：

• 必需：subscription.created、subscription.updated、subscription.active、subscription.past_due、subscription.canceled、subscription.revoked。
• 结账／客户对账回退机制必需：checkout.updated。
• 可选，但对后续分析很有用：order.paid。

应用目前会根据 subscription.* 负载以及成功的 checkout.updated 负载更新账单状态。请将 Webhook 传送格式保持为原始 JSON，并将端点签名密钥复制到 POLAR_WEBHOOK_SECRET。