mseep-lightfast-mcp 0.0.1__py3-none-any.whl

common/__init__.py

@@ -0,0 +1,21 @@
+"""Common types and utilities shared across lightfast-mcp core and tools."""
+
+from .types import (
+    HealthStatus,
+    OperationStatus,
+    ServerInfo,
+    ServerState,
+    ToolCall,
+    ToolCallState,
+    ToolResult,
+)
+
+__all__ = [
+    "HealthStatus",
+    "OperationStatus",
+    "ServerInfo",
+    "ServerState",
+    "ToolCall",
+    "ToolCallState",
+    "ToolResult",
+]

common/types.py

@@ -0,0 +1,182 @@
+"""Shared types for lightfast-mcp core and tools."""
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class OperationStatus(Enum):
+    """Standard operation status codes."""
+
+    SUCCESS = "success"
+    FAILED = "failed"
+    PENDING = "pending"
+    CANCELLED = "cancelled"
+    TIMEOUT = "timeout"
+
+
+class ServerState(Enum):
+    """Server lifecycle states."""
+
+    STOPPED = "stopped"
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    ERROR = "error"
+
+
+class ToolCallState(Enum):
+    """States of tool call execution."""
+
+    CALL = "call"
+    RESULT = "result"
+    ERROR = "error"
+
+
+class HealthStatus(Enum):
+    """Health check status."""
+
+    HEALTHY = "healthy"
+    UNHEALTHY = "unhealthy"
+    DEGRADED = "degraded"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class ServerInfo:
+    """Unified server information for both core and tools usage.
+
+    This class supports both lightweight usage (core) and comprehensive usage (tools).
+    Core servers can use minimal fields, while orchestration tools can use all fields.
+    """
+
+    # Core fields (always required)
+    name: str = ""
+    server_type: str = "unknown"
+    state: ServerState = ServerState.STOPPED
+
+    # Network configuration
+    host: str = "localhost"
+    port: int = 8000
+    transport: str = "stdio"
+    url: Optional[str] = None
+
+    # Runtime information (optional for core, used by tools)
+    pid: Optional[int] = None
+    start_time: Optional[datetime] = None
+    last_health_check: Optional[datetime] = None
+    health_status: HealthStatus = HealthStatus.UNKNOWN
+    error_message: str = ""
+    error_count: int = 0
+
+    # Tool information
+    tools: List[str] = field(default_factory=list)
+    tool_count: int = 0
+
+    # Legacy support for old ServerInfo interface
+    config: Optional[Any] = None
+
+    def __post_init__(self):
+        """Update computed fields."""
+        self.tool_count = len(self.tools)
+
+    @property
+    def is_running(self) -> bool:
+        """Check if server is in running state."""
+        return self.state == ServerState.RUNNING
+
+    @is_running.setter
+    def is_running(self, value: bool):
+        """Set running state (legacy support)."""
+        self.state = ServerState.RUNNING if value else ServerState.STOPPED
+
+    @property
+    def is_healthy(self) -> bool:
+        """Check if server is healthy."""
+        return self.health_status == HealthStatus.HEALTHY
+
+    @is_healthy.setter
+    def is_healthy(self, value: bool):
+        """Set healthy status (legacy support)."""
+        self.health_status = HealthStatus.HEALTHY if value else HealthStatus.UNHEALTHY
+
+    @property
+    def uptime_seconds(self) -> Optional[float]:
+        """Calculate uptime in seconds."""
+        if self.start_time:
+            return (datetime.utcnow() - self.start_time).total_seconds()
+        return None
+
+    @classmethod
+    def from_core_config(
+        cls, config, state: ServerState = ServerState.STOPPED
+    ) -> "ServerInfo":
+        """Create ServerInfo from core ServerConfig for lightweight usage."""
+        return cls(
+            name=config.name,
+            server_type=config.config.get("type", "unknown"),
+            state=state,
+            host=config.host,
+            port=config.port,
+            transport=config.transport,
+            url=f"http://{config.host}:{config.port}{config.path}"
+            if config.transport in ["http", "streamable-http"]
+            else None,
+            config=config,  # Store the original config for legacy support
+        )
+
+
+@dataclass
+class ToolCall:
+    """Represents a tool call at the application level."""
+
+    id: str
+    tool_name: str
+    arguments: Dict[str, Any]
+    server_name: Optional[str] = None
+    timestamp: Optional[datetime] = None
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = datetime.utcnow()
+        if not self.id:
+            self.id = str(uuid.uuid4())
+
+
+@dataclass
+class ToolResult:
+    """Represents a tool call result at the application level."""
+
+    id: str
+    tool_name: str
+    arguments: Dict[str, Any]
+    result: Any = None
+    error: Optional[str] = None
+    error_code: Optional[str] = None
+    server_name: Optional[str] = None
+    timestamp: Optional[datetime] = None
+    duration_ms: Optional[float] = None
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = datetime.utcnow()
+
+    @property
+    def state(self) -> ToolCallState:
+        """Get the current state of this tool result."""
+        if self.error:
+            return ToolCallState.ERROR
+        elif self.result is not None:
+            return ToolCallState.RESULT
+        else:
+            return ToolCallState.CALL
+
+    @property
+    def is_success(self) -> bool:
+        return self.state == ToolCallState.RESULT
+
+    @property
+    def is_error(self) -> bool:
+        return self.state == ToolCallState.ERROR

