timebox-mcp

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

설치 (PyPI)

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

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

준비

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

등록 (Claude Code)

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

또는 .mcp.json:

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

로컬 개발/미게시 버전:

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.

스모크 테스트

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:

   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는 동일 버전 재게시 불가 — 실패 시 버전을 올려 다시 태그.