Typeroll CMS

Typeroll CMS MCP 服务

@typeroll/mcp-server 包可将兼容 MCP 的 AI 客户端连接到 Typeroll CMS 公共 API。通过工具管理站点，读取和 写入页面、局部模板、内容类型、媒体、重定向和版本；触发部署；生成预览链接。

该服务是一个轻量传输适配器——工具会调用 Typeroll REST API， 少数工作流工具会组合连续的 API 调用，例如先配置再部署。身份验证由 API 层使用 站点级或组织级密钥完成；MCP 仅负责传递 Bearer 令牌。

网站起步工作区

运行 npx @typeroll/mcp-server@latest init ./my-site，为你自己的代码库生成一个项目文件夹。 它会将所有者规则保存在 brief/rules.md，将搜索策略保存在 brief/seo.md，并包含迁移说明、 workflows/ 下的任务入口、决策和 QA。MCP 0.45.77 新增了规则、SEO 和例行流程文件。使用 init ./my-site --update 可将这些文件添加到现有工作区；已编辑的文件会保留，以供手动审核。

这与生成的发布代码库相互独立。CMS 管理当前内容和设置。托管 MCP 无需本地工作区。请阅读 工作区指南和 引导式入门文档。 启动提示词仅存在于起步文件中：workflows/new-site.md 和 workflows/migration.md。workflows/interview.md 会逐个问题引导补充缺失的决策， 并从 brief/interview.md 继续。迁移时，文本保留与设计／图片保留可分别选择。 按需加载任务方案，不要将完整手册复制到上下文中。

单一 Page 模型

Core 0.2.0 和 MCP 0.45.0 使用一种内容实体：Page。所有文章、 清单、产品、目录条目和普通页面都使用相同的 API、编辑器、 区块、历史记录、预览和状态。content_type 用于选择架构、URL 模式 和默认 Page 模板。自定义值应放在 fields 中；标题、slug、路径、正文、 SEO 和状态都是内置的 Page 属性。引用使用 page_ref／page_ref_list， 没有详情 URL 的记录则使用空白类型路由模式。

使用 create_page、list_pages content_type=... 以及内容类型／Page 模板 工具。在编辑、引用、预览和构建过程中，始终使用 Page ID 和同一站点的 version。 现有安装必须先迁移，才能运行此版本。请参阅模型指南和 升级流程。

两种连接方式

• 远程 MCP——输入 URL。 使用支持 Streamable HTTP 的客户端， 并通过 OAuth 或 Bearer 标头进行身份验证。Cloud 端点为 https://app.typeroll.com/api/mcp；可自托管门户使用 https://<your-portal-host>/api/mcp。在 Core 0.2.78+ 上，登录并批准 个人访问即可，任何角色均可。无需复制 API 密钥。确认站点和版本，使用 select_site，并在站点调用时传递其 site_context。 可在「账户」→「AI 连接」中撤销访问权限。权限会实时检查； 连接将在 30 天后过期。重新连接前，旧版 OAuth 授权仍保持原有范围。 仍支持手动 Bearer 密钥。
• 本地 stdio——启动 npm 包。 使用能够通过环境变量运行本地 命令的客户端。请参阅下方说明。

请参阅客户端兼容性和验证状态， 了解 Claude Desktop、Claude Code、Cursor、VS Code、ChatGPT、Cline 和 Zed 的相关信息。 仅支持 MCP 并不代表 Typeroll 集成已经过测试。

此 npm 包提供 stdio 传输。托管端点作为 Typeroll 门户的一部分提供—— 工具界面相同，底层使用的包也相同。

关键作用域

• 组织级密钥（在 /app/settings/api-keys 创建）— 一个凭据即可访问组织中的所有站点，以及共享到组织中的所有站点。适用于托管式多站点连接。也可通过 stdio 使用，只需设置 TYPEROLL_SITE_ID，让安装绑定到一个站点。
• 站点级密钥（在 /app/sites/{siteId}/settings/api-keys 创建）— 单站点凭据的影响范围更小，例如，可将其交给使用自托管站点的客户。

