tdecollab 0.2.2 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 goodjoon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,16 +1,14 @@
 # tdecollab
 
-TDE 포털의 Confluence, JIRA, GitLab과 상호작용하는 CLI 및 MCP(Model Context Protocol) 통합 도구.
+Confluence, JIRA, GitLab을 하나의 CLI / TUI / MCP 서버로 통합 제공하는 도구.
 
-## 개요
+터미널에서 직접 사용하거나, AI 에이전트(Claude Desktop 등)와 연동하여 사용할 수 있습니다.
 
-tdecollab은 TDE 포털에서 제공하는 협업 도구들을 하나의 CLI와 MCP 서버로 통합하여, 터미널이나 AI 에이전트(Claude 등)를 통해 편리하게 사용할 수 있도록 하는 경량화 서비스입니다.
-
-### 지원 서비스
+## 지원 서비스
 
 | 서비스 | 주요 기능 |
 |--------|----------|
-| **Confluence** | 페이지 CRUD, Markdown↔Storage 변환, 검색, 라벨 관리, 페이지 트리 조회 |
+| **Confluence** | 페이지 CRUD, Markdown ↔ Storage Format 변환, 검색, 라벨 관리, 페이지 트리 조회 |
 | **JIRA** | 이슈 CRUD, JQL 검색, 상태 변경(트랜지션), 코멘트 관리, 프로젝트/보드 조회 |
 | **GitLab** | 프로젝트 조회, MR 관리, 파이프라인 조회, 브랜치 관리, 파일 조회 |
 
@@ -20,8 +18,6 @@ tdecollab은 TDE 포털에서 제공하는 협업 도구들을 하나의 CLI와
 
 ## 설치
 
-### npm에서 설치 (권장)
-
 ```bash
 # 전역 설치
 npm install -g tdecollab
@@ -30,30 +26,19 @@ npm install -g tdecollab
 npx -y tdecollab --help
 ```
 
-### 소스에서 빌드 (개발자용)
-
-```bash
-git clone <repository-url>
-cd tdecollab
-pnpm install
-pnpm build
-```
-
 ## 설정
 
-### 환경변수
-
-tdecollab은 다음 환경변수를 통해 각 서비스에 접속합니다:
+각 서비스 접속에 필요한 환경변수:
 
 ```env
 # Confluence
 CONFLUENCE_BASE_URL=https://confluence.example.com
-CONFLUENCE_USERNAME=your-username  # Basic Auth 사용 시 (선택)
+CONFLUENCE_USERNAME=your-username    # Basic Auth 사용 시 (선택)
 CONFLUENCE_API_TOKEN=your-api-token
 
 # JIRA
 JIRA_BASE_URL=https://jira.example.com
-JIRA_USERNAME=your-username         # PAT 사용 시 생략 가능 (선택)
+JIRA_USERNAME=your-username          # PAT 사용 시 생략 가능 (선택)
 JIRA_API_TOKEN=your-api-token
 
 # GitLab
@@ -61,168 +46,71 @@ GITLAB_BASE_URL=https://gitlab.example.com   # 미설정 시 https://gitlab.com
 GITLAB_PRIVATE_TOKEN=your-private-token
 ```
 
-### 설정 방법
+세 가지 설정 방법:
 
-**방법 1: .env 파일 사용 (로컬 개발)**
+1. **`.env` 파일** — 작업 디렉토리에 `.env` 파일을 두면 자동 로드됩니다.
+2. **셸 환경변수** — `export CONFLUENCE_BASE_URL=...` 후 `tdecollab` 실행
+3. **MCP 서버 설정** — Claude Desktop 설정 파일의 `env` 섹션에 추가 (아래 MCP 서버 섹션 참조)
 
-```bash
-# 프로젝트 루트에 .env 파일 생성
-echo "CONFLUENCE_BASE_URL=https://confluence.example.com" > .env
-echo "CONFLUENCE_API_TOKEN=your-token" >> .env
-```
+## 사용법
+
+### TUI (Terminal UI) 모드
+![[img_20260429004932.png]]
 
-**방법 2: 환경변수 직접 설정**
+인자 없이 실행하면 인터랙티브 TUI가 시작됩니다 — 메뉴 탐색, 폼 입력, 실시간 결과 확인이 한 화면에서 가능합니다.
 
 ```bash
-export CONFLUENCE_BASE_URL=https://confluence.example.com
-export CONFLUENCE_API_TOKEN=your-token
-tdecollab confluence space list
+tdecollab
 ```
 
