mcpField
A
acquia-source

acquia-source

github.com/grasmash开发8280 次安装4 周前更新
代码仓库

关于 acquia-source

面向 Acquia Source（基于 Drupal CMS 和 Drupal Canvas 的托管 SaaS CMS）的实用技能，为开发者和 Agent 提供认证、API、MCP 内容操作及 Canvas 组件和页面部署指引。

主要功能

  1. 01OAuth2 设置与令牌指引
  2. 02JSON:API 查询和资源指引
  3. 03通过 MCP 管理内容与建模
  4. 04Canvas 组件命令行流程
  5. 05Canvas 页面部署规则

适用场景

  1. 01自动化访问 Acquia Source API
  2. 02通过 MCP 客户端编辑内容
  3. 03创建并上传 Canvas 组件
  4. 04部署 Canvas 页面

MCP 相关

Acquia Source 提供实验性的站点专属 MCP 服务，使用 HTTP 传输和 OAuth2 动态客户端注册。它向客户端提供只读资源和写入工具，用于内容管理、内容建模以及 Drupal Canvas 页面和组件操作。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/grasmash/drupal-claude-skills --skill acquia-source

安装后在 Claude Code 中输入/acquia-source确认已加载。

详细介绍

Acquia Source

Acquia Source（“Source powered by Drupal CMS”）是一款托管式 SaaS CMS，基于 Drupal CMS 11+，并集成了 Drupal Canvas 页面构建器（drupal.org/project/canvas，前身为 Experience Builder）。你无法访问服务器或 SSH，也不能使用任意的贡献模块 — 你需要通过其 JSON:API、MCP 服务、Canvas Page API 和 @drupal-canvas CLI 进行交互。管理员登录地址为 https://source.acquia.com。

Acquia Source 是一款 SaaS 产品，不是 Acquia Cloud Platform。acli CLI 用于管理 Cloud Platform，不能管理 Source 站点 — 不要在这里使用它。Source 通过 Web 管理界面和以下 API 进行操作。

站点标识与凭据

  • CMS URL 的格式为 https://<uuid>.cms.acquia.site（创建站点时自动生成；之后可映射自定义域名）。此基础 URL 是 JSON:API 主机和 OAuth 主机。
  • API 客户端（OAuth2 client_id/secret）在管理界面的 API → API clients → Add API client 下创建。
  • @drupal-canvas CLI 从本地 .env 文件读取所有内容（绝不会提交到版本控制）： 
    CANVAS_SITE_URL=https://<uuid>.cms.acquia.site
CANVAS_CLIENT_ID=<client_id>
CANVAS_CLIENT_SECRET=<client_secret>
CANVAS_JSONAPI_PREFIX=api        # Source serves JSON:API under /api, not the Drupal default /jsonapi
# CANVAS_ACCESS_TOKEN=<token>    # optional: a pre-issued Bearer token instead of client credentials

身份验证（通过 simple_oauth 使用 OAuth2）

  • 令牌端点： POST https://<site>/oauth/token，Content-Type: application/x-www-form-urlencoded。
  • 授权类型： Authorization Code（需要用户参与）、Client Credentials（用于服务器/Agent — 自动化时使用此类型）、Refresh Token。
  • API 调用请求头： Authorization: Bearer <access_token>。
  • 作用域： 内容作用域，如 content:read / content:write（仅为示例 — 尚未公布完整列表）；Canvas CLI 需要 canvas:asset_library 和 canvas:js_component。创建 API 客户端时，启用 Client Credentials 并添加这些作用域。

手动获取 client-credentials 令牌：

curl -s -X POST "$CANVAS_SITE_URL/oauth/token" \
  -d grant_type=client_credentials \
  -d client_id="$CANVAS_CLIENT_ID" \
  -d client_secret="$CANVAS_CLIENT_SECRET" \
  -d scope="canvas:asset_library canvas:js_component" | jq -r .access_token

JSON:API

  • 基础路径在 Source 上为 /api（Drupal 默认的 /jsonapi 已被覆盖 — 设置 CANVAS_JSONAPI_PREFIX=api）。因此，集合的 URL 格式为 https://<site>/api/<entity_type>/<bundle>（例如 /api/node/article）。
  • 资源类型采用标准 Drupal 格式 {entity_type}--{bundle}（node--article、media--image、taxonomy_term--tags 等）。尚未确认存在 Source 专有前缀。
  • 管理界面提供 JSON:API Query Builder（API → JSON:API Query Builder），可生成实时查询和代码；还提供每个站点各自的 OpenAPI 文档（API → OpenAPI documentation）。可通过这些功能了解特定站点的确切 bundle 和字段。
