worklog-for-claude 0.1.0__tar.gz

worklog_for_claude-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+.env
+node_modules/
+__pycache__/
+*.pyc
+.DS_Store
+*.bak
+.worklogs/
+.version
+.version-checked
+.claude/
+update.sh
+
+# --- ai-bouncer start ---
+# ai-bouncer runtime artifacts
+.claude/ai-bouncer/.version-checked
+.claude/ai-bouncer/config.json
+.claude/ai-bouncer/manifest.json
+.claude/**/*.backup-*
+.claude/settings.json
+# ai-bouncer installed files
+.claude/agents/dev.md
+.claude/agents/intent.md
+.claude/agents/lead.md
+.claude/agents/qa.md
+.claude/agents/verifier.md
+.claude/agents/guides/tc-guide.md
+.claude/skills/dev-bounce/SKILL.md
+.claude/skills/update-bouncer/SKILL.md
+.claude/hooks/hooks.json
+.claude/hooks/plan-gate.sh
+.claude/hooks/bash-gate.sh
+.claude/hooks/doc-reminder.sh
+.claude/hooks/bash-audit.sh
+.claude/hooks/completion-gate.sh
+.claude/hooks/stop-active-cleanup.sh
+.claude/hooks/subagent-track.sh
+.claude/hooks/subagent-cleanup.sh
+.claude/hooks/lib/resolve-task.sh
+.claude/scripts/update-check.sh
+update.sh
+uninstall.sh
+# --- ai-bouncer end ---