-**방법 3: MCP 서버 설정에 포함 (Claude Desktop)**
+| 단축키 | 동작 |
+|---|---|
+| `↑↓` `Tab` `Shift+Tab` | 메뉴/필드 이동 |
+| `↵` | 메뉴 펼치기 / 경로 선택창 / 토글 |
+| `Ctrl+R` | 폼 실행 |
+| `Ctrl+S` | 입력값을 프리셋으로 저장 |
+| `Esc` | 뒤로 |
+| `q` | 종료 |
+| `j/k` `Ctrl+D/U` `Ctrl+F/B` `g/G` | 결과 마크다운 뷰 vim 스타일 스크롤 |
 
-Claude Desktop 설정 파일의 `env` 섹션에 환경변수를 추가합니다 (아래 MCP 서버 섹션 참조).
-
-## 사용법
+마지막 사용값은 `.tdecollab.json`에, 명령 히스토리는 `~/.tdecollab_history.json`에 자동 저장됩니다.
 
 ### CLI 명령어
 
 #### Confluence
 
 ```bash
-# 스페이스 목록 조회
+# 스페이스 목록
 tdecollab confluence space list
 
-# 페이지 조회
-tdecollab confluence page get <pageId>
-tdecollab confluence page get <pageId> --raw          # Storage Format 출력
-tdecollab confluence page get <pageId> --quiet        # 메타데이터 생략
-tdecollab confluence page get <pageId> --raw --quiet > page.html
-
-# 이미지 다운로드와 함께 페이지 조회
-tdecollab confluence page get <pageId> --download-images                    # 이미지를 ./images에 다운로드
-tdecollab confluence page get <pageId> -d --image-dir ./my-images          # 커스텀 디렉토리에 다운로드
-tdecollab confluence page get <pageId> -d -o page.md                       # Markdown 파일로 저장
-tdecollab confluence page get <pageId> -d --image-dir ./assets -o page.md  # 이미지와 함께 저장
-
-# 페이지 생성
-tdecollab confluence page create --space <key> --title <title> --content "Markdown 내용"
-tdecollab confluence page create --space <key> --title <title> --file <path>
-
-# 페이지 검색 (CQL)
-tdecollab confluence search "title ~ 'guide'"
-tdecollab confluence search "space = MYSPACE AND type = page"
-```
-
-#### JIRA
+# 페이지를 Markdown으로 다운로드 (이미지 포함)
+tdecollab confluence page get <pageId> -d --image-dir ./assets -o page.md
 
-```bash
-# 이슈 관리
-tdecollab jira issue get <issueKey>                      # 이슈 상세 조회
-tdecollab jira issue create -p PROJ -s "제목" -t Task     # 이슈 생성
-tdecollab jira issue update <issueKey> -s "새 제목"       # 이슈 수정
-tdecollab jira issue transition <issueKey> -l             # 가능한 트랜지션 조회
-tdecollab jira issue transition <issueKey> -t <id>        # 트랜지션 실행
-
-# JQL 검색
-tdecollab jira search "project = PROJ AND status = Open"
-tdecollab jira search "assignee = currentUser()" -n 50
-
-# 코멘트 관리
-tdecollab jira comment list <issueKey>
-tdecollab jira comment add <issueKey> "코멘트 내용"
-
-# 프로젝트/보드
-tdecollab jira project list
-tdecollab jira project get <projectKey>
-tdecollab jira board list [-p <projectKey>]
-tdecollab jira board sprints <boardId> [-s active]
+# 마크다운 파일로 페이지 생성/수정 (로컬 이미지 자동 업로드)
+tdecollab confluence page create --space <key> --title <title> --file <path_to_md>
+tdecollab confluence page update <pageId> --file <path_to_md>
 ```
 
