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

gfp_mcp/tools/project.py

@@ -0,0 +1,160 @@
+"""Project discovery tool handlers.
+
+These tools handle project listing and info retrieval from the
+server registry without making HTTP requests to the backend.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from mcp.types import TextContent, Tool
+
+from .base import EndpointMapping, ToolHandler
+
+if TYPE_CHECKING:
+    from ..client import FastAPIClient
+
+__all__ = ["ListProjectsHandler", "GetProjectInfoHandler"]
+
+logger = logging.getLogger(__name__)
+
+
+class ListProjectsHandler(ToolHandler):
+    """Handler for listing all active GDSFactory+ projects.
+
+    This is a registry-only tool that doesn't make HTTP requests.
+    It reads from the local server registry to discover running servers.
+    """
+
+    @property
+    def name(self) -> str:
+        return "list_projects"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="list_projects",
+            description=(
+                "List all active GDSFactory+ projects. Returns information about "
+                "all running servers including project name, path, port, PID, and PDK. "
+                "Use this to discover which projects are available for interaction."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {},
+            },
+        )
+
+    @property
+    def mapping(self) -> EndpointMapping | None:
+        # Registry-only tool, no HTTP endpoint
+        return None
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+        client: FastAPIClient,
+    ) -> list[TextContent]:
+        """List all projects from the registry.
+
+        Args:
+            arguments: MCP tool arguments (unused for this tool)
+            client: FastAPI client (used to access registry)
+
+        Returns:
+            List containing TextContent with project list
+        """
+        try:
+            projects = client.list_projects()
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps({"projects": projects}, indent=2),
+                )
+            ]
+        except Exception as e:
+            error_msg = f"Failed to list projects: {e!s}"
+            logger.exception(error_msg)
+            return [TextContent(type="text", text=json.dumps({"error": error_msg}))]
+
+
+class GetProjectInfoHandler(ToolHandler):
+    """Handler for getting detailed info about a specific project.
+
+    This tool makes an HTTP request to the project's /info endpoint
+    to retrieve detailed information including version and PDK details.
+    """
+
+    @property
+    def name(self) -> str:
+        return "get_project_info"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="get_project_info",
+            description=(
+                "Get detailed information about a specific project. Returns metadata "
+                "including project name, path, port, PID, PDK, and version. "
+                "Use this to get information about a running project."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "project": {
+                        "type": "string",
+                        "description": (
+                            "Project name or path. Can be the project directory name "
+                            "or full path."
+                        ),
+                    },
+                },
+                "required": ["project"],
+            },
+        )
+
+    @property
+    def mapping(self) -> EndpointMapping:
+        return EndpointMapping(method="GET", path="/info")
+
+    def transform_request(self, args: dict[str, Any]) -> dict[str, Any]:
+        """No request transformation needed - just routes to /info."""
+        return {}
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+        client: FastAPIClient,
+    ) -> list[TextContent]:
+        """Get project info via HTTP request.
+
+        Args:
+            arguments: MCP tool arguments with 'project' key
+            client: FastAPI client for making requests
+
+        Returns:
+            List containing TextContent with project info
+        """
+        try:
+            project = arguments.get("project")
+            if not project:
+                return [
+                    TextContent(
+                        type="text",
+                        text=json.dumps({"error": "project parameter is required"}),
+                    )
+                ]
+
+            response = await client.request(
+                method="GET",
+                path="/info",
+                project=project,
+            )
+            return [TextContent(type="text", text=json.dumps(response, indent=2))]
+        except Exception as e:
+            error_msg = f"Failed to get project info: {e!s}"
+            logger.exception(error_msg)
+            return [TextContent(type="text", text=json.dumps({"error": error_msg}))]

gfp_mcp/tools/samples.py

@@ -0,0 +1,215 @@
+"""Sample project tool handlers.
+
+These tools allow AI assistants to browse and read sample files
+from GDSFactory+ General PDK sample projects.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from mcp.types import TextContent, Tool
+
+from ..config import get_gfp_api_key
+from ..samples import (
+    GENERAL_PDK_PROJECTS,
+    get_sample_file_content,
+    list_sample_projects,
+)
+from .base import ToolHandler
+
+if TYPE_CHECKING:
+    from ..client import FastAPIClient
+
+__all__ = ["ListSamplesHandler", "GetSampleFileHandler"]
+
+logger = logging.getLogger(__name__)
+
+_API_KEY_ERROR = {
+    "error": "GFP API key not configured",
+    "instructions": (
+        "Set the GFP_API_KEY environment variable or configure "
+        "~/.gdsfactory/gdsfactoryplus.toml with your API key. "
+        "Get your key at: https://api.gdsfactory.com/api-keys/list"
+    ),
+}
+
+
+class ListSamplesHandler(ToolHandler):
+    """Handler for listing sample files from General PDK projects.
+
+    Downloads project ZIPs from the registry and returns file listings.
+    This is a registry-only tool that doesn't use the FastAPI backend.
+    """
+
+    @property
+    def name(self) -> str:
+        return "list_samples"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="list_samples",
+            description=(
+                "List all available sample files from GDSFactory+ General PDK "
+                "sample projects. Returns file listings for the basic and full "
+                "public PDK projects. Requires a GFP API key."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {},
+            },
+        )
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+        client: FastAPIClient,
+    ) -> list[TextContent]:
+        """List sample files from all General PDK projects.
+
+        Args:
+            arguments: MCP tool arguments (unused).
+            client: FastAPI client (unused, samples come from registry).
+
+        Returns:
+            List containing TextContent with project file listings.
+        """
+        api_key = get_gfp_api_key()
+        if not api_key:
+            return [TextContent(type="text", text=json.dumps(_API_KEY_ERROR))]
+
+        try:
+            projects = await list_sample_projects(api_key)
+            result = {
+                "projects": [{"name": p.name, "files": p.files} for p in projects]
+            }
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+        except Exception as e:
+            error_msg = f"Failed to fetch samples: {e!s}"
+            logger.exception(error_msg)
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps({"error": error_msg}),
+                )
+            ]
+
+
+class GetSampleFileHandler(ToolHandler):
+    """Handler for reading a specific sample file's content.
+
+    Downloads a project ZIP and extracts the requested file.
+    This is a registry-only tool that doesn't use the FastAPI backend.
+    """
+
+    @property
+    def name(self) -> str:
+        return "get_sample_file"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="get_sample_file",
+            description=(
+                "Get the content of a specific sample file from a GDSFactory+ "
+                "General PDK project. Use list_samples first to discover "
+                "available files. Requires a GFP API key."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "project": {
+                        "type": "string",
+                        "description": (
+                            "Sample project name "
+                            "(e.g., 'photonics--basic--public--pdk')."
+                        ),
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": (
+                            "File path within the project ZIP "
+                            "(as returned by list_samples)."
+                        ),
+                    },
+                },
+                "required": ["project", "path"],
+            },
+        )
+
+    async def handle(
+        self,
+        arguments: dict[str, Any],
+        client: FastAPIClient,
+    ) -> list[TextContent]:
+        """Get the content of a specific sample file.
+
+        Args:
+            arguments: MCP tool arguments with 'project' and 'path'.
+            client: FastAPI client (unused, samples come from registry).
+
+        Returns:
+            List containing TextContent with file content and metadata.
+        """
+        api_key = get_gfp_api_key()
+        if not api_key:
+            return [TextContent(type="text", text=json.dumps(_API_KEY_ERROR))]
+
+        project = arguments.get("project")
+        path = arguments.get("path")
+
+        if not project or not path:
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps(
+                        {"error": "Both 'project' and 'path' parameters are required"}
+                    ),
+                )
+            ]
+
+        try:
+            sample_file = await get_sample_file_content(api_key, project, path)
+            result = {
+                "project": sample_file.project,
+                "path": sample_file.path,
+                "content": sample_file.content,
+                "metadata": {"mime_type": sample_file.mime_type},
+            }
+            return [TextContent(type="text", text=json.dumps(result, indent=2))]
+        except ValueError:
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps(
+                        {
+                            "error": f"Unknown sample project: {project}",
+                            "available_projects": GENERAL_PDK_PROJECTS,
+                        }
+                    ),
+                )
+            ]
+        except KeyError:
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps(
+                        {
+                            "error": f"File not found in project: {path}",
+                            "suggestion": ("Use list_samples to see available files."),
+                        }
+                    ),
+                )
+            ]
+        except Exception as e:
+            error_msg = f"Failed to fetch sample file: {e!s}"
+            logger.exception(error_msg)
+            return [
+                TextContent(
+                    type="text",
+                    text=json.dumps({"error": error_msg}),
+                )
+            ]

