mcp-missioncache 1.0.2__py3-none-any.whl

mcp_missioncache/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for MissionCache project management."""
+
+__version__ = "1.0.0"

mcp_missioncache/active_task.py

@@ -0,0 +1,160 @@
+"""Per-session active MissionCache task pointer.
+
+Tracks which MissionCache checklist task numbers (e.g. ``"54a"``, ``"56"``) the
+caller is currently focused on. The statusline reads this to render the
+``Task:`` field, replacing the previous read of Claude Code's internal
+TodoList (which duplicated information Claude already prints in chat).
+
+Identifier shape: MissionCache's DB tracks projects, not checklist items. The
+items the user picks from (``54a``, ``8``, ``0.1``) are markdown lines in
+``<project>-tasks.md`` parsed by their numbering, not rows in ``tasks.db``.
+So the active-task pointer keys by ``(project_name, task_numbers)``.
+
+State file: ``~/.claude/hooks/state/active-missioncache-task/<session-id>.json``::
+
+    {
+      "project_name": "orbit-public-release",
+      "task_numbers": ["54a"],
+      "updated": "2026-04-28T12:34:56+03:00"
+    }
+
+Per-session keying matches the existing ``hooks/state/projects/<sid>.json``
+pattern. Concurrent sessions on the same project don't clobber each other.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+
+# Lives under ``~/.claude/`` (Claude Code's state dir), not ``~/.missioncache/``,
+# because session-scoped state is keyed by Claude Code session ids and
+# parallels the existing hook pointers.
+STATE_DIR = Path.home() / ".claude" / "hooks" / "state" / "active-missioncache-task"
+
+# Conservative session-id shape: alphanumeric + ``._-`` only, bounded length.
+# Covers Claude Code's UUIDs and Codex/OpenCode-style ids; rejects path
+# separators, ``..`` components, and null bytes that could escape STATE_DIR
+# when joined into a filename.
+_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+
+
+def _safe_session_id(session_id: str) -> bool:
+    """Return True iff session_id is safe to use as a filename component.
+
+    Defense in depth - the MCP layer already validates non-empty session ids,
+    but accepting any string here would let a misbehaving caller traverse
+    out of ``STATE_DIR`` via ``../foo`` or ``/etc/passwd``.
+    """
+    if not session_id or ".." in session_id:
+        return False
+    return bool(_SESSION_ID_RE.match(session_id))
+
+
+def _pointer_path(session_id: str) -> Path:
+    return STATE_DIR / f"{session_id}.json"
+
+
+def read_pointer(session_id: str) -> dict | None:
+    """Return the pointer dict for this session, or None if unset/unreadable."""
+    if not _safe_session_id(session_id):
+        return None
+    path = _pointer_path(session_id)
+    try:
+        return json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def write_pointer(
+    session_id: str, project_name: str, task_numbers: list[str]
+) -> Path:
+    """Write or replace the active-task pointer for this session.
+
+    Atomic via tmp-then-rename. Returns the written path. Raises
+    ValueError on session ids that would escape ``STATE_DIR`` - callers
+    above the MCP boundary should have already validated, but we
+    re-check here as defense in depth.
+    """
+    if not _safe_session_id(session_id):
+        raise ValueError(f"unsafe session_id: {session_id!r}")
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    path = _pointer_path(session_id)
+    payload = {
+        "project_name": project_name,
+        "task_numbers": list(task_numbers),
+        "updated": datetime.now().astimezone().isoformat(),
+    }
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(payload, indent=2))
+    os.replace(tmp, path)
+    return path
+
+
+def clear_pointer(session_id: str) -> bool:
+    """Delete the pointer for this session. Returns True if a file was removed."""
+    if not _safe_session_id(session_id):
+        return False
+    path = _pointer_path(session_id)
+    try:
+        path.unlink()
+        return True
+    except FileNotFoundError:
+        return False
+    except OSError:
+        return False
+
+
+def remove_task_numbers_everywhere(
+    project_name: str, completed_numbers: list[str]
+) -> list[str]:
+    """Remove ``completed_numbers`` from every session's pointer for ``project_name``.
+
+    Used as the auto-clear hook on ``update_tasks_file``: when items get
+    marked ``[x]``, they should disappear from any active-task pointer that
+    referenced them. Empty pointers are removed.
+
+    Returns the list of session ids that were modified (for logging/tests).
+    """
+    if not completed_numbers:
+        return []
+    if not STATE_DIR.is_dir():
+        return []
+
+    completed_set = set(completed_numbers)
+    affected: list[str] = []
+
+    for path in STATE_DIR.glob("*.json"):
+        try:
+            data = json.loads(path.read_text())
+        except (OSError, json.JSONDecodeError):
+            continue
+        if data.get("project_name") != project_name:
+            continue
+        existing = data.get("task_numbers") or []
+        remaining = [n for n in existing if n not in completed_set]
+        if remaining == existing:
+            continue
+        session_id = path.stem
+        if not _safe_session_id(session_id):
+            # Filename inside STATE_DIR but not a shape we'd write - leave alone.
+            continue
+        affected.append(session_id)
+        # Write empty pointer first when the set drains, then best-effort
+        # unlink. If unlink fails (permissions, FS error), the empty
+        # pointer is inert (statusline treats empty task_numbers as
+        # "hide field"), avoiding a stale-data race where the original
+        # file with the now-completed numbers would otherwise persist.
+        if remaining:
+            write_pointer(session_id, project_name, remaining)
+        else:
+            write_pointer(session_id, project_name, [])
+            try:
+                path.unlink()
+            except OSError:
+                pass
+
+    return affected