-#### GitLab
+#### JIRA / GitLab
 
 ```bash
-# 프로젝트
-tdecollab gitlab project list [--search <query>] [--owned] [--membership]
-tdecollab gitlab project get <projectId>
-
-# Merge Request
-tdecollab gitlab mr list <projectId> [-s opened|closed|merged|all]
-tdecollab gitlab mr get <projectId> <mrIid> [--changes]
-tdecollab gitlab mr create <projectId> --source <branch> --target <branch> --title <text>
-tdecollab gitlab mr merge <projectId> <mrIid> [--squash] [--remove-source-branch]
-tdecollab gitlab mr close <projectId> <mrIid>
-tdecollab gitlab mr comment <projectId> <mrIid> -b "코멘트 내용"
-
-# 파이프라인
-tdecollab gitlab pipeline list <projectId> [--status <status>] [--ref <branch>]
-tdecollab gitlab pipeline get <projectId> <pipelineId> [--jobs]
-
-# 브랜치
-tdecollab gitlab branch list <projectId> [--search <query>]
-tdecollab gitlab branch get <projectId> <branchName>
-tdecollab gitlab branch create <projectId> --name <branch> --ref <ref>
-tdecollab gitlab branch delete <projectId> <branchName>
-
-# 파일/저장소
-tdecollab gitlab file get <projectId> <filePath> [--ref <ref>]
-tdecollab gitlab file tree <projectId> [--path <dir>] [--ref <ref>] [--recursive]
+tdecollab jira issue get PROJ-1234
+tdecollab jira search "assignee = currentUser() AND status != Done"
+tdecollab gitlab mr list <projectId> -s opened
 ```
 
-### MCP 도구 목록
-
-MCP 서버를 통해 AI 에이전트(Claude 등)에서 사용할 수 있는 도구입니다.
-
-#### Confluence (9개)
-
-| 도구 | 설명 |
-|------|------|
-| `confluence_get_page` | 페이지 상세 조회 (Markdown 변환) |
-| `confluence_create_page` | 새 페이지 생성 (Markdown → Storage Format 자동 변환) |
-| `confluence_update_page` | 페이지 수정 |
-| `confluence_delete_page` | 페이지 삭제 |
-| `confluence_search_pages` | CQL로 페이지 검색 |
-| `confluence_get_spaces` | 스페이스 목록 조회 |
-| `confluence_get_page_tree` | 하위 페이지(자식 페이지) 목록 조회 |
-| `confluence_manage_labels` | 페이지 라벨 조회/추가/삭제 |
-| `confluence_convert_content` | Markdown ↔ Storage Format 양방향 변환 |
-
-#### JIRA (7개)
-
-| 도구 | 설명 |
-|------|------|
-| `jira_get_issue` | 이슈 상세 조회 |
-| `jira_create_issue` | 새 이슈 생성 |
-| `jira_update_issue` | 이슈 수정 |
-| `jira_search_issues` | JQL로 이슈 검색 |
-| `jira_transition_issue` | 이슈 상태 변경 (트랜지션 조회/실행) |
-| `jira_manage_comments` | 코멘트 조회/추가/수정/삭제 |
-| `jira_get_projects` | 프로젝트/보드/스프린트 조회 |
-
-#### GitLab (7개)
-
-| 도구 | 설명 |
-|------|------|
-| `gitlab_get_project` | 프로젝트 목록 또는 상세 조회 |
-| `gitlab_get_merge_request` | MR 목록 또는 상세 조회 (변경 파일 포함 가능) |
-| `gitlab_create_merge_request` | 새 Merge Request 생성 |
-| `gitlab_manage_merge_request` | MR 머지/닫기/재열기/코멘트 추가 |
-| `gitlab_get_pipelines` | 파이프라인 목록 또는 상세 조회 (Job 포함 가능) |
-| `gitlab_manage_branches` | 브랜치 목록/상세/생성/삭제 |
-| `gitlab_get_file` | 파일 내용 또는 디렉토리 트리 조회 |
-
-### MCP 서버 (Claude Desktop 연동)
+`tdecollab <service> --help` 또는 `tdecollab <service> <command> --help`로 모든 옵션을 확인할 수 있습니다.
+
+## MCP 서버 (Claude Desktop 연동)
 
 Claude Desktop에서 Confluence, JIRA, GitLab 도구를 사용할 수 있습니다.
 
-#### 설정 파일 위치
+### 설정 파일 위치
 
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
-#### npx 사용 (권장)
-
-별도 설치 없이 최신 버전을 자동으로 실행합니다:
+### npx 사용 (권장 — 별도 설치 불필요)
 
 ```json
 {
@@ -244,7 +132,7 @@ Claude Desktop에서 Confluence, JIRA, GitLab 도구를 사용할 수 있습니
 }
 ```
 
