mcp-orbit 0.2.0__py3-none-any.whl

mcp_orbit/__init__.py

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

mcp_orbit/app.py

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

mcp_orbit/config.py

@@ -0,0 +1,25 @@
+"""Configuration for the orbit 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() / ".claude" / "tasks.db"
+
+    # Centralized orbit root directory
+    orbit_root: Path = Path.home() / ".claude" / "orbit"
+
+    # Active and completed subdirectory names
+    active_dir_name: str = "active"
+    completed_dir_name: str = "completed"
+
+    class Config:
+        env_prefix = "ORBIT_"
+
+
+settings = Settings()

mcp_orbit/db.py

@@ -0,0 +1,35 @@
+"""Database wrapper for orbit_db."""
+
+from orbit_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_orbit/errors.py

@@ -0,0 +1,85 @@
+"""Error codes and handling for the orbit 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"
+
+
+class OrbitError(Exception):
+    """Base exception for orbit 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(OrbitError):
+    """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 OrbitFileNotFoundError(OrbitError):
+    """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(OrbitError):
+    """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(OrbitError):
+    """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_orbit/helpers.py

@@ -0,0 +1,194 @@
+"""Shared helper functions used across tool modules."""
+
+import logging
+from pathlib import Path
+
+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__)
+
+
+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.orbit_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 orbit files exist
+    has_orbit_files = False
+    if task.full_path:
+        task_dir = settings.orbit_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 orbit files
+    progress = None
+    if task.full_path:
+        progress = _parse_task_progress(
+            settings.orbit_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

mcp_orbit/iteration_log.py

@@ -0,0 +1,333 @@
+"""Iteration log integration for autonomous task execution.
+
+Progress tracking is done ONLY via checkboxes in the tasks.md file.
+Prompts do not have status fields - tasks.md is the single source of truth.
+"""
+
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+def get_iteration_log_path(task_dir: str | Path, task_name: str) -> Path:
+    """Get path to the iteration log file."""
+    return Path(task_dir) / f"{task_name}-iteration-log.md"
+
+
+def log_iteration(
+    task_dir: str | Path,
+    task_name: str,
+    iteration: int,
+    status: str,
+    task_title: str | None = None,
+    what_done: list[str] | None = None,
+    files_modified: list[str] | None = None,
+    validation: dict[str, str] | None = None,
+    error_details: str | None = None,
+    next_steps: list[str] | None = None,
+) -> str:
+    """Log an iteration to the iteration log.
+
+    Args:
+        task_dir: Task directory path
+        task_name: Task name
+        iteration: Iteration number
+        status: SUCCESS, FAILED, or BLOCKED
+        task_title: Title of the task being worked on
+        what_done: List of what was done/attempted
+        files_modified: List of modified files
+        validation: Dict of validation results {tests: PASS, typecheck: PASS, etc.}
+        error_details: Error details if status is FAILED
+        next_steps: Suggested next steps if FAILED
+
+    Returns:
+        The log entry that was written
+    """
+    log_path = get_iteration_log_path(task_dir, task_name)
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+    # Build the log entry
+    entry = f"\n## Iteration {iteration}"
+    if task_title:
+        entry += f" - {task_title}"
+    entry += f"\n**Status:** {status}\n"
+    entry += f"**Time:** {timestamp}\n\n"
+
+    if what_done:
+        header = (
+            "### What was done" if status == "SUCCESS" else "### What was attempted"
+        )
+        entry += f"{header}\n"
+        for item in what_done:
+            entry += f"- {item}\n"
+        entry += "\n"
+
+    if files_modified:
+        entry += "### Files modified\n"
+        for f in files_modified:
+            entry += f"- {f}\n"
+        entry += "\n"
+
+    if validation:
+        entry += "### Validation\n"
+        for check, result in validation.items():
+            entry += f"- {check}: {result}\n"
+        entry += "\n"
+
+    if error_details:
+        entry += f"### Error details\n{error_details}\n\n"
+
+    if next_steps:
+        entry += "### Next steps to try\n"
+        for step in next_steps:
+            entry += f"- {step}\n"
+        entry += "\n"
+
+    # Append to log
+    if log_path.exists():
+        with open(log_path, "a") as f:
+            f.write(entry)
+    else:
+        # Create new log with header
+        log_path.write_text(f"""# Iteration Log - {task_name}
+
+**Started:** {timestamp.split()[0]}
+**Max Iterations:** 20
+
+---
+{entry}""")
+
+    return entry
+
+
+def log_completion(
+    task_dir: str | Path,
+    task_name: str,
+    total_iterations: int,
+    duration_seconds: int,
+) -> str:
+    """Log task completion to the iteration log."""
+    log_path = get_iteration_log_path(task_dir, task_name)
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+
+    entry = f"""
+---
+
+# COMPLETED
+**Finished:** {timestamp}
+**Total iterations:** {total_iterations}
+**Duration:** {duration_seconds}s
+"""
+
+    if log_path.exists():
+        with open(log_path, "a") as f:
+            f.write(entry)
+
+    return entry
+
+
+def log_timeout(
+    task_dir: str | Path,
+    task_name: str,
+    max_iterations: int,
+    duration_seconds: int,
+) -> str:
+    """Log timeout to the iteration log."""
+    log_path = get_iteration_log_path(task_dir, task_name)
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+
+    entry = f"""
+---
+
+# TIMEOUT
+**Stopped:** {timestamp}
+**Reached max iterations:** {max_iterations}
+**Duration:** {duration_seconds}s
+"""
+
+    if log_path.exists():
+        with open(log_path, "a") as f:
+            f.write(entry)
+
+    return entry
+
+
+def get_iteration_status(task_dir: str | Path, task_name: str) -> dict[str, Any]:
+    """Get the current iteration loop status from the log file.
+
+    Returns:
+        Dict with status info: {
+            exists: bool,
+            started: str | None,
+            max_iterations: int | None,
+            iterations: int,
+            last_status: str | None,
+            completed: bool,
+            timed_out: bool,
+            blocked: bool,
+        }
+    """
+    log_path = get_iteration_log_path(task_dir, task_name)
+
+    if not log_path.exists():
+        return {
+            "exists": False,
+            "started": None,
+            "max_iterations": None,
+            "iterations": 0,
+            "last_status": None,
+            "completed": False,
+            "timed_out": False,
+            "blocked": False,
+        }
+
+    content = log_path.read_text()
+
+    # Parse started time
+    started_match = re.search(r"\*\*Started:\*\* (.+)", content)
+    started = started_match.group(1) if started_match else None
+
+    # Parse max iterations
+    max_match = re.search(r"\*\*Max Iterations:\*\* (\d+)", content)
+    max_iterations = int(max_match.group(1)) if max_match else None
+
+    # Count iterations
+    iterations = len(re.findall(r"## Iteration \d+", content))
+
+    # Get last status
+    status_matches = list(
+        re.finditer(r"\*\*Status:\*\* (SUCCESS|FAILED|BLOCKED)", content)
+    )
+    last_status = status_matches[-1].group(1) if status_matches else None
+
+    # Check for completion/timeout
+    completed = "# COMPLETED" in content
+    timed_out = "# TIMEOUT" in content
+    blocked = "BLOCKED" in content and not completed
+
+    return {
+        "exists": True,
+        "started": started,
+        "max_iterations": max_iterations,
+        "iterations": iterations,
+        "last_status": last_status,
+        "completed": completed,
+        "timed_out": timed_out,
+        "blocked": blocked,
+    }
+
+
+def _task_id_to_display(task_id: str) -> str:
+    """Convert task_id format to display format.
+
+    "01" -> "1"
+    "01-02" -> "1.2"
+    """
+    if "-" in task_id:
+        parts = task_id.split("-")
+        return f"{int(parts[0])}.{int(parts[1])}"
+    return str(int(task_id))
+
+
+def _is_task_completed(tasks_file: Path, task_id: str) -> bool:
+    """Check if a task is marked as completed in the tasks file.
+
+    Returns True if the checkbox is marked [x], False if [ ] or not found.
+    """
+    if not tasks_file.exists():
+        return False
+
+    content = tasks_file.read_text()
+    display_id = _task_id_to_display(task_id)
+
+    # Escape dots for regex
+    id_escaped = display_id.replace(".", r"\.")
+
+    # Check if task is marked completed: "- [x] N." or "- [x] N:"
+    if re.search(rf"^\s*- \[x\] {id_escaped}[.:]", content, re.MULTILINE):
+        return True
+
+    return False
+
+
+def get_prompts_status(
+    task_dir: str | Path, task_name: str | None = None
+) -> dict[str, Any]:
+    """Get status of optimized prompts for a task.
+
+    Progress is tracked via checkboxes in the tasks.md file, not via status fields
+    in prompt files.
+
+    Returns:
+        Dict with prompt status: {
+            exists: bool,
+            total: int,
+            completed: int,  # Tasks marked [x] in tasks.md
+            remaining: int,  # Tasks still [ ] in tasks.md
+            next_prompt: str | None,  # Path to next prompt for uncompleted task
+        }
+    """
+    task_dir = Path(task_dir)
+    prompts_dir = task_dir / "prompts"
+
+    if not prompts_dir.exists():
+        return {
+            "exists": False,
+            "total": 0,
+            "completed": 0,
+            "remaining": 0,
+            "next_prompt": None,
+        }
+
+    prompt_files = list(prompts_dir.glob("task-*-prompt.md"))
+
+    if not prompt_files:
+        return {
+            "exists": True,
+            "total": 0,
+            "completed": 0,
+            "remaining": 0,
+            "next_prompt": None,
+        }
+
+    # Find tasks file
+    if task_name:
+        tasks_file = task_dir / f"{task_name}-tasks.md"
+    else:
+        # Try to infer from directory name
+        tasks_file = task_dir / f"{task_dir.name}-tasks.md"
+
+    completed = 0
+    remaining = 0
+    next_prompt = None
+
+    for pf in sorted(prompt_files):
+        content = pf.read_text()
+
+        # Extract task_id from YAML frontmatter
+        task_id_match = re.search(
+            r"^task_id:\s*[\"']?([^\"'\n]+)[\"']?", content, re.MULTILINE
+        )
+        if task_id_match:
+            task_id = task_id_match.group(1).strip()
+
+            if _is_task_completed(tasks_file, task_id):
+                completed += 1
+            else:
+                remaining += 1
+                if next_prompt is None:
+                    next_prompt = str(pf)
+        else:
+            # No task_id found, count as remaining
+            remaining += 1
+            if next_prompt is None:
+                next_prompt = str(pf)
+
+    return {
+        "exists": True,
+        "total": len(prompt_files),
+        "completed": completed,
+        "remaining": remaining,
+        "next_prompt": next_prompt,
+    }