Metadata-Version: 2.4
Name: gfp-mcp
Version: 0.3.2
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
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/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.

## What is this?

This MCP server connects AI assistants to [GDSFactory+](https://gdsfactory.com), allowing you to design photonic ICs through natural language. Build components, run verification checks, and manage multiple projects directly from Claude Code or Claude Desktop.

## Quick Start

### 1. Install Prerequisites

- Python 3.10 or higher
- VSCode with the [GDSFactory+ extension](https://marketplace.visualstudio.com/items?itemName=gdsfactory.gdsfactoryplus) installed

### 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
uv tool install gfp-mcp
```

<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

<details>
<summary><strong>Claude Code</strong></summary>

Add to `.claude/settings.json`:

```json
{
    "mcpServers": {
        "gdsfactoryplus": {
            "command": "gfp-mcp-serve",
            "args": [],
            "env": {
                "GFP_API_URL": "http://localhost:8787"
            }
        }
    }
}
```

Or use the CLI:

```bash
claude mcp add gdsfactoryplus -- gfp-mcp-serve
```

</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

Add to your config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
    "mcpServers": {
        "gdsfactoryplus": {
            "command": "gfp-mcp-serve",
            "args": []
        }
    }
}
```

Restart Claude Desktop after adding the configuration.

</details>

<details>
<summary><strong>Cursor</strong></summary>

Coming soon. Follow the MCP integration instructions for Cursor when available.

</details>

### 4. Start Designing

The MCP server automatically discovers running GDSFactory+ servers via the registry (`~/.gdsfactory/server-registry.json`). On startup, it will log all discovered projects.

Try these commands with your AI assistant:

- "List all available photonic components"
- "Build an MZI interferometer"
- "Show me details about the directional coupler"
- "Build multiple components: mzi, coupler, and bend_euler"
- "List all my GDSFactory+ projects"

## Available Tools

- **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
- **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 (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

The MCP server automatically discovers all running GDSFactory+ projects via the server registry (`~/.gdsfactory/server-registry.json`). The registry is the source of truth for available servers. Use the `list_projects` tool to see all running projects, then specify the project name when building components:

```
User: "List all my GDSFactory+ projects"
Claude: [Uses list_projects tool to show all running servers]

User: "Build the mzi component in my_photonics_project"
Claude: [Routes request to the correct project]
```

## Troubleshooting

<details>
<summary><strong>Server not appearing in Claude</strong></summary>

1. Verify installation: `gfp-mcp-serve --help`
2. Check Claude Code logs: `claude --debug`
3. Restart Claude Desktop/Code
4. Ensure the GDSFactory+ VSCode extension is active and a project is open

</details>

<details>
<summary><strong>Connection refused errors</strong></summary>

The MCP server uses the registry (`~/.gdsfactory/server-registry.json`) to discover running servers.

1. Use the `list_projects` tool in Claude to check available servers
2. If no servers are found, ensure the GDSFactory+ VSCode extension is running with an active project:
   - Open VSCode with the GDSFactory+ extension installed
   - Open a GDSFactory+ project folder
   - The extension automatically starts the server and registers it
3. Check the MCP startup logs for discovered servers
4. Verify the registry is accessible at `~/.gdsfactory/server-registry.json`
5. For backward compatibility, you can set a specific server URL:

```bash
export GFP_API_URL="http://localhost:YOUR_PORT"
```

</details>

<details>
<summary><strong>Tool execution timeout</strong></summary>

Increase the timeout for long-running operations:

```bash
export GFP_MCP_TIMEOUT=600  # 10 minutes
```

</details>
