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

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}),
+                )
+            ]

gfp_mcp/tools/bbox.py

@@ -0,0 +1,115 @@
+"""Bounding box generation tool handler.
+
+This module provides the handler for generating bounding box
+GDS files from input GDS files.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.types import Tool
+
+from .base import EndpointMapping, ToolHandler, add_project_param
+
+__all__ = ["GenerateBboxHandler"]
+
+
+class GenerateBboxHandler(ToolHandler):
+    """Handler for generating bounding box GDS files.
+
+    Creates a simplified version of the layout with only a bounding box
+    on specified layers.
+    """
+
+    @property
+    def name(self) -> str:
+        return "generate_bbox"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="generate_bbox",
+            description=(
+                "Generate a bounding box GDS file from an input GDS. This creates "
+                "a simplified version of the layout with only a bounding box on "
+                "specified layers. Useful for creating abstract views, floorplanning, "
+                "or hierarchical design. Can optionally preserve specific layers and "
+                "ports."
+            ),
+            inputSchema=add_project_param(
+                {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": (
+                                "Path to the input GDS file. Can be absolute or relative "
+                                "to the project directory."
+                            ),
+                        },
+                        "outpath": {
+                            "type": "string",
+                            "description": (
+                                "Output path for the bounding box GDS. If not specified, "
+                                "uses the input filename with '-bbox' suffix."
+                            ),
+                            "default": "",
+                        },
+                        "layers_to_keep": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": (
+                                "List of layer names to preserve in the output. "
+                                "Other layers will be replaced by the bounding box."
+                            ),
+                            "default": [],
+                        },
+                        "bbox_layer": {
+                            "type": "array",
+                            "items": {"type": "integer"},
+                            "description": (
+                                "Layer (as [layer, datatype]) to use for the bounding box. "
+                                "Default is [99, 0]."
+                            ),
+                            "default": [99, 0],
+                        },
+                        "ignore_ports": {
+                            "type": "boolean",
+                            "description": (
+                                "If true, do not include ports in the output. "
+                                "Default is false."
+                            ),
+                            "default": False,
+                        },
+                    },
+                    "required": ["path"],
+                }
+            ),
+        )
+
+    @property
+    def mapping(self) -> EndpointMapping:
+        return EndpointMapping(method="POST", path="/api/bbox")
+
+    def transform_request(self, args: dict[str, Any]) -> dict[str, Any]:
+        """Transform generate_bbox MCP args to FastAPI params.
+
+        Args:
+            args: MCP tool arguments
+
+        Returns:
+            Dict with 'json_data' key for request body
+        """
+        json_data: dict[str, Any] = {"path": args["path"]}
+
+        if "outpath" in args and args["outpath"]:
+            json_data["outpath"] = args["outpath"]
+        if "layers_to_keep" in args and args["layers_to_keep"]:
+            json_data["layers_to_keep"] = args["layers_to_keep"]
+        if "bbox_layer" in args and args["bbox_layer"]:
+            json_data["bbox_layer"] = args["bbox_layer"]
+        if "ignore_ports" in args:
+            json_data["ignore_ports"] = args["ignore_ports"]
+
+        return {"json_data": json_data}

gfp_mcp/tools/build.py

@@ -0,0 +1,159 @@
+"""Build cells tool handler.
+
+This module provides the handler for building GDS cells, including
+optional PNG image rendering for visualization.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from mcp.types import ImageContent, TextContent, Tool
+
+from ..render import HAS_KLAYOUT, render_built_cells
+from .base import EndpointMapping, ToolHandler, add_project_param
+
+if TYPE_CHECKING:
+    from ..client import FastAPIClient
+
+__all__ = ["BuildCellsHandler"]
+
+logger = logging.getLogger(__name__)
+
+
+class BuildCellsHandler(ToolHandler):
+    """Handler for building GDS cells.
+
+    This handler builds one or more GDS cells and optionally renders
+    specified cells to PNG images for visualization.
+    """
+
+    @property
+    def name(self) -> str:
+        return "build_cells"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="build_cells",
+            description=(
+                "Build one or more GDS cells by name. This creates the physical layout "
+                "files (.gds) for photonic components. Pass a list of cell names to build. "
+                "For a single cell, pass a list with one element. All cells are built "
+                "in the background and saved to the project build directory. "
+                "Use the optional 'visualize' parameter to specify which cells should be "
+                "rendered to PNG images and returned in the response."
+            ),
+            inputSchema=add_project_param(
+                {
+                    "type": "object",
+                    "properties": {
+                        "names": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": "List of cell/component names to build (can be a single-item list)",
+                        },
+                        "visualize": {
+                            "type": "array",
+                            "items": {"type": "string"},
+                            "description": (
+                                "Optional list of cell names to render as PNG images. "
+                                "Only cells in this list will be visualized. If not provided, "
+                                "no images are returned. Use this to selectively view only "
+                                "the cells you need to inspect."
+                            ),
+                        },
+                        "with_metadata": {
+                            "type": "boolean",
+                            "description": (
+                                "Include metadata in the GDS files (default: true)"
+                            ),
+                            "default": True,
+                        },
+                        "register": {
+                            "type": "boolean",
+                            "description": (
+                                "Re-register the cells in the KLayout cache (default: true)"
+                            ),
+                            "default": True,
+                        },
+                    },
+                    "required": ["names"],
+                }
+            ),
+        )
+
+    @property
+    def mapping(self) -> EndpointMapping:
+        return EndpointMapping(method="POST", path="/api/build-cells")
+
+    def transform_request(self, args: dict[str, Any]) -> dict[str, Any]:
+        """Transform build_cells MCP args to FastAPI params.
+
+        Args:
+            args: MCP tool arguments
+
+        Returns:
+            Dict with 'params' key for query parameters and 'json_data' for body
+        """
+        return {
+            "params": {
+                "with_metadata": args.get("with_metadata", True),
+                "register": args.get("register", True),
+            },
+            "json_data": args["names"],
+        }
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+        client: FastAPIClient,
+    ) -> list[TextContent | ImageContent]:
+        """Build cells and optionally render images.
+
+        Args:
+            arguments: MCP tool arguments
+            client: FastAPI client for making requests
+
+        Returns:
+            List of TextContent with build results and optional ImageContent
+        """
+        try:
+            project = arguments.get("project")
+            transformed = self.transform_request(arguments)
+
+            response = await client.request(
+                method=self.mapping.method,
+                path=self.mapping.path,
+                params=transformed.get("params"),
+                json_data=transformed.get("json_data"),
+                project=project,
+            )
+
+            logger.debug("Build cells result: %s", response)
+
+            results: list[TextContent | ImageContent] = [
+                TextContent(
+                    type="text",
+                    text=json.dumps(response, indent=2),
+                )
+            ]
+
+            # Render images if klayout is available and visualize is specified
+            visualize = arguments.get("visualize", [])
+            if visualize and HAS_KLAYOUT:
+                results.extend(await render_built_cells(visualize, project))
+
+            return results
+
+        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}),
+                )
+            ]

