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

{mcp_standalone → gfp_mcp}/__init__.py

@@ -1,22 +1,22 @@
-"""MCP Standalone Server for GDSFactory+.
+"""GDSFactory+ MCP Server.
 
 This package provides a Model Context Protocol (MCP) server that exposes
 GDSFactory+ operations as tools for AI assistants. The server uses STDIO
 transport and proxies requests to the FastAPI backend.
 
 Architecture:
-- Standalone MCP server (this package)
+- Tool handlers in gfp_mcp/tools/ with co-located definitions and transformers
 - STDIO transport for universal compatibility
-- HTTP proxy to FastAPI backend
+- HTTP proxy to FastAPI backend via client.py
+- Multi-project routing via server registry
 - Zero changes to existing FastAPI server
-- No database conflicts (only FastAPI touches SQLite)
 
 Usage:
-    from gdsfactoryplus.mcp_standalone import main
+    from gfp_mcp import main
     main()
 
 Or via CLI:
-    gfp mcp-serve
+    gfp-mcp-serve
 """
 
 from __future__ import annotations
@@ -25,18 +25,20 @@ from .client import FastAPIClient
 from .config import MCPConfig
 from .resources import get_all_resources, get_resource_content
 from .server import create_server, main, run_server
-from .tools import get_all_tools, get_tool_by_name
+from .tools import get_all_tools, get_handler, get_tool_by_name
 
 __all__ = [
+    "__version__",
     "FastAPIClient",
     "MCPConfig",
     "create_server",
     "main",
     "run_server",
     "get_all_tools",
+    "get_handler",
     "get_tool_by_name",
     "get_all_resources",
     "get_resource_content",
 ]
 
-__version__ = "0.2.4"
+__version__ = "0.3.2"

{mcp_standalone → gfp_mcp}/client.py

@@ -294,17 +294,3 @@ class FastAPIClient:
             }
             for server in servers
         ]
-
-    async def get_project_info(self, project: str) -> dict[str, Any]:
-        """Get detailed information about a specific project.
-
-        Args:
-            project: Project name or path
-
-        Returns:
-            Project information from the server's /info endpoint
-
-        Raises:
-            ValueError: If project not found
-        """
-        return await self.request("GET", "/info", project=project)

gfp_mcp/config.py

@@ -0,0 +1,161 @@
+"""Configuration management for MCP standalone server."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Final
+
+try:
+    import tomllib  # Python 3.11+
+except ImportError:
+    import tomli as tomllib  # type: ignore[import-not-found]
+
+__all__ = ["MCPConfig", "get_gfp_api_key", "set_gfp_api_key"]
+
+
+class MCPConfig:
+    """Configuration for MCP standalone server.
+
+    Manages environment variables and default settings for the MCP server
+    that proxies requests to the FastAPI backend.
+    """
+
+    API_URL: Final[str | None] = os.getenv("GFP_API_URL")
+
+    TIMEOUT: Final[int] = int(os.getenv("GFP_MCP_TIMEOUT", "300"))
+
+    DEBUG: Final[bool] = os.getenv("GFP_MCP_DEBUG", "false").lower() in (
+        "true",
+        "1",
+        "yes",
+    )
+
+    REGISTRY_API_URL: Final[str] = "https://registry.gdsfactory.com"
+
+    MAX_RETRIES: Final[int] = 3
+    RETRY_BACKOFF: Final[float] = 0.5  # Initial backoff in seconds
+
+    @classmethod
+    def get_api_url(cls, override: str | None = None) -> str | None:
+        """Get the FastAPI base URL.
+
+        Args:
+            override: Optional URL to override the environment variable
+
+        Returns:
+            The API base URL or None if not configured
+        """
+        return override or cls.API_URL
+
+    @classmethod
+    def get_timeout(cls) -> int:
+        """Get the timeout for tool calls.
+
+        Returns:
+            Timeout in seconds
+        """
+        return cls.TIMEOUT
+
+
+def _read_api_key_from_toml(file_path: Path) -> str | None:
+    """Read the API key from a TOML configuration file.
+
+    Args:
+        file_path: Path to the TOML file.
+
+    Returns:
+        The API key string, or None if not found or file doesn't exist.
+    """
+    if not file_path.exists():
+        return None
+
+    try:
+        with open(file_path, "rb") as f:
+            config = tomllib.load(f)
+
+        return (
+            config.get("tool", {}).get("gdsfactoryplus", {}).get("api", {}).get("key")
+        )
+    except Exception:
+        return None
+
+
+def get_gfp_api_key() -> str | None:
+    """Retrieve the GFP API key from environment variables or config files.
+
+    Checks sources in priority order:
+    1. GFP_API_KEY environment variable
+    2. ~/.gdsfactory/gdsfactoryplus.toml
+    3. ./pyproject.toml
+
+    Returns:
+        The API key string, or None if not found.
+    """
+    # 1. Check environment variable (highest priority)
+    api_key = os.environ.get("GFP_API_KEY")
+    if api_key:
+        return api_key
+
+    # 2. Check global config file: ~/.gdsfactory/gdsfactoryplus.toml
+    global_config_path = Path.home() / ".gdsfactory" / "gdsfactoryplus.toml"
+    api_key = _read_api_key_from_toml(global_config_path)
+    if api_key:
+        return api_key
+
+    # 3. Check local project config: ./pyproject.toml
+    local_config_path = Path.cwd() / "pyproject.toml"
+    api_key = _read_api_key_from_toml(local_config_path)
+    if api_key:
+        return api_key
+
+    return None
+
+
+def set_gfp_api_key(api_key: str) -> None:
+    """Save the GFP API key to the global config file.
+
+    Writes to: ~/.gdsfactory/gdsfactoryplus.toml
+
+    Args:
+        api_key: The API key to save.
+
+    Raises:
+        ValueError: If api_key is empty or None.
+    """
+    if not api_key:
+        raise ValueError("API key is required")
+
+    config_dir = Path.home() / ".gdsfactory"
+    config_path = config_dir / "gdsfactoryplus.toml"
+
+    # Create directory if it doesn't exist
+    config_dir.mkdir(parents=True, exist_ok=True)
+
+    # Load existing config or create new one
+    config: dict = {}
+    if config_path.exists():
+        with open(config_path, "rb") as f:
+            config = tomllib.load(f)
+
+    # Set the API key in the nested structure
+    if "tool" not in config:
+        config["tool"] = {}
+    if "gdsfactoryplus" not in config["tool"]:
+        config["tool"]["gdsfactoryplus"] = {}
+    if "api" not in config["tool"]["gdsfactoryplus"]:
+        config["tool"]["gdsfactoryplus"]["api"] = {}
+
+    config["tool"]["gdsfactoryplus"]["api"]["key"] = api_key
+
+    # Write back to file using tomli_w if available, otherwise manual formatting
+    try:
+        import tomli_w
+
+        with open(config_path, "wb") as f:
+            tomli_w.dump(config, f)
+    except ImportError:
+        # Fallback: write TOML manually for this simple structure
+        with open(config_path, "w") as f:
+            f.write("[tool.gdsfactoryplus.api]\n")
+            f.write(f'key = "{api_key}"\n')

