dooray-mcp-js

Node.js로 구현된 Dooray MCP 서버입니다. dooray-go/dooray-mcp의 도구 이름과 API 동작을 따르지만 Go나 Homebrew가 필요하지 않습니다.

요구 사항

• Node.js 18 이상

• Dooray 개인 API 토큰

Related MCP server: mcp-gdocs

공식 문서

• Dooray API 공식 문서

범위

이 MCP 서버는 모든 Dooray API를 래핑하지 않습니다. 자주 사용되는 계정, 캘린더, 프로젝트, 게시물, 첨부 파일, 메신저 API에 중점을 둡니다.

대부분의 /admin/v1 및 /admin/v2 관리 API는 기본적으로 의도적으로 노출되지 않습니다. 특히 쓰기 가능한 관리 엔드포인트는 노출되지 않습니다.

읽기 전용 모드

Dooray 개인 API 토큰은 읽기 전용과 쓰기 권한이 분리되어 발급되지 않습니다. 쓰기 API를 호출할 수 있는 토큰은 Dooray API 수준에서 여전히 해당 권한을 가질 수 있습니다.

더 안전한 설치를 위해 이 서버는 MCP 도구 계층에서 읽기 전용 모드를 제공합니다. 읽기 전용 모드에서는 쓰기 가능한 도구가 tools/list에 노출되지 않으며 tools/call을 통해 호출할 수 없습니다.

실행

npx -y dooray-mcp-js --token "{personal-token}"

환경 변수를 사용할 수도 있습니다:

DOORAY_TOKEN="{personal-token}" npx -y dooray-mcp-js

읽기 전용 도구만 노출하여 실행:

DOORAY_TOKEN="{personal-token}" npx -y dooray-mcp-js --mode read-only

Codex

Codex에 패키지를 직접 등록:

codex mcp add dooray-mcp-js --env DOORAY_TOKEN="$DOORAY_TOKEN" -- npx -y dooray-mcp-js

토큰이 아직 DOORAY_TOKEN에 없으면 등록 시 전달하세요:

codex mcp add dooray-mcp-js --env DOORAY_TOKEN="{personal-token}" -- npx -y dooray-mcp-js

서버는 Codex가 시작할 때 DOORAY_TOKEN을 읽으므로 토큰을 명령 인수에 포함할 필요가 없습니다.

Codex 읽기 전용 등록

동일한 패키지와 토큰으로 두 번째 MCP 서버를 등록하되 읽기 전용 도구만 노출하세요:

codex mcp add dooray-mcp-js-read-only --env DOORAY_TOKEN="$DOORAY_TOKEN" -- npx -y dooray-mcp-js --mode read-only

환경 변수를 통해 모드를 설정할 수도 있습니다:

codex mcp add dooray-mcp-js-read-only --env DOORAY_TOKEN="$DOORAY_TOKEN" --env DOORAY_MCP_MODE=read-only -- npx -y dooray-mcp-js

Claude Desktop

{
  "mcpServers": {
    "dooray-mcp-js": {
      "command": "npx",
      "args": ["-y", "dooray-mcp-js"],
      "env": {
        "DOORAY_TOKEN": "{personal-token}"
      }
    }
  }
}

읽기 전용 Claude Desktop 구성:

{
  "mcpServers": {
    "dooray-mcp-js-read-only": {
      "command": "npx",
      "args": ["-y", "dooray-mcp-js", "--mode", "read-only"],
      "env": {
        "DOORAY_TOKEN": "{personal-token}"
      }
    }
  }
}

Claude Code

claude mcp add dooray-mcp-js --env DOORAY_TOKEN="{personal-token}" -- npx -y dooray-mcp-js

읽기 전용 등록:

claude mcp add dooray-mcp-js-read-only --env DOORAY_TOKEN="{personal-token}" -- npx -y dooray-mcp-js --mode read-only

프로젝트 구조

dooray-mcp-js/
├── src/
│   └── index.js      # MCP server entry point
├── package.json
└── README.md

로컬 개발

클론한 저장소에서 작업할 때 로컬 진입점을 직접 실행하세요:

DOORAY_TOKEN="{personal-token}" node ./src/index.js

도구

dooray-mcp-js 패키지는 현재 구현된 모든 도구를 노출합니다. 현재 서버에는 아직 삭제 도구가 없습니다.

• dooray_messenger

• dooray_calendar_calendars

• dooray_calendar_events

• dooray_calendar_post_event

• dooray_account_members

• dooray_account_member

• dooray_project

• dooray_posts (작업 게시물을 찾고 작업 본문과 fileIdList를 노출합니다. fileIdList에는 본문에 포함된 이미지/파일이 포함될 수 있습니다.)

• dooray_post_logs (게시물의 댓글과 활동 로그를 찾습니다)

• dooray_post_log (ID로 댓글 또는 활동 로그 하나를 찾습니다)

