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

gfp_mcp/samples.py

@@ -0,0 +1,206 @@
+"""Core module for downloading and extracting GDSFactory+ sample projects.
+
+Provides async functions to download sample project ZIPs from the registry
+and extract sample files (Python, YAML) for use by AI assistants.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import logging
+import mimetypes
+import zipfile
+from dataclasses import dataclass, field
+
+import httpx
+
+from .config import MCPConfig
+
+__all__ = [
+    "GENERAL_PDK_PROJECTS",
+    "SAMPLE_EXTENSIONS",
+    "SampleFile",
+    "SampleProject",
+    "get_sample_file_content",
+    "list_sample_projects",
+]
+
+logger = logging.getLogger(__name__)
+
+GENERAL_PDK_PROJECTS = [
+    "photonics--basic--public--pdk",
+    "photonics--full--public--pdk",
+]
+
+SAMPLE_EXTENSIONS = {".py", ".yml", ".yaml"}
+
+
+@dataclass
+class SampleProject:
+    """A sample project with its list of sample file paths."""
+
+    name: str
+    files: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SampleFile:
+    """A single sample file with its content."""
+
+    project: str
+    path: str
+    content: str
+    mime_type: str
+
+
+async def _download_project_zip(api_key: str, project_name: str) -> bytes:
+    """Download a project ZIP from the registry.
+
+    Args:
+        api_key: GFP API key for authentication.
+        project_name: Name of the project to download.
+
+    Returns:
+        Raw ZIP file bytes.
+
+    Raises:
+        httpx.HTTPStatusError: If the request fails.
+    """
+    url = f"{MCPConfig.REGISTRY_API_URL}/project/download/{project_name}"
+    headers = {"X-API-Key": api_key}
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, headers=headers, timeout=300.0)
+        response.raise_for_status()
+        return response.content
+
+
+def _extract_sample_files(zip_data: bytes, project_name: str) -> list[str]:
+    """Extract sample file paths from a project ZIP.
+
+    Finds files under any ``samples/`` directory, filters by extension,
+    and excludes ``__init__.py`` and ``__pycache__`` entries.
+
+    Args:
+        zip_data: Raw ZIP file bytes.
+        project_name: Project name (unused, kept for future use).
+
+    Returns:
+        Sorted list of file paths within the ZIP that are sample files.
+    """
+    sample_files = []
+
+    with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
+        for name in zf.namelist():
+            if zf.getinfo(name).is_dir():
+                continue
+
+            # Must be under a samples/ directory
+            parts = name.split("/")
+            if "samples" not in parts:
+                continue
+
+            # Filter by extension
+            ext = "." + name.rsplit(".", 1)[-1] if "." in name else ""
+            if ext not in SAMPLE_EXTENSIONS:
+                continue
+
+            # Exclude __init__.py and __pycache__
+            basename = parts[-1]
+            if basename == "__init__.py" or "__pycache__" in parts:
+                continue
+
+            sample_files.append(name)
+
+    return sorted(sample_files)
+
+
+def _extract_file_content(zip_data: bytes, file_path: str) -> str:
+    """Extract a single file's content from a ZIP.
+
+    Args:
+        zip_data: Raw ZIP file bytes.
+        file_path: Path within the ZIP to extract.
+
+    Returns:
+        UTF-8 decoded file content.
+
+    Raises:
+        KeyError: If the file is not found in the ZIP.
+    """
+    with zipfile.ZipFile(io.BytesIO(zip_data)) as zf:
+        return zf.read(file_path).decode("utf-8")
+
+
+def _get_mime_type(path: str) -> str:
+    """Determine MIME type from file path.
+
+    Args:
+        path: File path to check.
+
+    Returns:
+        MIME type string, defaults to ``text/plain``.
+    """
+    mime_type, _ = mimetypes.guess_type(path)
+    return mime_type or "text/plain"
+
+
+async def list_sample_projects(api_key: str) -> list[SampleProject]:
+    """Download both General PDK ZIPs and list their sample files.
+
+    Args:
+        api_key: GFP API key for authentication.
+
+    Returns:
+        List of SampleProject instances with file listings.
+    """
+    tasks = [
+        _download_project_zip(api_key, project) for project in GENERAL_PDK_PROJECTS
+    ]
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+
+    projects = []
+    for project_name, result in zip(GENERAL_PDK_PROJECTS, results):
+        if isinstance(result, Exception):
+            logger.warning("Failed to download project %s: %s", project_name, result)
+            projects.append(SampleProject(name=project_name, files=[]))
+            continue
+
+        files = _extract_sample_files(result, project_name)
+        projects.append(SampleProject(name=project_name, files=files))
+
+    return projects
+
+
+async def get_sample_file_content(api_key: str, project: str, path: str) -> SampleFile:
+    """Download a project ZIP and extract a specific file's content.
+
+    Args:
+        api_key: GFP API key for authentication.
+        project: Project name (must be in GENERAL_PDK_PROJECTS).
+        path: File path within the ZIP.
+
+    Returns:
+        SampleFile with the file's content and metadata.
+
+    Raises:
+        ValueError: If the project name is not recognized.
+        KeyError: If the file is not found in the ZIP.
+    """
+    if project not in GENERAL_PDK_PROJECTS:
+        raise ValueError(
+            f"Unknown sample project: {project}. "
+            f"Available projects: {GENERAL_PDK_PROJECTS}"
+        )
+
+    zip_data = await _download_project_zip(api_key, project)
+    content = _extract_file_content(zip_data, path)
+    mime_type = _get_mime_type(path)
+
+    return SampleFile(
+        project=project,
+        path=path,
+        content=content,
+        mime_type=mime_type,
+    )

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)