gfp_mcp/render.py

@@ -0,0 +1,139 @@
+"""GDS rendering utilities for MCP server.
+
+This module provides utilities for rendering GDS files to PNG images,
+enabling automatic image return when building cells.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from pathlib import Path
+
+from mcp.types import ImageContent
+
+from .registry import ServerRegistry
+from .utils import wait_for_gds_file
+
+__all__ = ["render_gds_to_png", "render_built_cells", "HAS_KLAYOUT"]
+
+logger = logging.getLogger(__name__)
+
+try:
+    import klayout.db as db
+    import klayout.lay as lay
+
+    HAS_KLAYOUT = True
+except ImportError:
+    HAS_KLAYOUT = False
+    db = None  # type: ignore[assignment]
+    lay = None  # type: ignore[assignment]
+
+
+def render_gds_to_png(
+    gds_path: Path,
+    width: int = 800,
+    height: int = 600,
+) -> bytes | None:
+    """Render GDS file to PNG image using klayout.
+
+    Args:
+        gds_path: Path to the GDS file to render
+        width: Image width in pixels (default: 800)
+        height: Image height in pixels (default: 600)
+
+    Returns:
+        PNG image as bytes, or None if klayout is not available or rendering fails
+    """
+    if not HAS_KLAYOUT:
+        logger.debug("klayout not available, skipping GDS rendering")
+        return None
+
+    if not gds_path.exists():
+        logger.warning("GDS file not found for rendering: %s", gds_path)
+        return None
+
+    try:
+        layout = db.Layout()
+        layout.read(str(gds_path))
+
+        layout_view = lay.LayoutView()
+        layout_view.load_layout(str(gds_path), True)
+
+        layout_view.max_hier()
+
+        layout_view.zoom_fit()
+
+        pixel_buffer = layout_view.get_pixels(width, height)
+
+        png_bytes = pixel_buffer.to_png_data()
+
+        logger.debug("Rendered GDS to PNG: %s (%dx%d)", gds_path, width, height)
+        return png_bytes
+
+    except Exception as e:
+        logger.warning("Failed to render GDS to PNG: %s - %s", gds_path, e)
+        return None
+
+
+async def render_built_cells(
+    cell_names: list[str],
+    project: str | None,
+) -> list[ImageContent]:
+    """Render built GDS cells to PNG images.
+
+    Args:
+        cell_names: List of cell names to render
+        project: Optional project name for routing
+
+    Returns:
+        List of ImageContent for successfully rendered cells
+    """
+    images: list[ImageContent] = []
+
+    if not cell_names:
+        return images
+
+    if not HAS_KLAYOUT:
+        logger.debug("klayout not available, skipping cell rendering")
+        return images
+
+    registry = ServerRegistry()
+    server_info = None
+
+    if project:
+        server_info = registry.get_server_by_project(project)
+    if not server_info:
+        servers = registry.list_servers()
+        if servers:
+            server_info = servers[0]
+
+    if not server_info:
+        logger.debug(
+            "No server found in registry, cannot determine project path for GDS rendering"
+        )
+        return images
+
+    project_path = Path(server_info.project_path)
+    gds_dir = project_path / "build" / "gds"
+
+    for cell_name in cell_names:
+        gds_path = gds_dir / f"{cell_name}.gds"
+
+        if await wait_for_gds_file(gds_path):
+            png_bytes = render_gds_to_png(gds_path)
+            if png_bytes:
+                images.append(
+                    ImageContent(
+                        type="image",
+                        data=base64.b64encode(png_bytes).decode("utf-8"),
+                        mimeType="image/png",
+                    )
+                )
+                logger.info("Added PNG image for cell: %s", cell_name)
+            else:
+                logger.debug("Failed to render GDS to PNG for cell: %s", cell_name)
+        else:
+            logger.debug("GDS file not found within timeout for cell: %s", cell_name)
+
+    return images

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