@jhl8041/dooray-mcp 0.1.5 → 0.1.7

package/docs/architecture.md

@@ -0,0 +1,227 @@
+# Dooray MCP Server - 아키텍처 문서
+
+## 개요
+
+Dooray MCP Server는 Model Context Protocol을 구현하여 AI 어시스턴트가 Dooray API와 상호작용할 수 있게 하는 TypeScript 기반 서버입니다.
+
+## 시스템 아키텍처
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   AI Assistant  │────▶│  MCP Server     │────▶│   Dooray API    │
+│   (Claude)      │◀────│  (dooray-mcp)   │◀────│                 │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+        │                       │
+        │                       │
+    stdio 통신              HTTPS 통신
+    (JSON-RPC)            (REST API)
+```
+
+## 핵심 컴포넌트
+
+### 1. MCP Server (`src/index.ts`)
+
+서버의 메인 엔트리 포인트로 다음 역할을 수행합니다:
+
+- **환경 변수 로드**: dotenv를 통한 설정 로드
+- **API 클라이언트 초기화**: Dooray API 연결 설정
+- **도구 레지스트리 관리**: 17개 MCP 도구 등록
+- **요청 핸들러**: `ListToolsRequest`, `CallToolRequest` 처리
+- **에러 처리**: Zod 검증 에러 및 API 에러 처리
+
+```typescript
+// 도구 레지스트리 구조
+const toolRegistry = {
+  'tool-name': {
+    handler: toolHandler,    // 실행 함수
+    schema: zodSchema        // 입력 검증 스키마
+  }
+};
+```
+
+### 2. API Client (`src/api/client.ts`)
+
+Dooray API와의 HTTP 통신을 담당합니다.
+
+**DoorayClient 클래스:**
+- 싱글톤 패턴으로 구현
+- Axios 인스턴스 래핑
+- 자동 인증 헤더 주입 (`dooray-api {token}`)
+- 응답/에러 인터셉터
+
+**지원 메서드:**
+| 메서드 | 용도 |
+|--------|------|
+| `get<T>()` | 단일 리소스 조회 |
+| `getPaginated<T>()` | 페이지네이션 목록 조회 |
+| `post<T>()` | 리소스 생성 |
+| `put<T>()` | 리소스 전체 수정 |
+| `patch<T>()` | 리소스 부분 수정 |
+| `delete<T>()` | 리소스 삭제 |
+| `uploadFile()` | 파일 업로드 |
+
+### 3. API Functions (`src/api/projects.ts`)
+
+Dooray Projects API 엔드포인트에 대한 래퍼 함수들입니다.
+
+**주요 함수:**
+- `getProjects()` - 프로젝트 목록
+- `getTasks()` - 업무 목록 (필터링 지원)
+- `createTask()` - 업무 생성
+- `updateTask()` - 업무 수정
+- `createTaskComment()` - 댓글 생성
+- `getMilestones()` - 마일스톤 목록
+- `getTags()` - 태그 목록
+- `getProjectWorkflows()` - 워크플로우 상태 목록
+
+### 4. Tools (`src/tools/`)
+
+각 MCP 도구는 다음 구조를 따릅니다:
+
+```typescript
+// 1. Zod 스키마 (입력 검증)
+export const toolSchema = z.object({
+  param: z.string().describe('설명')
+});
+
+// 2. 핸들러 함수 (비즈니스 로직)
+export async function toolHandler(args: ToolInput) {
+  const result = await apiCall(args);
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result) }]
+  };
+}
+
+// 3. 도구 정의 (MCP 등록)
+export const tool = {
+  name: 'tool-name',
+  description: '도구 설명',
+  inputSchema: { ... }
+};
+```
+
+### 5. Types (`src/types/`)
+
+**dooray-api.ts:**
+- Dooray API 응답/요청 타입 정의
+- `ApiResponse<T>` - 표준 응답 래퍼
+- `Task`, `Project`, `Milestone` 등 도메인 타입
+- `PaginatedResponse<T>` - 페이지네이션 응답
+
+**config.ts:**
+- `DoorayConfig` - 클라이언트 설정
+- `DoorayHeaders` - 커스텀 헤더
+
+### 6. Utils (`src/utils/`)
+
+**logger.ts:**
+- 로그 레벨: `ERROR`, `WARN`, `INFO`, `DEBUG`
+- stderr로 출력 (MCP stdio 통신과 분리)
+- `LOG_LEVEL` 환경 변수로 제어
+
+**errors.ts:**
+- `DoorayAPIError` - API 에러 기본 클래스
+- `AuthenticationError` - 인증 에러 (401)
+- `ValidationError` - 입력 검증 에러
+- `formatError()` - 에러 메시지 포맷팅
+
+**response-filters.ts:**
+- 응답 데이터 필터링 (토큰 절약)
+- `filterTaskForList()` - 목록용 간소화 필터
+
+**member-transform.ts:**
+- 멤버 데이터 변환 유틸리티
+- 내부 형식 → Dooray API 형식
+
+## 데이터 흐름
+
+### 도구 호출 흐름
+
+```
+1. Claude → MCP Server: CallToolRequest
+           │
+           ▼
+2. index.ts: toolRegistry에서 도구 조회
+           │
+           ▼
+3. Zod Schema: 입력 파라미터 검증
+           │
+           ▼
+4. Handler: API 함수 호출
+           │
+           ▼
+5. API Client: Dooray API HTTP 요청
+           │
+           ▼
+6. Response: 응답 처리 및 포맷팅
+           │
+           ▼
+7. MCP Server → Claude: 결과 반환
+```
+
+### 에러 처리 흐름
+
+```
+API Error 발생
+       │
+       ▼
+Axios Interceptor: 에러 캐치
+       │
+       ├─── 401: AuthenticationError 발생
+       │
+       ├─── 기타: DoorayAPIError 발생
+       │
+       ▼
+Handler: try-catch로 에러 캐치
+       │
+       ▼
+formatError(): 사용자 친화적 메시지 생성
+       │
+       ▼
+MCP Response: { isError: true, content: [...] }
+```
+
+## 설정
+
+### 환경 변수
+
+| 변수 | 필수 | 기본값 | 설명 |
+|------|------|--------|------|
+| `DOORAY_API_TOKEN` | O | - | Dooray API 인증 토큰 |
+| `DOORAY_API_BASE_URL` | X | `https://api.dooray.com` | API 기본 URL |
+| `LOG_LEVEL` | X | `INFO` | 로그 레벨 (ERROR/WARN/INFO/DEBUG) |
+
+### 타임아웃 설정
+
+| 요청 타입 | 타임아웃 |
+|-----------|----------|
+| 일반 요청 | 30초 |
+| 파일 업로드 | 60초 |
+
+## 보안 고려사항
+
+1. **API 토큰**: 환경 변수로만 전달, 코드에 하드코딩 금지
+2. **인증 헤더**: 모든 요청에 자동 주입
+3. **로깅**: stderr 사용으로 민감 정보 stdout 노출 방지
+4. **에러 처리**: API 응답 데이터 그대로 노출하지 않음
+
+## 확장 포인트
+
+### 새 도구 추가
+
+1. `src/tools/` 하위에 도구 파일 생성
+2. Zod 스키마, 핸들러, 도구 정의 구현
+3. `src/index.ts`에서 import 및 레지스트리 등록
+4. `tools` 배열에 도구 추가
+
+### 새 API 엔드포인트 추가
+
+1. `src/types/dooray-api.ts`에 타입 정의
+2. `src/api/projects.ts`에 API 함수 추가
+3. 필요시 새 도구 생성
+
+## 관련 문서
+
+- [프로젝트 개요](./project-overview.md)
+- [소스 트리 분석](./source-tree-analysis.md)
+- [개발 가이드](./development-guide.md)

