fpga-mcp 0.1.0__tar.gz

fpga_mcp-0.1.0/.dockerignore

@@ -0,0 +1,80 @@
+# Version control
+.git
+.gitignore
+.github/
+
+# Python build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+pip-wheel-metadata/
+
+# Test caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+ENV/
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# CI / local state
+*.log
+*.tmp
+*.bak
+.cache/
+node_modules/
+
+# Local config that might leak secrets / paths
+*.env
+.env
+config.local.json
+fpga-mcp-config.local.json
+
+# Local project outputs — should not bake into the image
+out/
+*.xpr
+*.qpf
+*.qsf
+*.al
+*.bit
+*.ltx
+*.sof
+*.rpt
+*.log.*
+
+# Examples are useful for documentation but add weight; keep them out
+# of the runtime image (the README links to the repo for browsing).
+examples/
+
+# Docs are baked into the wheel via the README; no need for source.
+docs/
+*.md
+!README.md
+
+# Scripts are dev-only.
+scripts/
+
+# Tests are dev-only — wheel doesn't ship them.
+tests/
+
+# The Tcl + methodology directories ARE included because they're needed
+# at runtime by the MCP server (see pyproject.toml force-include). Keep
+# them — do NOT add `tcl/` or `methodology/` here.

fpga_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,46 @@
+---
+name: Bug report
+about: Something is broken or behaves unexpectedly
+title: "[bug] "
+labels: bug
+---
+
+## What happened?
+
+<!-- Short description of the problem. -->
+
+## What did you expect?
+
+<!-- What you thought would happen. -->
+
+## How to reproduce
+
+```bash
+# Exact commands / MCP tool calls that trigger the bug.
+fpga-mcp version
+fpga-mcp ...
+```
+
+Steps:
+
+1.
+2.
+3.
+
+## Environment
+
+- `fpga-mcp` version: <!-- run `fpga-mcp version` and paste the line -->
+- Python:
+- OS (Windows / Linux / macOS + version):
+- EDA tool + version (Vivado / Quartus / TangDynasty, if relevant):
+- Tcl server started? (yes / no / n/a)
+
+## Logs / output
+
+```
+Paste the relevant traceback, log snippet, or MCP tool output here.
+```
+
+## Anything else?
+
+<!-- Workarounds you tried, related issues, etc. -->

fpga_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Discussions
+    url: https://github.com/wmm246/fpga-mcp/discussions
+    about: Ask questions, share flows, or discuss methodology patterns here.
+  - name: MCP specification
+    url: https://modelcontextprotocol.io
+    about: Read the Model Context Protocol spec when in doubt about MCP semantics.

fpga_mcp-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,34 @@
+---
+name: Feature request
+about: Suggest a new tool, vendor, prompt or behaviour
+title: "[feature] "
+labels: enhancement
+---
+
+## What's missing?
+
+<!-- What can't you do today that you wish you could? -->
+
+## Proposed solution
+
+<!-- Sketch the API / tool name / prompt behaviour you'd like. -->
+
+```python
+# Example: a new tool
+create_ip_xxx(name="clk_wiz", ...)
+```
+
+## Which vendor(s)?
+
+- [ ] Vivado
+- [ ] Quartus
+- [ ] Anlogic
+- [ ] Common (vendor-agnostic)
+
+## Alternatives you considered
+
+<!-- Are you using `exec_tcl` today as a workaround? Any other toolchain? -->
+
+## Anything else?
+
+<!-- Related issues, prior art, links to vendor docs, etc. -->

fpga_mcp-0.1.0/.github/ISSUE_TEMPLATE/new_vendor.md

