scribe-mcp 2.2__py3-none-any.whl

scribe_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""Scribe MCP server package."""
+
+__all__ = [
+    "config",
+    "db",
+    "server",
+    "state",
+    "tools",
+    "utils",
+]
+

scribe_mcp/__main__.py

@@ -0,0 +1,31 @@
+"""Package entrypoint for running the Scribe MCP server."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from collections.abc import Sequence
+
+from scribe_mcp.server import main as server_main
+
+
+def _parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run the Scribe MCP server over stdio.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="scribe-mcp 2.2",
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    _parse_args(argv)
+    asyncio.run(server_main())
+
+
+if __name__ == "__main__":
+    main()
+

scribe_mcp/bridges/__init__.py

@@ -0,0 +1,46 @@
+"""Bridge registry system for external integrations."""
+
+from .manifest import (
+    BridgeManifest,
+    BridgeState,
+    LogTypeConfig,
+    HookConfig,
+    BridgeProjectConfig,
+    BridgeValidationConfig,
+)
+from .plugin import BridgePlugin
+from .registry import BridgeRegistry
+from .api import BridgeToScribeAPI
+from .policy import BridgePolicyPlugin
+from .hooks import BridgeHookManager, get_hook_manager
+from .security import BridgeSecurityManager
+from .tools import BridgeToolWrapper, BridgeToolRegistry, get_tool_registry
+from .health import (
+    BridgeHealthMonitor,
+    get_health_monitor,
+    set_health_monitor,
+    create_health_monitor,
+)
+
+__all__ = [
+    "BridgeManifest",
+    "BridgeState",
+    "LogTypeConfig",
+    "HookConfig",
+    "BridgeProjectConfig",
+    "BridgeValidationConfig",
+    "BridgePlugin",
+    "BridgeRegistry",
+    "BridgeToScribeAPI",
+    "BridgePolicyPlugin",
+    "BridgeHookManager",
+    "get_hook_manager",
+    "BridgeSecurityManager",
+    "BridgeToolWrapper",
+    "BridgeToolRegistry",
+    "get_tool_registry",
+    "BridgeHealthMonitor",
+    "get_health_monitor",
+    "set_health_monitor",
+    "create_health_monitor",
+]

scribe_mcp/bridges/api.py

