Metadata-Version: 2.4
Name: timebox-mcp
Version: 0.1.1
Summary: Timebox Planner MCP server — stdio wrapper over the REST API
Project-URL: Repository, https://github.com/dchain-enterprise/timebox-planner
Author: dchain-enterprise
License: Proprietary
Keywords: llm,mcp,stdio,timebox
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.13,>=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# timebox-mcp

Timebox Planner REST API를 감싸는 stdio MCP 서버.
프로젝트/태스크/위키(+파일 첨부)/브레인덤프/타임라인 블록/우선순위/주간 목표를 LLM 툴로 노출한다.
`upload_wiki_attachment(page_id, file_path)` 로 로컬 파일을 위키 페이지에 첨부할 수 있다(object storage).

## 설치 (PyPI)

repo 클론 없이 설치할 수 있다.

```bash
uvx timebox-mcp          # 일회 실행(권장)
# 또는
pip install timebox-mcp  # 영구 설치 → `timebox-mcp` 명령
```

## 준비

1. 웹 설정 화면 → **API 토큰** → 토큰 발급 (`tbx_...`, 발급 직후 한 번만 표시).
2. `cd apps/mcp && uv sync`

## 등록 (Claude Code)

```bash
claude mcp add timebox \
  --env TIMEBOX_API_URL=http://localhost:8000 \
  --env TIMEBOX_API_TOKEN=tbx_... \
  -- uvx timebox-mcp
```

또는 `.mcp.json`:

```json
{
  "mcpServers": {
    "timebox": {
      "command": "uvx",
      "args": ["timebox-mcp"],
      "env": {
        "TIMEBOX_API_URL": "http://localhost:8000",
        "TIMEBOX_API_TOKEN": "tbx_...",
        "TIMEBOX_DEFAULT_PROJECT": "652f..."
      }
    }
  }
}
```

로컬 개발/미게시 버전:

```bash
uv run --directory /path/to/timebox-planner/apps/mcp timebox-mcp
```

⚠️ 실제 토큰이 든 `.mcp.json`은 커밋하지 마세요 — 개인 설정(`~/.claude.json` 또는 `claude mcp add`)을 사용하세요.

- `TIMEBOX_API_URL` — API 서버 주소 (기본 `http://localhost:8000`)
- `TIMEBOX_API_TOKEN` — 필수. 개인 API 토큰
- `TIMEBOX_DEFAULT_PROJECT` — 선택. 주로 보는 프로젝트의 고유 ID. 설정하면 프로젝트 인자를 생략한 태스크/위키 툴이 이 프로젝트로 기본 동작한다. ID는 웹 **프로젝트 설정 → 프로젝트 ID**에서 복사(`get_default_project` 툴로 확인).
- `TIMEBOX_WEB_URL` — 선택. 위키 툴 출력의 `link`(및 공개 페이지 `public_link`)를 만들 웹 앱 주소. API 주소와 다르다. 기본 `https://timebox-planner-web.bucks.dchain-connect.com`.

## 스모크 테스트

```bash
TIMEBOX_API_TOKEN=tbx_... uv run python -c \
  "from timebox_mcp.client import TimeboxClient; print(TimeboxClient().request('GET', '/projects'))"
```

## 릴리스 (PyPI 게시)

`mcp-v*` 태그를 push하면 `.github/workflows/mcp-release.yml`이 검증 후 PyPI에 게시한다.

1. `apps/mcp/pyproject.toml`의 `version`을 올린다 (예: `0.1.0` → `0.2.0`).
2. 커밋 후 태그를 버전과 **정확히 일치**시켜 push:
   ```bash
   git commit -am "chore(mcp): bump version to 0.2.0"
   git tag mcp-v0.2.0
   git push origin mcp-v0.2.0
   ```
3. 워크플로가 ruff/mypy/pytest → 버전 일치 확인 → `uv build` → `uv publish`.

전제조건: GitHub repo(또는 org) secret `PYPI_API_TOKEN` 등록 필요. PyPI는 동일 버전 재게시 불가 — 실패 시 버전을 올려 다시 태그.