mcp_missioncache/app.py

@@ -0,0 +1,5 @@
+"""FastMCP application instance, shared across tool modules."""
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("missioncache")

mcp_missioncache/config.py

@@ -0,0 +1,29 @@
+"""Configuration for the MissionCache MCP server."""
+
+from pathlib import Path
+
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Server configuration from environment variables."""
+
+    # Path to the task database
+    db_path: Path = Path.home() / ".missioncache" / "tasks.db"
+
+    # Centralized MissionCache root directory
+    root: Path = Path.home() / ".missioncache"
+
+    # Active and completed subdirectory names
+    active_dir_name: str = "active"
+    completed_dir_name: str = "completed"
+
+    # Dashboard base URL for out-of-band sync notifications (task creation).
+    # Failures are silently ignored - dashboard is optional.
+    dashboard_url: str = "http://localhost:8787"
+
+    class Config:
+        env_prefix = "MISSIONCACHE_"
+
+
+settings = Settings()

mcp_missioncache/db.py

@@ -0,0 +1,35 @@
+"""Database wrapper for missioncache_db."""
+
+from missioncache_db import Repository, Task, TaskDB, TaskStatus
+
+from .config import settings
+
+# Module-level singleton
+_db: TaskDB | None = None
+
+
+def get_db() -> TaskDB:
+    """Get or create the TaskDB singleton."""
+    global _db
+    if _db is None:
+        _db = TaskDB(db_path=settings.db_path)
+        _db.initialize()
+    return _db
+
+
+def repo_to_dict(repo: Repository) -> dict:
+    """Convert Repository dataclass to dict."""
+    from dataclasses import asdict
+
+    return asdict(repo)
+
+
+# Re-export for convenience
+__all__ = [
+    "get_db",
+    "repo_to_dict",
+    "Task",
+    "Repository",
+    "TaskDB",
+    "TaskStatus",
+]

mcp_missioncache/errors.py

@@ -0,0 +1,86 @@
+"""Error codes and handling for the MissionCache MCP server."""
+
+from enum import Enum
+from typing import Any
+
+
+class ErrorCode(str, Enum):
+    """Standard error codes for structured error responses."""
+
+    TASK_NOT_FOUND = "TASK_NOT_FOUND"
+    REPO_NOT_FOUND = "REPO_NOT_FOUND"
+    FILE_NOT_FOUND = "FILE_NOT_FOUND"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    DB_ERROR = "DB_ERROR"
+    PERMISSION_ERROR = "PERMISSION_ERROR"
+    INVALID_STATE = "INVALID_STATE"
+    OPERATION_FAILED = "OPERATION_FAILED"
+    ALREADY_EXISTS = "ALREADY_EXISTS"
+
+
+class MissionCacheError(Exception):
+    """Base exception for MissionCache errors with structured response."""
+
+    def __init__(
+        self, code: ErrorCode, message: str, details: dict[str, Any] | None = None
+    ):
+        self.code = code
+        self.message = message
+        self.details = details or {}
+        super().__init__(message)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for MCP response."""
+        return {
+            "error": True,
+            "code": self.code.value,
+            "message": self.message,
+            "details": self.details,
+        }
+
+
+class TaskNotFoundError(MissionCacheError):
+    """Task not found in database."""
+
+    def __init__(self, task_id: int | str, message: str | None = None):
+        super().__init__(
+            ErrorCode.TASK_NOT_FOUND,
+            message or f"Task not found: {task_id}",
+            {"task_id": task_id},
+        )
+
+
+class MissionCacheFileNotFoundError(MissionCacheError):
+    """File not found on filesystem."""
+
+    def __init__(self, path: str, message: str | None = None):
+        super().__init__(
+            ErrorCode.FILE_NOT_FOUND,
+            message or f"File not found: {path}",
+            {"path": path},
+        )
+
+
+class ValidationError(MissionCacheError):
+    """Input validation failed."""
+
+    def __init__(self, message: str, field: str | None = None):
+        details = {"field": field} if field else {}
+        super().__init__(ErrorCode.VALIDATION_ERROR, message, details)
+
+
+class InvalidStateError(MissionCacheError):
+    """Operation invalid for current state."""
+
+    def __init__(
+        self,
+        message: str,
+        current_state: str | None = None,
+        expected_state: str | None = None,
+    ):
+        details = {}
+        if current_state:
+            details["current_state"] = current_state
+        if expected_state:
+            details["expected_state"] = expected_state
+        super().__init__(ErrorCode.INVALID_STATE, message, details)

