velocms

@velocms/mcp

一个适用于 VeloCMS 的 MCP 服务 — 可通过 Claude Code、Claude Desktop、Cursor 或任何其他 MCP 客户端来起草、编辑、发布和管理博客（文章、媒体、评论、成员、 站点设置）。

它是对 VeloCMS 公共 API 的轻量级、类型化封装 （https://<your-blog>/api/v1；任何 VeloCMS 站点都可通过 /api/openapi 查看文档）：每个 工具对应一次真实的 API 调用，并通过 Zod 验证输入、提供易读的 错误信息 — 不抓取数据、不进行浏览器自动化，只使用平台自身支持的 REST API。

功能介绍

工具	功能
list_posts	分页列出文章，可按状态（draft/published）筛选
get_post	按 ID 获取单篇文章，包括完整内容和 SEO 字段
create_post	创建新文章（默认为 draft）
update_post	部分更新现有文章 — 只更改传入的字段
delete_post	永久删除文章
publish_post	将文章状态设为 published（会设置 published_at）
unpublish_post	将文章状态改回 draft
list_media	分页列出媒体库，可按 MIME 类型筛选
list_comments	分页列出评论，可按文章或审核状态筛选
moderate_comment	将评论状态设为 approved、pending 或 spam
list_members	列出订阅者/读者（邮箱会脱敏，例如 u***@example.com）
get_site_settings	读取博客名称、描述和功能标志

每个工具都附带说明，供大模型了解何时以及如何使用它 — 这正是 MCP 的意义，而不仅仅是多绕几步的 REST 代理。 完整参数列表请见下文的工具参考。

设置

1. 获取 VeloCMS API 密钥

在 VeloCMS 控制面板中：Settings → API Keys → 创建一个包含所需 权限范围的密钥（posts:read、posts:write、media:read、comments:read、 comments:moderate、members:read、site-settings:read 等）。API 访问 需要 Pro plan 或更高版本。

2. 配置 MCP 客户端

无需克隆此仓库 — npx 会按需获取并运行它。

Claude Code

claude mcp add velocms \
  --env VELOCMS_SITE_URL=https://myblog.velocms.org \
  --env VELOCMS_API_KEY=velo_your_64_char_hex_key_here \
  -- npx -y -p @velocms/mcp velocms-mcp

MCP 服务会在会话启动时注册工具，因此添加配置后，请重新启动 Claude Code 会话。

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "velocms": {
      "command": "npx",
      "args": ["-y", "-p", "@velocms/mcp", "velocms-mcp"],
      "env": {
        "VELOCMS_SITE_URL": "https://myblog.velocms.org",
        "VELOCMS_API_KEY": "velo_your_64_char_hex_key_here"
      }
    }
  }
}

编辑后重新启动 Claude Desktop。

Cursor / 任何其他 MCP 客户端

配置方式与上面相同 — 将客户端的 MCP 配置指向 npx -y -p @velocms/mcp velocms-mcp，并在其 env 中设置 VELOCMS_SITE_URL 和 VELOCMS_API_KEY。服务通过 stdio 提供标准 MCP，因此任何支持 stdio MCP 服务的客户端都能使用。

3. 本地安装（贡献开发 / 从源代码运行）

git clone https://github.com/VeloCMS/velocms-mcp.git
cd velocms-mcp
npm install
npm run build
cp .env.example .env
# edit .env and set VELOCMS_SITE_URL + VELOCMS_API_KEY
VELOCMS_SITE_URL=... VELOCMS_API_KEY=... node dist/index.js

配置参考

环境变量	必填	说明
VELOCMS_SITE_URL	是	博客的基本 URL — *.velocms.org 子域名或已绑定的自定义域名。无需末尾斜杠。
VELOCMS_API_KEY	是	来自 /admin/settings → API Keys 的 API 密钥。需要 Pro plan 或更高版本。绝不会记录到日志中。

如果缺少任一变量，服务会向 stderr 输出清晰的提示并立即退出 （process.exit(1)）— 不会以配置不完整的状态启动。

工具参考

参数名称采用 camelCase；服务会为你将其映射到 API 的 snake_case JSON 字段。