@@ -0,0 +1,39 @@
+---
+name: New vendor support
+about: Request support for a new FPGA vendor / toolchain
+title: "[vendor] "
+labels: enhancement, vendor
+---
+
+## Vendor
+
+- Name: <!-- e.g. Gowin / Lattice Diamond / Microsemi Libero -->
+- Tool binary: <!-- e.g. `gowin` / `diamond` / `libero` -->
+- Tcl scripting entry point: <!-- how do you open a Tcl shell? -->
+
+## Tool list you'd like covered
+
+<!-- Approximate tool count + which categories. The existing catalogues are
+     ~150-350 specs per vendor; you don't need to enumerate every command,
+     but the categories help us scope the work. -->
+
+- [ ] Project lifecycle (create/open/close, add sources, set top)
+- [ ] Synthesis & implementation runs
+- [ ] IP / block design
+- [ ] Constraints (timing / physical)
+- [ ] Reports (timing / utilization / DRC)
+- [ ] Simulation
+- [ ] Hardware manager / programmer
+- [ ] Netlist queries
+- [ ] Other: <!-- describe -->
+
+## Tcl command samples
+
+```tcl
+# 3-5 representative Tcl commands from this vendor's documentation.
+# e.g. how do you create a project, run synthesis, generate a bitstream.
+```
+
+## Anything else?
+
+<!-- Link to vendor docs, sample Tcl scripts, etc. -->

fpga_mcp-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,41 @@
+## Summary
+
+<!-- One or two sentences: what does this PR change? -->
+
+## Motivation
+
+<!-- Why is this needed? Link issues with "Fixes #123" / "Closes #123". -->
+
+## What changed
+
+<!-- Bullet list of the main changes. -->
+
+- 
+- 
+- 
+
+## Checklist
+
+- [ ] `pytest` passes locally (`pip install -e '.[dev]' && pytest`)
+- [ ] `ruff check src tests` is clean
+- [ ] If new tool(s) added: spec lives in `src/fpga_mcp/tool_defs/<vendor>.py`
+      and follows the naming convention (`viv_` / `q_` / `a_` prefix, or no
+      prefix for common)
+- [ ] If new tool(s) added: `tests/test_tool_defs.py` catalogue invariants
+      still pass (no duplicate names, every spec has summary + category)
+- [ ] README / CHANGELOG updated if user-visible
+- [ ] No new dependencies unless discussed in the PR description
+
+## Test plan
+
+<!-- How did you verify this works? -->
+
+```bash
+# Commands you ran.
+pytest -k <pattern>
+ruff check src tests
+```
+
+## Screenshots / logs
+
+<!-- Optional. For UI or large output changes. -->

fpga_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,164 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
+  pull_request:
+    branches: [main, master]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+
+      - name: Lint (ruff)
+        run: ruff check src tests
+
+      - name: Test (pytest)
+        run: pytest -ra
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    # Build dist artifacts on every CI run so we catch packaging regressions
+    # early. The actual PyPI upload only happens on tag pushes (see `release`).
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build sdist + wheel
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  smoke:
+    # Cross-platform end-to-end smoke test: spin up the mock Tcl server
+    # three times (once per vendor) and drive each backend through a full
+    # create_project → add_sources → run_synthesis → report_timing flow.
+    # Catches OS-specific socket / encoding regressions that unit tests
+    # might miss.
+    needs: test
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+      - name: Run e2e smoke script
+        run: python scripts/smoke_e2e.py
+
+  examples:
+    # Run the verifiable example scripts end-to-end.
+    #   - timing_closure_demo: drives the broken → fix → re-verify loop,
+    #     asserts WNS_final >= 0.
+    #   - core_features_demo: drives every category of the EDABackend
+    #     contract (lifecycle, project, sources, synth, impl, IP, reports,
+    #     simulation, bitstream, programming, exec_tcl, session) through
+    #     the typed Python tools and asserts each one returns a
+    #     well-formed result. 14 phases; exits 0 only if all pass.
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+      - name: Run timing_closure_demo
+        run: python examples/timing_closure_demo/verify_timing_closure.py
+      - name: Run core_features_demo
+        run: python examples/core_features_demo/verify_core_features.py
+
+  docker:
+    # Build the Docker image. Doesn't push — push is handled by a
+    # separate workflow triggered on tag, or by maintainers manually.
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Build image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: false
+          load: true
+          tags: fpga-mcp:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - name: Smoke check the image
+        run: |
+          docker run --rm fpga-mcp:ci version
+          docker run --rm fpga-mcp:ci backends
+
+  release:
+    # Publish to PyPI when a `v*` tag is pushed. Requires two repo secrets:
+    #   PYPI_API_TOKEN  — a scoped PyPI upload token.
+    # Without these secrets the job is skipped silently (CI still passes).
+    needs: [build, smoke, examples, docker]
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: |
+          python -m pip install --upgrade pip
+          pip install twine
+          twine upload --skip-existing dist/*
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          draft: false
+          prerelease: ${{ contains(github.ref_name, 'rc') || contains(github.ref_name, 'beta') }}
+

fpga_mcp-0.1.0/.gitignore

@@ -0,0 +1,72 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+wheelhouse/
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# FPGA project artifacts
+*.xpr
+*.qpf
+*.qsf
+*.qar
+*.al
+*.alp
+*.bit
+*.bin
+*.ltx
+*.rpt
+*.log
+*.jou
+*.str
+*.summary
+*.pb
+*.bak
+Xilinx*/
+vivado_*/
+*.restore
+*_sim/
+*.wdb
+*.wcfg
+*.so
+*.so.*
+*.o
+*.obj
+*.tmp
+*.out
+
+# Project-local editor configs
+.claude/
+.cursor/