worklog_for_claude-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: worklog-for-claude
+Version: 0.1.0
+Summary: MCP server for worklog and project documentation management
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.21.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# worklog-mcp
+
+**The project doc that writes itself.**
+
+MCP server that manages worklogs and keeps `PROJECT.md` up to date — across Claude Code, Cursor, and Claude Desktop.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+[![Python](https://img.shields.io/badge/Python-3.10+-green)](https://python.org)
+
+---
+
+## What It Does
+
+- **Worklog** — records what you worked on into `.worklogs/YYYY-MM-DD.md`, optionally syncs to Notion
+- **Project doc** — creates and maintains `PROJECT.md` with structure, decisions, and solved problems
+- **Gap detection** — compares recent git commits to `PROJECT.md` and surfaces what's missing
+- **Any client** — Claude Code, Cursor, Claude Desktop, anything MCP-compatible
+
+## Install
+
+```bash
+git clone https://github.com/kangraemin/worklog-for-claude
+cd worklog-for-claude/mcp
+uv sync
+```
+
+## Connect
+
+Add to your MCP client config. Replace the path with the absolute path to this `mcp/` directory.
+
+**Claude Code** — `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "worklog-mcp": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/worklog-for-claude/mcp", "run", "worklog-mcp"]
+    }
+  }
+}
+```
+
+**Cursor** — `~/.cursor/mcp.json` (same format)
+
+**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (same format)
+
+See `examples/` for complete config files.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `write_worklog` | Append an entry to `.worklogs/YYYY-MM-DD.md` |
+| `read_worklog` | Read worklog for a given date (default: today) |
+| `write_worklog_to_notion` | Send worklog entry to Notion DB |
+| `read_project_doc` | Read `PROJECT.md` with section parsing |
+| `create_project_doc` | Create `PROJECT.md` with 7 standard sections |
+| `analyze_gaps` | Compare recent git commits to `PROJECT.md`, return gaps |
+| `update_project_doc` | Update a specific section (replace or append) |
+
+## PROJECT.md Sections
+
+```
+## 이게 뭔가       — one-line description
+## 왜 만들었나     — motivation and problem
+## 구조            — folder/file structure
+## 기술 스택       — tech choices and reasons
+## 주요 결정들     — key architectural decisions
+## 해결한 문제들   — bugs and how they were fixed
+## 지금 상태       — current state, what works, what's next
+```
+
+## Notion Setup
+
+Set environment variables before running the server:
+
+```bash
+export NOTION_TOKEN=secret_...
+export NOTION_DB_ID=your-db-id
+```
+
+Or pass them directly as tool arguments.
+
+Required Notion DB columns: `Title`, `Project`, `Cost`, `Duration`, `Model`, `Tokens`, `DateTime`
+
+## Gap Detection
+
+`analyze_gaps` watches your git history and finds what's missing in `PROJECT.md`:
+
+- `feat:` commits → checks `주요 결정들`, `지금 상태`
+- `fix:` commits → checks `해결한 문제들`
+- `refactor:` commits → checks `구조`, `기술 스택`
+- Empty sections → always flagged
+- Recent `docs:` or `PROJECT.md` commit → skips gap check
+
+## Test
+
+```bash
+uv run pytest tests/ -v
+```
+
+71 tests, all passing.

worklog_for_claude-0.1.0/README.md

@@ -0,0 +1,103 @@
+# worklog-mcp
+
+**The project doc that writes itself.**
+
+MCP server that manages worklogs and keeps `PROJECT.md` up to date — across Claude Code, Cursor, and Claude Desktop.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](../LICENSE)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+[![Python](https://img.shields.io/badge/Python-3.10+-green)](https://python.org)
+
+---
+
+## What It Does
+
+- **Worklog** — records what you worked on into `.worklogs/YYYY-MM-DD.md`, optionally syncs to Notion
+- **Project doc** — creates and maintains `PROJECT.md` with structure, decisions, and solved problems
+- **Gap detection** — compares recent git commits to `PROJECT.md` and surfaces what's missing
+- **Any client** — Claude Code, Cursor, Claude Desktop, anything MCP-compatible
+
+## Install
+
+```bash
+git clone https://github.com/kangraemin/worklog-for-claude
+cd worklog-for-claude/mcp
+uv sync
+```
+
+## Connect
+
+Add to your MCP client config. Replace the path with the absolute path to this `mcp/` directory.
+
+**Claude Code** — `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "worklog-mcp": {
+      "command": "uv",
+      "args": ["--directory", "/path/to/worklog-for-claude/mcp", "run", "worklog-mcp"]
+    }
+  }
+}
+```
+
+**Cursor** — `~/.cursor/mcp.json` (same format)
+
+**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (same format)
+
+See `examples/` for complete config files.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `write_worklog` | Append an entry to `.worklogs/YYYY-MM-DD.md` |
+| `read_worklog` | Read worklog for a given date (default: today) |
+| `write_worklog_to_notion` | Send worklog entry to Notion DB |
+| `read_project_doc` | Read `PROJECT.md` with section parsing |
+| `create_project_doc` | Create `PROJECT.md` with 7 standard sections |
+| `analyze_gaps` | Compare recent git commits to `PROJECT.md`, return gaps |
+| `update_project_doc` | Update a specific section (replace or append) |
+
+## PROJECT.md Sections
+
+```
+## 이게 뭔가       — one-line description
+## 왜 만들었나     — motivation and problem
+## 구조            — folder/file structure
+## 기술 스택       — tech choices and reasons
+## 주요 결정들     — key architectural decisions
+## 해결한 문제들   — bugs and how they were fixed
+## 지금 상태       — current state, what works, what's next
+```
+
+## Notion Setup
+
+Set environment variables before running the server:
+
+```bash
+export NOTION_TOKEN=secret_...
+export NOTION_DB_ID=your-db-id
+```
+
+Or pass them directly as tool arguments.
+
+Required Notion DB columns: `Title`, `Project`, `Cost`, `Duration`, `Model`, `Tokens`, `DateTime`
+
+## Gap Detection
+
+`analyze_gaps` watches your git history and finds what's missing in `PROJECT.md`:
+
+- `feat:` commits → checks `주요 결정들`, `지금 상태`
+- `fix:` commits → checks `해결한 문제들`
+- `refactor:` commits → checks `구조`, `기술 스택`
+- Empty sections → always flagged
+- Recent `docs:` or `PROJECT.md` commit → skips gap check
+
+## Test
+
+```bash
+uv run pytest tests/ -v
+```
+
+71 tests, all passing.

worklog_for_claude-0.1.0/examples/claude-code-settings.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "worklog-mcp": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/ABSOLUTE/PATH/TO/worklog-for-claude/mcp",
+        "run",
+        "worklog-mcp"
+      ],
+      "env": {
+        "NOTION_TOKEN": "secret_...",
+        "NOTION_DB_ID": "your-notion-db-id"
+      }
+    }
+  }
+}