两种密钥的格式都类似于 typeroll_live_…；可通过门户撤销任一种密钥，任何使用该密钥的客户端都会立即停止工作。也可以通过 MCP 列出和撤销密钥（list_api_keys、revoke_api_key、list_organization_api_keys、revoke_organization_api_key）。新密钥及其他新凭据只能在门户中创建，这样创建者只能看到一次密钥，且密钥不会进入 Agent 对话或日志。

Stdio 快速入门

1. 在 Typeroll 门户中创建 API 密钥 — 请参阅上文的两个作用域选项。组织级密钥通常是最佳默认选择。

2. 在 Agent 客户端中添加本地 MCP 服务。 此示例使用 mcpServers 架构；请根据客户端的文档配置进行调整：

   {
     "mcpServers": {
       "typeroll": {
         "command": "npx",
         "args": ["-y", "@typeroll/mcp-server"],
         "env": {
           "TYPEROLL_API_URL": "https://app.typeroll.com",
           "TYPEROLL_API_KEY": "typeroll_live_REPLACE_WITH_YOUR_KEY"
         }
       }
     }
   }
   

   如果使用自托管门户，请将 TYPEROLL_API_URL 指向该门户（例如 https://cms.example.com）。stdio 服务和 typeroll extension CLI 均要求使用 HTTPS，环回主机除外。

   如需使用可选的、与 Agent 无关的工作区，请运行 npx @typeroll/mcp-server init ./my-site。该命令会创建项目说明、简报、决策和 QA 文件。本地客户端配置为可选项，使用 --client claude|cursor|vscode 启用；配方也为可选项，使用 --recipes 启用。使用 --update 可升级未修改的生成文件，同时保留已有编辑内容。请参阅Agent 工作区。

3. 告诉 Agent 你想完成什么工作。 可以这样发送第一条消息：

   “连接到 Typeroll，告诉我你发现了什么 — 站点名称、页面数量、有哪些全局区块，以及定义了哪些内容类型。然后我会给你一项任务。”

   Agent 可以依次调用 get_site、get_site_capabilities、list_pages、list_partials、list_content_types 和 list_block_types，然后汇报结果。在选择 HTML 模式或报告缺少站点构建功能之前，必须先检查功能概览和区块选项板。

环境变量（stdio）

变量	必需	说明
TYPEROLL_API_URL	是	Typeroll 门户的基础 URL。必须使用 HTTPS；仅当主机为 localhost、127.0.0.1 或 [::1] 时，才接受普通 HTTP。
TYPEROLL_API_KEY	是	typeroll_live_… Bearer 令牌。
TYPEROLL_SITE_ID	有时需要	固定到特定站点。密钥可以访问多个站点时为必填；每个 stdio 进程只针对一个站点。若只能访问一个站点，则会自动检测。

Extension 开发者命令行工具

此软件包还会安装 typeroll。有了组织级 API 密钥，外部 Extension 仓库便可使用与门户相同的开发者和安装 API：

typeroll extension validate
typeroll extension push --draft
typeroll extension install --site test-site --config local-extension-config.json
typeroll extension configure --site test-site --installation install-abc \
  --config local-extension-config.json
typeroll extension promote 1.0.0

清单文件默认为 typeroll-extension.json；使用 --manifest 可选择其他文件。对于私有 Extension，install 会将站点添加到该 Extension 的 allowed_site_ids。仅提供站点 ID 时，只会匹配属于你自己的开发者组织的站点；若要在其他组织的站点上安装，请传入 --site <organization-id>/<site-id>，此格式会写入允许列表。本地验证是快速的预检。门户始终会执行完整的架构、兼容性、来源和资源哈希验证。extension configure 默认会排入生产部署；仅在批量更新并计划之后统一部署时，才传入 --no-deploy。

Agent 应先阅读的内容