mcp_missioncache/helpers.py

@@ -0,0 +1,377 @@
+"""Shared helper functions used across tool modules."""
+
+import asyncio
+import logging
+import os
+import re
+import sqlite3
+import urllib.request
+from datetime import datetime
+from pathlib import Path
+
+import missioncache_db  # type: ignore[import-not-found]
+
+from . import orbit
+from .config import settings
+from .db import Task, get_db
+from .errors import TaskNotFoundError, ValidationError
+from .models import TaskDetail, TaskProgress, TaskSummary
+
+logger = logging.getLogger(__name__)
+
+
+# Session-id charset for binding. Matches active_task._SESSION_ID_RE so any
+# session_id accepted there is also bindable here. Bounded length (128) is
+# conservative; Claude Code UUIDs are 36 chars, other tools may use slightly
+# longer ids. Defends downstream filename interpolation in the per-session
+# pointer write against path traversal.
+_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+
+
+def _resolve_session_id(session_id: str | None) -> str | None:
+    """Resolve the effective Claude session id for a binding tool.
+
+    Precedence: a non-empty explicit ``session_id`` wins. An empty string
+    or ``None`` is treated as "no id provided" and falls back to
+    ``CLAUDE_CODE_SESSION_ID``, which Claude Code 2.1.154+ injects into
+    every stdio MCP subprocess's environment. (Empty and absent are
+    deliberately equivalent here: a caller that fumbles client-side
+    resolution and passes "" still binds to the right session instead of
+    failing.) The env value is stripped, so a stray trailing newline or
+    whitespace-only value normalizes to ``None`` rather than leaking into a
+    filename or DB row. The env var is per subprocess and a stdio server is 1:1 with
+    the Claude Code session that spawned it, so the fallback always names
+    the calling session - safe even for concurrent sessions (each has its
+    own subprocess + env).
+
+    Returns ``None`` when neither is available: pre-2.1.154 Claude Code, or
+    a non-Claude client (Codex/OpenCode) that doesn't set the var. Callers
+    treat ``None`` exactly as a missing session id (skip binding, or raise),
+    so behavior for those clients is unchanged. The returned value is NOT
+    validated here - downstream ``_bind_session_to_project`` /
+    ``active_task.write_pointer`` enforce the session-id charset before it
+    reaches a filename or DB row.
+    """
+    if session_id:
+        return session_id
+    return (os.environ.get("CLAUDE_CODE_SESSION_ID") or "").strip() or None
+
+
+def _bind_session_to_project(session_id: str | None, project_name: str) -> bool:
+    """Bind a Claude Code session to a project so the statusline picks it up.
+
+    Writes the ``project_state`` row in ``~/.claude/hooks-state.db`` (source
+    of truth the statusline reads) and the per-session
+    ``~/.claude/hooks/state/projects/<sid>.json`` pointer (read by
+    ``find_task_for_cwd``) atomically with task creation. This eliminates
+    the "Claude skipped the binding step" failure mode where the slash
+    command's client-side bash binding gets bypassed silently.
+
+    Mirrors ``hooks/session_start.py:_bind_session_to_project``. The two
+    helpers are deliberately not yet extracted to a shared library; if a
+    third caller appears, this is the right time to lift them into
+    ``missioncache_db``.
+
+    Direct SQL only - the dashboard may not be running, and degrading
+    silently to HTTP would re-introduce the failure mode this binding is
+    designed to eliminate. Failures log a stderr breadcrumb but do not
+    raise; the binding is best-effort, task creation is the load-bearing
+    operation.
+
+    Returns ``True`` on success, ``False`` on validation or IO failure.
+    """
+    if not session_id or not project_name:
+        return False
+    if not _SESSION_ID_RE.match(session_id):
+        logger.warning("Skipping session binding: invalid session_id shape")
+        return False
+
+    # Resolve missioncache_db symbols via attribute access (not module-level
+    # `from missioncache_db import X`) so test fixtures that monkeypatch
+    # ``missioncache_db.HOOKS_STATE_DB_PATH`` to a tmp path are honored.
+    db_path = missioncache_db.HOOKS_STATE_DB_PATH
+    try:
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(str(db_path))
+        try:
+            missioncache_db.init_hooks_state_db_schema(conn)
+            conn.execute(
+                "INSERT INTO project_state (session_id, project_name, updated_at) "
+                "VALUES (?, ?, datetime('now', 'localtime')) "
+                "ON CONFLICT(session_id) DO UPDATE SET "
+                "project_name = excluded.project_name, "
+                "updated_at = datetime('now', 'localtime')",
+                (session_id, project_name),
+            )
+            conn.commit()
+        finally:
+            conn.close()
+    except sqlite3.Error as e:
+        logger.warning(
+            f"Failed to bind session to project={project_name!r}: {e}"
+        )
+        return False
+
+    pointer_file = (
+        Path.home() / ".claude" / "hooks" / "state" / "projects" / f"{session_id}.json"
+    )
+    try:
+        missioncache_db.atomic_write_json(
+            pointer_file,
+            {
+                "projectName": project_name,
+                "updated": datetime.now().astimezone().isoformat(),
+                "sessionId": session_id,
+            },
+        )
+    except OSError as e:
+        # DB row already written - the per-session pointer is a secondary
+        # concern (used by find_task_for_cwd, not by the statusline). Log
+        # but report partial success since the statusline binding landed.
+        logger.warning(f"Failed to write per-session pointer: {e}")
+        return False
+    return True
+
+
+async def _notify_dashboard_task_created() -> None:
+    """Fire-and-forget POST to the dashboard so it syncs immediately.
+
+    The dashboard polls SQLite every 60 seconds; this shaves that lag
+    off the user-visible "created a project, doesn't show up yet" case.
+    Silently swallows every failure - the dashboard is optional, may
+    not be running, and we never want to fail a tool call over it.
+    """
+    url = f"{settings.dashboard_url}/api/hooks/task-created"
+
+    def _post() -> None:
+        try:
+            req = urllib.request.Request(
+                url,
+                data=b"{}",
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            urllib.request.urlopen(req, timeout=0.5)
+        except Exception:
+            pass
+
+    await asyncio.to_thread(_post)
+
+
+def _resolve_to_git_root(path: str) -> str:
+    """Walk parents of ``path`` looking for ``.git``; return the git root.
+
+    Mirrors ``git rev-parse --show-toplevel`` semantics - the first
+    ancestor (closest to ``path``) that contains a ``.git`` entry
+    (directory or file, the latter for submodules) is the git root.
+    Falls back to the resolved input if no ancestor has ``.git``
+    before the filesystem root, so non-git project locations stay
+    supported.
+
+    Used at the MCP-tool boundary (``create_orbit_files``,
+    ``set_task_repo``) to enforce git-root resolution server-side
+    instead of trusting callers to do it. Slash command guidance
+    can be skipped silently by the model; tool-level enforcement
+    cannot. Callers that legitimately want a sub-package within a
+    monorepo to be the project boundary should pass
+    ``resolve_git_root=False`` to the tool rather than calling this
+    helper directly.
+
+    Symlinks are followed once via ``Path.resolve()`` before the walk
+    so a symlink to a subdir of a git repo lands on the real path.
+    ``OSError`` mid-walk (permission denied on ``.git`` probing) is
+    treated as "no git root found" and returns the resolved input.
+    """
+    current = Path(path).expanduser().resolve()
+
+    walker = current
+    while walker != walker.parent:
+        try:
+            if (walker / ".git").exists():
+                return str(walker)
+        except OSError:
+            return str(current)
+        walker = walker.parent
+    return str(current)
+
+
+def _validate_path(
+    path: str, field_name: str = "path", must_be_under: Path | None = None
+) -> Path:
+    """Validate and resolve a filesystem path.
+
+    Checks for empty strings and null bytes, then resolves the path.
+    If must_be_under is provided, verifies the resolved path is contained
+    within that directory.
+
+    Raises:
+        ValidationError: If path is empty, contains null bytes, or resolves
+            outside the required root directory.
+    """
+    if not path or not path.strip():
+        raise ValidationError(f"{field_name} cannot be empty", field=field_name)
+    if "\x00" in path:
+        raise ValidationError(f"{field_name} contains null bytes", field=field_name)
+    resolved = Path(path).resolve()
+    if must_be_under is not None:
+        root = must_be_under.resolve()
+        if resolved != root and not str(resolved).startswith(str(root) + "/"):
+            raise ValidationError(
+                f"{field_name} must be within {root}", field=field_name
+            )
+    return resolved
+
+
+def _resolve_task_dir(
+    db, task_id: int | None, task_name: str | None
+) -> tuple[Path, str]:
+    """Resolve task directory and name from task_id or task_name.
+
+    Returns:
+        Tuple of (task_dir, task_name).
+
+    Raises:
+        TaskNotFoundError: If task cannot be found.
+    """
+    task = None
+    if task_id:
+        task = db.get_task(task_id)
+    elif task_name:
+        task = db.get_task_by_name(task_name)
+
+    if not task:
+        identifier = task_id if task_id is not None else (task_name or "unknown")
+        raise TaskNotFoundError(identifier)
+
+    task_dir = settings.root / task.full_path
+    return task_dir, task.name
+
+
+def _task_to_summary(
+    task: Task, db=None, time_seconds: int | None = None
+) -> TaskSummary:
+    """Convert a Task to TaskSummary with time info.
+
+    Args:
+        task: Task object to convert.
+        db: Database instance (auto-resolved if None).
+        time_seconds: Pre-fetched time in seconds. If None, fetches from DB.
+    """
+    if db is None:
+        db = get_db()
+
+    # Get time tracking info (use pre-fetched if available)
+    if time_seconds is None:
+        time_seconds = db.get_task_time(task.id)
+    time_formatted = db.format_duration(time_seconds)
+
+    # Get effective last updated (uses file mtime if more recent)
+    effective_last = db.get_effective_last_updated(task)
+    last_worked_ago = db.format_time_ago(effective_last)
+
+    # Get repo info if available
+    repo_name = None
+    repo_path = None
+    if task.repo_id:
+        repo = db.get_repo(task.repo_id)
+        if repo:
+            repo_name = repo.short_name
+            repo_path = repo.path
+
+    # Check if MissionCache files exist
+    has_orbit_files = False
+    if task.full_path:
+        task_dir = settings.root / task.full_path
+        has_orbit_files = task_dir.exists() and any(
+            (task_dir / f).exists()
+            for f in [
+                f"{task.name}-context.md",
+                f"{task.name}-tasks.md",
+                f"{task.name}-plan.md",
+                "context.md",
+                "tasks.md",
+            ]
+        )
+
+    return TaskSummary(
+        id=task.id,
+        name=task.name,
+        status=task.status,
+        type=task.task_type,
+        repo_name=repo_name,
+        repo_path=repo_path,
+        jira_key=task.jira_key,
+        tags=task.tags,
+        time_total_seconds=time_seconds,
+        time_formatted=time_formatted,
+        last_worked_on=effective_last,
+        last_worked_ago=last_worked_ago,
+        has_orbit_files=has_orbit_files,
+    )
+
+
+def _task_to_detail(
+    task: Task, include_subtasks: bool = True, include_updates: bool = True
+) -> TaskDetail:
+    """Convert a Task to TaskDetail with full information."""
+    db = get_db()
+
+    # Get base summary fields
+    summary = _task_to_summary(task, db)
+
+    # Parse progress from MissionCache files
+    progress = None
+    if task.full_path:
+        progress = _parse_task_progress(
+            settings.root / task.full_path, task.name
+        )
+
+    # Get subtasks if this is a parent task
+    subtasks = []
+    if include_subtasks:
+        hierarchy = db.get_active_tasks_hierarchical(task.repo_id)
+        if task.id in hierarchy.get("children", {}):
+            for subtask in hierarchy["children"][task.id]:
+                subtasks.append(_task_to_summary(subtask, db))
+
+    # Get recent updates for non-coding tasks
+    recent_updates = []
+    if include_updates and task.task_type == "non-coding":
+        recent_updates = db.get_task_updates(task.id, limit=5)
+
+    return TaskDetail(
+        **summary.model_dump(by_alias=True),
+        full_path=task.full_path,
+        parent_id=task.parent_id,
+        branch=task.branch,
+        pr_url=task.pr_url,
+        created_at=task.created_at,
+        updated_at=task.updated_at,
+        completed_at=task.completed_at,
+        progress=progress,
+        subtasks=subtasks,
+        recent_updates=recent_updates,
+    )
+
+
+def _parse_task_progress(task_dir: Path, task_name: str) -> TaskProgress | None:
+    """Parse progress from the tasks.md file."""
+    if not task_dir.exists():
+        return None
+
+    # Try both naming conventions
+    tasks_files = [
+        task_dir / f"{task_name}-tasks.md",
+        task_dir / "tasks.md",
+    ]
+
+    for tasks_file in tasks_files:
+        if tasks_file.exists():
+            try:
+                content = tasks_file.read_text()
+                return orbit.parse_task_progress(content)
+            except Exception as e:
+                logger.warning(f"Failed to parse {tasks_file}: {e}")
+                continue
+
+    return None