Metadata-Version: 2.4
Name: synthpilot
Version: 1.4.0
Summary: Platform-scoped FPGA development tools for Vivado, Anlogic TD, and Quartus
Project-URL: Homepage, https://synthpilot.dev
Author: Xiaochuan
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Keywords: ai,anlogic,eda,fpga,mcp,quartus,vivado
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# SynthPilot

**Let AI build your FPGA designs.**

SynthPilot is an MCP (Model Context Protocol) server that gives AI assistants full control over AMD Vivado. **510 Vivado tools** cover the entire FPGA development flow — project management, synthesis, implementation, timing analysis, IP configuration, Block Design, simulation, debug, and device programming.

## Quick Start

```bash
# Install
pip install synthpilot

# Activate your free license
synthpilot activate YOUR-LICENSE-KEY

# Set up Vivado integration
synthpilot install

# Done! Open Vivado → start chatting with AI
```

Activation verifies the new key before atomically replacing the user config;
failed verification preserves the working key. `SYNTHPILOT_LICENSE` takes
precedence over the user config and must be unset before changing or
deactivating the persisted credential.

## Update

```bash
# pip
pip install --upgrade synthpilot

# uvx (always pulls latest)
uvx synthpilot@latest --version
```

## MCP Configuration

**Claude Desktop / Claude Code / Cursor:**

```json
{
  "mcpServers": {
    "synthpilot": {
      "command": "synthpilot"
    }
  }
}
```