此软件包附带 AGENTS.md，这是一份独立的指南，介绍 Typeroll 约定、常见操作，以及 Agent 需要遵守的安全边界。请让你的 Agent 阅读此文件，或使用 sections_only: true 调用 read_guide 工具，然后请求相关章节。加载本地配方时，请遵循客户端自身的说明。

工具范围

这些工具分属多个类别，总数超过 100 个。完整参考和具体操作配方请参阅 AGENTS.md。

• 技能 + 指南（自描述操作手册） — read_guide、 list_skills、read_skill。服务会在运行时公布自己的操作 指南和内置操作方案，无需本地副本。 read_guide 支持章节索引和单独章节；只有任务需要时才使用完整 手册。随后，list_skills 会列出任务操作方案（tr-new-site、 tr-migrate-wp、tr-brand、tr-responsive，等等）；read_skill name=… 可加载其中一项。所有读取操作都在本地完成——无需 API 密钥或站点 上下文——因此通过托管连接器和 stdio 使用时效果完全相同。
• 发现 — get_site、create_site（引导创建新站点——仅限组织级 密钥）、create_site_and_migrate / create_site_and_plan（创建新站点并 迁移 WordPress 或生成 AI 站点规划——仅限组织级密钥）、update_site （名称/slug/域名/语言；管理员还可设置 ai_scripts_enabled）、 list_versions、read_site_settings、update_site_settings（管理员； 包括门户「设置」表单接受的所有字段，例如 default_og_image、 twitter_handle、organization JSON-LD 和 staging_url）。
• 站点生命周期 — archive_site、restore_site 和 purge_site_media （清除已归档站点的媒体；不可撤销）。与门户中的操作一样，需要所有者组织的管理员权限。
• 访问权限 — 列出并撤销站点 API 密钥（list_api_keys、 revoke_api_key；撤销需要站点管理员权限）和组织 API 密钥 （list_organization_api_keys、revoke_organization_api_key）、 跨组织共享（list_site_shares、share_site、 update_site_share、revoke_site_share；需要站点管理员权限）以及编辑者邀请 链接（create_organization_invite、list_organization_invites、 revoke_organization_invite；需要组织密钥）。共享权限不会超出调用者自身的权限范围。 新 API 密钥只能在门户中创建，因此密钥不会经过 Agent 对话。
• 门户 AI 助手 — read_organization_ai_settings、 set_organization_ai_key、remove_organization_ai_key 和 set_organization_ai_site_access：设置组织自己的 Anthropic 密钥（经过验证、 加密且不会返回），并选择显示内置 AI 聊天的站点。需要组织密钥以及所有者/管理员权限。 MCP 本身不依赖此密钥。
• 工作流 — list_workflows、start_workflow（迁移、站点规划、 SEO/链接/性能审计、内容生成与改进、schema 标记、URL 一致性检查、重建与部署）、 get_workflow、approve_workflow。 启动工作流需要写入权限；rebuild_deploy 会发布内容，因此需要管理员权限。 只有在用户同意后才能批准审核关卡。
• 组织发布连接 — read_organization_publishing_connections（状态、修订版本和浏览器专用 OAuth 步骤所需的 connect_urls）、 diagnose_organization_github_connection（说明 GitHub 未连接的原因、拥有该 App 的每个账户，以及需要采取操作的人员和对应的一项修复方法）、 diagnose_organization_cloudflare_connection（说明 Hosting Group 的 Cloudflare 连接无法工作的原因、需要采取操作的人员和对应的一项修复方法，以及 Analytics 和重定向规则缺少哪些可选权限）、 disconnect_organization_publishing_provider、 connect_organization_cloudflare（客户 API 令牌）、 prepare_organization_media_storage、save_organization_media_access。 仅限组织密钥。
• 页面 — 列出、读取、批量读取、创建、更新（PATCH）、替换 （PUT）、批量更新、删除、克隆、获取预览、set_page_mode （在区块/HTML 之间切换；HTML 永远不会转换为区块）。
• 区块（实例） — get_page_blocks、add_block、 update_block、move_block、remove_block、duplicate_block、 set_block_responsive。这些工具都接受 target（页面、partial、页面 模板），因此同一组工具可编辑所有区块容器。
• 全局区块（partials） — 列出（默认使用摘要模式）、读取、 创建自由区块（区块或 HTML）、更新、替换、删除、 set_partial_mode、查找使用该区块的页面、make_block_global、 detach_global_block。区块页面通过 core/global_block 引用全局区块。
• 区块模板 — list_block_templates、read_block_template、 save_block_template、update_block_template、delete_block_template、 insert_block_template（插入独立副本）。
• 样式 — list_styles、create_style、update_style、 delete_style、apply_standard_styles。新的页眉/页脚应使用 tr-header-footer 中的原生 template/site_logo + core/navigation 方案。
• 区块类型 — 列出、读取、创建、更新、删除、 查找使用该区块类型的页面，以及 .tcblocks 导出/导入。 自定义客户端 JavaScript（script）会在 API 密钥的权限范围内接受，并像门户的区块类型编辑器一样记录审计日志。站点的「允许 AI 编写区块脚本」设置（update_site ai_scripts_enabled）仅控制门户内的聊天助手， 不影响 API 密钥或 MCP。
• 内容类型 — list_content_types、read_content_type、 create_content_type、update_content_type、delete_content_type。 每条记录都是一个 Page；list_pages 可按 content_type 筛选。 change_page_content_type 可重新归类 Page，同时不更改其身份或现有 URL。 page_completeness 会报告缺失和过时的值。
• 页面模板 — 列出/读取/创建/更新/删除可复用的区块布局， 包括文章/清单起始模板。可为每种内容类型设置默认模板，也可为每个 Page 设置覆盖模板。 正文仍是 Page 自己可编辑的区块树。
• 媒体 — get_import_readiness、get_media_upload_status（门户的 上传预检）、列出/读取、带签名的上传 URL、 upload_media_from_url、upload_media_batch_from_urls（1–50 个来源，每个最大 25 MiB，返回部分成功结果）、upload_media_inline、元数据 更新和删除。导入需要已验证的组织存储。使用 Core 0.1.97 时，URL 导入会通过客户的 Cloudflare transfer Worker 完成；门户和 MCP 均不会下载图片内容。对于本地文件， create_upload_url 会授予直接 R2 PUT 权限，随后调用 finalize_media 验证并锁定原始文件。 响应式变体由组织选定的构建提供方单独准备。普通创作上传在连接存储前 可以使用草稿存储；导入工具不得以此绕过就绪状态检查。旧版维护工具包括 finalize_all_media 和 generate_image_variants。 suggest_alt_text_context 会为 Agent 的视觉模型返回提示词。参见媒体 API 和工具指南。
• 渲染控制 — 语义化的 core/navigation、映射后的 core/post_card、core/table_of_contents、每个站点的 trailing_slash、精确的 iframe_allowed_hosts、icon_192，以及每个页面的 append_seo_suffix=false。区块编辑器支持带标签的枚举、 按行分隔的列表、嵌套的重复数组、区块 data 中的响应式值，以及内部页面 URL 选择器。
• 重定向 — 列出、创建、删除。更改 slug 时还会自动创建 301 重定向。
• 表单 — 列出、读取、创建、更新、删除、列出提交记录。 使用 core/form 区块或 HTML 模式下的 <x-form id="…" /> 引用来放置表单；预览/构建时，服务器会将两者展开为相同的完整签名表单外壳。 使用管理员密钥时，read_form 会返回表单的电子邮件通知和允许列表中的签名 Webhook（actions，密钥会隐藏）； create_form/update_form 可像门户的表单编辑器一样设置这些内容。
• 扩展安装 — 列出/读取已安装的扩展，并通过 API 密钥更新清单定义的安装配置， 使用 update_extension_installation_config；未提供的和已屏蔽的密钥会保留。可用此功能设置同意文案、政策链接等前端配置。默认会将生产部署加入队列；仅在批量修改并准备之后统一部署时，才传入 deploy: false。 同一管理员密钥还可执行门户中的其他安装操作：install_extension、 set_extension_installation_status（启用/禁用）、uninstall_extension、 pair_extension_issuer、read_extension_diagnostics 和 launch_extension_admin_page（生成一次性启动授权，用于向该页面的 launch_url 发送 POST；已获批准的原生页面使用 call_extension_admin）。 安装的服务器凭据需在门户中轮换，因此新凭据不会显示给 Agent。
• 扩展开发 — 使用组织级密钥可调用： list_developer_extensions、read_developer_extension、 update_developer_extension、save_extension_version、 publish_extension_version、set_extension_version_lifecycle 和 list_developer_extension_installations——与 typeroll extension CLI 使用相同的开发者 API。注册扩展和轮换其客户端密钥都会返回密钥，因此这些操作仅在门户和 CLI 中进行。
• 设置 — 读取 + 补丁更新，包括浅合并的 cookie_consent、 scripts_head / scripts_body_end / custom_css（由于调用者持有 API 密钥，因此这些内容可信；门户内的聊天 AI 无法访问）。
• 核心模块 — 列出旧版 apps 注册表、读取架构 + 已屏蔽的状态，并使用与内容和部署相同的管理员 API 密钥启用、配置或禁用任意模块。密钥字段在服务器端加密，且不会返回； Analytics 配置由平台处理。对于响应中包含 affects_build: true 的更新，需要在更新后部署。list_organization_analytics 和 set_organization_analytics 可查看和更改组织内所选站点的 Analytics（需要组织密钥）。
• 搜索 + 链接完整性 — search_pages 以及 check_internal_links；后者会解析已保存的数据库内容，检查页面、Page/Facet 路由、媒体和重定向链，而无需抓取公开站点。
• 批量操作 — bulk_replace_text，可对页面、partials、区块数据和自定义 Page 字段执行试运行。
• 迁移清单 — 批量添加/更新决策、递归执行 import_sitemap、 直接导入或通过 CSV 回退方式执行 import_gsc_performance，以及精简模式的 verify_migration_urls（除非明确请求，否则不返回成功的行）；此外还有 repair_migration_plain_text，可先试运行，再清理允许列表中的纯文本字段内旧版 WordPress 实体和标记。
• 分支 — 创建、读取、删除、合并、diff_version（显示分支相对于主版本新增、修改和删除的内容）和 reset_version（丢弃分支的所有更改，同时保留分支）。与门户一样，创建、合并、删除和重置都需要站点管理员权限。已部署的分支有自己的稳定地址，由 list_versions / read_version 通过 deploy_url 报告。
• 部署 — 触发（使用 dry_run 可仅构建而不发布）、列出、获取 状态。已完成的任务会报告 cost：构建消耗的服务器时间，并按阶段细分。 此估算基于费率表，而非账单记录。
• 预览 — get_preview_link（用于浏览器导航的签名 URL； 支持 page_id、slug 或 path；传入 include_working_copy: true 还可渲染未保存的草稿）。
• 草稿（缓冲区模型） — 每次内容写入都会存入每份文档的未保存草稿（工作副本）；部署和普通预览仅显示已保存内容。使用 commit_working_copy 或在写入调用中设置 save: true 可显式保存；使用 read_working_copy / discard_working_copy 检查/丢弃草稿。状态变更和结构操作会立即生效。
• 历史记录 — list_page_revisions、read_page_revision 和 restore_page_revision（恢复到草稿，或使用 save: true 保存）可撤销页面 在先前保存时发生的更改；preview_page_revision 会先将已保存状态渲染为完整预览文档。 list_partial_revisions、 read_partial_revision 和 restore_partial_revision 可对页眉、页脚和全局区块执行相同操作。

