MCP 教程

概述

MCP（Model Context Protocol） 让 AI 助手通过标准协议直接读写 Baklib 线上数据——知识库文章、站点页面、资源库（DAM）、应用库等，而无需您手动复制粘贴。适合「用对话查清单、批量整理内容、辅助录入与改写」等场景。

Baklib 官方 MCP Server 包为 @baklib/baklib-mcp-server（npm）。鉴权使用与个人中心 API 密钥 相同的 <key>:<secret> 格式。配置完成后，AI 应优先通过 MCP 工具获取真实数据；任何写入线上 Baklib 的操作，仍须您在对话中明确确认后再执行。

操作步骤

步骤一：准备 API 密钥

登录 Baklib 工作台，进入 个人中心 → API密钥（/my/access_keys）。
创建密钥并 一次性保存 完整 Secret（格式为 <key>:<secret>）。
详细步骤见 API 密钥。

预期结果：您持有一对可用于 MCP 与 Open API 的密钥。

步骤二：配置 Token

任选以下方式之一（环境变量优先于文件）：

方式 A（推荐）：在 MCP 客户端配置中通过环境变量注入：

# 文件 ~/.config/BAKLIB_MCP_TOKEN 内容为单行，无引号：
<key>:<secret>

或在 MCP 配置的 env 字段写入 BAKLIB_MCP_TOKEN（见步骤三示例）。

方式 B：写入用户级配置文件：

mkdir -p ~/.config
printf '%s' '<key>:<secret>' > ~/.config/BAKLIB_MCP_TOKEN
chmod 600 ~/.config/BAKLIB_MCP_TOKEN

注意：Token 文件含敏感信息，勿提交到 Git 或写入公开文档。

预期结果：MCP Server 启动时可读取有效 Token。

步骤三：在 AI 客户端注册 MCP Server

配置文件路径因客户端而异（Cursor 常见为 ~/.cursor/mcp.json；Claude Desktop、VS Code 请参阅各自 MCP 文档）。JSON 结构示例：

{
  "mcpServers": {
    "baklib": {
      "command": "npx",
      "args": [
        "-y",
        "@baklib/baklib-mcp-server@0.5.2"
      ],
      "env": {
        "BAKLIB_MCP_TOKEN": "<key>:<secret>"
      }
    }
  }
}

将上述片段合并到您的 MCP 配置（server 名称可自定义）。
建议使用 @baklib/baklib-mcp-server@0.5.2 或以上版本，以支持按 purpose 获取 DAM signed_id 等能力。
保存配置后 重启客户端或刷新 MCP 连接。
帮助中心 [MCP 页][1] 提供「复制安装命令」「连接到 Cursor / VS Code」等快捷入口，可按页面指引操作。

预期结果：客户端工具列表中出现 Baklib 相关 MCP 工具（如知识库 list/get、站点页面、DAM 上传等，以当前版本 schema 为准）。

步骤四：安装配套 Agent Skills（推荐）

仅配置 MCP 即可查询与写入；若希望 AI 正确撰写 Baklib 文档编辑器 Markdown（dam-id、链接卡片、片段等），建议同时安装社区技能：

npx skills add baklib-tools/skills --skill baklib-mcp --skill baklib-bke-markdown

详见 SKILLS 使用指南。

预期结果：AI 在写入知识库正文或站点富文本时遵循文档编辑器扩展语法，避免版式错乱。

步骤五：验证与常见工作流

验证连接

在对话中请 AI「列出我有哪些知识库 / 站点」——应返回基于 MCP 的真实清单，而非臆测。
若出现 401、认证失败等错误，检查 Token 格式与 MCP 重载是否生效。

读取类（低风险，通常可直接执行）

列出知识库空间、文章目录
读取单篇文章或站点页面内容并摘要
查询 DAM 资源清单

写入类（须先确认）

创建/更新知识库文章：正文使用 文档编辑器 Markdown；通过 MCP 写入 Markdown 来源正文时，须在参数中显式声明 body_type / content_type 为 markdown，否则可能按纯文本写入导致标题、列表等版式错乱
上传 DAM 并更新站点页：典型流程为 dam_upload_entity →（必要时按 purpose=dynamic_form 取 signed_id）→ site_update_page 写入 template_variables
批量导入或同步：可配合 baklib-intake-assistant、baklib-data-import 等技能

预期结果：读取返回真实数据；写入前 AI 向您说明将改动的对象与范围，经您同意后再执行。

常见问题

Q：MCP 与直接调 Open API 有什么区别？
A：MCP 为 AI 客户端提供的标准工具接口，便于对话式操作；底层仍使用 Open API 鉴权。除非您明确要求用 curl/脚本，否则 AI 应优先走 MCP。

Q：密钥与 CLI 用的是同一套吗？
A：是。均在 API 密钥创建；CLI 另支持 baklib config set-token，见 CLI 教程。

Q：站点页图片字段如何填？
A：先通过 MCP 上传图片取得 signed_id；若模板表单需要特定 purpose，使用 MCP 按 purpose 获取 signed_id（站点表单 DAM 字段一般为 dynamic_form），再写入页面 template_variables。勿手写未文档化的 HTTP 调用。

Q：私有化部署如何配置？
A：MCP Server 与 Open API 基址（base URL） 须指向您私有化实例的 API 域名，而非 https://baklib.com。在 MCP 客户端或 @baklib/baklib-mcp-server 环境变量中配置对应 API 地址。部署与域名规划见 Docker 免费部署安装。

概述