lightfast_mcp/__init__.py

@@ -0,0 +1,50 @@
+"""
+Lightfast MCP - Production-ready MCP server implementations for creative applications.
+
+This package provides core MCP (Model Context Protocol) server implementations
+for creative applications like Blender. It focuses purely on the server
+implementations themselves.
+
+🎯 Core MCP Servers:
+- Blender MCP Server: Control Blender through MCP protocol
+- Mock MCP Server: Testing and development server
+
+🔧 Development Tools:
+- Available separately in the `tools` package
+- Use `from tools.orchestration import get_orchestrator` for development tools
+
+Example Usage:
+```python
+# Core server usage
+from lightfast_mcp.servers.blender import BlenderMCPServer
+from lightfast_mcp.core import ServerConfig
+
+config = ServerConfig(name="my-blender", config={"type": "blender"})
+server = BlenderMCPServer(config)
+await server.run()
+
+# Development tools (optional)
+from tools.orchestration import get_orchestrator
+orchestrator = get_orchestrator()
+# orchestrator.start_server(config) # Example usage
+```
+"""
+
+# Core MCP server infrastructure (always available)
+from .core import BaseServer, ServerConfig, ServerInfo
+
+# Core server implementations (always available)
+from .servers.blender import BlenderMCPServer
+from .servers.mock import MockMCPServer
+
+__all__ = [
+    # Core infrastructure
+    "BaseServer",
+    "ServerConfig",
+    "ServerInfo",
+    # Server implementations
+    "BlenderMCPServer",
+    "MockMCPServer",
+]
+
+__version__ = "0.0.1"

lightfast_mcp/core/__init__.py

@@ -0,0 +1,14 @@
+"""Core infrastructure for MCP server implementations."""
+
+# Import shared types from common module
+from common import HealthStatus, ServerInfo, ServerState
+
+from .base_server import BaseServer, ServerConfig
+
+__all__ = [
+    "BaseServer",
+    "ServerConfig",
+    "ServerInfo",
+    "ServerState",
+    "HealthStatus",
+]

lightfast_mcp/core/base_server.py