worklog_for_claude-0.1.0/examples/claude-desktop-config.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "worklog-mcp": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/ABSOLUTE/PATH/TO/worklog-for-claude/mcp",
+        "run",
+        "worklog-mcp"
+      ],
+      "env": {
+        "NOTION_TOKEN": "secret_...",
+        "NOTION_DB_ID": "your-notion-db-id"
+      }
+    }
+  }
+}

worklog_for_claude-0.1.0/examples/cursor-mcp.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "worklog-mcp": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/ABSOLUTE/PATH/TO/worklog-for-claude/mcp",
+        "run",
+        "worklog-mcp"
+      ],
+      "env": {
+        "NOTION_TOKEN": "secret_...",
+        "NOTION_DB_ID": "your-notion-db-id"
+      }
+    }
+  }
+}

worklog_for_claude-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "worklog-for-claude"
+version = "0.1.0"
+description = "MCP server for worklog and project documentation management"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.28.1",
+    "mcp[cli]>=1.21.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+worklog-for-claude = "worklog_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/worklog_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-httpx>=0.36.0",
+]

worklog_for_claude-0.1.0/src/worklog_mcp/server.py

@@ -0,0 +1,39 @@
+from mcp.server.fastmcp import FastMCP
+from worklog_mcp.tools.worklog import write_worklog, read_worklog
+from worklog_mcp.tools.project_doc import (
+    read_project_doc,
+    create_project_doc,
+    analyze_gaps,
+    update_project_doc,
+)
+from worklog_mcp.tools.notion import write_worklog_to_notion
+from worklog_mcp.utils.git import get_commits_since_file_update
+
+
+def get_commits_since_update(project_path: str = ".") -> int:
+    """PROJECT.md 마지막 수정 이후 커밋 수 반환. hook에서 빠르게 호출하는 용도.
+
+    Args:
+        project_path: 프로젝트 루트 디렉토리 경로 (기본값: 현재 디렉토리)
+    """
+    return get_commits_since_file_update(project_path, "PROJECT.md")
+
+
+mcp = FastMCP("worklog-mcp")
+
+mcp.tool()(write_worklog)
+mcp.tool()(read_worklog)
+mcp.tool()(read_project_doc)
+mcp.tool()(create_project_doc)
+mcp.tool()(analyze_gaps)
+mcp.tool()(update_project_doc)
+mcp.tool()(write_worklog_to_notion)
+mcp.tool()(get_commits_since_update)
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

worklog_for_claude-0.1.0/src/worklog_mcp/tools/notion.py