list_posts — page?、perPage?（最多 100）、status?（draft | published）。

get_post — id（必填）。

create_post — title（必填，≤255 个字符）、slug?、contentHtml?、 contentJson?（TipTap ProseMirror 文档——除非需要使用它，否则优先选择 contentHtml）、excerpt?（≤500）、status?（默认为 draft | published）、 tags?（字符串数组）、seoTitle?（≤60）、seoDescription?（≤160）。

update_post — id（必填）+ 任意 create_post 字段 （此处均为可选）。除 id 外至少需要一个字段——工具会在发起任何网络请求前 拒绝无操作调用。

delete_post — id（必填）。永久删除。

publish_post / unpublish_post — id（必填）。分别是 update_post({ status: "published" }) / update_post({ status: "draft" }) 的简写。

list_media — page?、perPage?、type?（MIME 类型前缀，例如 "image"）。

list_comments — page?、perPage?、postId?、status?（approved | pending | spam）。

moderate_comment — id（必填）、status（必填：approved | pending | spam）。

list_members — page?、perPage?、tier?（free | paid）。

get_site_settings — 无参数。

错误处理模型

VeloCMS API 会返回格式统一的 JSON 错误封装：

{ "error": { "code": "RATE_LIMITED", "message": "...", "details": {} } }

此客户端会直接显示该消息（绝不会显示原始堆栈跟踪）， 并补充可操作的提示：

• 401（UNAUTHORIZED）——消息会提示你检查 VELOCMS_API_KEY。
• 403（PLAN_UPGRADE_REQUIRED）——消息会指引你前往 /admin/billing。
• 403（INVALID_SCOPE/FORBIDDEN）——消息会提示你检查密钥的作用域。
• 429（RATE_LIMITED）——会解析 Retry-After 响应标头（秒），并将其纳入错误消息；如果你直接调用客户端库， 还会将其作为 retryAfterSeconds 返回。
• 任何其他非 2xx 状态码——会按原样显示 API 自身的 code + message。

速率限制基于套餐（Pro：30 次/分钟、1,000 次/小时 · Business：120 次/分钟、 5,000 次/小时 · Agency：300 次/分钟、20,000 次/小时）——此服务不会自动重试； 遇到限制时会立即失败并告知等待时间，交互式工具调用绝不会悄无声息地阻塞。

安全性

• 你的 API 密钥是限定租户范围的凭据——只能访问为其签发密钥的那个博客， 并且只能访问该密钥作用域允许的端点。
• 密钥只会从环境中读取一次，绝不会记录、回显或包含在任何工具输出中。
• API 会屏蔽 list_members 返回的成员邮箱（例如 u***@example.com）——此服务不会看到或处理未屏蔽的 成员个人身份信息（PII）。
• API 会将加密的租户设置（Stripe 密钥、AI 提供商密钥）排除在 get_site_settings 返回内容之外——无法通过此服务读取这些信息。

关于此 MCP 服务的说明

• moderate_comment 的请求体字段是 status，不是 action — 根据 API 自身的架构，PATCH /api/v1/comments/{id}/moderate 接受 { "status": "approved" | "pending" | "spam" }，因此工具的输入字段名称与之保持一致。
• get_post 和 get_site_settings 会直接返回记录（不会封装在 { "data": ... } 中）——只有写入端点（create_post、 update_post、moderate_comment）会封装其响应，与 API 自身在此处的不一致保持一致（已在 openapi.yaml 中说明）。
• 目前没有 upload_media 工具——POST /api/v1/media 接受 multipart/form-data，这与典型的 MCP 客户端传输方式难以适配。你可以使用 list_media 引用已通过控制面板上传的媒体文件。欢迎提交贡献以实现此功能。

开发

npm install
npm run typecheck   # tsc --noEmit
npm test             # vitest — all tests run against a mocked fetch, no live API calls
npm run build        # emits dist/

测试套件涵盖：每个请求中的 Authorization: Bearer 标头、每个工具精确的方法／URL／请求体映射、401/403/429/500 响应的错误代码映射，以及缺少环境变量时的快速失败路径。本仓库中的测试均不会发起真实网络请求。

许可证

MIT — 详见 LICENSE。