@@ -0,0 +1,205 @@
+"""Base server interface for all MCP servers in the lightfast-mcp ecosystem."""
+
+# Import shared types from common module
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, ClassVar
+
+from fastmcp import FastMCP
+
+# Import shared types from common module
+from common import HealthStatus, ServerInfo, ServerState
+
+from ..utils.logging_utils import get_logger
+
+
+@dataclass
+class ServerConfig:
+    """Configuration for an MCP server."""
+
+    # Basic server info
+    name: str
+    description: str
+    version: str = "1.0.0"
+
+    # Network configuration
+    host: str = "localhost"
+    port: int = 8000
+    transport: str = "stdio"  # stdio, http, or streamable-http
+    path: str = "/mcp"
+
+    # Server-specific configuration
+    config: dict[str, Any] = field(default_factory=dict)
+
+    # Dependencies and requirements
+    dependencies: list[str] = field(default_factory=list)
+    required_apps: list[str] = field(
+        default_factory=list
+    )  # e.g., ["Blender", "TouchDesigner"]
+
+
+class BaseServer(ABC):
+    """Base class for all MCP servers in the lightfast-mcp ecosystem."""
+
+    # Server metadata - subclasses should override these
+    SERVER_TYPE: ClassVar[str] = "base"
+    SERVER_VERSION: ClassVar[str] = "1.0.0"
+    REQUIRED_DEPENDENCIES: ClassVar[list[str]] = []
+    REQUIRED_APPS: ClassVar[list[str]] = []
+
+    def __init__(self, config: ServerConfig):
+        """Initialize the base server with configuration."""
+        self.config = config
+        self.logger = get_logger(f"{self.__class__.__name__}")
+        self.mcp: FastMCP | None = None
+        self.info = ServerInfo.from_core_config(config)
+
+        # Initialize the FastMCP instance
+        self._init_mcp()
+
+    def _init_mcp(self):
+        """Initialize the FastMCP instance with lifespan management."""
+        self.mcp = FastMCP(
+            self.config.name,
+            description=self.config.description,
+            lifespan=self._server_lifespan,
+        )
+
+        # Register tools
+        self._register_tools()
+
+    @abstractmethod
+    def _register_tools(self):
+        """Register server-specific tools. Must be implemented by subclasses."""
+        pass
+
+    @asynccontextmanager
+    async def _server_lifespan(self, server: FastMCP) -> AsyncIterator[dict[str, Any]]:
+        """Manage server startup and shutdown lifecycle."""
+        try:
+            self.logger.info(f"{self.config.name} starting up...")
+
+            # Perform startup checks
+            await self._startup_checks()
+
+            # Custom startup logic
+            await self._on_startup()
+
+            self.info.state = ServerState.RUNNING
+            self.info.health_status = HealthStatus.HEALTHY
+
+            yield {}
+
+        except Exception as e:
+            self.logger.error(f"Error during {self.config.name} startup: {e}")
+            self.info.error_message = str(e)
+            self.info.health_status = HealthStatus.UNHEALTHY
+            raise
+        finally:
+            # Custom shutdown logic
+            await self._on_shutdown()
+
+            self.info.state = ServerState.STOPPED
+            self.logger.info(f"{self.config.name} shutting down.")
+
+    async def _startup_checks(self):
+        """Perform basic startup checks."""
+        # Check dependencies
+        for dep in self.REQUIRED_DEPENDENCIES:
+            if not await self._check_dependency(dep):
+                raise RuntimeError(f"Required dependency not available: {dep}")
+
+        # Check required applications
+        for app in self.REQUIRED_APPS:
+            if not await self._check_application(app):
+                self.logger.warning(f"Required application may not be available: {app}")
+
+    async def _check_dependency(self, dependency: str) -> bool:
+        """Check if a required dependency is available."""
+        try:
+            __import__(dependency)
+            return True
+        except ImportError:
+            return False
+
+    async def _check_application(self, app: str) -> bool:
+        """Check if a required application is available. Override in subclasses."""
+        return True
+
+    async def _on_startup(self):
+        """Custom startup logic. Override in subclasses if needed."""
+        # Default implementation does nothing
+        return
+
+    async def _on_shutdown(self):
+        """Custom shutdown logic. Override in subclasses if needed."""
+        # Default implementation does nothing
+        return
+
+    async def health_check(self) -> bool:
+        """Perform a health check on the server."""
+        try:
+            # Basic health check - can be overridden by subclasses
+            is_healthy = await self._perform_health_check()
+            self.info.health_status = (
+                HealthStatus.HEALTHY if is_healthy else HealthStatus.UNHEALTHY
+            )
+            self.info.last_health_check = datetime.utcnow()
+            return is_healthy
+        except Exception as e:
+            self.logger.error(f"Health check failed: {e}")
+            self.info.health_status = HealthStatus.UNHEALTHY
+            self.info.error_message = str(e)
+            return False
+
+    async def _perform_health_check(self) -> bool:
+        """Perform server-specific health check. Override in subclasses."""
+        return self.info.is_running
+
+    def get_tools(self) -> list[str]:
+        """Get list of available tools."""
+        if self.mcp:
+            # This would need to be implemented based on FastMCP's API
+            # For now, we'll store tools in info during registration
+            pass
+        return self.info.tools
+
+    def run(self, **kwargs):
+        """Run the server with the configured transport."""
+        if not self.mcp:
+            raise RuntimeError("MCP server not initialized")
+
+        # Build URL for HTTP transports
+        if self.config.transport in ["http", "streamable-http"]:
+            self.info.url = (
+                f"http://{self.config.host}:{self.config.port}{self.config.path}"
+            )
+            self.logger.info(f"Server will be available at: {self.info.url}")
+
+        # Run with appropriate transport
+        if self.config.transport == "stdio":
+            self.mcp.run()
+        elif self.config.transport in ["http", "streamable-http"]:
+            self.mcp.run(
+                transport=self.config.transport,
+                host=self.config.host,
+                port=self.config.port,
+                path=self.config.path,
+                **kwargs,
+            )
+        else:
+            raise ValueError(f"Unsupported transport: {self.config.transport}")
+
+    @classmethod
+    def create_from_config(cls, config: ServerConfig) -> "BaseServer":
+        """Create a server instance from configuration."""
+        return cls(config)
+
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__}({self.config.name})"
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(name='{self.config.name}', type='{self.SERVER_TYPE}')"