@@ -0,0 +1,104 @@
+import os
+from datetime import datetime
+
+import httpx
+
+
+def _md_to_notion_blocks(content: str) -> list[dict]:
+    """마크다운 텍스트를 Notion block 리스트로 변환."""
+    blocks = []
+    for line in content.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        text = stripped[:2000]
+        if stripped.startswith("### "):
+            blocks.append({"object": "block", "type": "heading_3",
+                           "heading_3": {"rich_text": [{"text": {"content": text[4:]}}]}})
+        elif stripped.startswith("## "):
+            blocks.append({"object": "block", "type": "heading_2",
+                           "heading_2": {"rich_text": [{"text": {"content": text[3:]}}]}})
+        elif stripped.startswith("# "):
+            blocks.append({"object": "block", "type": "heading_1",
+                           "heading_1": {"rich_text": [{"text": {"content": text[2:]}}]}})
+        elif stripped.startswith("- "):
+            blocks.append({"object": "block", "type": "bulleted_list_item",
+                           "bulleted_list_item": {"rich_text": [{"text": {"content": text[2:]}}]}})
+        else:
+            blocks.append({"object": "block", "type": "paragraph",
+                           "paragraph": {"rich_text": [{"text": {"content": text}}]}})
+    return blocks
+
+
+def write_worklog_to_notion(
+    title: str,
+    content: str,
+    project: str,
+    notion_token: str = "",
+    notion_db_id: str = "",
+    cost: float = 0.0,
+    duration: int = 0,
+    model: str = "claude-sonnet-4-6",
+    tokens: int = 0,
+) -> str:
+    """워크로그를 Notion DB에 기록한다.
+
+    Args:
+        title: 작업 제목 (Notion 페이지 제목)
+        content: 워크로그 내용 (마크다운)
+        project: 프로젝트 이름
+        notion_token: Notion API 토큰. 미지정 시 NOTION_TOKEN 환경변수 사용
+        notion_db_id: Notion DB ID. 미지정 시 NOTION_DB_ID 환경변수 사용
+        cost: 이번 작업 비용 (USD)
+        duration: 소요 시간 (분)
+        model: 사용한 모델
+        tokens: 사용한 토큰 수
+    """
+    token = notion_token or os.environ.get("NOTION_TOKEN", "")
+    db_id = notion_db_id or os.environ.get("NOTION_DB_ID", "")
+
+    if not token:
+        raise ValueError("NOTION_TOKEN이 필요합니다. 파라미터 또는 환경변수로 설정하세요.")
+    if not db_id:
+        raise ValueError("NOTION_DB_ID가 필요합니다. 파라미터 또는 환경변수로 설정하세요.")
+
+    now = datetime.now().isoformat()
+    blocks = _md_to_notion_blocks(content)
+
+    payload: dict = {
+        "parent": {"database_id": db_id},
+        "icon": {"type": "emoji", "emoji": "📖"},
+        "properties": {
+            "Title": {"title": [{"text": {"content": title}}]},
+            "Project": {"select": {"name": project}},
+            "Model": {"select": {"name": model}},
+            "DateTime": {"date": {"start": now}},
+        },
+        "children": blocks,
+    }
+
+    if cost:
+        payload["properties"]["Cost"] = {"number": round(cost, 3)}
+    if duration:
+        payload["properties"]["Duration"] = {"number": duration}
+    if tokens:
+        payload["properties"]["Tokens"] = {"number": tokens}
+
+    try:
+        response = httpx.post(
+            "https://api.notion.com/v1/pages",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Notion-Version": "2022-06-28",
+                "Content-Type": "application/json",
+            },
+            json=payload,
+            timeout=30.0,
+        )
+    except httpx.TimeoutException:
+        raise RuntimeError("Notion API 타임아웃 (30초)")
+
+    if response.status_code == 200:
+        return "OK"
+
+    raise RuntimeError(f"Notion API 실패: HTTP {response.status_code} — {response.text[:200]}")

worklog_for_claude-0.1.0/src/worklog_mcp/tools/project_doc.py