直接访问 REST API

如果不需要 MCP 封装，也可以通过 curl 直接访问相同的功能：

curl -H "Authorization: Bearer typeroll_live_..." \
  https://app.typeroll.com/api/v1/sites/<siteId>/pages

MCP 服务纯粹是其上的易用性层。完整的 v1 契约，包括负载封装、Page ID 和内容类型路由，详见 docs/v1-api.md。

安全模型

• API 密钥的作用范围为站点级或组织级（参见上文“密钥作用范围”）——由服务端强制执行。站点级密钥无法访问任何其他站点；组织级密钥可以访问组织自己的站点，以及明确共享给该组织的站点，并受共享权限级别限制。
• 管理密钥、共享、邀请、工作流和发布连接时，使用与门户相同的权限检查。密钥无法创建权限范围超过自身的密钥或共享；组织级路由会拒绝站点级密钥。
• 所有写入调用（POST、PUT、PATCH、DELETE）都会记录审计日志，包括密钥前缀、IP、方法、路径和状态。读取操作不记录（权衡成本与价值）。
• 速率限制：每个密钥每分钟可读取 600 次、写入 60 次。429 响应会带有 Retry-After 标头。
• 保存时，服务端会对 HTML 进行净化——从页面/局部内容（包括 core/html 块输出）中移除 <script>、事件处理程序和 javascript: URL。可编写脚本的区域是有意设置的例外，且密钥持有者可在自身权限范围内使用 API 密钥写入所有这些区域：站点设置中的 scripts_* 和 custom_css、块类型中的 script，以及 core/embed 块实例的 js 字段。这些写入与所有 API 写入一样，都会记录审计日志。只有门户内的聊天助手还受到额外限制，必须在每个站点单独选择启用（ai_scripts_enabled）；站点管理员可在门户中设置此项，也可通过 update_site 设置。
• 权限与门户相同。 每个工具都会应用相应门户操作所需的角色：设置、AI 脚本开关、应用、发布和域名需要管理员权限；归档、恢复和清除媒体则需要拥有该站点的组织管理员权限。
• 可随时在门户中撤销密钥。撤销会在下一个请求时生效（不会取消正在处理的请求，但下一个请求会返回 401）。