Or with `uvx` (requires [uv](https://docs.astral.sh/uv/)):

```json
{
  "mcpServers": {
    "synthpilot": {
      "command": "uvx",
      "args": ["synthpilot@latest"]
    }
  }
}
```

At MCP startup, SynthPilot verifies the license and registers only the selected
platform tools included in that Free, Pro, Trial, or Max entitlement. Locked
tool schemas are not advertised to the AI client. The plan is never selected by
an MCP or CLI argument; restart the MCP process after a license change to refresh
its stable tool list.

The single installed package uses one local MCP name, `synthpilot`; the startup
`--platform` argument selects Vivado, Anlogic, or Quartus, while the verified
license selects the entitlement. Repository-specific configuration does not
require another package:

```bash
# Codex supports user/project; Claude Code supports user/project/local.
synthpilot install-mcp --client codex --platform quartus --scope project
synthpilot install-mcp --client claude_code --platform anlogic --scope local
```

Omitting `--scope` keeps user scope. Codex project entries are written to
`.codex/config.toml`; Claude Code registration uses its official scoped CLI.
Claude Desktop and Cursor remain user-scope clients. An incompatible mixed
scope request is rejected before any client config changes.

## Unified Codex and Claude workflow plugin

The package includes one optional skills-only plugin shared by Codex and
Claude Code. It provides setup, Vivado, Anlogic, and Quartus workflows without
starting a duplicate MCP server:

```bash
synthpilot plugin export ./synthpilot-plugin-bundle
codex plugin marketplace add ./synthpilot-plugin-bundle
codex plugin add synthpilot@synthpilot-local
claude plugin marketplace add ./synthpilot-plugin-bundle
claude plugin install synthpilot@synthpilot-local --scope user
```

Use `install-mcp` separately to select the repository's platform. Disabling or
uninstalling the plugin removes workflow prompts only; the CLI and direct MCP
entry remain available. The included manifests are a local U2 distribution
and have not been submitted to a public marketplace.

## Anlogic Tang Dynasty

The Windows Anlogic profile runs a managed `td_commands_prompt.exe` process and
exposes 98 structured TD tools for analysis, constraints, deterministic builds,
and advanced flows. Register or start the platform-scoped server with:

```bash
synthpilot install-mcp --platform anlogic
synthpilot --platform anlogic
```

The complete Anlogic server has 102 tools: 4 on Free, 90 on Pro/Trial, and all
102 on Max. Raw TD Tcl execution is hidden from every plan. A representative
Windows TD 6.2.1 source flow and a fresh, receipt-bound onefile passed project
creation, source/top registration, bitstream generation, close/reopen
persistence, active cancellation, client disconnect, and zero-residual-process
checks. Comprehensive A2/A3/A5 query, constraint, and advanced-command live
matrices and TD 6.2.2-only command validation remain pending; 6.2.2-only
commands fail closed on older versions.

## Intel/Altera Quartus

The Windows and Linux Quartus profile provides a managed `quartus_sh -s`
bridge, five connection/version/capability diagnostics, and nine read-only
project-status, device, report-panel, Fitter-resource, assignment, and compiled
design-name tools, plus one-file existing-HDL source registration, one fixed
top-level-entity setter, no-overwrite project creation, existing-project entry,
and four managed build start/status/log/cancel tools:

```bash
synthpilot setup --platform quartus
synthpilot install-mcp --platform quartus
synthpilot --platform quartus
```

The complete Quartus server has 24 tools: 6 on Free and all 24 on Pro, Trial,
and Max. Setup and doctor only perform bounded `quartus_sh --version` discovery
and do not leave a persistent shell running, create or open a project, or start
a build. For an existing project, use `quartus_open_project`, run Q2 read-only queries, start a build, poll its
status/log until terminal, then call `quartus_close_project`. Compiled-project report/resource
and assignment-query matrices have passed on Windows Lite 25.1. The feature-frozen
clean-session create/source/top-level/Fit/report/close-reopen workflow and
managed build lifecycle have also passed on Lite 25.1. Build jobs are server-bound:
disconnecting the MCP server cancels the active job, and jobs do not survive a
server restart. Standard, Pro, Linux, and packaged lifecycle acceptance remain
pending. `quartus_create_project` creates and opens
an empty project without overwrite and can set its family/part.
`quartus_add_source_file` registers one existing `.v`, `.sv`, `.vhd`, or `.vhdl`
file beneath the managed project per call without creating, copying, editing,
replacing, or deleting source content. `quartus_set_top_level_entity` changes
only the fixed `TOP_LEVEL_ENTITY` field; generic project configuration and
post-create device retargeting are not exposed. The feature-frozen clean-session
workflow is create, add sources one at a time, set top level, build/poll, inspect
reports, and close/reopen. Windows Lite 25.1 live validation is complete;
onefile normal/forced-disconnect and cross-platform/edition validation remain
RC gates. Q4 capabilities are deferred until after the RC decision.
Raw Quartus Tcl is hidden from every plan.

## Features

| | Free | Pro | Max |
|---|---|---|---|
| **Tools** | 43 | 475 | All 510 |
| **Project & Synthesis** | ✅ | ✅ | ✅ |
| **IP Config & Block Design** | — | ✅ | ✅ |
| **Simulation & Debug** | — | ✅ | ✅ |
| **Custom Tcl & Non-Project** | — | — | ✅ |
| **Devices** | 1 | 2 | 3 |

## Requirements

- Python 3.10+

Platform support is capability-specific:

| Target | Current acceptance status |
|---|---|
| Windows x64 package | Primary release target; fresh onefile, wheel, upgrade, and forced-disconnect acceptance are RC gates |
| Linux x86_64 package | `manylinux_2_17` packaging target; fresh package and process-lifecycle acceptance are RC gates |
| Local AMD Vivado | Windows, Vivado 2018.1+ |
| Remote Vivado over SSH | Implemented for a remote Linux profile; end-to-end R2 live acceptance remains pending |
| Anlogic Tang Dynasty | Windows-only execution; a TD 6.2.1 representative bitstream flow and fresh onefile lifecycle passed, while comprehensive A2/A3/A5 and TD 6.2.2-only live matrices remain pending |
| Intel Quartus | Backend is available on Windows and Linux; the source workflow is live-tested on Windows Lite 25.1, while packaged, Linux, Standard, and Pro acceptance remain pending |

Pending entries are not claims of completed vendor or packaged validation. The
[platform acceptance ledger](https://github.com/LNC0831/SynthPilot/blob/master/docs/PLATFORM_ACCEPTANCE.md)
records exact passed/deferred scope; `docs/RC_ACCEPTANCE.md` defines release
gates.

## Links

- 📖 **Documentation:** [www.synthpilot.dev/docs.html](https://www.synthpilot.dev/docs.html)
- 🆓 **Get Free License:** [www.synthpilot.dev](https://www.synthpilot.dev)
- 📧 **Support:** support@synthpilot.dev
- 📋 **Issues:** [GitHub Issues](https://github.com/LNC0831/SynthPilot/issues)
