gfp-mcp 0.1.0__py3-none-any.whl

gfp_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,360 @@
+Metadata-Version: 2.4
+Name: gfp-mcp
+Version: 0.1.0
+Summary: Model Context Protocol (MCP) server for GDSFactory+ photonic IC design
+Author: GDSFactory+ Team
+License: MIT
+Project-URL: Homepage, https://github.com/doplaydo/gfp-mcp
+Project-URL: Repository, https://github.com/doplaydo/gfp-mcp
+Project-URL: Documentation, https://github.com/doplaydo/gfp-mcp#readme
+Project-URL: Changelog, https://github.com/doplaydo/gfp-mcp/blob/main/CHANGELOG.md
+Project-URL: Issue Tracker, https://github.com/doplaydo/gfp-mcp/issues
+Keywords: mcp,gdsfactory,photonics,ic-design,eda,model-context-protocol,photonic-ic,gds
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+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: psutil>=5.9.0
+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"
+
+# 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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Model Context Protocol (MCP) server for GDSFactory+ that exposes photonic IC design operations as tools for AI assistants like Claude Code and Claude Desktop.
+
+## Overview
+
+This project implements a standalone MCP server that bridges AI assistants with GDSFactory+ photonic IC design capabilities. The server acts as a lightweight proxy that exposes GDSFactory+ operations through standardized MCP tools while maintaining zero modifications to the existing FastAPI backend.
+
+## Features
+
+### Phase 1: Core Building Tools (Complete)
+
+- **build_cell** - Build a single GDS cell by name
+- **build_cells** - Build multiple GDS cells in batch
+- **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
+
+### Multi-Project Support
+
+The MCP server integrates with the GDSFactory+ server registry to support working with multiple projects simultaneously. The registry is stored at `~/.gdsfactory/server-registry.json` and is automatically managed by GDSFactory+ servers.
+
+#### How It Works
+
+1. When you start a GDSFactory+ server with `gfp serve`, it registers itself in the shared registry
+2. The MCP server reads from this registry to discover available projects
+3. Tools accept an optional `project` parameter to route requests to specific servers
+4. The MCP server automatically resolves project names to the correct port
+
+#### Example Usage
+
+```
+User: "List all running GDSFactory+ projects"
+Claude: [Uses list_projects tool to show all registered servers]
+
+User: "Build the mzi component in the my_photonics_project"
+Claude: [Uses build_cell tool with project="my_photonics_project"]
+```
+
+**Note**: The MCP has read-only access to the registry. Only GDSFactory+ servers can register/unregister themselves.
+
+### Architecture
+
+```
+AI Assistant (Claude) <-> MCP Server (STDIO) <-> HTTP Client <-> FastAPI Server
+```
+
+**Key Benefits:**
+- Universal MCP client compatibility via STDIO transport
+- Zero modifications to existing FastAPI server
+- Clean separation of concerns
+- No database conflicts (only FastAPI touches SQLite)
+- Scalable architecture ready for 20+ tools
+
+## Installation
+
+### From PyPI (Recommended)
+
+Install the package from PyPI:
+
+```bash
+pip install gfp-mcp
+```
+
+Or with uv:
+
+```bash
+uv pip install gfp-mcp
+```
+
+### From Source (Development)
+
+For development or if you want the latest unreleased changes:
+
+```bash
+git clone https://github.com/doplaydo/gfp-mcp.git
+cd gfp-mcp
+pip install -e ".[dev]"
+```
+
+### Prerequisites
+
+- Python 3.10 or higher
+- GDSFactory+ with FastAPI server running
+
+### Verify Installation
+
+```bash
+gfp-mcp-serve --help
+```
+
+## Quick Start
+
+### 1. Start the FastAPI Server
+
+In one terminal:
+
+```bash
+gfp serve --port 8787
+```
+
+### 2. Configure Your AI Assistant
+
+#### Claude Code
+
+Add to `.claude/settings.json`:
+
+```json
+{
+    "mcpServers": {
+        "gdsfactoryplus": {
+            "command": "gfp-mcp-serve",
+            "args": [],
+            "env": {
+                "GFP_API_URL": "http://localhost:8787"
+            }
+        }
+    }
+}
+```
+
+Or use the command line:
+
+```bash
+claude mcp add gdsfactoryplus -- gfp-mcp-serve
+```
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+    "mcpServers": {
+        "gdsfactoryplus": {
+            "command": "gfp-mcp-serve",
+            "args": []
+        }
+    }
+}
+```
+
+For Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+For Linux: `~/.config/Claude/claude_desktop_config.json`
+
+### 3. Use the Tools
+
+Ask your AI assistant to:
+
+- "List all available photonic components"
+- "Build the mzi component"
+- "Show me details about the coupler component"
+- "Build multiple components: mzi, coupler, and bend_euler"
+
+## Environment Variables
+
+Configure the MCP server using environment variables:
+
+```bash
+# FastAPI server URL (default: http://localhost:8787)
+export GFP_API_URL="http://localhost:8787"
+
+# Request timeout in seconds (default: 300)
+export GFP_MCP_TIMEOUT=300
+
+# Enable debug logging (default: false)
+export GFP_MCP_DEBUG=true
+```
+
+## Project Structure
+
+```
+gfp-mcp/
+├── mcp_standalone/          # MCP server implementation
+│   ├── __init__.py         # Package exports
+│   ├── config.py           # Configuration management
+│   ├── client.py           # HTTP client for FastAPI
+│   ├── registry.py         # Server registry (multi-project support)
+│   ├── tools.py            # MCP tool definitions
+│   ├── mappings.py         # Tool → Endpoint mappings
+│   ├── server.py           # MCP server core
+│   └── README.md           # Detailed documentation
+├── tests/                  # Test suite
+│   ├── test_mcp_tools.py
+│   ├── test_mcp_mappings.py
+│   ├── test_mcp_integration.py
+│   └── test_registry.py
+├── mcp_serve.py            # CLI entry point
+├── MCP_QUICKSTART.md       # Quick start guide
+├── MCP_IMPLEMENTATION_STATUS.md  # Implementation details
+└── README.md               # This file
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Run all MCP tests
+pytest tests/test_mcp_*.py -v
+
+# Run with coverage
+pytest tests/test_mcp_*.py --cov=mcp_standalone --cov-report=term-missing
+
+# Run specific test file
+pytest tests/test_mcp_tools.py -v
+```
+
+All tests are passing (46/46 tests):
+- Tool definitions: 15 tests
+- Endpoint mappings: 13 tests
+- Integration & client: 9 tests
+- Registry integration: 9 tests
+
+## Example Workflows
+
+### Build and Verify a Component
+
+```
+User: "List all available photonic components"
+Claude: [Uses list_cells tool]
+
+User: "Build the mzi component"
+Claude: [Uses build_cell tool with name="mzi"]
+
+User: "Show me the details of the mzi component"
+Claude: [Uses get_cell_info tool with name="mzi"]
+```
+
+### Batch Build Multiple Components
+
+```
+User: "Build the following components: mzi, coupler, and bend_euler"
+Claude: [Uses build_cells tool with names=["mzi", "coupler", "bend_euler"]]
+```
+
+## Troubleshooting
+
+### Error: "Connection refused to localhost:8787"
+
+**Cause**: FastAPI server is not running
+
+**Solution**: Start the FastAPI server:
+
+```bash
+gfp serve --port 8787
+```
+
+### Error: "MCP server not responding"
+
+**Cause**: STDIO transport issue or MCP client misconfiguration
+
+**Solution**:
+1. Check Claude Code/Desktop logs with `claude --debug`
+2. Restart the MCP server
+3. Verify the configuration in settings.json
+
+### Error: "Tool execution timeout"
+
+**Cause**: Long-running operation exceeded timeout
+
+**Solution**: Increase the timeout:
+
+```bash
+export GFP_MCP_TIMEOUT=600  # 10 minutes
+gfp mcp-serve
+```
+
+## Roadmap
+
+### Future Phases
+
+- **Phase 2**: Verification tools (DRC, LVS)
+- **Phase 3**: SPICE workflow tools
+- **Phase 4**: Simulation & advanced tools
+- **Phase 5**: Comprehensive testing & documentation
+
+## Documentation
+
+- [Quick Start Guide](MCP_QUICKSTART.md) - Step-by-step setup instructions
+- [Implementation Status](MCP_IMPLEMENTATION_STATUS.md) - Detailed implementation notes
+- [MCP Standalone README](mcp_standalone/README.md) - Architecture details
+- [Contributing Guide](CONTRIBUTING.md) - Development and release guidelines
+- [Changelog](CHANGELOG.md) - Version history and release notes
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:
+
+- Development setup
+- Running tests and code quality checks
+- Making changes and submitting PRs
+- Release process (for maintainers)
+
+Quick checklist:
+
+1. All tests pass: `pytest tests/test_mcp_*.py -v`
+2. Code quality: `ruff check . && ruff format --check .`
+3. Documentation is updated
+4. Changes are backward compatible
+
+## License
+
+See the main GDSFactory+ project for license information.
+
+## Support
+
+For issues or questions:
+
+1. Check the [Quick Start Guide](MCP_QUICKSTART.md) troubleshooting section
+2. Review the [Implementation Status](MCP_IMPLEMENTATION_STATUS.md) document
+3. Enable debug mode with `GFP_MCP_DEBUG=true` and check server logs
+4. Open an issue on GitHub
+
+## Acknowledgments
+
+Built on the Model Context Protocol by Anthropic, enabling seamless AI assistant integration with photonic IC design workflows.

gfp_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mcp_standalone/__init__.py,sha256=7PhYozHyiRK_oFui0RkF5GJWxA2OZoWVcU_-ESfHIR4,953
+mcp_standalone/client.py,sha256=gUs9m2M27OP-GYmJ9fkojyxv212ETVJFqp0v2uN8Q2c,8205
+mcp_standalone/config.py,sha256=zr2LnI_wNEcMWrnB_WLscR-skkXjE33ZPBtK08XjaX0,1386
+mcp_standalone/mappings.py,sha256=jXEHwSrSYNDuVeMRM2dsSUsr38CzrHBLoe6exkJhqvc,7695
+mcp_standalone/registry.py,sha256=1E61UalVot8HUS3cALjM7ejYB0qR6tI5QbQSZZeQe7Y,6401
+mcp_standalone/server.py,sha256=Celd9j0KY1Fl_Qw09b9Px03vGhtaTUac2ozlYdGJ23A,7100
+mcp_standalone/tools.py,sha256=__j9N396-cJj9CKi6EAdP5_J-xESrbRZG35KNzdszXM,12349
+gfp_mcp-0.1.0.dist-info/METADATA,sha256=dVk1r3JfmlEY3RcqVSDqMLYm2fPAqwYjM4cTUD6sVQE,10442
+gfp_mcp-0.1.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+gfp_mcp-0.1.0.dist-info/entry_points.txt,sha256=mgyus9dsB_8mjgnztuHNPqzPi-7HcPg1iYzfM5NMIjk,61
+gfp_mcp-0.1.0.dist-info/top_level.txt,sha256=g2hRJHoDDPNtrNdXR70T7FR9Ev6DTRJiGW7ZvlvnXMc,15
+gfp_mcp-0.1.0.dist-info/RECORD,,

gfp_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gfp_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gfp-mcp-serve = mcp_standalone.server:main

gfp_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_standalone

mcp_standalone/__init__.py

@@ -0,0 +1,39 @@
+"""MCP Standalone Server for GDSFactory+.
+
+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)
+- STDIO transport for universal compatibility
+- HTTP proxy to FastAPI backend
+- Zero changes to existing FastAPI server
+- No database conflicts (only FastAPI touches SQLite)
+
+Usage:
+    from gdsfactoryplus.mcp_standalone import main
+    main()
+
+Or via CLI:
+    gfp mcp-serve
+"""
+
+from __future__ import annotations
+
+from .client import FastAPIClient
+from .config import MCPConfig
+from .server import create_server, main, run_server
+from .tools import get_all_tools, get_tool_by_name
+
+__all__ = [
+    "FastAPIClient",
+    "MCPConfig",
+    "create_server",
+    "main",
+    "run_server",
+    "get_all_tools",
+    "get_tool_by_name",
+]
+
+__version__ = "0.1.0"

mcp_standalone/client.py

@@ -0,0 +1,268 @@
+"""HTTP client wrapper for communicating with FastAPI backend."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+from typing import Any
+
+import httpx
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+from .config import MCPConfig
+from .registry import ServerRegistry
+
+__all__ = ["FastAPIClient"]
+
+logger = logging.getLogger(__name__)
+
+
+class FastAPIClient:
+    """Async HTTP client for FastAPI backend.
+
+    Handles connection pooling, retries, and error handling for
+    communication with the GDSFactory+ FastAPI server.
+
+    Supports multi-project routing via the server registry.
+    """
+
+    def __init__(self, base_url: str | None = None) -> None:
+        """Initialize the FastAPI client.
+
+        Args:
+            base_url: Base URL for the FastAPI server (default from config)
+                     If not provided, will use project-based routing via registry
+        """
+        self.base_url = base_url or MCPConfig.get_api_url(None)
+        self.timeout = MCPConfig.get_timeout()
+        self._client: httpx.AsyncClient | None = None
+        self._registry = ServerRegistry()
+
+    async def __aenter__(self) -> Self:
+        """Enter async context."""
+        await self.start()
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Exit async context."""
+        await self.close()
+
+    async def start(self) -> None:
+        """Start the HTTP client with connection pooling."""
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=httpx.Timeout(self.timeout),
+                limits=httpx.Limits(max_keepalive_connections=5, max_connections=10),
+            )
+            logger.debug("HTTP client started with base URL: %s", self.base_url)
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+            logger.debug("HTTP client closed")
+
+    def _resolve_base_url(self, project: str | None = None) -> str:
+        """Resolve the base URL for a request.
+
+        Args:
+            project: Optional project name/path to route to specific server
+
+        Returns:
+            Base URL for the request
+
+        Raises:
+            ValueError: If project not found in registry
+        """
+        # If no project specified, use default base_url
+        if project is None:
+            return self.base_url
+
+        # Look up project in registry
+        server_info = self._registry.get_server_by_project(project)
+        if server_info is None:
+            msg = (
+                f"Project '{project}' not found in registry. "
+                "Make sure the server is running for this project."
+            )
+            raise ValueError(msg)
+
+        return f"http://localhost:{server_info.port}"
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        params: dict[str, Any] | None = None,
+        json_data: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        project: str | None = None,
+    ) -> Any:
+        """Make an HTTP request with retry logic.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: API endpoint path
+            params: Query parameters
+            json_data: JSON body data
+            data: Form data
+            project: Optional project name to route to specific server
+
+        Returns:
+            Response data (parsed JSON or raw content)
+
+        Raises:
+            httpx.HTTPError: If request fails after retries
+            ValueError: If project not found in registry
+        """
+        if self._client is None:
+            await self.start()
+
+        # Resolve the base URL for this request
+        base_url = self._resolve_base_url(project)
+
+        last_error = None
+        backoff = MCPConfig.RETRY_BACKOFF
+
+        for attempt in range(MCPConfig.MAX_RETRIES):
+            try:
+                logger.debug(
+                    "Request attempt %d/%d: %s %s (project=%s, base=%s)",
+                    attempt + 1,
+                    MCPConfig.MAX_RETRIES,
+                    method,
+                    path,
+                    project or "default",
+                    base_url,
+                )
+
+                # Build full URL with the resolved base URL
+                full_url = f"{base_url}{path}"
+
+                response = await self._client.request(  # type: ignore[union-attr]
+                    method=method,
+                    url=full_url,
+                    params=params,
+                    json=json_data,
+                    data=data,
+                )
+                response.raise_for_status()
+
+                # Try to parse JSON, fall back to text
+                try:
+                    return response.json()
+                except (ValueError, TypeError):
+                    return response.text
+
+            except httpx.HTTPError as e:
+                last_error = e
+                logger.warning("Request failed (attempt %d): %s", attempt + 1, e)
+
+                # Don't retry on client errors (4xx)
+                if (
+                    isinstance(e, httpx.HTTPStatusError)
+                    and 400 <= e.response.status_code < 500
+                ):
+                    raise
+
+                # Exponential backoff for retries
+                if attempt < MCPConfig.MAX_RETRIES - 1:
+                    await asyncio.sleep(backoff)
+                    backoff *= 2
+
+        # All retries failed
+        logger.error("All %d attempts failed", MCPConfig.MAX_RETRIES)
+        raise last_error  # type: ignore[misc]
+
+    async def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        """Make a GET request.
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+
+        Returns:
+            Response data
+        """
+        return await self.request("GET", path, params=params)
+
+    async def post(
+        self,
+        path: str,
+        json_data: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> Any:
+        """Make a POST request.
+
+        Args:
+            path: API endpoint path
+            json_data: JSON body data
+            data: Form data
+
+        Returns:
+            Response data
+        """
+        return await self.request("POST", path, json_data=json_data, data=data)
+
+    async def health_check(self, project: str | None = None) -> bool:
+        """Check if the FastAPI server is reachable.
+
+        Args:
+            project: Optional project name to check specific server
+
+        Returns:
+            True if server is healthy, False otherwise
+        """
+        try:
+            await self.request("GET", "/health", project=project)
+        except Exception:
+            logger.exception("FastAPI server health check failed")
+            return False
+        else:
+            base_url = self._resolve_base_url(project)
+            logger.info("FastAPI server is healthy at %s", base_url)
+            return True
+
+    def list_projects(self) -> list[dict[str, Any]]:
+        """List all active projects from the registry.
+
+        Returns:
+            List of project information dictionaries
+        """
+        servers = self._registry.list_servers()
+        return [
+            {
+                "project_name": server.project_name,
+                "project_path": server.project_path,
+                "port": server.port,
+                "pid": server.pid,
+                "pdk": server.pdk,
+                "started_at": server.started_at,
+            }
+            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)