gfp_mcp/tools/simulation.py

@@ -0,0 +1,153 @@
+"""SAX circuit simulation tool handler.
+
+This module provides the handler for running SAX circuit simulations
+on photonic components, with fallback to the old API.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from mcp.types import Tool
+
+from .base import EndpointMapping, ToolHandler, add_project_param
+
+__all__ = ["SimulateComponentHandler"]
+
+
+class SimulateComponentHandler(ToolHandler):
+    """Handler for running SAX circuit simulations.
+
+    Supports both the new SAX API (/api/sax/{name}/simulate) and
+    falls back to the old API (/api/simulate) if the new endpoint
+    returns 404.
+    """
+
+    @property
+    def name(self) -> str:
+        return "simulate_component"
+
+    @property
+    def definition(self) -> Tool:
+        return Tool(
+            name="simulate_component",
+            description=(
+                "Run a SAX circuit simulation on a photonic component by name. "
+                "This simulates the optical behavior of the component using its "
+                "SAX model. Returns S-parameters showing how light propagates "
+                "through the component's ports. Use this to analyze component "
+                "performance before fabrication. Supports customizing both layout "
+                "parameters (e.g., {'length_mmi': 12, 'gap_mmi': 0.3}) and SAX "
+                "model simulation settings (e.g., {'wl': [1.5, 1.55, 1.6], 'loss': 0.2})."
+            ),
+            inputSchema=add_project_param(
+                {
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": (
+                                "Name of the component/cell to simulate. The component "
+                                "must have a SAX model defined."
+                            ),
+                        },
+                        "layout": {
+                            "type": "object",
+                            "description": (
+                                "Optional component-specific geometric parameters. "
+                                "Use this to customize the component's physical dimensions "
+                                "before simulation. Example: {'length_mmi': 12, 'gap_mmi': 0.3}. "
+                                "Default is empty (use default layout parameters)."
+                            ),
+                        },
+                        "model": {
+                            "type": "object",
+                            "description": (
+                                "Optional SAX simulation settings. Use this to configure "
+                                "simulation parameters like wavelength sweeps or loss values. "
+                                "Example: {'wl': [1.5, 1.55, 1.6], 'loss': 0.2}. "
+                                "Default is empty (use default model parameters)."
+                            ),
+                        },
+                        "how": {
+                            "type": "string",
+                            "enum": ["from_layout", "from_netlist"],
+                            "description": (
+                                "Simulation method. 'from_layout' simulates from the physical "
+                                "layout geometry (default). 'from_netlist' simulates from the "
+                                "hierarchical netlist representation."
+                            ),
+                        },
+                    },
+                    "required": ["name"],
+                }
+            ),
+        )
+
+    @property
+    def mapping(self) -> EndpointMapping:
+        return EndpointMapping(method="POST", path="/api/sax/{name}/simulate")
+
+    def transform_request(self, args: dict[str, Any]) -> dict[str, Any]:
+        """Transform simulate_component MCP args to FastAPI request body.
+
+        Supports both new SAX API (/api/sax/{name}/simulate) and falls back
+        to old API (/api/simulate) if the new endpoint returns 404.
+
+        Args:
+            args: MCP tool arguments
+
+        Returns:
+            Dict with 'path', 'json_data' for new API and fallback data for old API
+        """
+        name = args["name"]
+        layout = args.get("layout", {})
+        model = args.get("model", {})
+        how = args.get("how", "from_layout")
+
+        return {
+            "path": f"/api/sax/{name}/simulate",
+            "json_data": {
+                "layout": layout,
+                "model": model,
+                "from_netlist": how == "from_netlist",
+            },
+            "fallback_path": "/api/simulate",
+            "fallback_json_data": {
+                "name": name,
+                "layout": layout,
+                "model": model,
+                "how": how,
+            },
+        }
+
+    def transform_response(self, response: Any) -> dict[str, Any]:
+        """Transform simulate_component response for LLM consumption.
+
+        Returns only the file path and token estimate instead of the full
+        S-parameter data, which can be extremely large (500k+ tokens).
+
+        Args:
+            response: FastAPI response containing simulation results
+
+        Returns:
+            Dict with file path, token estimate, and metadata
+        """
+        if not isinstance(response, dict):
+            return {"error": f"Unexpected response type: {type(response).__name__}"}
+
+        # Estimate tokens (rough heuristic: ~4 chars per token)
+        json_str = json.dumps(response)
+        estimated_tokens = len(json_str) // 4
+
+        file_path = response.get("file_path")
+
+        return {
+            "file_path": file_path,
+            "estimated_tokens": estimated_tokens,
+            "message": f"Simulation complete. Results saved to: {file_path}",
+            "note": "Use the Read tool to view the simulation results at this path.",
+            "simulation_id": response.get("simulation_id"),
+            "cached": response.get("cached", False),
+        }

gfp_mcp/utils.py

@@ -0,0 +1,55 @@
+"""Common utilities for MCP server.
+
+This module provides shared utility functions used across the MCP server,
+including file polling and other async helpers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from pathlib import Path
+
+__all__ = ["wait_for_gds_file"]
+
+logger = logging.getLogger(__name__)
+
+
+async def wait_for_gds_file(
+    gds_path: Path,
+    timeout: float = 30.0,
+    poll_interval: float = 0.5,
+    min_age: float = 0.1,
+) -> bool:
+    """Poll for GDS file to be created with timeout.
+
+    This function waits for a GDS file to exist and be stable (not actively
+    being written to) before returning. Useful for waiting on build operations.
+
+    Args:
+        gds_path: Path to the expected GDS file
+        timeout: Maximum time to wait in seconds (default: 30.0)
+        poll_interval: Time between polls in seconds (default: 0.5)
+        min_age: Minimum file age in seconds to ensure write is complete (default: 0.1)
+
+    Returns:
+        True if file exists and is ready, False if timeout reached
+    """
+    start_time = time.monotonic()
+    logger.debug("Waiting for GDS file: %s (timeout: %.1fs)", gds_path, timeout)
+
+    while time.monotonic() - start_time < timeout:
+        if gds_path.exists():
+            file_age = time.time() - gds_path.stat().st_mtime
+            if file_age >= min_age:
+                logger.debug("GDS file ready: %s (age: %.2fs)", gds_path, file_age)
+                return True
+            logger.debug(
+                "GDS file exists but too new (age: %.2fs), waiting...", file_age
+            )
+
+        await asyncio.sleep(poll_interval)
+
+    logger.warning("Timeout waiting for GDS file: %s", gds_path)
+    return False