• dooray_post_log_create (게시물에 댓글을 추가합니다. 본문은 { "mimeType": "text/x-markdown", "content": "..." } 형식입니다.)

• dooray_post_log_update (동일한 본문 형식으로 댓글 또는 활동 로그를 업데이트합니다)

• dooray_post_files (일반 첨부 파일을 나열합니다. 빈 결과나 AUTH_FORBIDDEN_ERROR는 fileIdList 항목을 다운로드할 수 있는지 여부를 결정하지 않습니다.)

• dooray_post_file_download (dooray_posts.fileIdList의 ID(본문에 포함된 이미지 포함) 또는 media=raw가 있는 일반 첨부 파일 ID를 다운로드합니다. 권한 부여는 구성된 API 오리진과 HTTPS file-api.dooray.com으로 제한됩니다.)

• os

작업 URL 및 본문 파일 읽기

요청이 Dooray 작업 본문, 본문에 포함된 이미지 또는 본문이 참조하는 파일을 요구할 때 이 워크플로우를 사용하세요. 댓글과 활동 로그는 별도의 리소스이며 이 워크플로우에 필요하지 않습니다.

1. 작업 URL을 파싱합니다. /task/{projectId}/{postId}는 두 ID를 직접 제공합니다. 레거시 /project/tasks/{postId} 형식은 postId만 제공하므로 끝의 숫자를 projectId로 사용해서는 안 됩니다.

2. 레거시 URL 형식에 대해서만 프로젝트를 확인합니다. operation=find_projects와 필수 type, scope, state 필터로 dooray_project를 호출합니다. 관련 필터 조합을 반복하고 size를 최대 100으로 하여 page 값을 계속 진행하면서 모든 결과 페이지를 확인합니다.

3. 일치하는 게시물을 검색합니다. 새 URL 형식의 프로젝트 ID 또는 레거시 URL에서 발견된 후보 프로젝트 ID로 dooray_posts를 호출합니다. size를 최대 100으로 사용하고 필요에 따라 page 값을 계속 진행하면서 반환된 게시물 ID를 URL의 postId와 대조합니다. 잘못된 프로젝트 ID 하나로 조회하거나 첫 번째 결과 페이지만 확인하는 것은 작업 또는 해당 파일을 사용할 수 없다는 증거가 아닙니다.

4. 일치하는 dooray_posts 결과에서 작업 본문을 읽습니다. 사용자가 명시적으로 댓글이나 활동 기록을 요청하지 않는 한 dooray_post_logs를 호출하지 마세요.

5. 일치하는 게시물에 fileIdList가 포함된 경우 검증된 동일한 projectId와 postId를 사용하여 나열된 모든 ID에 대해 dooray_post_file_download를 한 번씩 호출합니다. 이러한 ID는 일반적으로 작업 본문에 포함된 이미지를 나타내지만 다른 본문 파일을 나타낼 수도 있습니다.

6. 반환된 로컬 filePath를 이미지 뷰어 또는 적절한 문서 파서로 검사합니다. 다운로드 결과에는 fileName, mimeType, size, temporary도 포함됩니다.

dooray_post_files는 일반 첨부 파일을 나열하기 위해 노출되지만 본문 파일에 사용되는 fileIdList 경로와는 별개입니다. dooray_posts.fileIdList에서 직접 다운로드가 작동하더라도 빈 목록이나 AUTH_FORBIDDEN_ERROR를 반환할 수 있습니다. 따라서 두 결과 모두 본문 이미지나 파일에 접근할 수 없다는 증거로 보고해서는 안 됩니다. dooray_post_file_download의 fetch failed 오류나 시간 초과도 권한 결과가 아닌 전송 실패이므로 재시도하거나 별도로 보고해야 합니다. 검증된 projectId, postId, fileId로 직접 다운로드가 403 또는 404와 같은 최종 Dooray 응답을 반환하는 경우에만 파일을 접근 금지 또는 누락으로 보고하세요.

읽기 전용 모드 도구

--mode read-only 또는 DOORAY_MCP_MODE=read-only가 설정되면 쓰기 가능한 Dooray 도구가 tools/list에 노출되지 않으며 tools/call을 통해 호출할 수 없습니다.

읽기 전용 모드에서 노출:

• dooray_calendar_calendars

• dooray_calendar_events

• dooray_account_members

• dooray_account_member

• dooray_project

• dooray_posts

• dooray_post_logs

• dooray_post_log

• dooray_post_files

• dooray_post_file_download

• os

읽기 전용 모드에서 숨김:

• dooray_messenger

• dooray_calendar_post_event

• dooray_post_log_create

• dooray_post_log_update

옵션

• --token: Dooray 개인 API 토큰. 기본값은 DOORAY_TOKEN입니다.

• --endpoint: Dooray API 엔드포인트. 기본값은 https://api.dooray.com입니다.

• --mode: 도구 노출 모드. full 또는 read-only를 사용하세요. 기본값은 DOORAY_MCP_MODE 또는 full입니다.