@@ -0,0 +1,164 @@
+import re
+from pathlib import Path
+from worklog_mcp.utils.git import get_diff, get_commits_since_file_update
+
+SECTIONS = ["이게 뭔가", "왜 만들었나", "구조", "기술 스택", "주요 결정들", "해결한 문제들", "지금 상태"]
+
+
+def _parse_sections(content: str) -> dict[str, str]:
+    """PROJECT.md 내용을 섹션별로 파싱."""
+    sections: dict[str, str] = {s: "" for s in SECTIONS}
+    current = None
+    lines: list[str] = []
+
+    for line in content.splitlines():
+        m = re.match(r"^## (.+)$", line)
+        if m:
+            if current is not None:
+                sections[current] = "\n".join(lines).strip()
+            candidate = m.group(1).strip()
+            current = candidate if candidate in SECTIONS else None
+            lines = []
+        elif current is not None:
+            lines.append(line)
+
+    if current is not None:
+        sections[current] = "\n".join(lines).strip()
+
+    return sections
+
+
+def read_project_doc(project_path: str) -> dict:
+    """PROJECT.md를 읽어 반환한다.
+
+    Args:
+        project_path: 프로젝트 루트 디렉토리 경로
+    """
+    path = Path(project_path).resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"Path not found: {project_path}")
+
+    doc_path = path / "PROJECT.md"
+    if not doc_path.exists():
+        return {"exists": False, "content": "", "sections": {}}
+
+    content = doc_path.read_text(encoding="utf-8")
+    return {
+        "exists": True,
+        "content": content,
+        "sections": _parse_sections(content),
+    }
+
+
+def create_project_doc(project_path: str, sections: dict[str, str]) -> str:
+    """PROJECT.md를 생성한다. 이미 존재하면 에러.
+
+    Args:
+        project_path: 프로젝트 루트 디렉토리 경로
+        sections: 섹션별 초기 내용 (없으면 빈 섹션)
+    """
+    path = Path(project_path).resolve()
+    if not path.exists():
+        raise FileNotFoundError(f"Path not found: {project_path}")
+
+    doc_path = path / "PROJECT.md"
+    if doc_path.exists():
+        raise FileExistsError(f"PROJECT.md already exists at {doc_path}")
+
+    project_name = path.name
+    lines = [f"# {project_name}\n"]
+    for section in SECTIONS:
+        lines.append(f"\n## {section}\n")
+        content = sections.get(section, "")
+        if content:
+            lines.append(f"{content}\n")
+
+    doc_path.write_text("".join(lines), encoding="utf-8")
+    return f"Created {doc_path}"
+
+
+def analyze_gaps(project_path: str, n: int = 10) -> dict:
+    """PROJECT.md와 최근 변경사항을 반환한다. Claude가 gap을 판단한다.
+
+    Args:
+        project_path: 프로젝트 루트 디렉토리 경로
+        n: 분석할 최근 커밋 수 (기본 10)
+
+    Returns:
+        {
+            "project_doc": str | None,       # 현재 PROJECT.md 내용 (없으면 None)
+            "sections": dict[str, str],      # 섹션별 파싱 결과 (없으면 {})
+            "diff_mode": "full" | "summary",
+            "diff": str,
+            "changed_files": list[str],
+            "commits": list[str],
+            "line_count": int,
+            "commits_since_doc_update": int, # PROJECT.md 마지막 수정 이후 커밋 수
+        }
+    """
+    path = Path(project_path).resolve()
+
+    diff_info = get_diff(str(path), n=n)
+
+    doc_path = path / "PROJECT.md"
+    if doc_path.exists():
+        project_doc = doc_path.read_text(encoding="utf-8")
+        sections = _parse_sections(project_doc)
+    else:
+        project_doc = None
+        sections = {}
+
+    commits_since = get_commits_since_file_update(str(path), "PROJECT.md")
+
+    return {
+        "project_doc": project_doc,
+        "sections": sections,
+        "diff_mode": diff_info["mode"],
+        "diff": diff_info["diff"],
+        "changed_files": diff_info["changed_files"],
+        "commits": diff_info["commits"],
+        "line_count": diff_info["line_count"],
+        "commits_since_doc_update": commits_since,
+    }
+
+
+def update_project_doc(
+    project_path: str, section: str, content: str, append: bool = False
+) -> str:
+    """PROJECT.md의 특정 섹션을 업데이트한다.
+
+    Args:
+        project_path: 프로젝트 루트 디렉토리 경로
+        section: 업데이트할 섹션명 (예: "이게 뭔가")
+        content: 새 내용
+        append: True면 기존 내용에 추가, False면 교체
+    """
+    path = Path(project_path).resolve()
+    doc_path = path / "PROJECT.md"
+
+    if not doc_path.exists():
+        raise FileNotFoundError(f"PROJECT.md not found at {doc_path}")
+
+    if section not in SECTIONS:
+        raise ValueError(f"Invalid section: '{section}'. Must be one of: {SECTIONS}")
+
+    full_content = doc_path.read_text(encoding="utf-8")
+    parsed = _parse_sections(full_content)
+
+    if append and parsed.get(section):
+        parsed[section] = parsed[section] + "\n" + content
+    else:
+        parsed[section] = content
+
+    # 재조립: 헤더(# 프로젝트명) 유지
+    header_match = re.match(r"^(#[^\n]*\n)", full_content)
+    header = header_match.group(1) if header_match else ""
+
+    lines = [header] if header else []
+    for s in SECTIONS:
+        lines.append(f"\n## {s}\n")
+        if parsed.get(s):
+            lines.append(f"{parsed[s]}\n")
+
+    doc_path.write_text("".join(lines), encoding="utf-8")
+    return f"Updated section '{section}' in {doc_path}"