gfp-mcp 0.2.4__py3-none-any.whl → 0.3.2__py3-none-any.whl

gfp_mcp/server.py

@@ -0,0 +1,235 @@
+"""MCP server implementation for GDSFactory+.
+
+This module provides the main MCP server that exposes GDSFactory+ operations
+as tools for AI assistants using the STDIO transport.
+
+The server uses a handler-based architecture where each tool has its own
+handler class that encapsulates:
+- Tool definition (name, description, input schema)
+- Request transformation (MCP args -> HTTP params/body)
+- Response transformation (HTTP response -> MCP format)
+- Execution logic (handle method)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import (
+    ImageContent,
+    Resource,
+    TextContent,
+    Tool,
+)
+
+from .client import FastAPIClient
+from .config import MCPConfig
+from .resources import get_all_resources, get_resource_content
+from .tools import get_all_tools, get_handler
+
+__all__ = ["create_server", "run_server", "main"]
+
+logger = logging.getLogger(__name__)
+
+
+_INSTRUCTIONS = """
+GDSFactory+ MCP Server Instructions
+===================================
+
+This MCP server connects AI assistants to GDSFactory+ for photonic IC design.
+Use this context to understand how to interact with the server effectively.
+
+Server Discovery
+----------------
+Use the `list_projects` tool to discover running GDSFactory+ servers / projects.
+Each project has its own server with a unique port.
+
+If no servers are found, instruct the user to:
+1. Open VSCode with the GDSFactory+ extension installed
+2. Open a GDSFactory+ project folder
+3. The extension will automatically start and register the server
+
+Typically, users will invoke you from the project directory they are working on.
+If unclear, ask the user what project they are working on.
+
+Multi-Project Routing
+---------------------
+All tools (except list_projects) support an optional `project` parameter.
+Use this to target a specific project when multiple GDSFactory+ servers are running.
+
+If not specified, the first available server from the registry is used as a fallback.
+You are adviced against ever using this fallback.
+
+Designing Custom cells / factories
+---------------------------------
+Users may request you to build and design custom cells. Always consult the `list_samples` tool to discover examples of how to design cells.
+Always make sure to run DRC/LVS/Connectivity checks on custom cells you have built.
+Before running a DRC consult with the user if they would like to run the DRC, as these can take a long time to complete.
+When users ask for specific characteristics of a cell / factory, you are to run simulations and use python scripts to analyze and verify the results.
+Always write your new designs in python code, even though an example might show yaml.
+Make sure to save your designs in project_name/custom_cells/**.py, and notify the user that they are saved here.
+
+Best Practices
+--------------
+1. Always call `list_projects` first to discover available servers
+2. Use the `project` parameter when working with multiple projects
+3. For verification tools (DRC, connectivity, LVS), provide full paths to GDS files
+4. Simulation results may be large - the server optimizes responses for token efficiency
+5. When building cells, use the `visualize` parameter to get PNG previews
+"""
+
+
+def create_server(api_url: str | None = None) -> Server:
+    """Create an MCP server instance.
+
+    Args:
+        api_url: Optional FastAPI base URL (default from config)
+
+    Returns:
+        Configured MCP Server instance
+    """
+    server = Server("gdsfactoryplus", instructions=_INSTRUCTIONS.strip())
+
+    client = FastAPIClient(api_url)
+
+    @server.list_tools()
+    async def list_tools() -> list[Tool]:
+        """List all available MCP tools.
+
+        Returns:
+            List of tool definitions
+        """
+        tools = get_all_tools()
+        logger.info("Listing %d tools", len(tools))
+        return tools
+
+    @server.list_resources()
+    async def list_resources() -> list[Resource]:
+        """List all available MCP resources.
+
+        Returns:
+            List of resource definitions
+        """
+        resources = get_all_resources()
+        logger.info("Listing %d resources", len(resources))
+        return resources
+
+    @server.read_resource()
+    async def read_resource(uri: str) -> str:
+        """Read a specific resource by URI.
+
+        Args:
+            uri: Resource URI
+
+        Returns:
+            Resource content as string
+
+        Raises:
+            ValueError: If resource URI is not found
+        """
+        logger.info("Resource requested: %s", uri)
+
+        content = get_resource_content(uri)
+        if content is None:
+            error_msg = f"Unknown resource URI: {uri}"
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+
+        return content
+
+    @server.call_tool()
+    async def call_tool(
+        name: str, arguments: dict[str, Any]
+    ) -> list[TextContent | ImageContent]:
+        """Call an MCP tool.
+
+        Uses handler dispatch to route tool calls to the appropriate handler.
+        Each handler encapsulates request/response transformation and execution.
+
+        Args:
+            name: Tool name
+            arguments: Tool arguments
+
+        Returns:
+            List of text and/or image content responses
+        """
+        logger.info("Tool called: %s", name)
+        logger.debug("Arguments: %s", arguments)
+
+        handler = get_handler(name)
+        if handler is None:
+            import json
+
+            error_msg = f"Unknown tool: {name}"
+            logger.error(error_msg)
+            return [TextContent(type="text", text=json.dumps({"error": error_msg}))]
+
+        return await handler.handle(arguments, client)
+
+    server._http_client = client  # type: ignore[attr-defined]  # noqa: SLF001
+
+    return server
+
+
+async def run_server(api_url: str | None = None) -> None:
+    """Run the MCP server with STDIO transport.
+
+    Args:
+        api_url: Optional FastAPI base URL (default from config)
+    """
+    log_level = logging.DEBUG if MCPConfig.DEBUG else logging.INFO
+    logging.basicConfig(
+        level=log_level,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+    logger.info("Starting GDSFactory+ MCP server")
+    base_url_info = MCPConfig.get_api_url(api_url) or "registry-based routing"
+    logger.info("Base URL: %s", base_url_info)
+    logger.info("Timeout: %ds", MCPConfig.get_timeout())
+
+    server = create_server(api_url)
+    client: FastAPIClient = server._http_client  # type: ignore[attr-defined]  # noqa: SLF001
+
+    try:
+        await client.start()
+
+        async with stdio_server() as (read_stream, write_stream):
+            logger.info("MCP server ready (STDIO transport)")
+            await server.run(
+                read_stream,
+                write_stream,
+                server.create_initialization_options(),
+            )
+
+    except KeyboardInterrupt:
+        logger.info("Shutting down MCP server (keyboard interrupt)")
+    except Exception:
+        logger.exception("MCP server error")
+        raise
+    finally:
+        await client.close()
+        logger.info("MCP server stopped")
+
+
+def main(api_url: str | None = None) -> None:
+    """Main entry point for MCP server.
+
+    Args:
+        api_url: Optional FastAPI base URL (default from config)
+    """
+    try:
+        asyncio.run(run_server(api_url))
+    except KeyboardInterrupt:
+        pass
+    except Exception:
+        logger.exception("Fatal error")
+        raise
+
+
+if __name__ == "__main__":
+    main()

gfp_mcp/tools/__init__.py

@@ -0,0 +1,134 @@
+"""MCP tool definitions and handlers for GDSFactory+.
+
+This package contains all tool handlers, each co-locating:
+- MCP Tool definition (name, description, input schema)
+- Request transformation (MCP args -> HTTP params/body)
+- Response transformation (HTTP response -> MCP format)
+- Execution logic (handle method)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import (
+    PROJECT_PARAM_SCHEMA,
+    EndpointMapping,
+    ToolHandler,
+    add_project_param,
+)
+
+# Import all handlers
+from .bbox import GenerateBboxHandler
+from .build import BuildCellsHandler
+from .cells import GetCellInfoHandler, ListCellsHandler
+from .connectivity import CheckConnectivityHandler
+from .drc import CheckDrcHandler
+from .freeze import FreezeCellHandler
+from .lvs import CheckLvsHandler
+from .pdk import GetPdkInfoHandler
+from .port import GetPortCenterHandler
+from .project import GetProjectInfoHandler, ListProjectsHandler
+from .samples import GetSampleFileHandler, ListSamplesHandler
+from .simulation import SimulateComponentHandler
+
+if TYPE_CHECKING:
+    from mcp.types import Tool
+
+__all__ = [
+    # Base classes
+    "EndpointMapping",
+    "ToolHandler",
+    # Registry and utilities
+    "TOOL_HANDLERS",
+    "get_all_tools",
+    "get_tool_by_name",
+    "get_handler",
+    "PROJECT_PARAM_SCHEMA",
+    "add_project_param",
+    # Handler classes
+    "ListProjectsHandler",
+    "GetProjectInfoHandler",
+    "BuildCellsHandler",
+    "ListCellsHandler",
+    "GetCellInfoHandler",
+    "CheckDrcHandler",
+    "CheckConnectivityHandler",
+    "CheckLvsHandler",
+    "SimulateComponentHandler",
+    "GetPortCenterHandler",
+    "GenerateBboxHandler",
+    "FreezeCellHandler",
+    "GetPdkInfoHandler",
+    "ListSamplesHandler",
+    "GetSampleFileHandler",
+]
+
+
+def _create_handler_registry() -> dict[str, ToolHandler]:
+    """Create the tool handlers registry.
+
+    Returns:
+        Dict mapping tool names to handler instances
+    """
+    handlers = [
+        # Project discovery tools
+        ListProjectsHandler(),
+        GetProjectInfoHandler(),
+        # Core building tools
+        BuildCellsHandler(),
+        ListCellsHandler(),
+        GetCellInfoHandler(),
+        # Verification tools
+        CheckDrcHandler(),
+        CheckConnectivityHandler(),
+        CheckLvsHandler(),
+        # Advanced tools
+        SimulateComponentHandler(),
+        GetPortCenterHandler(),
+        GenerateBboxHandler(),
+        FreezeCellHandler(),
+        GetPdkInfoHandler(),
+        # Sample project tools
+        ListSamplesHandler(),
+        GetSampleFileHandler(),
+    ]
+    return {handler.name: handler for handler in handlers}
+
+
+# Tool handlers registry - each handler is keyed by its tool name for O(1) lookup
+TOOL_HANDLERS: dict[str, ToolHandler] = _create_handler_registry()
+
+
+def get_all_tools() -> list[Tool]:
+    """Get all available MCP tools.
+
+    Returns:
+        List of Tool definitions from all registered handlers
+    """
+    return [handler.definition for handler in TOOL_HANDLERS.values()]
+
+
+def get_tool_by_name(name: str) -> Tool | None:
+    """Get a tool definition by name.
+
+    Args:
+        name: Tool name to look up
+
+    Returns:
+        Tool definition if found, None otherwise
+    """
+    handler = TOOL_HANDLERS.get(name)
+    return handler.definition if handler else None
+
+
+def get_handler(name: str) -> ToolHandler | None:
+    """Get a tool handler by name.
+
+    Args:
+        name: Tool name to look up
+
+    Returns:
+        ToolHandler instance if found, None otherwise
+    """
+    return TOOL_HANDLERS.get(name)

gfp_mcp/tools/base.py

@@ -0,0 +1,235 @@
+"""Base classes for tool handlers.
+
+This module provides the foundational classes for the MCP tool handler
+architecture, including the abstract ToolHandler base class and
+EndpointMapping for HTTP routing.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from mcp.types import ImageContent, TextContent, Tool
+
+if TYPE_CHECKING:
+    from ..client import FastAPIClient
+
+__all__ = [
+    "EndpointMapping",
+    "ToolHandler",
+    "PROJECT_PARAM_SCHEMA",
+    "add_project_param",
+]
+
+logger = logging.getLogger(__name__)
+
+# Common schema components for project routing
+PROJECT_PARAM_SCHEMA = {
+    "project": {
+        "type": "string",
+        "description": (
+            "Optional project name or path to route this request to a specific server. "
+            "If not provided, uses the first available server from the registry or "
+            "GFP_API_URL if set. Use list_projects to see available projects."
+        ),
+    },
+}
+
+
+def add_project_param(schema: dict) -> dict:
+    """Add optional project parameter to a tool schema.
+
+    Args:
+        schema: Tool input schema dict
+
+    Returns:
+        Schema with project parameter added to properties
+    """
+    if "properties" not in schema:
+        schema["properties"] = {}
+    schema["properties"].update(PROJECT_PARAM_SCHEMA)
+    return schema
+
+
+@dataclass
+class EndpointMapping:
+    """Configuration for mapping an MCP tool to a FastAPI endpoint.
+
+    This class defines the HTTP method and path for a tool's backend endpoint.
+    Unlike the previous implementation in mappings.py, request and response
+    transformers are now methods on the ToolHandler class.
+
+    Attributes:
+        method: HTTP method (GET, POST, etc.)
+        path: API endpoint path (e.g., "/api/build-cells")
+    """
+
+    method: str
+    path: str
+
+
+class ToolHandler(ABC):
+    """Abstract base class for MCP tool handlers.
+
+    Each tool handler encapsulates:
+    - The MCP Tool definition (name, description, input schema)
+    - The HTTP endpoint mapping (method, path)
+    - Request transformation (MCP args -> HTTP params/body)
+    - Response transformation (HTTP response -> MCP format)
+    - Execution logic (handle method)
+
+    Subclasses must implement the `name` and `definition` properties.
+    Other methods have sensible defaults but can be overridden.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Tool name identifier.
+
+        This must match the name in the Tool definition and is used
+        for routing in the server's call_tool handler.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def definition(self) -> Tool:
+        """MCP Tool definition.
+
+        Returns the complete Tool object with name, description,
+        and input schema for the MCP protocol.
+        """
+        ...
+
+    @property
+    def mapping(self) -> EndpointMapping | None:
+        """Endpoint mapping for HTTP-backed tools.
+
+        Returns None for registry-only tools (like list_projects)
+        that don't make HTTP requests to the backend.
+        """
+        return None
+
+    def transform_request(self, args: dict[str, Any]) -> dict[str, Any]:
+        """Transform MCP tool arguments to HTTP request parameters.
+
+        Override this method to customize how tool arguments are
+        converted to HTTP request format.
+
+        Args:
+            args: MCP tool arguments from the client
+
+        Returns:
+            Dict that may contain:
+            - "params": Query parameters for GET requests
+            - "json_data": JSON body for POST requests
+            - "data": Form data for POST requests
+            - "path": Dynamic path override (e.g., "/api/cell/{name}")
+            - "fallback_path": Alternative endpoint for 404 fallback
+            - "fallback_json_data": Alternative body for fallback request
+        """
+        return {}
+
+    def transform_response(self, response: Any) -> Any:
+        """Transform HTTP response to MCP-friendly format.
+
+        Override this method to customize how backend responses are
+        formatted for the AI assistant.
+
+        Args:
+            response: Raw response from the FastAPI backend
+
+        Returns:
+            Transformed response (typically a dict or the original response)
+        """
+        return response
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+        client: FastAPIClient,
+    ) -> list[TextContent | ImageContent]:
+        """Execute the tool and return results.
+
+        This is the main entry point called by the server's call_tool handler.
+        The default implementation uses the endpoint mapping and transformers.
+        Override for custom execution logic (e.g., registry-only tools).
+
+        Args:
+            arguments: MCP tool arguments from the client
+            client: FastAPI client for making HTTP requests
+
+        Returns:
+            List of TextContent and/or ImageContent responses
+        """
+        import httpx
+
+        mapping = self.mapping
+        if mapping is None:
+            error_msg = f"Tool {self.name} has no endpoint mapping"
+            logger.error(error_msg)
+            return [TextContent(type="text", text=json.dumps({"error": error_msg}))]
+
+        try:
+            project = arguments.get("project")
+            transformed = self.transform_request(arguments)
+
+            method = mapping.method
+            path = transformed.get("path", mapping.path)
+            params = transformed.get("params")
+            json_data = transformed.get("json_data")
+            data = transformed.get("data")
+            fallback_path = transformed.get("fallback_path")
+            fallback_json_data = transformed.get("fallback_json_data")
+
+            try:
+                response = await client.request(
+                    method=method,
+                    path=path,
+                    params=params,
+                    json_data=json_data,
+                    data=data,
+                    project=project,
+                )
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code == 404 and fallback_path:
+                    logger.info(
+                        "Endpoint %s returned 404, trying fallback: %s",
+                        path,
+                        fallback_path,
+                    )
+                    response = await client.request(
+                        method=method,
+                        path=fallback_path,
+                        params=params,
+                        json_data=fallback_json_data,
+                        data=data,
+                        project=project,
+                    )
+                else:
+                    raise
+
+            result = self.transform_response(response)
+            logger.debug("Tool %s result: %s", self.name, result)
+
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps(result, indent=2),
+                )
+            ]
+
+        except Exception as e:
+            error_msg = f"Tool execution failed: {e!s}"
+            logger.exception(error_msg)
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps({"error": error_msg}),
+                )
+            ]