package/docs/development-guide.md

@@ -0,0 +1,336 @@
+# Dooray MCP Server - 개발 가이드
+
+## 시작하기
+
+### 사전 요구사항
+
+- **Node.js**: v18.0.0 이상
+- **npm**: Node.js와 함께 설치됨
+- **Dooray API 토큰**: [Dooray 설정](https://dooray.com/settings/token)에서 발급
+
+### 설치
+
+```bash
+# 저장소 클론
+git clone https://github.com/jhl8041/dooray-mcp.git
+cd dooray-mcp
+
+# 의존성 설치
+npm install
+```
+
+### 환경 설정
+
+`.env` 파일 생성:
+```bash
+cp .env.example .env
+```
+
+`.env` 파일 편집:
+```env
+DOORAY_API_TOKEN=your_api_token_here
+DOORAY_API_BASE_URL=https://api.dooray.com  # 선택사항
+LOG_LEVEL=INFO  # ERROR, WARN, INFO, DEBUG
+```
+
+## 개발 명령어
+
+| 명령어 | 설명 |
+|--------|------|
+| `npm run build` | TypeScript → JavaScript 컴파일 |
+| `npm run dev` | tsx로 직접 실행 (컴파일 없이) |
+| `npm run watch` | 파일 변경 감지 및 자동 재컴파일 |
+
+### 개발 워크플로우
+
+1. **개발 모드 실행**
+   ```bash
+   npm run dev
+   ```
+   - tsx가 TypeScript를 직접 실행
+   - 빠른 피드백 루프
+
+2. **빌드 및 테스트**
+   ```bash
+   npm run build
+   node dist/index.js
+   ```
+
+3. **Watch 모드**
+   ```bash
+   npm run watch
+   ```
+   - 파일 변경 시 자동 재컴파일
+   - 별도 터미널에서 `node dist/index.js` 실행
+
+## 프로젝트 구조
+
+```
+src/
+├── index.ts          # 엔트리 포인트
+├── api/              # API 클라이언트
+├── tools/            # MCP 도구
+├── types/            # TypeScript 타입
+└── utils/            # 유틸리티
+```
+
+자세한 내용은 [소스 트리 분석](./source-tree-analysis.md) 참조
+
+## 새 도구 추가하기
+
+### 1. 도구 파일 생성
+
+`src/tools/projects/` 또는 `src/tools/common/`에 새 파일 생성:
+
+```typescript
+// src/tools/projects/new-tool.ts
+
+import { z } from 'zod';
+import { getClient } from '../../api/client.js';
+import { formatError } from '../../utils/errors.js';
+
+// 1. Zod 스키마 정의
+export const newToolSchema = z.object({
+  param1: z.string().describe('파라미터 설명'),
+  param2: z.number().optional().describe('선택적 파라미터'),
+});
+
+export type NewToolInput = z.infer<typeof newToolSchema>;
+
+// 2. 핸들러 함수 구현
+export async function newToolHandler(args: NewToolInput) {
+  try {
+    const client = getClient();
+    const result = await client.get('/some/endpoint', { param: args.param1 });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error: ${formatError(error)}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+// 3. 도구 정의
+export const newTool = {
+  name: 'new-tool',
+  description: `도구에 대한 상세 설명.
+
+사용 예시, 주의사항 등을 포함.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      param1: {
+        type: 'string',
+        description: '파라미터 설명',
+      },
+      param2: {
+        type: 'number',
+        description: '선택적 파라미터',
+      },
+    },
+    required: ['param1'],
+  },
+};
+```
+
+### 2. index.ts에 등록
+
+```typescript
+// src/index.ts
+
+// Import 추가
+import { newTool, newToolHandler, newToolSchema } from './tools/projects/new-tool.js';
+
+// toolRegistry에 추가
+const toolRegistry = {
+  // ... 기존 도구들
+  'new-tool': { handler: newToolHandler, schema: newToolSchema },
+};
+
+// tools 배열에 추가
+const tools = [
+  // ... 기존 도구들
+  newTool,
+];
+```
+
+### 3. 빌드 및 테스트
+
+```bash
+npm run build
+```
+
+## 코드 스타일 가이드
+
+### TypeScript
+
+- **엄격 모드**: `tsconfig.json`에서 `strict: true` 사용
+- **타입 정의**: 모든 함수 파라미터와 반환값에 타입 명시
+- **Zod 스키마**: 런타임 검증에 Zod 사용
+
+### 네이밍 컨벤션
+
+| 대상 | 스타일 | 예시 |
+|------|--------|------|
+| 파일 | kebab-case | `get-task-list.ts` |
+| 클래스 | PascalCase | `DoorayClient` |
+| 함수/변수 | camelCase | `getTaskList` |
+| 상수 | UPPER_SNAKE_CASE | `DEFAULT_BASE_URL` |
+| 타입/인터페이스 | PascalCase | `TaskListParams` |
+
+### 에러 처리
+
+```typescript
+// 권장 패턴
+try {
+  const result = await apiCall();
+  return { content: [...], isError: false };
+} catch (error) {
+  return {
+    content: [{ type: 'text', text: formatError(error) }],
+    isError: true,
+  };
+}
+```
+
+## API 클라이언트 사용
+
+### 기본 사용법
+
+```typescript
+import { getClient } from '../api/client.js';
+
+const client = getClient();
+
+// GET 요청
+const data = await client.get<ResponseType>('/endpoint');
+
+// GET 요청 (페이지네이션)
+const paginated = await client.getPaginated<ItemType>('/endpoint', { page: 0, size: 20 });
+
+// POST 요청
+const created = await client.post<ResponseType>('/endpoint', { body: data });
+
+// PUT 요청
+const updated = await client.put<ResponseType>('/endpoint', { body: data });
+```
+
+### 커스텀 헤더
+
+```typescript
+const result = await client.get('/endpoint', {}, {
+  'X-Custom-Header': 'value'
+});
+```
+
+## 타입 추가하기
+
+### Dooray API 타입
+
+`src/types/dooray-api.ts`에 추가:
+
+```typescript
+// 새 타입 정의
+export interface NewEntity {
+  id: string;
+  name: string;
+  // ...
+}
+
+// 파라미터 타입
+export interface NewEntityParams {
+  filter?: string;
+  page?: number;
+  size?: number;
+}
+```
+
+## 디버깅
+
+### 로그 레벨 설정
+
+```bash
+export LOG_LEVEL=DEBUG
+npm run dev
+```
+
+로그는 stderr로 출력되어 MCP stdio 통신과 분리됩니다.
+
+### MCP Inspector 사용
+
+MCP Inspector를 사용하여 도구 호출을 테스트할 수 있습니다.
+
+```bash
+npx @anthropic-ai/mcp-inspector dist/index.js
+```
+
+## 배포
+
+### npm 배포
+
+```bash
+# 버전 업데이트
+npm version patch  # 또는 minor, major
+
+# 빌드 (prepare 스크립트에서 자동 실행)
+npm run build
+
+# 배포
+npm publish
+```
+
+### 로컬 테스트
+
+```bash
+# 글로벌 설치 테스트
+npm link
+dooray-mcp  # 실행 테스트
+npm unlink
+```
+
+## 문제 해결
+
+### 일반적인 문제
+
+**1. "DOORAY_API_TOKEN is required" 에러**
+- `.env` 파일에 토큰이 설정되어 있는지 확인
+- 환경 변수가 올바르게 로드되는지 확인
+
+**2. 401 Unauthorized 에러**
+- API 토큰이 유효한지 확인
+- 토큰이 만료되지 않았는지 확인
+
+**3. TypeScript 컴파일 에러**
+- `npm install`로 의존성 재설치
+- `tsconfig.json` 설정 확인
+
+**4. MCP 연결 실패**
+- Claude Desktop 설정 파일 경로 확인
+- JSON 형식이 올바른지 확인
+
+## 관련 문서
+
+- [프로젝트 개요](./project-overview.md)
+- [아키텍처 문서](./architecture.md)
+- [소스 트리 분석](./source-tree-analysis.md)
+
+## 외부 리소스
+
+- [Model Context Protocol 문서](https://modelcontextprotocol.io)
+- [Dooray API 문서](https://dooray.com/docs/api)
+- [TypeScript 핸드북](https://www.typescriptlang.org/docs/)
+- [Zod 문서](https://zod.dev/)

package/docs/index.md

@@ -0,0 +1,115 @@
+# Dooray MCP Server - 문서 인덱스
+
+> AI 어시스턴트 개발을 위한 프로젝트 문서 허브
+
+## 프로젝트 요약
+
+| 항목 | 값 |
+|------|-----|
+| **타입** | CLI / MCP Server |
+| **언어** | TypeScript |
+| **아키텍처** | Tool-based MCP Server |
+| **저장소 구조** | Monolith |
+
+## 빠른 참조
+
+- **기술 스택**: TypeScript 5.7, Node.js 18+, MCP SDK 1.0.4, Axios, Zod
+- **진입점**: `src/index.ts`
+- **아키텍처 패턴**: Tool Pattern + Layered Architecture
+- **도구 수**: 17개 MCP 도구
+
+## 생성된 문서
+
+### 핵심 문서
+
+| 문서 | 설명 |
+|------|------|
+| [프로젝트 개요](./project-overview.md) | 프로젝트 소개, 기술 스택, 주요 기능 |
+| [아키텍처 문서](./architecture.md) | 시스템 구조, 컴포넌트, 데이터 흐름 |
+| [소스 트리 분석](./source-tree-analysis.md) | 디렉토리 구조, 파일별 설명 |
+| [개발 가이드](./development-guide.md) | 설정, 개발 명령어, 새 도구 추가 방법 |
+
+## 기존 문서
+
+| 문서 | 설명 |
+|------|------|
+| [README.md](../README.md) | 설치 및 사용법 (한국어) |
+| [CLAUDE.md](../CLAUDE.md) | AI 어시스턴트용 도구 상세 문서 (영어) |
+
+## 시작하기
+
+### 1. 설치
+
+```bash
+npm install -g @jhl8041/dooray-mcp
+```
+
+### 2. 환경 변수 설정
+
+```bash
+export DOORAY_API_TOKEN=<발급받은_토큰>
+```
+
+### 3. Claude Desktop 설정
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dooray": {
+      "command": "npx @jhl8041/dooray-mcp@latest",
+      "env": { "DOORAY_API_TOKEN": "발급받은_토큰" }
+    }
+  }
+}
+```
+
+## MCP 도구 목록
+
+### 공통 도구
+
+| 도구 | 설명 |
+|------|------|
+| `get-my-member-info` | 현재 사용자 정보 조회 |
+
+### 프로젝트 도구
+
+| 도구 | 설명 |
+|------|------|
+| `get-project-list` | 프로젝트 목록 조회 |
+| `get-project` | 프로젝트 상세 정보 |
+| `get-project-workflow-list` | 워크플로우 상태 목록 |
+| `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-template-list` | 템플릿 목록 |
+| `get-project-template` | 템플릿 상세 |
+| `get-project-member-list` | 프로젝트 멤버 목록 |
+| `get-project-member-group-list` | 멤버 그룹 목록 |
+
+## 개발 명령어
+
+```bash
+npm run build   # TypeScript 컴파일
+npm run dev     # 개발 모드 실행
+npm run watch   # Watch 모드
+```
+
+## 외부 링크
+
+- [Dooray 공식 사이트](https://dooray.com)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Dooray API 문서](https://dooray.com/docs/api)
+- [GitHub 저장소](https://github.com/jhl8041/dooray-mcp)
+
+---
+
+*이 문서는 BMAD Document Project 워크플로우에 의해 자동 생성되었습니다.*
+*마지막 업데이트: 2026-01-27*