da-mcp

문서 작성(DA)을 위한 원격 Model Context Protocol(MCP) 서버입니다. 이 서버는 Claude나 ChatGPT와 같은 LLM 어시스턴트에게 DA 관리 작업에 대한 직접적인 접근을 제공합니다.

기능

• 10가지 DA 관리 도구: DA 저장소 관리를 위한 완전한 도구 세트

• 원격 접근: Cloudflare Workers에 배포 가능하며 전 세계 엣지 분산 지원

• 스트리밍 가능한 HTTP: 원격 서버를 위한 최신 MCP 전송 프로토콜

• 토큰 패스스루: Authorization 헤더에 DA API 토큰을 전달하는 간단한 인증 방식

• 프로덕션 준비: 오류 처리, 로깅, CORS 지원, 상태 확인 기능

• TypeScript: 신뢰성과 유지보수성을 위한 완전한 타입 기반 코드베이스

Related MCP server: Core Content Services MCP Server

아키텍처

┌─────────────────┐
│   MCP Client    │
│ (Claude/Cursor) │
└────────┬────────┘
         │ Streamable HTTP
         │ + DA Token
         ↓
┌─────────────────────────┐
│  DA MCP                 │
│  ┌──────────────────┐   │
│  │   MCP Server     │   │
│  │   (10 Tools)     │   │
│  └──────────────────┘   │
└───────────┬─────────────┘
            │ HTTPS + Token
            ↓
┌─────────────────────────┐
│  DA Admin API           │
│  (admin.da.live)        │
└─────────────────────────┘

프로젝트 구조

src/
├── index.ts              # Cloudflare Worker entry point
├── mcp/
│   ├── server.ts         # MCP server initialization
│   ├── tools.ts          # Tool definitions (schemas)
│   └── handlers.ts       # Tool implementation handlers
└── da-admin/
    ├── client.ts         # DA Admin API client
    └── types.ts          # TypeScript types

사용 가능한 도구

사전 요구 사항

• Node.js 18+ 및 npm

• Cloudflare 계정(무료 티어 사용 가능)

• Wrangler CLI 설치(npm install -g wrangler)

• DA 관리 API 토큰

설치

1. 저장소를 클론하고 의존성을 설치합니다:

git clone <repository-url>
cd da-mcp
npm install

2. Wrangler를 구성합니다:

필요한 경우 wrangler.toml을 편집하여 배포 설정을 사용자 지정합니다.

개발

로컬 개발

핫 리로드로 서버를 로컬에서 실행합니다:

npm run dev

서버는 http://localhost:8787에서 사용할 수 있습니다.

테스트 엔드포인트

• 상태 확인: http://localhost:8787/health

• MCP 엔드포인트: http://localhost:8787/mcp

MCP Inspector로 테스트

1. 로컬 서버를 시작합니다: npm run dev

2. MCP Inspector를 엽니다.

3. 연결을 구성합니다:

   • 유형: Streamable HTTP

   • URL: http://localhost:8787/mcp

   • 헤더: Authorization: Bearer YOUR_DA_TOKEN

배포

Cloudflare Workers에 배포

# Deploy to production
npm run deploy

# Or deploy to development environment
wrangler deploy --env development

공개 URL

배포 후 MCP 서버는 다음 주소에서 접근할 수 있습니다:

• 직접 MCP 엔드포인트:
  https://da-mcp.adobeaem.workers.dev/mcp

• AEM API 라우터를 통한 IMS 인증:
  https://mcp.adobeaemcloud.com/adobe/mcp/da
  (Adobe IMS 로그인을 지원합니다. 자세한 내용은 아래 인증 섹션을 참조하세요.)

클라이언트 구성

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 이에 상응하는 파일에 추가합니다:

{
  "mcpServers": {
    "da-live-admin": {
      "type": "streamable-http",
      "url": "https://da-mcp.adobeaem.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DA_USER_IMS_TOKEN"
      }
    }
  }
}

VS Code / Cursor

.vscode/mcp.json 또는 Cursor 설정에 추가합니다:

{
  "mcpServers": {
    "da-admin-mcp-direct": {
      "url": "https://da-mcp.adobeaem.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_DA_USER_IMS_TOKEN"
      }
    },
    "da-prod-mcp": {
      "url": "https://mcp.adobeaemcloud.com/adobe/mcp/da"
    }
  }
}

인증

서버는 간단한 토큰 패스스루 인증을 사용합니다:

1. 클라이언트가 Authorization 헤더에 DA 관리 API 토큰을 보냅니다.

2. 서버가 토큰을 추출하여 DA 관리 API에 전달합니다.

3. DA 관리 API에 대한 모든 요청은 이 토큰을 사용합니다.

Authorization 헤더 형식:

Authorization: Bearer YOUR_DA_USER_IMS_TOKEN

또는 간단히:

Authorization: YOUR_DA_USER_IMS_TOKEN

참고: API 라우터의 공개(인증된) URL을 통해 API에 접근하는 경우, IMS(Adobe Identity Management Service) 로그인은 AEM API 라우터에서 자동으로 처리됩니다. 이 경우 Authorization 헤더에 DA 관리 API 토큰을 제공할 필요가 없습니다—IMS 로그인 흐름이 인증을 제공합니다.

사용 예시

구성 후 AI 어시스턴트에게 DA 작업을 요청할 수 있습니다:

Claude, can you list all the sources in the adobe/my-docs repository?

Please get the content of docs/index.md from the adobe/my-docs repository.

Create a new file at docs/new-page.md with some markdown content.

API 엔드포인트

GET /health

서버 상태를 반환하는 상태 확인 엔드포인트입니다.

응답:

{
  "status": "healthy",
  "service": "da-mcp",
  "version": "1.0.0",
  "environment": "production",
  "timestamp": "2025-01-07T12:00:00.000Z"
}

POST /mcp

도구 실행을 위한 MCP 프로토콜 엔드포인트입니다. DA 관리 API 토큰이 포함된 Authorization 헤더가 필요합니다.

오류 처리

모든 도구에는 포괄적인 오류 처리가 포함되어 있습니다:

• 401 인증 실패: DA 관리 토큰이 없거나 유효하지 않음

• 404 찾을 수 없음: 잘못된 엔드포인트

• 408 시간 초과: 요청이 30초 이상 걸림

• 500 내부 오류: 세부 정보가 포함된 서버 측 오류

오류는 LLM 클라이언트가 쉽게 이해할 수 있도록 형식화됩니다.

로깅

서버는 중요한 이벤트와 오류를 Cloudflare Workers 로그에 기록합니다:

# View logs in real-time
wrangler tail

# View logs for specific environment
wrangler tail --env production

모니터링

배포된 Worker를 모니터링합니다:

1. Cloudflare 대시보드: 호출, 오류, 성능 확인

2. Wrangler Tail: 실시간 로그(wrangler tail)

3. 상태 엔드포인트: /health에서 정기적인 상태 확인

기여

기여를 환영합니다! 다음을 수행해 주세요:

1. 저장소를 포크합니다.

2. 기능 브랜치를 만듭니다.

3. 테스트와 함께 변경 사항을 적용합니다.

4. 풀 리퀘스트를 제출합니다.