@@ -0,0 +1,204 @@
+"""API for bridges to call Scribe operations."""
+
+from typing import Dict, List, Any, Optional
+import logging
+from datetime import datetime, timezone
+import uuid
+import hashlib
+
+logger = logging.getLogger(__name__)
+
+
+class BridgeToScribeAPI:
+    """
+    API interface for bridge→Scribe calls.
+
+    All operations enforce permissions via BridgePolicyPlugin
+    and inject bridge metadata automatically.
+    """
+
+    def __init__(self, bridge_id: str, manifest, storage_backend, policy):
+        self.bridge_id = bridge_id
+        self.manifest = manifest
+        self._storage = storage_backend
+        self._policy = policy
+
+    async def append_entry(
+        self,
+        project_name: str,
+        message: str,
+        status: str = "info",
+        agent: Optional[str] = None,
+        meta: Optional[Dict[str, Any]] = None,
+        log_type: str = "progress"
+    ) -> Dict[str, Any]:
+        """
+        Append entry to Scribe log on behalf of bridge.
+
+        Enforces permissions and injects bridge metadata.
+
+        Args:
+            project_name: Target project
+            message: Log message
+            status: Entry status (info, success, warn, error, bug, plan)
+            agent: Agent name (defaults to bridge:<bridge_id>)
+            meta: Additional metadata
+            log_type: Log type (progress, doc_updates, bugs, etc.)
+
+        Returns:
+            Dict with ok=True, entry_id, timestamp
+
+        Raises:
+            PermissionError: If bridge lacks permission
+        """
+        # Check permission
+        if not self._policy.can_append_entry(project_name, log_type):
+            raise PermissionError(
+                f"Bridge {self.bridge_id} cannot append to {project_name}/{log_type}"
+            )
+
+        # Inject bridge metadata
+        meta = meta or {}
+        meta["source_bridge_id"] = self.bridge_id
+        meta["bridge_version"] = self.manifest.version
+
+        # Map status to emoji
+        emoji_map = {
+            "info": "ℹ️",
+            "success": "✅",
+            "warn": "⚠️",
+            "error": "❌",
+            "bug": "🐞",
+            "plan": "📋"
+        }
+        emoji = emoji_map.get(status, "ℹ️")
+
+        # Fetch project record
+        project = await self._storage.fetch_project(project_name)
+        if not project:
+            raise ValueError(f"Project '{project_name}' not found")
+
+        # Generate entry ID and timestamp
+        entry_id = str(uuid.uuid4())[:8]
+        ts = datetime.now(timezone.utc)
+        timestamp_str = ts.isoformat()
+        agent_name = agent or f"bridge:{self.bridge_id}"
+
+        # Create raw line and compute hash
+        raw_line = f"{timestamp_str} | {agent_name} | {message}"
+        sha256_hash = hashlib.sha256(raw_line.encode()).hexdigest()
+
+        # Insert entry via storage backend
+        await self._storage.insert_entry(
+            entry_id=entry_id,
+            project=project,
+            ts=ts,
+            emoji=emoji,
+            agent=agent_name,
+            message=message,
+            meta=meta,
+            raw_line=raw_line,
+            sha256=sha256_hash
+        )
+
+        logger.info(f"Bridge {self.bridge_id} appended entry to {project_name}: {message[:50]}")
+
+        return {
+            "ok": True,
+            "entry_id": entry_id,
+            "timestamp": timestamp_str
+        }
+
+    async def query_entries(
+        self,
+        project_name: str,
+        limit: int = 50,
+        **filters
+    ) -> List[Dict[str, Any]]:
+        """
+        Query entries from Scribe log.
+
+        Args:
+            project_name: Target project
+            limit: Maximum entries to return
+            **filters: Additional query filters
+
+        Returns:
+            List of log entries
+
+        Raises:
+            PermissionError: If bridge lacks permission
+        """
+        if not self._policy.can_read_entries(project_name):
+            raise PermissionError(
+                f"Bridge {self.bridge_id} cannot read from {project_name}"
+            )
+
+        entries = await self._storage.fetch_recent_entries(project_name, limit, filters)
+        logger.info(f"Bridge {self.bridge_id} queried {len(entries)} entries from {project_name}")
+
+        return entries
+
+    async def create_project(
+        self,
+        name: str,
+        description: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        meta: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a new Scribe project on behalf of bridge.
+
+        Args:
+            name: Project name
+            description: Project description
+            tags: Project tags
+            meta: Additional metadata
+
+        Returns:
+            Dict with ok=True, project_name, tags
+
+        Raises:
+            PermissionError: If bridge lacks permission
+        """
+        if not self._policy.can_create_projects():
+            raise PermissionError(
+                f"Bridge {self.bridge_id} cannot create projects"
+            )
+
+        # Apply prefix if configured
+        prefix = self.manifest.project_config.project_prefix
+        original_name = name
+        full_name = f"{prefix}{name}" if prefix else name
+
+        # Add auto-tags
+        all_tags = list(tags or [])
+        all_tags.extend(self.manifest.project_config.auto_tag)
+        all_tags.append(f"bridge:{self.bridge_id}")
+
+        # Inject bridge metadata
+        project_meta = dict(meta or {})
+        project_meta.update(self.manifest.project_config.default_metadata)
+        project_meta["managed_by_bridge"] = self.bridge_id
+        project_meta["bridge_version"] = self.manifest.version
+
+        # Create via storage with bridge ownership
+        await self._storage.upsert_project(
+            name=full_name,
+            repo_root=".",
+            progress_log_path=f".scribe/docs/dev_plans/{full_name}/PROGRESS_LOG.md",
+            docs_json=None,
+            bridge_id=self.bridge_id,
+            bridge_managed=True
+        )
+
+        logger.info(f"Bridge {self.bridge_id} created project: {full_name}")
+
+        return {
+            "ok": True,
+            "project_name": full_name,
+            "original_name": original_name,
+            "tags": all_tags,
+            "bridge_managed": True,
+            "bridge_id": self.bridge_id
+        }

scribe_mcp/bridges/examples/__init__.py

@@ -0,0 +1,10 @@
+"""
+Example bridge plugins for reference and testing.
+
+This package contains example implementations of Scribe bridge plugins:
+- hello_world_plugin: Minimal example demonstrating bridge lifecycle
+"""
+
+from .hello_world_plugin import HelloWorldBridgePlugin, create_plugin
+
+__all__ = ["HelloWorldBridgePlugin", "create_plugin"]

scribe_mcp/bridges/examples/hello_world_plugin.py

@@ -0,0 +1,177 @@
+"""
+Hello World Example Bridge Plugin
+
+This is a minimal example showing how to create a Scribe bridge plugin.
+Use this as a template for your own bridge implementations.
+
+To enable:
+1. Copy .scribe/config/bridges/hello_world.yaml.example to hello_world.yaml
+2. Set enabled: true
+3. Restart the Scribe MCP server
+
+Example Usage:
+    This plugin is automatically loaded by the BridgeRegistry when enabled.
+    It demonstrates:
+    - Activation/deactivation lifecycle
+    - Health check reporting
+    - Pre-append hook for entry modification
+    - Post-append hook for event tracking
+"""
+
+from typing import Any, Dict, Optional
+import logging
+
+from bridges.plugin import BridgePlugin
+
+logger = logging.getLogger(__name__)
+
+
+class HelloWorldBridgePlugin(BridgePlugin):
+    """
+    Minimal example bridge plugin demonstrating the bridge lifecycle.
+
+    This plugin:
+    - Logs activation/deactivation events
+    - Provides a simple health check
+    - Demonstrates pre/post append hooks
+    - Tracks append events with a counter
+
+    Attributes:
+        bridge_id: Unique identifier for this bridge instance
+        manifest: Bridge manifest configuration
+        _active: Whether the bridge is currently active
+        _append_count: Number of appends processed
+    """
+
+    def __init__(self, manifest: Any):
+        """
+        Initialize the HelloWorld bridge plugin.
+
+        Args:
+            manifest: Loaded BridgeManifest configuration
+        """
+        super().__init__(manifest)
+        self._active = False
+        self._append_count = 0
+        logger.info(f"HelloWorldBridgePlugin initialized: {self.bridge_id}")
+
+    async def on_activate(self) -> None:
+        """
+        Called when the bridge is activated.
+
+        This is where you'd initialize connections, load resources, etc.
+        """
+        self._active = True
+        self._append_count = 0
+        logger.info(f"HelloWorldBridge activated: {self.bridge_id}")
+
+    async def on_deactivate(self) -> None:
+        """
+        Called when the bridge is deactivated.
+
+        This is where you'd clean up connections, save state, etc.
+        """
+        self._active = False
+        logger.info(
+            f"HelloWorldBridge deactivated: {self.bridge_id} "
+            f"(processed {self._append_count} appends)"
+        )
+
+    async def health_check(self) -> Dict[str, Any]:
+        """
+        Return health status for monitoring.
+
+        The BridgeRegistry calls this periodically to monitor bridge health.
+
+        Returns:
+            Dict with 'healthy' bool and optional details:
+            {
+                "healthy": True,
+                "bridge_id": "hello_world",
+                "append_count": 42,
+                "message": "Optional status message"
+            }
+        """
+        return {
+            "healthy": self._active,
+            "bridge_id": self.bridge_id,
+            "append_count": self._append_count,
+            "message": "Hello from the example bridge!"
+        }
+
+    async def pre_append(self, entry_data: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """
+        Called before an entry is appended.
+
+        This hook can:
+        - Modify entry_data and return the modified version
+        - Return None to use the original entry_data unchanged
+        - Return False to reject the append (only if critical=true in manifest)
+
+        Example use cases:
+        - Add metadata tags
+        - Enrich entries with external data
+        - Validate entry format
+        - Filter sensitive information
+
+        Args:
+            entry_data: The entry about to be appended
+
+        Returns:
+            Modified entry_data dict, None for original, or False to reject
+        """
+        # Example: Add a tag to indicate this went through our bridge
+        if entry_data.get("meta") is None:
+            entry_data["meta"] = {}
+
+        entry_data["meta"]["hello_world_processed"] = True
+
+        logger.debug(
+            f"HelloWorldBridge pre_append: "
+            f"{entry_data.get('message', '')[:50]}"
+        )
+
+        return entry_data
+
+    async def post_append(
+        self,
+        entry_data: Dict[str, Any],
+        result: Dict[str, Any]
+    ) -> None:
+        """
+        Called after an entry is successfully appended.
+
+        This hook is for side effects only - you cannot modify the entry.
+
+        Example use cases:
+        - Send notifications
+        - Update metrics/dashboards
+        - Trigger downstream workflows
+        - Log to external systems
+
+        Args:
+            entry_data: The entry that was appended
+            result: The result from the append operation
+        """
+        self._append_count += 1
+
+        logger.debug(
+            f"HelloWorldBridge post_append #{self._append_count}: "
+            f"success={result.get('ok')}"
+        )
+
+
+def create_plugin(manifest: Any) -> HelloWorldBridgePlugin:
+    """
+    Factory function to create plugin instance.
+
+    The BridgeRegistry uses this function to instantiate the plugin.
+    This pattern allows for plugin initialization customization.
+
+    Args:
+        manifest: Loaded BridgeManifest configuration
+
+    Returns:
+        Initialized HelloWorldBridgePlugin instance
+    """
+    return HelloWorldBridgePlugin(manifest)