curl -s -H "Authorization: Bearer $TOKEN" \
  "$CANVAS_SITE_URL/api/node/article?page[limit]=5" | jq '.data[].attributes.title'

MCP 服务（连接 AI Agent）

Acquia Source 提供 MCP 服务（HTTP 传输，使用 OAuth2 和动态客户端注册）。该服务处于实验阶段，且需逐站点启用 — 请先启用。

  1. 启用： 管理界面 → Configurations → Experimental features → MCP Server 开关。
  2. 获取 URL： 在 Source 管理界面的 MCP Client Configuration 中复制站点的 MCP URL（端点 URL 按站点配置；没有可直接写死的固定公共路径）。
  3. 在 Claude Code 中注册： 
    claude mcp add acquia-source-mcp <ACQUIA_SOURCE_SITE_MCP_URL>
    然后运行 /mcp，选择 acquia-source-mcp，再点击 Authenticate 完成 OAuth 流程（动态客户端注册 — 无需手动提供 client_id）。

提供的功能（通过 drupal:// 和 canvas:// URI 提供只读资源和写入工具）：

  • 内容管理 — 内容类型、媒体类型、分类词汇表、文本格式；创建/更新节点、媒体和分类词条。
  • 内容建模 — 字段存储、字段类型；创建内容类型并添加字段。
  • Drupal Canvas — 组件和页面；管理布局和组件属性。

当 Agent 需要通过对话方式建模内容或编辑 Canvas 布局时，优先使用 MCP 服务，而不是手动编写 JSON:API 调用；对于确定性、脚本化的部署，则使用 JSON:API/页面 API。

Canvas 代码组件 — CLI 工作流

使用官方工具搭建和管理 React/JSX 代码组件（安装官方 Canvas 技能，了解组件编写规范，切勿另起炉灶）：

  • npx @drupal-canvas/create@latest — 搭建代码库（默认模板：acquia/nebula，其中包含 AGENTS.md 和 SETUP.md，介绍 Page API 参考和注意事项）。
  • npx canvas download / npx canvas upload -c <comp1,comp2> -y — 在代码库和站点之间拉取/推送组件。canvas.config.json（已提交）定义结构；.env（未提交）存放上述密钥。

Canvas Page API — 部署页面

页面的构建方式是先上传组件，再通过 PATCH 为页面设置完整的组件树。以下规则来之不易（不遵守的话会白费数小时）：

  • 每次 PATCH 都会替换整个页面。 切勿通过多次 PATCH 增量构建；应组装完整的组件树，并在一个原子请求中发送。
  • 每次上传都会更改版本哈希。 每次 canvas upload 后都要重新查找所有组件版本哈希；切勿将其硬编码。只有发生更改的组件才会获得新哈希。
  • FormattedText 会在实时站点上移除内联 style 属性（在 Storybook 中可用，在实时站点上则失效）。要设置文本对齐方式，请添加带有 CVA 变体的 layout 属性（left_aligned/center_aligned/right_aligned）；切勿使用内联 style="text-align:…"。
  • Image 组件需要 Drupal 媒体管线 URL（包含 alternateWidths）。外部 URL / data URI 虽然会被接受且不报错，但在实时站点上会渲染为不可见的 0×0 图片。徽标请使用内联 SVG/文本；内容图片请先上传为 Drupal 媒体。
  • 不要将原始十六进制颜色作为属性值 — 使用映射到 global.css 中 Tailwind 主题令牌的 CVA 变体。
  • 内边距会叠加： section 会添加 px-4，grid_container 会添加 px-6 → 在 375px 屏幕上约为 80px。请在内部容器上使用响应式前缀（px-0 md:px-6）。
  • 空插槽容器需要 min-w-*/min-h-*，以便在 Canvas 编辑器中保持可交互。
  • 部署脚本模式：读取 .env → 获取客户端凭据令牌 → 一次性查找所有版本哈希 → 构建组件树（先父项后子项，每个实例使用新的 UUID，inputs 为 json.dumps() 字符串）→ 单次 PATCH。在顶部保留一个 VERSIONS 字典。

文档

评论

支持 Markdown