lightfast_mcp/exceptions.py

@@ -0,0 +1,55 @@
+"""Custom exceptions for the lightfast-mcp project."""
+
+
+class LightfastMCPError(Exception):
+    """Base exception for all lightfast-mcp related errors."""
+
+    pass
+
+
+class ServerStartupError(LightfastMCPError):
+    """Raised when a server fails to start up properly."""
+
+    pass
+
+
+class ServerConfigurationError(LightfastMCPError):
+    """Raised when there are issues with server configuration."""
+
+    pass
+
+
+class BlenderMCPError(LightfastMCPError):
+    """Base exception for all Blender MCP Server related errors."""
+
+    pass
+
+
+class BlenderConnectionError(BlenderMCPError):
+    """Raised when there are issues connecting to or maintaining a connection with Blender."""
+
+    pass
+
+
+class BlenderCommandError(BlenderMCPError):
+    """Raised when a command sent to Blender fails during its execution within Blender."""
+
+    pass
+
+
+class BlenderResponseError(BlenderMCPError):
+    """Raised when the response from Blender is unexpected, malformed, or indicates an error."""
+
+    pass
+
+
+class BlenderTimeoutError(BlenderConnectionError):
+    """Raised specifically when a timeout occurs while waiting for a response from Blender."""
+
+    pass
+
+
+class InvalidCommandTypeError(BlenderMCPError):
+    """Raised if an unsupported command type is sent to Blender."""
+
+    pass

lightfast_mcp/servers/__init__.py

@@ -0,0 +1 @@
+# This file makes the 'servers' directory a Python package.

lightfast_mcp/servers/blender/__init__.py

@@ -0,0 +1,5 @@
+"""Blender MCP server module."""
+
+from .server import BlenderMCPServer
+
+__all__ = ["BlenderMCPServer"]