-#### 전역 설치 사용
+### 전역 설치 후 사용
 
 ```bash
 npm install -g tdecollab
@@ -258,29 +146,6 @@ npm install -g tdecollab
       "args": ["mcp"],
       "env": {
         "CONFLUENCE_BASE_URL": "https://confluence.example.com",
-        "CONFLUENCE_USERNAME": "your-username",
-        "CONFLUENCE_API_TOKEN": "your-api-token",
-        "JIRA_BASE_URL": "https://jira.example.com",
-        "JIRA_API_TOKEN": "your-jira-token",
-        "GITLAB_BASE_URL": "https://gitlab.example.com",
-        "GITLAB_PRIVATE_TOKEN": "your-gitlab-token"
-      }
-    }
-  }
-}
-```
-
-#### 로컬 개발 버전 사용
-
-```json
-{
-  "mcpServers": {
-    "tdecollab-dev": {
-      "command": "node",
-      "args": ["/absolute/path/to/tdecollab/dist/index.js"],
-      "env": {
-        "CONFLUENCE_BASE_URL": "https://confluence.example.com",
-        "CONFLUENCE_USERNAME": "your-username",
         "CONFLUENCE_API_TOKEN": "your-api-token",
         "JIRA_BASE_URL": "https://jira.example.com",
         "JIRA_API_TOKEN": "your-jira-token",
@@ -292,47 +157,18 @@ npm install -g tdecollab
 }
 ```
 
-설정 후 Claude Desktop을 재시작하면 Confluence, JIRA, GitLab 도구를 사용할 수 있습니다.
-
-## 개발
-
-```bash
-# 개발 모드 (MCP 서버)
-pnpm dev
-
-# CLI 실행
-pnpm cli -- confluence page get 12345
+설정 후 Claude Desktop을 재시작하면 도구가 활성화됩니다.
 
-# 테스트
-pnpm test
+### 제공 MCP 도구
 
-# 빌드
-pnpm build
-
-# 포맷팅
-pnpm format
-```
-
-## 프로젝트 구조
-
-```
-src/
-├── index.ts          # MCP 서버 엔트리포인트
-├── cli.ts            # CLI 엔트리포인트
-├── common/           # 공통 모듈 (인증, HTTP, 설정, 에러)
-├── confluence/       # Confluence 모듈 (api/tools/commands/converters)
-├── jira/             # JIRA 모듈 (api/tools/commands)
-├── gitlab/           # GitLab 모듈 (api/tools/commands)
-└── mcp/              # MCP 서버 코어
-```
+| 서비스 | 도구 |
+|---|---|
+| **Confluence (9)** | `confluence_get_page`, `confluence_create_page`, `confluence_update_page`, `confluence_delete_page`, `confluence_search_pages`, `confluence_get_spaces`, `confluence_get_page_tree`, `confluence_manage_labels`, `confluence_convert_content` |
+| **JIRA (7)** | `jira_get_issue`, `jira_create_issue`, `jira_update_issue`, `jira_search_issues`, `jira_transition_issue`, `jira_manage_comments`, `jira_get_projects` |
+| **GitLab (7)** | `gitlab_get_project`, `gitlab_get_merge_request`, `gitlab_create_merge_request`, `gitlab_manage_merge_request`, `gitlab_get_pipelines`, `gitlab_manage_branches`, `gitlab_get_file` |
 
-## 문서
+자세한 도구별 파라미터는 Claude Desktop의 MCP 도구 검색 UI 또는 `tdecollab mcp` 실행 시 stderr 로그를 참조하세요.
 
-상세한 설계 문서는 `docs/` 디렉토리를 참조하세요.
+## 라이선스
 
-- [아키텍처](docs/architecture.md)
-- [인증 및 설정](docs/auth-and-config.md)
-- [MCP 서버 설계](docs/mcp-server-design.md)
-- Confluence: [API 스펙](docs/confluence/api-spec.md) | [기능 정의](docs/confluence/features.md) | [MCP 도구](docs/confluence/mcp-tools.md)
-- JIRA: [API 스펙](docs/jira/api-spec.md) | [기능 정의](docs/jira/features.md) | [MCP 도구](docs/jira/mcp-tools.md)
-- GitLab: [API 스펙](docs/gitlab/api-spec.md) | [기능 정의](docs/gitlab/features.md) | [MCP 도구](docs/gitlab/mcp-tools.md)
+[MIT](LICENSE)