mcp-orbit 0.2.0__tar.gz

mcp_orbit-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.duckdb
+*.duckdb.wal
+*.db-journal
+.DS_Store
+CLAUDE.local.md
+.serena/
+.playwright-mcp/

mcp_orbit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomer Brami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_orbit-0.2.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: mcp-orbit
+Version: 0.2.0
+Summary: MCP server for the orbit Claude Code plugin: project management with time tracking
+Project-URL: Homepage, https://github.com/tomerbr1/claude-orbit
+Project-URL: Repository, https://github.com/tomerbr1/claude-orbit
+Project-URL: Issues, https://github.com/tomerbr1/claude-orbit/issues
+Author-email: Tomer Brami <tomerbrami@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,mcp,model-context-protocol,orbit,task-tracking
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: orbit-db>=1.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MCP Orbit Server
+
+MCP server for orbit project management with time tracking.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```bash
+mcp-orbit
+```
+
+Or via uvx:
+
+```bash
+uvx --from ~/.claude/plugins/local/orbit/mcp-server mcp-orbit
+```

mcp_orbit-0.2.0/README.md

@@ -0,0 +1,21 @@
+# MCP Orbit Server
+
+MCP server for orbit project management with time tracking.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```bash
+mcp-orbit
+```
+
+Or via uvx:
+
+```bash
+uvx --from ~/.claude/plugins/local/orbit/mcp-server mcp-orbit
+```

mcp_orbit-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "mcp-orbit"
+version = "0.2.0"
+description = "MCP server for the orbit Claude Code plugin: project management with time tracking"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    {name = "Tomer Brami", email = "tomerbrami@gmail.com"}
+]
+keywords = ["claude-code", "orbit", "mcp", "model-context-protocol", "task-tracking"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "orbit-db>=1.0.0",
+    "mcp>=1.0.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/tomerbr1/claude-orbit"
+Repository = "https://github.com/tomerbr1/claude-orbit"
+Issues = "https://github.com/tomerbr1/claude-orbit/issues"
+
+[project.scripts]
+mcp-orbit = "mcp_orbit.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_orbit"]

mcp_orbit-0.2.0/src/mcp_orbit/__init__.py

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

mcp_orbit-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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