Adobe Analytics MCP Tool

Adobe Analytics 2.0 API를 위한 Model Context Protocol (MCP) 서버입니다.

빠른 시작

1. 빌드

npm install
npm run build

2. MCP 설정 파일에 추가

~/.cursor/mcp.json 파일에 다른 MCP 설정과 동일한 패턴으로 추가하세요:

"adobe-analytics": {
  "command": "npx",
  "args": ["-y", "mcp-adobe-analytics-tool@latest"]
}

또는 로컬 프로젝트를 직접 사용하려면:

"adobe-analytics": {
  "command": "npx",
  "args": ["-y", "node", "D:\\ai\\mcp-adobe-analytics-tool\\dist\\index.js"]
}

첫 번째 방법(npx 패키지)을 사용하려면 npm에 배포해야 합니다. 두 번째 방법(로컬 경로)을 사용하면 배포 없이 바로 사용할 수 있습니다.

기본값이 소스 코드에 설정되어 있으므로 환경 변수 설정이 필요 없습니다.

3. Cursor 재시작

Cursor를 재시작하면 MCP 서버가 자동으로 연결됩니다.

설치

npm install
npm run build

사용 가능한 도구

이 MCP 도구는 Adobe Analytics 2.0 API Swagger 스펙을 기반으로 구현되었습니다.

1. adobe_analytics_run_report

Adobe Analytics 리포트를 실행합니다.

매개변수:

• rsid (필수): 리포트 세트 ID
• metrics (필수): 지표 ID 목록 (예: ['pageviews', 'visits'])
• dimensions (선택): 차원 ID 목록 (첫 번째 차원만 사용)
• dateRange (선택): 날짜 범위 (예: '2024-01-01/2024-01-31' 또는 'YYYY-MM-DD/YYYY-MM-DD' 형식)
• limit (선택): 결과 제한 수
• page (선택): 페이지 번호

참고: 이 도구는 Adobe Analytics 2.0 API의 RankedRequest 구조를 사용합니다.

2. adobe_analytics_list_segments

세그먼트 목록을 조회합니다.

매개변수:

• rsids (선택): 리포트 세트 ID 목록 (쉼표로 구분)
• limit (선택): 페이지당 결과 수 (기본값: 10)
• page (선택): 페이지 번호 (기본값: 0)
• locale (선택): 로케일 (기본값: en_US)

3. adobe_analytics_list_calculated_metrics

계산된 지표 목록을 조회합니다.

매개변수:

• rsids (선택): 리포트 세트 ID 목록 (쉼표로 구분)
• limit (선택): 페이지당 결과 수 (기본값: 10)
• page (선택): 페이지 번호 (기본값: 0)
• locale (선택): 로케일 (기본값: en_US)

4. adobe_analytics_list_dimensions

차원 목록을 조회합니다.

매개변수:

• rsid (필수): 리포트 세트 ID
• locale (선택): 로케일 (기본값: en_US)
• segmentable (선택): 세그먼트에서 유효한 차원만 포함
• reportable (선택): 리포트에서 유효한 차원만 포함
• expansion (선택): 추가 메타데이터 필드 (예: ['tags', 'categories'])

5. adobe_analytics_list_metrics

지표 목록을 조회합니다.

매개변수:

• rsid (필수): 리포트 세트 ID
• locale (선택): 로케일 (기본값: en_US)
• segmentable (선택): 세그먼트에서 유효한 지표만 포함
• expansion (선택): 추가 메타데이터 필드 (예: ['tags', 'categories'])

환경 변수 설정 (선택적)

기본값이 소스 코드에 설정되어 있지만, 필요시 환경 변수로 오버라이드할 수 있습니다:

기본 설정 (코드에 포함)

• ADOBE_CLIENT_ID: babf2eab4da64a3581602b79448f3826
• ADOBE_ACCESS_TOKEN: 기본 Access Token (코드에 포함)
• ADOBE_GLOBAL_COMPANY_ID: ibanka1
• ADOBE_API_BASE_URL: https://analytics.adobe.io/api

커스터마이징

다른 설정을 사용하려면 .env 파일을 생성하거나 환경 변수를 설정하세요:

ADOBE_CLIENT_ID=your-client-id
ADOBE_ACCESS_TOKEN=your-access-token
ADOBE_GLOBAL_COMPANY_ID=your-company-id
ADOBE_API_BASE_URL=https://analytics.adobe.io/api

개발

빌드

npm run build

개발 모드

# stdio 모드
npm run dev

# HTTP 서버 모드
npm run dev:server

실행

# stdio 모드
npm start

# HTTP 서버 모드
npm run start:server

HTTP 서버 모드

HTTP 서버로 실행할 수도 있습니다:

npm run start:server

기본 포트는 3000입니다. 환경 변수 PORT로 변경할 수 있습니다.

엔드포인트

• GET /health: 헬스 체크
• GET /tools: 사용 가능한 도구 목록
• POST /tools/:toolName: 도구 실행

Docker

docker build -t mcp-adobe-analytics-tool .
docker run -p 3000:3000 mcp-adobe-analytics-tool

Adobe Analytics 인증 설정

Adobe Analytics API를 사용하려면 Adobe Developer Console에서 OAuth 인증을 설정해야 합니다.

기본 설정

현재 프로젝트에는 기본 인증 정보가 포함되어 있습니다:

• Client ID: babf2eab4da64a3581602b79448f3826
• Global Company ID: ibanka1
• Access Token: 코드에 기본값 포함

Access Token 만료

Access Token은 24시간 후 만료됩니다. 만료되면:

1. 새 Access Token을 발급받아 .env 파일에 설정하거나
2. JWT 방식으로 전환 (Private Key 필요)

JWT 방식 사용 (선택적)

Access Token 대신 JWT를 사용하려면:

ADOBE_CLIENT_ID=your-client-id
ADOBE_CLIENT_SECRET=your-client-secret
ADOBE_ORGANIZATION_ID=your-org-id
ADOBE_TECHNICAL_ACCOUNT_ID=your-tech-account-id
ADOBE_TECHNICAL_ACCOUNT_EMAIL=your-tech-account-email@techacct.adobe.com
ADOBE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----
ADOBE_GLOBAL_COMPANY_ID=your-company-id

중요: Global Company ID는 Adobe Analytics 조직의 고유 식별자입니다. 이 값은 모든 API 요청의 경로에 포함됩니다 (예: /{globalCompanyId}/reports).

API 스펙 기반 구현

이 MCP 도구는 Adobe Analytics 2.0 API의 공식 Swagger 스펙을 기반으로 구현되었습니다:

• Base URL: https://analytics.adobe.io/api
• 모든 엔드포인트는 /{globalCompanyId}/... 경로 형식 사용
• 인증: OAuth 2.0 JWT Bearer 토큰 + x-api-key 헤더
• 리포트 실행은 RankedRequest 구조 사용

라이선스

MIT