deepwork 0.5.1__py3-none-any.whl → 0.7.0__py3-none-any.whl

deepwork/mcp/server.py

@@ -0,0 +1,253 @@
+"""FastMCP server for DeepWork workflows.
+
+This module creates and configures the MCP server that exposes workflow
+management tools to AI agents.
+
+Usage:
+    deepwork serve --path /path/to/project
+
+IMPORTANT: If you modify any tool signatures, parameters, or return types in this
+file, you MUST also update the documentation in doc/mcp_interface.md to keep it
+in sync with the implementation.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from fastmcp import FastMCP
+
+from deepwork.mcp.quality_gate import QualityGate
+from deepwork.mcp.schemas import (
+    AbortWorkflowInput,
+    FinishedStepInput,
+    StartWorkflowInput,
+)
+from deepwork.mcp.state import StateManager
+from deepwork.mcp.tools import WorkflowTools
+
+# Configure logging
+logger = logging.getLogger("deepwork.mcp")
+
+
+def create_server(
+    project_root: Path | str,
+    enable_quality_gate: bool = True,
+    quality_gate_timeout: int = 120,
+    quality_gate_max_attempts: int = 3,
+) -> FastMCP:
+    """Create and configure the MCP server.
+
+    Args:
+        project_root: Path to the project root
+        enable_quality_gate: Whether to enable quality gate evaluation (default: True)
+        quality_gate_timeout: Timeout in seconds for quality gate (default: 120)
+        quality_gate_max_attempts: Max attempts before failing quality gate (default: 3)
+
+    Returns:
+        Configured FastMCP server instance
+    """
+    project_path = Path(project_root).resolve()
+
+    # Initialize components
+    state_manager = StateManager(project_path)
+
+    quality_gate: QualityGate | None = None
+    if enable_quality_gate:
+        quality_gate = QualityGate(
+            timeout=quality_gate_timeout,
+        )
+
+    tools = WorkflowTools(
+        project_root=project_path,
+        state_manager=state_manager,
+        quality_gate=quality_gate,
+        max_quality_attempts=quality_gate_max_attempts,
+    )
+
+    # Create MCP server
+    mcp = FastMCP(
+        name="deepwork",
+        instructions=_get_server_instructions(),
+    )
+
+    # =========================================================================
+    # MCP Tool Registrations
+    # =========================================================================
+    # IMPORTANT: When modifying these tool signatures (parameters, return types,
+    # descriptions), update doc/mcp_interface.md to keep documentation in sync.
+    # =========================================================================
+
+    def _log_tool_call(tool_name: str, params: dict[str, Any] | None = None) -> None:
+        """Log a tool call with stack information."""
+        stack = [entry.model_dump() for entry in state_manager.get_stack()]
+        log_data = {
+            "tool": tool_name,
+            "stack": stack,
+            "stack_depth": len(stack),
+        }
+        if params:
+            log_data["params"] = params
+        logger.info("MCP tool call: %s", log_data)
+
+    @mcp.tool(
+        description=(
+            "List all available DeepWork workflows. "
+            "Returns job names, workflow definitions, and step information. "
+            "Call this first to discover available workflows."
+        )
+    )
+    def get_workflows() -> dict[str, Any]:
+        """Get all available workflows."""
+        _log_tool_call("get_workflows")
+        response = tools.get_workflows()
+        return response.model_dump()
+
+    @mcp.tool(
+        description=(
+            "Start a new workflow session. "
+            "Creates a git branch, initializes state tracking, and returns "
+            "the first step's instructions. "
+            "Required parameters: goal (what user wants), job_name, workflow_name. "
+            "Optional: instance_id for naming (e.g., 'acme', 'q1-2026'). "
+            "Supports nested workflows - starting a workflow while one is active "
+            "pushes onto the stack. Use abort_workflow to cancel and return to parent."
+        )
+    )
+    async def start_workflow(
+        goal: str,
+        job_name: str,
+        workflow_name: str,
+        instance_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Start a workflow and get first step instructions."""
+        _log_tool_call(
+            "start_workflow",
+            {
+                "goal": goal,
+                "job_name": job_name,
+                "workflow_name": workflow_name,
+                "instance_id": instance_id,
+            },
+        )
+        input_data = StartWorkflowInput(
+            goal=goal,
+            job_name=job_name,
+            workflow_name=workflow_name,
+            instance_id=instance_id,
+        )
+        response = await tools.start_workflow(input_data)
+        return response.model_dump()
+
+    @mcp.tool(
+        description=(
+            "Report that you've finished a workflow step. "
+            "Validates outputs against quality criteria (if configured), "
+            "then returns either: "
+            "'needs_work' with feedback to fix issues, "
+            "'next_step' with instructions for the next step, or "
+            "'workflow_complete' when finished (pops from stack if nested). "
+            "Required: outputs (list of file paths created). "
+            "Optional: notes about work done. "
+            "Optional: quality_review_override_reason to skip quality review (must explain why)."
+        )
+    )
+    async def finished_step(
+        outputs: list[str],
+        notes: str | None = None,
+        quality_review_override_reason: str | None = None,
+    ) -> dict[str, Any]:
+        """Report step completion and get next instructions."""
+        _log_tool_call(
+            "finished_step",
+            {
+                "outputs": outputs,
+                "notes": notes,
+                "quality_review_override_reason": quality_review_override_reason,
+            },
+        )
+        input_data = FinishedStepInput(
+            outputs=outputs,
+            notes=notes,
+            quality_review_override_reason=quality_review_override_reason,
+        )
+        response = await tools.finished_step(input_data)
+        return response.model_dump()
+
+    @mcp.tool(
+        description=(
+            "Abort the current workflow and return to the parent workflow (if nested). "
+            "Use this when a workflow cannot be completed and needs to be abandoned. "
+            "Required: explanation (why the workflow is being aborted). "
+            "Returns the aborted workflow info and the resumed parent workflow (if any)."
+        )
+    )
+    async def abort_workflow(
+        explanation: str,
+    ) -> dict[str, Any]:
+        """Abort the current workflow and return to parent."""
+        _log_tool_call("abort_workflow", {"explanation": explanation})
+        input_data = AbortWorkflowInput(explanation=explanation)
+        response = await tools.abort_workflow(input_data)
+        return response.model_dump()
+
+    return mcp
+
+
+def _get_server_instructions() -> str:
+    """Get the server instructions for agents.
+
+    Returns:
+        Instructions string describing how to use the DeepWork MCP server.
+    """
+    return """# DeepWork Workflow Server
+
+This MCP server guides you through multi-step workflows with quality gates.
+
+## Workflow
+
+1. **Discover**: Call `get_workflows` to see available workflows
+2. **Start**: Call `start_workflow` with your goal, job_name, and workflow_name
+3. **Execute**: Follow the step instructions returned
+4. **Checkpoint**: Call `finished_step` with your outputs when done with each step
+5. **Iterate**: If `needs_work`, fix issues and call `finished_step` again
+6. **Continue**: If `next_step`, execute new instructions and repeat
+7. **Complete**: When `workflow_complete`, the workflow is done
+
+## Quality Gates
+
+Steps may have quality criteria. When you call `finished_step`:
+- Your outputs are evaluated against the criteria
+- If any fail, you'll get `needs_work` status with feedback
+- Fix the issues and call `finished_step` again
+- After passing, you'll get the next step or completion
+
+## Nested Workflows
+
+Workflows can be nested - starting a new workflow while one is active pushes
+onto a stack. This is useful when a step requires running another workflow.
+
+- All tool responses include a `stack` field showing the current workflow stack
+- Each stack entry shows `{workflow: "job/workflow", step: "current_step"}`
+- When a workflow completes, it pops from the stack and resumes the parent
+- Use `abort_workflow` to cancel the current workflow and return to parent
+
+## Aborting Workflows
+
+If a workflow cannot be completed, use `abort_workflow` with an explanation:
+- The current workflow is marked as aborted and popped from the stack
+- If there was a parent workflow, it becomes active again
+- The explanation is saved for debugging and audit purposes
+
+## Best Practices
+
+- Always call `get_workflows` first to understand available options
+- Provide clear goals when starting - they're used for context
+- Create all expected outputs before calling `finished_step`
+- Use instance_id for meaningful names (e.g., client name, quarter)
+- Read quality gate feedback carefully before retrying
+- Check the `stack` field in responses to understand nesting depth
+- Use `abort_workflow` rather than leaving workflows in a broken state
+"""