gfp_mcp/tools/cells.py

@@ -0,0 +1,103 @@
+"""Cell listing and info tool handlers.
+
+These tools provide information about available cells/components
+in the current PDK.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.types import Tool
+
+from .base import EndpointMapping, ToolHandler, add_project_param
+
+__all__ = ["ListCellsHandler", "GetCellInfoHandler"]
+
+
+class ListCellsHandler(ToolHandler):
+    """Handler for listing all available cells/components."""
+
+    @property
+    def name(self) -> str:
+        return "list_cells"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="list_cells",
+            description=(
+                "List all available cells/components that can be built. Returns "
+                "the names of all registered component factories in the current PDK. "
+                "Use this to discover what components are available before building."
+            ),
+            inputSchema=add_project_param(
+                {
+                    "type": "object",
+                    "properties": {},
+                }
+            ),
+        )
+
+    @property
+    def mapping(self) -> EndpointMapping:
+        return EndpointMapping(method="GET", path="/api/cells")
+
+    def transform_response(self, response: Any) -> dict[str, Any]:
+        """Transform list_cells response to MCP format.
+
+        Args:
+            response: FastAPI response (list of cell names)
+
+        Returns:
+            Formatted response with cell names
+        """
+        if isinstance(response, list):
+            return {"cells": response, "count": len(response)}
+        return response
+
+
+class GetCellInfoHandler(ToolHandler):
+    """Handler for getting detailed info about a specific cell."""
+
+    @property
+    def name(self) -> str:
+        return "get_cell_info"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="get_cell_info",
+            description=(
+                "Get detailed information about a specific cell/component. Returns "
+                "metadata including the source file, parameters, and other details "
+                "about the component factory."
+            ),
+            inputSchema=add_project_param(
+                {
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "Name of the cell/component to get info about",
+                        },
+                    },
+                    "required": ["name"],
+                }
+            ),
+        )
+
+    @property
+    def mapping(self) -> EndpointMapping:
+        return EndpointMapping(method="GET", path="/api/cell-info")
+
+    def transform_request(self, args: dict[str, Any]) -> dict[str, Any]:
+        """Transform get_cell_info MCP args to FastAPI params.
+
+        Args:
+            args: MCP tool arguments
+
+        Returns:
+            Dict with 'params' key for query parameters
+        """
+        return {"params": {"name": args["name"]}}

gfp_mcp/tools/connectivity.py

@@ -0,0 +1,70 @@
+"""Connectivity check tool handler.
+
+This module provides the handler for running local connectivity
+checks on GDS files.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.types import Tool
+
+from .base import EndpointMapping, ToolHandler, add_project_param
+
+__all__ = ["CheckConnectivityHandler"]
+
+
+class CheckConnectivityHandler(ToolHandler):
+    """Handler for running connectivity checks on GDS files.
+
+    This is a fast, local check that verifies all layers are properly
+    connected and identifies any connectivity violations.
+    """
+
+    @property
+    def name(self) -> str:
+        return "check_connectivity"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="check_connectivity",
+            description=(
+                "Run a local connectivity check on a GDS file. This verifies that "
+                "all layers are properly connected and identifies any connectivity "
+                "violations. This is a fast, local check (does not require uploading "
+                "to a remote server). Use this to quickly check for disconnected "
+                "components. Returns XML results showing connectivity issues."
+            ),
+            inputSchema=add_project_param(
+                {
+                    "type": "object",
+                    "properties": {
+                        "path": {
+                            "type": "string",
+                            "description": (
+                                "Path to the GDS file to check. Can be absolute or "
+                                "relative to the project directory."
+                            ),
+                        },
+                    },
+                    "required": ["path"],
+                }
+            ),
+        )
+
+    @property
+    def mapping(self) -> EndpointMapping:
+        return EndpointMapping(method="POST", path="/api/check-connectivity")
+
+    def transform_request(self, args: dict[str, Any]) -> dict[str, Any]:
+        """Transform check_connectivity MCP args to FastAPI params.
+
+        Args:
+            args: MCP tool arguments
+
+        Returns:
+            Dict with 'json_data' key for request body
+        """
+        return {"json_data": {"path": args["path"]}}