{gfp_mcp-0.2.1.dist-info → gfp_mcp-0.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gfp-mcp
-Version: 0.2.1
+Version: 0.3.2
 Summary: Model Context Protocol (MCP) server for GDSFactory+ photonic IC design
 Author: GDSFactory+ Team
 License: MIT
@@ -27,19 +27,24 @@ License-File: LICENSE
 Requires-Dist: mcp>=1.7.1
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: typing-extensions>=4.0.0; python_version < "3.11"
+Requires-Dist: tomli>=2.0.0; python_version < "3.11"
 Requires-Dist: psutil>=5.9.0
+Provides-Extra: render
+Requires-Dist: klayout>=0.28.0; extra == "render"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: bump-my-version>=0.26.0; extra == "dev"
+Requires-Dist: build>=1.4.0; extra == "dev"
 Dynamic: license-file
 
 # GDSFactory+ MCP Server
 
 [![PyPI version](https://img.shields.io/pypi/v/gfp-mcp.svg)](https://pypi.org/project/gfp-mcp/)
 [![Python versions](https://img.shields.io/pypi/pyversions/gfp-mcp.svg)](https://pypi.org/project/gfp-mcp/)
-[![Tests](https://github.com/doplaydo/gfp-mcp/workflows/Tests/badge.svg)](https://github.com/doplaydo/gfp-mcp/actions)
+[![Tests](https://github.com/doplaydo/gfp-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/doplaydo/gfp-mcp/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 Model Context Protocol (MCP) server for GDSFactory+ that enables AI assistants like Claude to design and build photonic integrated circuits.
@@ -57,15 +62,32 @@ This MCP server connects AI assistants to [GDSFactory+](https://gdsfactory.com),
 
 ### 2. Install the MCP Server
 
+**With uv (recommended):**
+
+If you don't have `uv` installed, see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
 ```bash
-pip install gfp-mcp
+uv tool install gfp-mcp
 ```
 
-Or with uv:
+<details>
+<summary>Ephemeral approach</summary>
+
+Run without installing:
 
 ```bash
 uvx --from gfp-mcp gfp-mcp-serve
 ```
+</details>
+
+<details>
+<summary><strong>Alternative: pip install</strong></summary>
+
+```bash
+pip install gfp-mcp
+```
+
+</details>
 
 ### 3. Connect to Your AI Assistant
 
@@ -143,16 +165,23 @@ Try these commands with your AI assistant:
 
 ## Available Tools
 
-- **build_cell** - Build a single GDS cell by name
-- **build_cells** - Build multiple GDS cells in batch
+- **build_cells** - Build one or more GDS cells by name (pass a list, can be single-item)
 - **list_cells** - List all available photonic components
 - **get_cell_info** - Get detailed component metadata
-- **download_gds** - Download built GDS files
 - **list_projects** - List all running GDSFactory+ server instances
 - **get_project_info** - Get detailed information about a specific project
-- **check_drc** - Run Design Rule Check verification
+- **check_drc** - Run Design Rule Check verification (returns structured format with all violations including simplified location data for LLM-friendly troubleshooting)
 - **check_connectivity** - Run connectivity verification
 - **check_lvs** - Run Layout vs. Schematic verification
+- **simulate_component** - Run SAX circuit simulations with custom parameters
+  - Basic: `{"name": "mzi"}` - Simulate with default parameters
+  - Custom layout: `{"name": "mzi", "layout": {"length_mmi": 12, "gap_mmi": 0.3}}` - Customize component geometry
+  - Wavelength sweep: `{"name": "coupler", "model": {"wl": [1.5, 1.55, 1.6]}}` - Simulate at multiple wavelengths
+  - Full example: `{"name": "mzi", "layout": {"length": 100}, "model": {"wl": [1.5, 1.55, 1.6], "loss": 0.2}, "how": "from_layout"}`
+- **get_port_center** - Get physical coordinates of component ports
+- **generate_bbox** - Generate bounding box GDS from layout
+- **freeze_cell** - Freeze parametric cell as static netlist
+- **get_pdk_info** - Get current PDK information
 
 ## Multi-Project Support