Journey / SameUp CMS MCP Server

Journey / SameUp CMS용으로 개발된 Model Context Protocol (MCP) 서버입니다. AI 어시스턴트(Claude Desktop, Cursor, Antigravity 등)가 CMS REST API와 직접 대화하여 컴포넌트 및 페이지 관리를 수행할 수 있게 합니다.

기능

• Modern TypeScript & MCP SDK: @modelcontextprotocol/sdk 및 zod 기반의 타입 안전 도구.

• 자동 인증: CMS API(/api/v1/login)에 자동 로그인하고, 반환된 auth 쿠키(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"
      }
    }
  }
}