devscontext 0.1.0__py3-none-any.whl

devscontext/server.py

@@ -0,0 +1,374 @@
+"""MCP server for DevsContext.
+
+This module provides the Model Context Protocol (MCP) server implementation
+that exposes DevsContext functionality as MCP tools.
+
+The server runs over stdio transport and provides the following tools:
+    - get_task_context: Get synthesized context for a task
+    - search_context: Search across all configured sources
+    - get_standards: Get coding standards documentation
+
+Example:
+    Run as MCP server:
+        devscontext serve
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from devscontext.config import load_devscontext_config
+from devscontext.core import DevsContextCore
+from devscontext.logging import get_logger
+
+logger = get_logger(__name__)
+
+# Initialize the MCP server
+server = Server("devscontext")
+
+# Global core instance (initialized on startup)
+_core: DevsContextCore | None = None
+
+
+def get_core() -> DevsContextCore:
+    """Get or create the global DevsContextCore instance.
+
+    Lazily initializes the core on first access using
+    the configuration loaded from the config file.
+
+    Returns:
+        The singleton DevsContextCore instance.
+    """
+    global _core
+    if _core is None:
+        config = load_devscontext_config()
+        _core = DevsContextCore(config)
+        logger.info("DevsContextCore initialized")
+    return _core
+
+
+@server.list_tools()  # type: ignore[no-untyped-call, untyped-decorator]
+async def list_tools() -> list[Tool]:
+    """List available MCP tools.
+
+    Returns:
+        List of Tool definitions for get_task_context, search_context,
+        and get_standards.
+    """
+    return [
+        Tool(
+            name="get_task_context",
+            description=(
+                "Use this when starting work on a Jira ticket. "
+                "Fetches and synthesizes everything you need: ticket requirements, "
+                "acceptance criteria, discussion comments, related meeting transcripts, "
+                "architecture docs, ADRs, and applicable coding standards. "
+                "Call this FIRST when the user says 'work on PROJ-123' or 'start TICKET-456'."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {
+                        "type": "string",
+                        "description": "Jira ticket ID (e.g., 'PROJ-123', 'TICKET-456')",
+                    },
+                    "refresh": {
+                        "type": "boolean",
+                        "description": "Force refresh, bypassing cache",
+                        "default": False,
+                    },
+                },
+                "required": ["task_id"],
+            },
+        ),
+        Tool(
+            name="search_context",
+            description=(
+                "Use this for freeform questions about the codebase, architecture, "
+                "or past decisions. Searches across Jira tickets, meeting transcripts, "
+                "and documentation. Use when the user asks questions like "
+                "'how do we handle errors?', 'what was decided about webhooks?', "
+                "or 'why did we choose SQS?'. Input is a natural language question."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {
+                        "type": "string",
+                        "description": "Natural language question or search terms",
+                    },
+                },
+                "required": ["query"],
+            },
+        ),
+        Tool(
+            name="get_standards",
+            description=(
+                "Use this when checking coding conventions before or during implementation. "
+                "Returns coding standards, style guides, and best practices from local docs. "
+                "Filter by area: 'testing', 'error-handling', 'typescript', 'api', etc. "
+                "Use when the user asks 'what are our testing conventions?' or "
+                "'how should I handle errors?' or before writing significant code."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "area": {
+                        "type": "string",
+                        "description": (
+                            "Filter by area: 'testing', 'typescript', 'error-handling', etc. "
+                            "Omit to get all standards."
+                        ),
+                    },
+                },
+            },
+        ),
+    ]
+
+
+@server.call_tool()  # type: ignore[untyped-decorator]
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    """Handle MCP tool calls.
+
+    Routes tool calls to the appropriate core method and formats
+    the response for the MCP client.
+
+    Args:
+        name: The name of the tool to call.
+        arguments: The tool arguments as a dictionary.
+
+    Returns:
+        List containing a single TextContent with the tool result.
+    """
+    start_time = time.monotonic()
+    core = get_core()
+
+    logger.info(
+        "Tool call received",
+        extra={"tool": name, "arguments": arguments},
+    )
+
+    try:
+        if name == "get_task_context":
+            return await _handle_get_task_context(core, arguments, start_time)
+
+        elif name == "search_context":
+            return await _handle_search_context(core, arguments, start_time)
+
+        elif name == "get_standards":
+            return await _handle_get_standards(core, arguments, start_time)
+
+        else:
+            logger.warning("Unknown tool called", extra={"tool": name})
+            return [TextContent(type="text", text=f"Error: Unknown tool '{name}'")]
+
+    except Exception as e:
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        logger.exception(
+            "Tool call failed",
+            extra={"tool": name, "error": str(e), "duration_ms": duration_ms},
+        )
+        return [
+            TextContent(
+                type="text",
+                text=f"Error: An unexpected error occurred while processing '{name}': {e}",
+            )
+        ]
+
+
+async def _handle_get_task_context(
+    core: DevsContextCore,
+    arguments: dict[str, Any],
+    start_time: float,
+) -> list[TextContent]:
+    """Handle the get_task_context tool call.
+
+    Args:
+        core: The DevsContextCore instance.
+        arguments: Tool arguments.
+        start_time: When the request started for duration logging.
+
+    Returns:
+        List containing TextContent with the synthesized context.
+    """
+    task_id = arguments.get("task_id", "")
+    refresh = arguments.get("refresh", False)
+
+    if not task_id:
+        logger.warning("get_task_context called without task_id")
+        return [TextContent(type="text", text="Error: task_id is required")]
+
+    try:
+        result = await core.get_task_context(
+            task_id=task_id,
+            use_cache=not refresh,
+        )
+
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        logger.info(
+            "get_task_context completed",
+            extra={
+                "task_id": task_id,
+                "source_count": len(result.sources_used),
+                "cached": result.cached,
+                "duration_ms": duration_ms,
+            },
+        )
+
+        # Return the synthesized markdown directly
+        return [TextContent(type="text", text=result.synthesized)]
+
+    except Exception as e:
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        logger.exception(
+            "get_task_context failed",
+            extra={"task_id": task_id, "error": str(e), "duration_ms": duration_ms},
+        )
+        return [
+            TextContent(
+                type="text",
+                text=f"Error fetching context for {task_id}: {e}\n\n"
+                f"Please check that your Jira and Fireflies credentials are configured correctly.",
+            )
+        ]
+
+
+async def _handle_search_context(
+    core: DevsContextCore,
+    arguments: dict[str, Any],
+    start_time: float,
+) -> list[TextContent]:
+    """Handle the search_context tool call.
+
+    Args:
+        core: The DevsContextCore instance.
+        arguments: Tool arguments.
+        start_time: When the request started for duration logging.
+
+    Returns:
+        List containing TextContent with search results.
+    """
+    query = arguments.get("query", "")
+
+    if not query:
+        logger.warning("search_context called without query")
+        return [TextContent(type="text", text="Error: query is required")]
+
+    try:
+        result = await core.search_context(query=query)
+
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        logger.info(
+            "search_context completed",
+            extra={
+                "query": query,
+                "result_count": result["result_count"],
+                "duration_ms": duration_ms,
+            },
+        )
+
+        sources = result.get("sources", [])
+        sources_str = ", ".join(sources) if isinstance(sources, list) else str(sources)
+
+        response_text = f"""# Search Results for "{query}"
+
+**Sources searched:** {sources_str}
+**Results found:** {result["result_count"]}
+
+---
+
+{result["results"]}
+"""
+        return [TextContent(type="text", text=response_text)]
+
+    except Exception as e:
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        logger.exception(
+            "search_context failed",
+            extra={"query": query, "error": str(e), "duration_ms": duration_ms},
+        )
+        return [
+            TextContent(
+                type="text",
+                text=f"Error searching for '{query}': {e}",
+            )
+        ]
+
+
+async def _handle_get_standards(
+    core: DevsContextCore,
+    arguments: dict[str, Any],
+    start_time: float,
+) -> list[TextContent]:
+    """Handle the get_standards tool call.
+
+    Args:
+        core: The DevsContextCore instance.
+        arguments: Tool arguments.
+        start_time: When the request started for duration logging.
+
+    Returns:
+        List containing TextContent with standards content.
+    """
+    area = arguments.get("area")
+
+    try:
+        result = await core.get_standards(area=area)
+
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        logger.info(
+            "get_standards completed",
+            extra={"area": area, "duration_ms": duration_ms},
+        )
+
+        area_text = f" ({area})" if area else ""
+        response_text = f"""# Coding Standards{area_text}
+
+{result["content"]}
+"""
+        return [TextContent(type="text", text=response_text)]
+
+    except Exception as e:
+        duration_ms = int((time.monotonic() - start_time) * 1000)
+        logger.exception(
+            "get_standards failed",
+            extra={"area": area, "error": str(e), "duration_ms": duration_ms},
+        )
+        return [
+            TextContent(
+                type="text",
+                text=f"Error fetching standards: {e}",
+            )
+        ]
+
+
+async def run_server() -> None:
+    """Run the MCP server over stdio transport.
+
+    Sets up the stdio transport and runs the server until interrupted.
+    """
+    logger.info("Starting MCP server")
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            server.create_initialization_options(),
+        )
+
+
+def main() -> None:
+    """Entry point for the MCP server.
+
+    Configures logging and runs the async server.
+    """
+    asyncio.run(run_server())
+
+
+if __name__ == "__main__":
+    main()

devscontext/storage.py

@@ -0,0 +1,321 @@
+"""SQLite storage for pre-built context.
+
+This module provides persistent storage for pre-built context that has been
+processed by the background agent. The MCP server can then retrieve this
+context instantly instead of fetching on-demand.
+
+Uses aiosqlite for async SQLite access.
+
+Example:
+    storage = PrebuiltContextStorage(".devscontext/cache.db")
+    await storage.initialize()
+
+    # Store pre-built context
+    await storage.store(context)
+
+    # Retrieve context
+    context = await storage.get("PROJ-123")
+    if context and not context.is_expired():
+        # Use the pre-built context
+        ...
+
+    await storage.close()
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+
+from devscontext.logging import get_logger
+from devscontext.models import PrebuiltContext
+
+logger = get_logger(__name__)
+
+
+class PrebuiltContextStorage:
+    """SQLite storage for pre-built context.
+
+    Provides async storage and retrieval of pre-built context that was
+    created by the background preprocessing agent.
+
+    The storage uses a single SQLite table with the following schema:
+        - task_id: TEXT PRIMARY KEY
+        - synthesized: TEXT (markdown content)
+        - sources_used: TEXT (JSON array)
+        - context_quality_score: REAL (0-1)
+        - gaps: TEXT (JSON array)
+        - built_at: TEXT (ISO timestamp)
+        - expires_at: TEXT (ISO timestamp)
+        - source_data_hash: TEXT (for staleness detection)
+    """
+
+    def __init__(self, db_path: str = ".devscontext/cache.db") -> None:
+        """Initialize storage with database path.
+
+        Args:
+            db_path: Path to SQLite database file.
+        """
+        self._db_path = Path(db_path)
+        self._conn: aiosqlite.Connection | None = None
+
+    async def initialize(self) -> None:
+        """Create database and table if needed.
+
+        Creates the parent directory if it doesn't exist.
+        """
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = await aiosqlite.connect(self._db_path)
+
+        await self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS prebuilt_context (
+                task_id TEXT PRIMARY KEY,
+                synthesized TEXT NOT NULL,
+                sources_used TEXT NOT NULL,
+                context_quality_score REAL NOT NULL,
+                gaps TEXT NOT NULL,
+                built_at TEXT NOT NULL,
+                expires_at TEXT NOT NULL,
+                source_data_hash TEXT NOT NULL
+            )
+        """)
+        await self._conn.commit()
+
+        logger.info(
+            "Storage initialized",
+            extra={"db_path": str(self._db_path)},
+        )
+
+    async def store(self, context: PrebuiltContext) -> None:
+        """Store pre-built context, replacing if exists.
+
+        Args:
+            context: PrebuiltContext to store.
+        """
+        if self._conn is None:
+            raise RuntimeError("Storage not initialized. Call initialize() first.")
+
+        await self._conn.execute(
+            """
+            INSERT OR REPLACE INTO prebuilt_context
+            (task_id, synthesized, sources_used, context_quality_score,
+             gaps, built_at, expires_at, source_data_hash)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                context.task_id,
+                context.synthesized,
+                json.dumps(context.sources_used),
+                context.context_quality_score,
+                json.dumps(context.gaps),
+                context.built_at.isoformat(),
+                context.expires_at.isoformat(),
+                context.source_data_hash,
+            ),
+        )
+        await self._conn.commit()
+
+        logger.info(
+            "Stored pre-built context",
+            extra={
+                "task_id": context.task_id,
+                "quality_score": context.context_quality_score,
+                "gaps_count": len(context.gaps),
+            },
+        )
+
+    async def get(self, task_id: str) -> PrebuiltContext | None:
+        """Get pre-built context if exists.
+
+        Note: This returns the context even if expired. Use is_expired()
+        to check if it should be refreshed.
+
+        Args:
+            task_id: Task identifier to retrieve.
+
+        Returns:
+            PrebuiltContext if found, None otherwise.
+        """
+        if self._conn is None:
+            raise RuntimeError("Storage not initialized. Call initialize() first.")
+
+        cursor = await self._conn.execute(
+            """
+            SELECT task_id, synthesized, sources_used, context_quality_score,
+                   gaps, built_at, expires_at, source_data_hash
+            FROM prebuilt_context
+            WHERE task_id = ?
+            """,
+            (task_id,),
+        )
+        row = await cursor.fetchone()
+
+        if row is None:
+            return None
+
+        return PrebuiltContext(
+            task_id=row[0],
+            synthesized=row[1],
+            sources_used=json.loads(row[2]),
+            context_quality_score=row[3],
+            gaps=json.loads(row[4]),
+            built_at=datetime.fromisoformat(row[5]),
+            expires_at=datetime.fromisoformat(row[6]),
+            source_data_hash=row[7],
+        )
+
+    async def is_stale(self, task_id: str, current_hash: str) -> bool:
+        """Check if stored context is stale.
+
+        Context is stale if the source data has changed (Jira ticket updated).
+
+        Args:
+            task_id: Task identifier.
+            current_hash: Current hash of source data (ticket.updated).
+
+        Returns:
+            True if stale or not found, False if fresh.
+        """
+        if self._conn is None:
+            raise RuntimeError("Storage not initialized. Call initialize() first.")
+
+        cursor = await self._conn.execute(
+            "SELECT source_data_hash FROM prebuilt_context WHERE task_id = ?",
+            (task_id,),
+        )
+        row = await cursor.fetchone()
+
+        if row is None:
+            return True  # Not found = stale
+
+        return bool(row[0] != current_hash)
+
+    async def delete(self, task_id: str) -> bool:
+        """Delete pre-built context for a task.
+
+        Args:
+            task_id: Task identifier to delete.
+
+        Returns:
+            True if deleted, False if not found.
+        """
+        if self._conn is None:
+            raise RuntimeError("Storage not initialized. Call initialize() first.")
+
+        cursor = await self._conn.execute(
+            "DELETE FROM prebuilt_context WHERE task_id = ?",
+            (task_id,),
+        )
+        await self._conn.commit()
+
+        deleted = cursor.rowcount > 0
+        if deleted:
+            logger.info("Deleted pre-built context", extra={"task_id": task_id})
+
+        return deleted
+
+    async def delete_expired(self) -> int:
+        """Delete all expired entries.
+
+        Returns:
+            Number of entries deleted.
+        """
+        if self._conn is None:
+            raise RuntimeError("Storage not initialized. Call initialize() first.")
+
+        now = datetime.now(UTC).isoformat()
+        cursor = await self._conn.execute(
+            "DELETE FROM prebuilt_context WHERE expires_at < ?",
+            (now,),
+        )
+        await self._conn.commit()
+
+        count = cursor.rowcount
+        if count > 0:
+            logger.info("Deleted expired contexts", extra={"count": count})
+
+        return count
+
+    async def list_all(self) -> list[dict[str, Any]]:
+        """List all stored contexts (summary only).
+
+        Returns:
+            List of dicts with task_id, quality_score, built_at, expires_at.
+        """
+        if self._conn is None:
+            raise RuntimeError("Storage not initialized. Call initialize() first.")
+
+        cursor = await self._conn.execute(
+            """
+            SELECT task_id, context_quality_score, built_at, expires_at, gaps
+            FROM prebuilt_context
+            ORDER BY built_at DESC
+            """
+        )
+        rows = await cursor.fetchall()
+
+        return [
+            {
+                "task_id": row[0],
+                "quality_score": row[1],
+                "built_at": row[2],
+                "expires_at": row[3],
+                "gaps_count": len(json.loads(row[4])),
+            }
+            for row in rows
+        ]
+
+    async def get_stats(self) -> dict[str, Any]:
+        """Get storage statistics for CLI status command.
+
+        Returns:
+            Dict with total, active, expired counts and average quality.
+        """
+        if self._conn is None:
+            raise RuntimeError("Storage not initialized. Call initialize() first.")
+
+        now = datetime.now(UTC).isoformat()
+
+        # Total count
+        cursor = await self._conn.execute("SELECT COUNT(*) FROM prebuilt_context")
+        total_row = await cursor.fetchone()
+        total: int = total_row[0] if total_row else 0
+
+        # Active (not expired) count
+        cursor = await self._conn.execute(
+            "SELECT COUNT(*) FROM prebuilt_context WHERE expires_at >= ?",
+            (now,),
+        )
+        active_row = await cursor.fetchone()
+        active: int = active_row[0] if active_row else 0
+
+        # Average quality score
+        cursor = await self._conn.execute("SELECT AVG(context_quality_score) FROM prebuilt_context")
+        avg_quality_row = await cursor.fetchone()
+        avg_quality: float = (
+            avg_quality_row[0] if avg_quality_row and avg_quality_row[0] is not None else 0.0
+        )
+
+        # Last build time
+        cursor = await self._conn.execute("SELECT MAX(built_at) FROM prebuilt_context")
+        last_build_row = await cursor.fetchone()
+        last_build: str | None = last_build_row[0] if last_build_row and last_build_row[0] else None
+
+        return {
+            "total": total,
+            "active": active,
+            "expired": total - active,
+            "avg_quality": avg_quality,
+            "last_build": last_build,
+        }
+
+    async def close(self) -> None:
+        """Close database connection."""
+        if self._conn is not None:
+            await self._conn.close()
+            self._conn = None
+            logger.debug("Storage connection closed")