deepwork/mcp/state.py

@@ -0,0 +1,422 @@
+"""Workflow state management for MCP server.
+
+State is persisted to `.deepwork/tmp/session_[id].json` for transparency
+and recovery.
+
+Supports nested workflows via a session stack - when a step starts a new
+workflow, it's pushed onto the stack. When a workflow completes or is
+aborted, it's popped from the stack.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+
+import aiofiles
+
+from deepwork.mcp.schemas import StackEntry, StepProgress, WorkflowSession
+
+
+class StateError(Exception):
+    """Exception raised for state management errors."""
+
+    pass
+
+
+class StateManager:
+    """Manages workflow session state with stack-based nesting support.
+
+    Sessions are persisted to `.deepwork/tmp/` as JSON files for:
+    - Transparency: Users can inspect session state
+    - Recovery: Sessions survive server restarts
+    - Debugging: State history is preserved
+
+    This implementation is async-safe and uses a lock to prevent
+    concurrent access issues.
+
+    Supports nested workflows via a session stack - starting a new workflow
+    while one is active pushes onto the stack. Completing or aborting pops
+    from the stack.
+    """
+
+    def __init__(self, project_root: Path):
+        """Initialize state manager.
+
+        Args:
+            project_root: Path to the project root
+        """
+        self.project_root = project_root
+        self.sessions_dir = project_root / ".deepwork" / "tmp"
+        self._session_stack: list[WorkflowSession] = []
+        self._lock = asyncio.Lock()
+
+    def _ensure_sessions_dir(self) -> None:
+        """Ensure the sessions directory exists."""
+        self.sessions_dir.mkdir(parents=True, exist_ok=True)
+
+    def _session_file(self, session_id: str) -> Path:
+        """Get the path to a session file."""
+        return self.sessions_dir / f"session_{session_id}.json"
+
+    def _generate_session_id(self) -> str:
+        """Generate a unique session ID."""
+        return str(uuid.uuid4())[:8]
+
+    def _generate_branch_name(
+        self, job_name: str, workflow_name: str, instance_id: str | None
+    ) -> str:
+        """Generate a git branch name for the workflow.
+
+        Format: deepwork/[job_name]-[workflow_name]-[instance_id or date]
+        """
+        date_str = datetime.now(UTC).strftime("%Y%m%d")
+        instance = instance_id or date_str
+        return f"deepwork/{job_name}-{workflow_name}-{instance}"
+
+    async def create_session(
+        self,
+        job_name: str,
+        workflow_name: str,
+        goal: str,
+        first_step_id: str,
+        instance_id: str | None = None,
+    ) -> WorkflowSession:
+        """Create a new workflow session.
+
+        Args:
+            job_name: Name of the job
+            workflow_name: Name of the workflow
+            goal: User's goal for this workflow
+            first_step_id: ID of the first step
+            instance_id: Optional instance identifier
+
+        Returns:
+            New WorkflowSession
+        """
+        async with self._lock:
+            self._ensure_sessions_dir()
+
+            session_id = self._generate_session_id()
+            branch_name = self._generate_branch_name(job_name, workflow_name, instance_id)
+            now = datetime.now(UTC).isoformat()
+
+            session = WorkflowSession(
+                session_id=session_id,
+                job_name=job_name,
+                workflow_name=workflow_name,
+                instance_id=instance_id,
+                goal=goal,
+                branch_name=branch_name,
+                current_step_id=first_step_id,
+                current_entry_index=0,
+                step_progress={},
+                started_at=now,
+                status="active",
+            )
+
+            await self._save_session_unlocked(session)
+            self._session_stack.append(session)
+            return session
+
+    async def _save_session_unlocked(self, session: WorkflowSession) -> None:
+        """Save session to file (must be called with lock held)."""
+        self._ensure_sessions_dir()
+        session_file = self._session_file(session.session_id)
+        content = json.dumps(session.to_dict(), indent=2)
+        async with aiofiles.open(session_file, "w", encoding="utf-8") as f:
+            await f.write(content)
+
+    async def _save_session(self, session: WorkflowSession) -> None:
+        """Save session to file with lock."""
+        async with self._lock:
+            await self._save_session_unlocked(session)
+
+    async def load_session(self, session_id: str) -> WorkflowSession:
+        """Load a session from file.
+
+        Args:
+            session_id: Session ID to load
+
+        Returns:
+            WorkflowSession
+
+        Raises:
+            StateError: If session not found
+        """
+        async with self._lock:
+            session_file = self._session_file(session_id)
+            if not session_file.exists():
+                raise StateError(f"Session not found: {session_id}")
+
+            async with aiofiles.open(session_file, encoding="utf-8") as f:
+                content = await f.read()
+                data = json.loads(content)
+
+            session = WorkflowSession.from_dict(data)
+            # Replace top of stack or push if empty
+            if self._session_stack:
+                self._session_stack[-1] = session
+            else:
+                self._session_stack.append(session)
+            return session
+
+    def get_active_session(self) -> WorkflowSession | None:
+        """Get the currently active session (top of stack).
+
+        Returns:
+            Active session or None if no session active
+        """
+        return self._session_stack[-1] if self._session_stack else None
+
+    def require_active_session(self) -> WorkflowSession:
+        """Get active session (top of stack) or raise error.
+
+        Returns:
+            Active session
+
+        Raises:
+            StateError: If no active session
+        """
+        if not self._session_stack:
+            raise StateError("No active workflow session. Use start_workflow to begin a workflow.")
+        return self._session_stack[-1]
+
+    async def start_step(self, step_id: str) -> None:
+        """Mark a step as started.
+
+        Args:
+            step_id: Step ID to start
+
+        Raises:
+            StateError: If no active session
+        """
+        async with self._lock:
+            session = self.require_active_session()
+            now = datetime.now(UTC).isoformat()
+
+            if step_id not in session.step_progress:
+                session.step_progress[step_id] = StepProgress(
+                    step_id=step_id,
+                    started_at=now,
+                )
+            else:
+                session.step_progress[step_id].started_at = now
+
+            session.current_step_id = step_id
+            await self._save_session_unlocked(session)
+
+    async def complete_step(
+        self, step_id: str, outputs: list[str], notes: str | None = None
+    ) -> None:
+        """Mark a step as completed.
+
+        Args:
+            step_id: Step ID to complete
+            outputs: Output files created
+            notes: Optional notes
+
+        Raises:
+            StateError: If no active session
+        """
+        async with self._lock:
+            session = self.require_active_session()
+            now = datetime.now(UTC).isoformat()
+
+            if step_id not in session.step_progress:
+                session.step_progress[step_id] = StepProgress(
+                    step_id=step_id,
+                    started_at=now,
+                )
+
+            progress = session.step_progress[step_id]
+            progress.completed_at = now
+            progress.outputs = outputs
+            progress.notes = notes
+
+            await self._save_session_unlocked(session)
+
+    async def record_quality_attempt(self, step_id: str) -> int:
+        """Record a quality gate attempt for a step.
+
+        Args:
+            step_id: Step ID
+
+        Returns:
+            Total number of attempts for this step
+
+        Raises:
+            StateError: If no active session
+        """
+        async with self._lock:
+            session = self.require_active_session()
+
+            if step_id not in session.step_progress:
+                session.step_progress[step_id] = StepProgress(step_id=step_id)
+
+            session.step_progress[step_id].quality_attempts += 1
+            await self._save_session_unlocked(session)
+
+            return session.step_progress[step_id].quality_attempts
+
+    async def advance_to_step(self, step_id: str, entry_index: int) -> None:
+        """Advance the session to a new step.
+
+        Args:
+            step_id: New current step ID
+            entry_index: Index in workflow step_entries
+
+        Raises:
+            StateError: If no active session
+        """
+        async with self._lock:
+            session = self.require_active_session()
+            session.current_step_id = step_id
+            session.current_entry_index = entry_index
+            await self._save_session_unlocked(session)
+
+    async def complete_workflow(self) -> WorkflowSession | None:
+        """Mark the workflow as complete and pop from stack.
+
+        Returns:
+            The new active session after popping, or None if stack is empty
+
+        Raises:
+            StateError: If no active session
+        """
+        async with self._lock:
+            session = self.require_active_session()
+            now = datetime.now(UTC).isoformat()
+            session.completed_at = now
+            session.status = "completed"
+            await self._save_session_unlocked(session)
+
+            # Pop completed session from stack
+            self._session_stack.pop()
+
+            # Return new active session (if any)
+            return self._session_stack[-1] if self._session_stack else None
+
+    async def abort_workflow(
+        self, explanation: str
+    ) -> tuple[WorkflowSession, WorkflowSession | None]:
+        """Abort the current workflow and pop from stack.
+
+        Args:
+            explanation: Reason for aborting the workflow
+
+        Returns:
+            Tuple of (aborted session, new active session or None)
+
+        Raises:
+            StateError: If no active session
+        """
+        async with self._lock:
+            session = self.require_active_session()
+            now = datetime.now(UTC).isoformat()
+            session.completed_at = now
+            session.status = "aborted"
+            session.abort_reason = explanation
+            await self._save_session_unlocked(session)
+
+            # Pop aborted session from stack
+            self._session_stack.pop()
+
+            # Return aborted session and new active session (if any)
+            new_active = self._session_stack[-1] if self._session_stack else None
+            return session, new_active
+
+    def get_all_outputs(self) -> list[str]:
+        """Get all outputs from all completed steps.
+
+        Returns:
+            List of all output file paths
+
+        Raises:
+            StateError: If no active session
+        """
+        session = self.require_active_session()
+        outputs: list[str] = []
+        for progress in session.step_progress.values():
+            outputs.extend(progress.outputs)
+        return outputs
+
+    def get_stack(self) -> list[StackEntry]:
+        """Get the current workflow stack as StackEntry objects.
+
+        Returns:
+            List of StackEntry with workflow and step info, bottom to top
+        """
+        return [
+            StackEntry(
+                workflow=f"{s.job_name}/{s.workflow_name}",
+                step=s.current_step_id,
+            )
+            for s in self._session_stack
+        ]
+
+    def get_stack_depth(self) -> int:
+        """Get the current stack depth.
+
+        Returns:
+            Number of active workflow sessions on the stack
+        """
+        return len(self._session_stack)
+
+    async def list_sessions(self) -> list[WorkflowSession]:
+        """List all saved sessions.
+
+        Returns:
+            List of WorkflowSession objects
+        """
+        if not self.sessions_dir.exists():
+            return []
+
+        sessions = []
+        for session_file in self.sessions_dir.glob("session_*.json"):
+            try:
+                async with aiofiles.open(session_file, encoding="utf-8") as f:
+                    content = await f.read()
+                    data = json.loads(content)
+                sessions.append(WorkflowSession.from_dict(data))
+            except (json.JSONDecodeError, ValueError):
+                # Skip corrupted files
+                continue
+
+        return sorted(sessions, key=lambda s: s.started_at, reverse=True)
+
+    async def find_active_sessions_for_workflow(
+        self, job_name: str, workflow_name: str
+    ) -> list[WorkflowSession]:
+        """Find active sessions for a specific workflow.
+
+        Args:
+            job_name: Job name
+            workflow_name: Workflow name
+
+        Returns:
+            List of active sessions matching the criteria
+        """
+        all_sessions = await self.list_sessions()
+        return [
+            s
+            for s in all_sessions
+            if s.job_name == job_name and s.workflow_name == workflow_name and s.status == "active"
+        ]
+
+    async def delete_session(self, session_id: str) -> None:
+        """Delete a session file.
+
+        Args:
+            session_id: Session ID to delete
+        """
+        async with self._lock:
+            session_file = self._session_file(session_id)
+            if session_file.exists():
+                session_file.unlink()
+
+            # Remove from stack if present
+            self._session_stack = [s for s in self._session_stack if s.session_id != session_id]