更多信息

• 完整的端到端生产环境设置指南及故障排查： docs/claude-code-mcp-setup.md
• Agent 操作指南：AGENTS.md
• 样板技能（站点构建、品牌、表单、SEO、博客、内容类型、迁移、图像生成、改版等）： skills/

许可证

MIT —— 详见 LICENSE。

使用 read_app_documentation 查找所选站点已启用模块和扩展的使用说明。只有已启用的安装才会通过提供方经过身份验证的文档契约获取私有应用指南；这些指南不会打包到 MCP 中。通用发现需要 Core 0.2.8；受保护指南需要应用隔离版本。

Agent 工作区与精简发现

MCP 0.45.23 引入了与 Agent 无关的 typeroll init 工作区、可选客户端适配器、安全的基于哈希的 init --update，以及只读的 typeroll doctor。使用 workspace-mcp 将本地调用绑定到 typeroll.json；其中不会存储凭据。由于 typeroll.json 会提交到版本库，只有当其 portal 为 https://app.typeroll.com 或与私下设置的 TYPEROLL_API_URL 匹配时，才会接收 API 密钥。配方是可选的，不会自动注入。

精简模式会公开五个发现／执行工具，而非所有架构。在托管端点上选择 ?tools=compact（Core 0.2.27+）、在工作区中设置 tool_mode，或在旧版 stdio 中设置 TYPEROLL_MCP_TOOL_MODE=compact。完整模式仍然可用。读／写／管理封装器共用常规验证和授权。

有关文件夹布局、命令、版本要求和上下文预算建议，请参阅Agent 工作区。

个人连接与打包工作流

个人 OAuth 默认使用精简发现。阅读 tr-edit-site 了解编辑工作流，并在选择站点后实时获取站点／应用说明。此流程适用于 Cloud 和自托管 Core。 插件包说明介绍了可复现的 ChatGPT/Codex 和 Claude 套件；尚未提交任何目录收录申请。