1. 地址与鉴权

假设服务地址为 http://127.0.0.1:8000。

1.1 外部 API 与 MCP

外部 API 与 MCP 使用标准 HTTP Bearer Token。Bearer 后面的值是 user 表中对应用户的 token 字段：

Authorization: Bearer YOUR_USER_TOKEN

服务端按 user.token 查询用户；MCP 仍要求该用户是管理员。不再读取 XToken，也不要求 JWT。

敏感信息不要写入脚本、日志或文档；本文档中的 token 仅为占位符。

1.2 管理后台 API

/api/admin/* 接口走后台登录后的 VToken 鉴权，而不是 XToken：

VToken: YOUR_VTOKEN

如果只有外部用户 Token，应优先使用本文档中的 /api/api_* 接口或 /api/mcp。

1.3 通用响应

外部 HTTP API 通常返回：

{
  "code": 200,
  "msg": "ok",
  "data": {}
}

401：Token 缺失、无效或未登录。
403：用户没有管理员权限。
400：请求格式或文件解析失败。
422：业务参数校验失败。
500：服务器或存储内部错误。

2. MCP 服务启用与配置

MCP 默认关闭。管理员需先在后台 MCP 管理页启用服务；关闭时 POST /api/mcp 返回 HTTP 404，响应文本为 MCP service is disabled。

配置接口使用后台登录后的 VToken，仅管理员可调用：

GET /api/admin/option/mcp/get
POST /api/admin/option/mcp/update
Content-Type: application/json
VToken: YOUR_VTOKEN

更新请求体支持两个字段：

{"enabled": true, "disable_localhost_protection": false}

enabled：MCP 服务总开关。
disable_localhost_protection：是否关闭 MCP 自带的 DNS rebinding 防护，默认 false（保留防护）。保留防护时，若服务监听在本机回环地址、而请求的 Host 头是外部域名，MCP 会直接返回 403；通过反向代理以域名访问 MCP 的场景需要把它设为 true。服务暴露在浏览器可达网络中时建议保持 false。

启用后的外部 MCP 调用使用标准 HTTP Bearer Token，值来自管理员用户的 user.token：

POST /api/mcp
Content-Type: application/json
Authorization: Bearer YOUR_USER_TOKEN

未携带或无效 token 返回 401 和 WWW-Authenticate；权限不足返回 403。资源元数据地址为 GET /.well-known/oauth-protected-resource。

MCP 使用 JSON-RPC 2.0。

2.1 初始化

curl -X POST 'http://127.0.0.1:8000/api/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "my-client", "version": "1.0.0"}
    }
  }'

2.2 查询工具列表

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

当前工具共 19 个：

list_columns
get_column
create_column
update_column
delete_column
list_articles
get_article
create_article
update_article
delete_article
create_theme_file
edit_theme_file
delete_theme_file
create_theme_directory
delete_theme_directory
list_theme_directory
read_theme_file
rename_theme_path
upload_file

2.3 工具调用通用格式

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {"name": "TOOL_NAME", "arguments": {}}
}

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "content": [{"type": "text", "text": "..."}],
    "structuredContent": {}
  }
}

工具失败时，通常返回 result.isError: true 和文本错误信息。

VVCMS 外部 API 与 MCP：鉴权、响应与启用