Headlesshost Mcp

Headlesshost MCP 服务

一个模型上下文协议（MCP）服务，可与 Headlesshost 平台 API 完整通信。此服务支持 AI 助手通过 Headlesshost 平台管理内容站点、预发布站点、页面、版块、受众、用户和文件上传。

基于 @modelcontextprotocol/sdk v1.26 构建，包含工具注释、结构化日志记录和 Zod 输入验证。

演示

https://www.youtube.com/watch?v=xGGwcrI7gSo&feature=youtu.be

安装

1. 克隆此仓库

2. 安装依赖：

   npm install
   

3. 构建服务：

   npm run build
   

配置

服务需要通过 HEADLESSHOST_API_KEY 环境变量设置 Headlesshost API 密钥。

用法

使用 Claude Desktop

将此配置添加到 Claude Desktop 配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

本地开发

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "node",
      "args": ["/path/to/kapiti.mcp/build/index.js"],
      "env": {
        "HEADLESSHOST_API_KEY": "your-auth-token"
      }
    }
  }
}

通过 npx

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "npx",
      "args": ["headlesshost-mcp-server@latest"],
      "env": {
        "HEADLESSHOST_API_KEY": "your-auth-token"
      }
    }
  }
}

使用 Claude Code

添加到 .claude/settings.json：

{
  "mcpServers": {
    "headlesshost-cms": {
      "command": "node",
      "args": ["/path/to/kapiti.mcp/build/index.js"],
      "env": {
        "HEADLESSHOST_API_KEY": "your-auth-token"
      }
    }
  }
}

使用其他 MCP 客户端

此服务兼容任何 MCP 客户端，包括 VS Code、Zed Editor、Continue.dev 和自定义 MCP 实现。

将客户端配置为使用：

• 命令：node
• 参数：["/path/to/kapiti.mcp/build/index.js"]
• 环境变量：设置 HEADLESSHOST_API_KEY

工具（53）

所有工具均包含 MCP 注释（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），以帮助客户端呈现适当的界面和确认提示。

通用（3）

工具	描述
ping	测试身份验证和连接
health	检查 API 健康状态
get_ref_data	获取系统参考数据和查找项

用户管理（4）

工具	描述
create_user	在当前账户中创建新用户
get_user	按 ID 获取用户详情
update_user	更新用户信息和声明
delete_user	从系统中删除用户

账户管理（3）

工具	描述
create_account	创建新用户账户
get_account	获取当前账户信息
update_account	更新账户信息

文件上传（3）

工具	描述
upload_user_profile_image	为用户上传个人资料图片
upload_staging_site_file	向预发布站点上传文件
upload_staging_site_image	向预发布站点上传图片

内容站点（5）

工具	描述
create_content_site	创建新的内容站点
get_content_sites	获取账户中的所有内容站点
get_content_site	按 ID 获取内容站点详情
update_content_site	更新内容站点信息
delete_content_site	删除内容站点

预发布站点（9）

工具	描述
update_staging_site	更新预发布站点信息
delete_staging_site	删除预发布站点
publish_staging_site	发布预发布站点，使其上线
get_staging_site	获取预发布站点详情
get_staging_site_pages	获取预发布站点页面
get_staging_site_configuration	获取预发布站点配置，包括版块类型
get_staging_site_logs	获取自上次发布以来的变更日志
get_published_sites	获取内容站点对应的已发布站点
revert_staging_site	将预发布站点还原到之前的状态
clone_staging_site	克隆预发布站点

页面（6）

工具	描述
create_staging_site_page	创建新页面
get_staging_site_page	获取页面详情（可选包含版块）
update_staging_site_page	更新页面
delete_staging_site_page	删除页面
revert_staging_site_page	将页面还原到之前的状态
get_staging_site_page_logs	获取页面自上次发布以来的变更日志

版块（7）

工具	描述
create_staging_site_section	在页面中创建新版块
get_staging_site_section	获取版块详情
update_staging_site_section	更新版块
delete_staging_site_section	删除版块
publish_staging_site_section	发布单个版块
revert_staging_site_section	将版块还原到之前的状态
get_staging_site_section_logs	获取版块自上次发布以来的变更日志

站点受众（4）

工具	描述
create_staging_site_audience	为站点创建受众（语言区域/细分组合）
get_staging_site_audience	获取受众详情
update_staging_site_audience	更新受众
delete_staging_site_audience	删除受众（无法删除基础受众）

版块受众（4）

工具	描述
create_staging_site_section_audience	为版块创建受众覆盖设置
get_staging_site_section_audience	获取版块受众详情
update_staging_site_section_audience	更新版块受众覆盖设置
delete_staging_site_section_audience	删除版块受众覆盖设置

分析（4）

工具	描述
get_content_site_logs	获取最近 15 条活动日志
get_content_site_hits	获取每日访问量分析
get_content_site_accounts	获取关联账号
get_content_site_claims	获取当前用户声明

资源

该服务提供 2 个用于配置和监控的资源：

• API 配置 (config://api) — 可用端点和当前设置
• API 健康状态 (health://api) — 实时连接状态和响应时间

开发

构建服务：

npm run build

在开发模式下运行：

npm run dev

监视更改：

npm run watch

运行 MCP 检查器以进行调试：

npm run inspector

错误处理

该服务包含结构化错误处理：

• API 身份验证验证
• 网络连接检查
• 通过 MCP 日志记录功能进行结构化日志记录（错误会发送给客户端）
• API 超时时的优雅回退

安全性

• 所有操作均需进行 API 密钥身份验证
• 安全处理环境变量
• 使用 Zod 模式验证所有工具输入
• 工具注释会向客户端标示破坏性操作