Journey / SameUp CMS MCP Server

为 Journey / SameUp CMS 开发的模型上下文协议（MCP）服务器。它使人工智能助手（如 Claude Desktop、Cursor、Antigravity 等）能够直接与 CMS REST API 通信，从而进行组件和页面管理。

功能

• 现代 TypeScript 与 MCP SDK： 基于 @modelcontextprotocol/sdk 和 zod 的类型安全工具。

• 自动身份验证： 自动登录 CMS API（/api/v1/login），保存返回的 auth cookie（at），并在过期时自动刷新。

• 兼容本地开发： 自动容忍自签名（self-signed）SSL 证书（CMS_IGNORE_SSL=true）。

安装与运行

1. 安装依赖

pnpm install

2. 环境变量 (.env)

在根目录中配置 .env 文件：

CMS_API_URL=https://api-journey.sameup.dev
CMS_EMAIL=your-admin-email@sameup.co
CMS_PASSWORD=your-secure-password
CMS_IGNORE_SSL=true

3. 编译与启动

# Projeyi derle
pnpm run build

# Doğrudan derlenmiş dosyayı çalıştır
pnpm start

# Geliştirme modu (Hot reload)
pnpm run dev

可用的 MCP 工具 (Tools)

1. list_components

列出 SameUp CMS 上定义的所有活动组件（Custom、SingleLine、Markdown、Photo、Dropdown 等）。

参数：

• search (string, 可选): 按组件标题或 slug 过滤（例如："banner"、"markdown"）。

• type (string, 可选): 按组件类型过滤（例如："Custom"、"SingleLine"、"Markdown"）。

• includeDetails (boolean, 可选, 默认: false): 当传入 true 时，还会获取 Custom 组件的子字段（children）。

2. get_component_detail

根据特定组件的 ID 或 Slug 信息获取其所有属性；如果该组件为 Custom 类型，则同时以层级结构获取其子组件（children）。

参数：

• id (number, 可选): 组件的数字 ID（例如：1、25）。

• slug (string, 可选): 组件的 slug 名称（例如："announcements"、"app-banner"）。 （注意：必须至少提供 id 或 slug 字段之一）。

3. create_component

在 CMS 上定义一个新的组件模板。通过一次调用即可同时创建 Custom 主组件及其关联的 children 字段。

参数：

• title (string, 必填): 组件名称（例如："Hero Banner"、"Feature Card"）。

• slug (string, 必填): 与前端匹配的唯一 slug（例如："hero-banner"、"feature-card"）。

• componentType (string, 必填): "Custom"、"SingleLine"、"Markdown"、"Photo"、"Document"、"Dropdown"、"Video"、"Form"、"FormItem"、"List"。

• canBeRepeated (boolean, 可选, 默认: false): 是否可重复列表？

• reusable (boolean, 可选, 默认: true): 是否可重用？

• data (string, 可选): 默认数据/文本。

• parentId (number, 可选): 如果要添加到现有主组件下，则为父组件 ID。

• children (array, 可选): Custom 组件的子字段列表（title、slug、componentType、canBeRepeated、reusable、data）。

IDE / MCP 客户端配置

Claude Desktop / Cursor / Antigravity 配置

您可以向 mcp_config.json 或 claude_desktop_config.json 文件中添加以下代码块：

{
  "mcpServers": {
    "journey-cms": {
      "command": "node",
      "args": [
        "/path/to/journey-mcp/dist/index.js"
      ],
      "env": {
        "CMS_API_URL": "https://api-journey.sameup.dev",
        "CMS_EMAIL": "your-admin-email@sameup.co",
        "CMS_PASSWORD": "your-secure-password",
        "CMS_IGNORE_SSL": "true"
      }
    }
  }
}