fpga_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial public release of `fpga-mcp`.
+- Multi-vendor EDA backend abstraction: Xilinx Vivado, Intel Quartus, Anlogic.
+- Vivado backend driven by a bundled Tcl TCP server (port 9999), similar in
+  spirit to SynthPilot but reimplemented from scratch and MIT-licensed.
+- Quartus backend driven by `quartus_sh -t` over a Tcl session.
+- Anlogic backend driven by the TangDynasty / TD CLI flow.
+- MCP server exposing project / synth / impl / IP / sim / bitstream / reports
+  tool groups, all parameterized by the active backend.
+- **689 declarative MCP tools** (vs. the original 22 hand-written tools):
+  - 22 high-level vendor-agnostic tools (`create_project`, `run_synthesis`,
+    `report_timing`, `exec_tcl`, …) routed to backend Python methods.
+  - 343 Vivado tools (`viv_*`) covering project/fileset, synth/impl runs,
+    IP/BD, constraints, timing reports, utilization/DRC, simulation,
+    hardware manager, debug cores, netlist queries and parts.
+  - 167 Quartus tools (`q_*`) covering project/flow, SDC/STA timing,
+    reports, IP/Qsys, power and EDA.
+  - 157 Anlogic TangDynasty tools (`a_*`) covering project/files, synth/impl,
+    IP, constraints, reports, netlist, simulation and programming.
+- Declarative `ToolSpec` catalogue + factory pattern: adding a tool = one
+  line in the right `tool_defs/<vendor>.py`. The factory builds the runtime
+  callable automatically, validates required args, and dispatches to either
+  a Python handler or a rendered Tcl command.
+- Methodology layer (`methodology/*.md`) exposing named expert workflows as
+  MCP prompts: full-flow, timing-closure, cdc-audit, resource-budgeting,
+  soc-bringup, sim-signoff, bitstream-handoff.
+- CLI: `fpga-mcp setup`, `fpga-mcp doctor [--fix]`, `fpga-mcp run`,
+  `fpga-mcp backends`, `fpga-mcp tcl-server-path <backend>`,
+  `fpga-mcp version`.
+- `pyproject.toml` packaging with `fpga-mcp` / `fpga` console scripts.
+- 69-test suite covering: Tcl helpers, config + env overrides, package
+  surface, FastMCP server (tool count ≥ 500, vendor coverage, prompt list,
+  non-empty descriptions), tool factory (spec parsing, arg inference,
+  template rendering, handler dispatch, catalogue invariants), all three
+  backends via in-process mock Tcl servers, and the CLI.
+
+### Changed
+- Renamed the project from `omni-fpga-mcp` to `fpga-mcp`. Package name,
+  import path, console scripts, env vars (`FPGA_MCP_*`), config paths and
+  CI all use the new name.
+- Switched the server from the hand-written `fpga_mcp.tools` module (8
+  domain modules, 22 functions) to the declarative
+  `fpga_mcp.tool_defs` factory. The old `tools/` directory has been
+  removed; the 22 high-level tools remain available via
+  `tool_defs/common.py` + `_handlers.py` with identical behaviour.
+
+### Removed
+- `fpga_mcp/tools/` — superseded by `fpga_mcp/tool_defs/` + `_handlers.py`.