Journey / SameUp CMS MCP Server

Journey / SameUp CMS 向けに開発された Model Context Protocol (MCP) サーバーです。AI アシスタント (Claude Desktop、Cursor、Antigravity など) が CMS REST API と直接通信して、コンポーネントとページ管理を行えるようにします。

特徴

• モダンな TypeScript & MCP SDK: @modelcontextprotocol/sdk と zod に基づく型安全なツール。

• 自動認証: CMS API (/api/v1/login) に自動ログインし、返された認証 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 上に新しいコンポーネントテンプレートを定義します。1回の呼び出しで、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"
      }
    }
  }
}