@jhl8041/dooray-mcp 0.1.5 → 0.1.6

package/docs/project-overview.md

@@ -0,0 +1,105 @@
+# Dooray MCP Server - 프로젝트 개요
+
+## 소개
+
+**Dooray MCP Server**는 [Dooray](https://dooray.com) 프로젝트 관리 시스템과 AI 어시스턴트(Claude)를 연결하는 **Model Context Protocol (MCP)** 서버입니다.
+
+이 서버를 통해 Claude가 Dooray의 프로젝트, 업무(Task), 마일스톤, 태그 등을 조회하고 관리할 수 있습니다.
+
+## 핵심 정보
+
+| 항목 | 값 |
+|------|-----|
+| **프로젝트 이름** | @jhl8041/dooray-mcp |
+| **버전** | 0.1.5 |
+| **프로젝트 타입** | CLI / MCP Server |
+| **라이선스** | MIT |
+| **저장소** | https://github.com/jhl8041/dooray-mcp |
+
+## 기술 스택
+
+| 카테고리 | 기술 | 버전 | 용도 |
+|----------|------|------|------|
+| **언어** | TypeScript | 5.7.2 | 정적 타입 지원 |
+| **런타임** | Node.js | >= 18.0.0 | 서버 실행 환경 |
+| **프로토콜** | MCP SDK | 1.0.4 | Model Context Protocol 구현 |
+| **HTTP** | Axios | 1.7.9 | Dooray API 통신 |
+| **검증** | Zod | 3.24.1 | 입력 스키마 검증 |
+| **환경변수** | dotenv | 16.4.7 | 환경 설정 로드 |
+
+## 아키텍처 패턴
+
+이 프로젝트는 다음 아키텍처 패턴을 따릅니다:
+
+### 1. Tool Pattern (도구 패턴)
+각 MCP 도구는 일관된 구조를 가집니다:
+- **Schema**: Zod를 이용한 입력 검증 스키마
+- **Handler**: 비즈니스 로직을 실행하는 비동기 함수
+- **Tool Definition**: MCP에 등록되는 도구 메타데이터
+
+### 2. API Client Pattern (API 클라이언트 패턴)
+- 싱글톤 패턴의 `DoorayClient` 클래스
+- Axios 인터셉터를 활용한 인증 및 에러 처리
+- 표준화된 응답 처리 (`extractResult`, `extractPaginatedResult`)
+
+### 3. Layered Architecture (계층형 아키텍처)
+```
+src/
+├── index.ts          # 엔트리 포인트 (MCP 서버)
+├── api/              # API 계층 (HTTP 통신)
+├── tools/            # 도구 계층 (MCP 도구 구현)
+├── types/            # 타입 정의 계층
+└── utils/            # 유틸리티 계층
+```
+
+## 주요 기능
+
+### MCP 도구 (17개)
+
+**공통 도구 (1개)**
+- `get-my-member-info` - 현재 사용자 정보 조회
+
+**프로젝트 도구 (16개)**
+- 프로젝트 조회: `get-project-list`, `get-project`
+- 업무 관리: `get-task-list`, `get-task`, `create-task`, `update-task`
+- 댓글 관리: `create-task-comment`, `get-task-comment-list`, `update-task-comment`
+- 메타데이터: `get-milestone-list`, `get-tag-list`, `get-project-workflow-list`
+- 템플릿: `get-project-template-list`, `get-project-template`
+- 멤버: `get-project-member-list`, `get-project-member-group-list`
+
+## 사용 방법
+
+### 설치
+```bash
+npm install -g @jhl8041/dooray-mcp
+```
+
+### 환경 변수 설정
+```bash
+export DOORAY_API_TOKEN=<발급받은_토큰>
+```
+
+### Claude Desktop 연동
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "dooray": {
+      "command": "npx @jhl8041/dooray-mcp@latest",
+      "env": { "DOORAY_API_TOKEN": "발급받은_토큰" }
+    }
+  }
+}
+```
+
+## 관련 문서
+
+- [아키텍처 문서](./architecture.md)
+- [소스 트리 분석](./source-tree-analysis.md)
+- [개발 가이드](./development-guide.md)
+
+## 외부 링크
+
+- [Dooray 공식 사이트](https://dooray.com)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Dooray API 문서](https://dooray.com/docs/api)

package/docs/project-scan-report.json

@@ -0,0 +1,120 @@
+{
+  "workflow_version": "1.2.0",
+  "timestamps": {
+    "started": "2026-01-27T00:00:00.000Z",
+    "last_updated": "2026-01-27T00:15:00.000Z",
+    "completed": "2026-01-27T00:15:00.000Z"
+  },
+  "mode": "initial_scan",
+  "scan_level": "deep",
+  "project_root": "/Users/nhn/repository/dooray-mcp",
+  "output_folder": "/Users/nhn/repository/dooray-mcp/docs",
+  "completed_steps": [
+    {
+      "step": "step_0.5",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:01:00.000Z",
+      "summary": "Loaded documentation requirements for cli project type"
+    },
+    {
+      "step": "step_1",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:02:00.000Z",
+      "summary": "Classified as monolith with 1 part (cli type)"
+    },
+    {
+      "step": "step_2",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:03:00.000Z",
+      "summary": "Found 2 existing docs (README.md, CLAUDE.md)"
+    },
+    {
+      "step": "step_3",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:04:00.000Z",
+      "summary": "Tech stack: TypeScript 5.7, MCP SDK 1.0.4, Node.js 18+"
+    },
+    {
+      "step": "step_4",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:08:00.000Z",
+      "summary": "Deep scan complete - analyzed index.ts, api/, tools/, types/, utils/"
+    },
+    {
+      "step": "step_5",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:09:00.000Z",
+      "summary": "Source tree documented with 5 critical directories"
+    },
+    {
+      "step": "step_6",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:10:00.000Z",
+      "summary": "Dev setup and build commands documented"
+    },
+    {
+      "step": "step_8",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:11:00.000Z",
+      "summary": "Architecture documentation written"
+    },
+    {
+      "step": "step_9",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:13:00.000Z",
+      "summary": "All supporting docs written (overview, source-tree, dev-guide)"
+    },
+    {
+      "step": "step_10",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:14:00.000Z",
+      "summary": "Master index generated"
+    },
+    {
+      "step": "step_12",
+      "status": "completed",
+      "timestamp": "2026-01-27T00:15:00.000Z",
+      "summary": "Workflow complete"
+    }
+  ],
+  "current_step": "completed",
+  "findings": {
+    "project_classification": {
+      "repository_type": "monolith",
+      "parts_count": 1,
+      "primary_tech": "TypeScript + MCP SDK"
+    },
+    "technology_stack": {
+      "language": "TypeScript 5.7.2",
+      "runtime": "Node.js >= 18.0.0",
+      "framework": "MCP SDK 1.0.4",
+      "http_client": "Axios 1.7.9",
+      "validation": "Zod 3.24.1"
+    },
+    "architecture": {
+      "pattern": "Tool-based MCP Server",
+      "layers": ["Entry Point", "API Client", "Tools", "Types", "Utils"],
+      "tools_count": 17
+    },
+    "existing_docs": [
+      "README.md",
+      "CLAUDE.md"
+    ]
+  },
+  "project_types": [
+    {
+      "part_id": "main",
+      "project_type_id": "cli",
+      "display_name": "CLI / MCP Server"
+    }
+  ],
+  "outputs_generated": [
+    "project-scan-report.json",
+    "project-overview.md",
+    "architecture.md",
+    "source-tree-analysis.md",
+    "development-guide.md",
+    "index.md"
+  ],
+  "resume_instructions": "Workflow completed successfully"
+}

package/docs/source-tree-analysis.md

@@ -0,0 +1,240 @@
+# Dooray MCP Server - 소스 트리 분석
+
+## 전체 구조
+
+```
+dooray-mcp/
+├── src/                          # TypeScript 소스 코드
+│   ├── index.ts                  # [진입점] MCP 서버 메인
+│   ├── api/                      # API 통신 계층
+│   │   ├── client.ts             # Dooray HTTP 클라이언트
+│   │   ├── projects.ts           # 프로젝트/업무 API 함수
+│   │   └── common.ts             # 공통 API 유틸리티
+│   ├── tools/                    # MCP 도구 구현
+│   │   ├── common/               # 공통 도구 (1개)
+│   │   │   └── get-my-member-info.ts
+│   │   └── projects/             # 프로젝트 도구 (16개)
+│   │       ├── get-project-list.ts
+│   │       ├── get-project.ts
+│   │       ├── get-task-list.ts
+│   │       ├── get-task.ts
+│   │       ├── create-task.ts
+│   │       ├── update-task.ts
+│   │       ├── create-task-comment.ts
+│   │       ├── get-task-comment-list.ts
+│   │       ├── update-task-comment.ts
+│   │       ├── get-milestone-list.ts
+│   │       ├── get-tag-list.ts
+│   │       ├── get-project-template-list.ts
+│   │       ├── get-project-template.ts
+│   │       ├── get-project-member-list.ts
+│   │       ├── get-project-member-group-list.ts
+│   │       └── get-project-workflow-list.ts
+│   ├── types/                    # TypeScript 타입 정의
+│   │   ├── dooray-api.ts         # Dooray API 타입
+│   │   └── config.ts             # 설정 타입
+│   └── utils/                    # 유틸리티 함수
+│       ├── logger.ts             # 로깅 유틸리티
+│       ├── errors.ts             # 에러 클래스
+│       ├── member-transform.ts   # 멤버 데이터 변환
+│       └── response-filters.ts   # 응답 필터링
+├── dist/                         # 컴파일된 JavaScript (빌드 결과물)
+├── docs/                         # 프로젝트 문서
+├── node_modules/                 # npm 의존성
+├── package.json                  # 프로젝트 메타데이터
+├── package-lock.json             # 의존성 잠금 파일
+├── tsconfig.json                 # TypeScript 설정
+├── .env.example                  # 환경 변수 예시
+├── README.md                     # 프로젝트 README (한국어)
+├── CLAUDE.md                     # AI 어시스턴트용 문서 (영어)
+└── .gitignore                    # Git 제외 파일
+```
+
+## 디렉토리별 상세 설명
+
+### `src/` - 소스 코드 루트
+
+TypeScript 소스 코드가 위치하는 메인 디렉토리입니다.
+
+#### `src/index.ts` - 진입점
+
+MCP 서버의 메인 엔트리 포인트입니다.
+
+**역할:**
+- 환경 변수 로드 (dotenv)
+- API 클라이언트 초기화
+- MCP 서버 생성 및 설정
+- 도구 레지스트리 관리
+- 요청 핸들러 등록 (list_tools, call_tool)
+- stdio 트랜스포트 연결
+- 전역 에러 핸들링
+
+**의존성:** api/client, utils/logger, 모든 tools
+
+---
+
+### `src/api/` - API 통신 계층
+
+Dooray REST API와의 HTTP 통신을 담당합니다.
+
+#### `src/api/client.ts`
+
+**DoorayClient 클래스:**
+- Axios 인스턴스 래핑
+- 인증 헤더 자동 주입
+- 요청/응답 인터셉터
+- HTTP 메서드 (GET, POST, PUT, PATCH, DELETE)
+- 파일 업로드 지원
+
+**내보내기:**
+- `DoorayClient` 클래스
+- `initializeClient()` - 클라이언트 초기화
+- `getClient()` - 싱글톤 인스턴스 반환
+
+#### `src/api/projects.ts`
+
+Dooray Projects API 엔드포인트 함수들:
+
+| 함수 | 엔드포인트 | 용도 |
+|------|-----------|------|
+| `getProjects()` | GET /project/v1/projects | 프로젝트 목록 |
+| `getProjectDetails()` | GET /project/v1/projects/{id} | 프로젝트 상세 |
+| `getTasks()` | GET /project/v1/projects/{id}/posts | 업무 목록 |
+| `getTaskDetails()` | GET /project/v1/posts/{id} | 업무 상세 |
+| `createTask()` | POST /project/v1/projects/{id}/posts | 업무 생성 |
+| `createDraftTask()` | POST /project/v1/post-drafts | 임시 업무 생성 |
+| `updateTask()` | PUT /project/v1/projects/{id}/posts/{id} | 업무 수정 |
+| `createTaskComment()` | POST .../posts/{id}/logs | 댓글 생성 |
+| `getTaskComments()` | GET .../posts/{id}/logs | 댓글 목록 |
+| `updateTaskComment()` | PUT .../logs/{id} | 댓글 수정 |
+| `getMilestones()` | GET .../milestones | 마일스톤 목록 |
+| `getTags()` | GET .../tags | 태그 목록 |
+| `getProjectWorkflows()` | GET .../workflows | 워크플로우 목록 |
+| `getProjectTemplates()` | GET .../templates | 템플릿 목록 |
+| `getProjectTemplate()` | GET .../templates/{id} | 템플릿 상세 |
+| `getProjectMembers()` | GET .../members | 멤버 목록 |
+| `getProjectMemberGroups()` | GET .../member-groups | 멤버 그룹 목록 |
+
+---
+
+### `src/tools/` - MCP 도구 계층
+
+각 파일은 하나의 MCP 도구를 정의합니다.
+
+**파일 구조 패턴:**
+```
+export const toolSchema = z.object({...});     // Zod 입력 스키마
+export async function toolHandler(args) {...}  // 핸들러 함수
+export const tool = { name, description, inputSchema }; // 도구 정의
+```
+
+#### `src/tools/common/`
+
+| 파일 | 도구 이름 | 용도 |
+|------|-----------|------|
+| `get-my-member-info.ts` | `get-my-member-info` | 현재 사용자 정보 |
+
+#### `src/tools/projects/`
+
+| 파일 | 도구 이름 | 용도 |
+|------|-----------|------|
+| `get-project-list.ts` | `get-project-list` | 프로젝트 목록 조회 |
+| `get-project.ts` | `get-project` | 프로젝트 상세 조회 |
+| `get-task-list.ts` | `get-task-list` | 업무 목록 (필터링/정렬) |
+| `get-task.ts` | `get-task` | 업무 상세 조회 |
+| `create-task.ts` | `create-task` | 업무 생성 (일반/임시) |
+| `update-task.ts` | `update-task` | 업무 수정 |
+| `create-task-comment.ts` | `create-task-comment` | 댓글 생성 |
+| `get-task-comment-list.ts` | `get-task-comment-list` | 댓글 목록 |
+| `update-task-comment.ts` | `update-task-comment` | 댓글 수정 |
+| `get-milestone-list.ts` | `get-milestone-list` | 마일스톤 목록 |
+| `get-tag-list.ts` | `get-tag-list` | 태그 목록 |
+| `get-project-workflow-list.ts` | `get-project-workflow-list` | 워크플로우 상태 |
+| `get-project-template-list.ts` | `get-project-template-list` | 템플릿 목록 |
+| `get-project-template.ts` | `get-project-template` | 템플릿 상세 |
+| `get-project-member-list.ts` | `get-project-member-list` | 멤버 목록 |
+| `get-project-member-group-list.ts` | `get-project-member-group-list` | 멤버 그룹 |
+
+---
+
+### `src/types/` - 타입 정의 계층
+
+#### `src/types/dooray-api.ts`
+
+Dooray API 관련 모든 TypeScript 타입:
+
+**공통 타입:**
+- `ApiResponse<T>` - API 응답 래퍼
+- `Member`, `MemberInfo` - 멤버 정보
+- `PaginatedResponse<T>` - 페이지네이션
+
+**도메인 타입:**
+- `Project`, `ProjectListParams`
+- `Task`, `TaskListParams`, `CreateTaskParams`, `UpdateTaskParams`
+- `TaskComment`, `CreateTaskCommentParams`
+- `Milestone`, `Tag`, `Workflow`
+- `ProjectTemplate`, `ProjectMember`, `ProjectMemberGroup`
+
+#### `src/types/config.ts`
+
+설정 관련 타입:
+- `DoorayConfig` - 클라이언트 설정
+- `DoorayHeaders` - HTTP 헤더
+
+---
+
+### `src/utils/` - 유틸리티 계층
+
+#### `src/utils/logger.ts`
+
+간단한 로깅 유틸리티:
+- `LogLevel` enum (ERROR, WARN, INFO, DEBUG)
+- `Logger` 클래스 (싱글톤)
+- stderr 출력 (MCP stdio 분리)
+- `LOG_LEVEL` 환경 변수 지원
+
+#### `src/utils/errors.ts`
+
+커스텀 에러 클래스:
+- `DoorayAPIError` - API 에러 기본 클래스
+- `AuthenticationError` - 인증 실패 (401)
+- `ValidationError` - 입력 검증 실패
+- `formatError()` - 에러 메시지 포맷팅
+
+#### `src/utils/response-filters.ts`
+
+응답 데이터 필터링 (토큰 최적화):
+- `filterTaskForList()` - 목록용 간소화
+- `filterPaginatedResponse()` - 페이지네이션 응답 필터
+
+#### `src/utils/member-transform.ts`
+
+멤버 데이터 변환:
+- `transformMembers()` - 내부 → API 형식 변환
+
+---
+
+### 루트 디렉토리 파일
+
+| 파일 | 용도 |
+|------|------|
+| `package.json` | npm 프로젝트 설정 |
+| `tsconfig.json` | TypeScript 컴파일러 설정 |
+| `README.md` | 프로젝트 설명 (한국어) |
+| `CLAUDE.md` | AI 어시스턴트용 상세 문서 |
+| `.env.example` | 환경 변수 예시 |
+
+---
+
+### 빌드 출력 (`dist/`)
+
+`npm run build` 실행 시 생성:
+- `.js` - 컴파일된 JavaScript
+- `.d.ts` - TypeScript 선언 파일
+- `.js.map` - 소스맵
+
+## 관련 문서
+
+- [프로젝트 개요](./project-overview.md)
+- [아키텍처 문서](./architecture.md)
+- [개발 가이드](./development-guide.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhl8041/dooray-mcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "MCP server for Dooray",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",