flist-mcp 0.16.0__tar.gz

flist_mcp-0.16.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,48 @@
+name: Bug report
+description: Report incorrect filelists, diagnostics, conflicts, or dependency graphs.
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: Do not attach proprietary RTL unless you are authorized to disclose it.
+  - type: input
+    id: version
+    attributes:
+      label: flist-mcp version or commit
+      placeholder: 0.16.0 or a commit SHA
+    validations:
+      required: true
+  - type: textarea
+    id: invocation
+    attributes:
+      label: Tool invocation
+      description: Include top modules, source globs, defines, and resolutions.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Provide minimal non-proprietary SystemVerilog sources or a repository link.
+    validations:
+      required: true
+  - type: textarea
+    id: observed
+    attributes:
+      label: Observed result
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected result
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Operating system, Python version, and uv version.
+    validations:
+      required: true

flist_mcp-0.16.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/Bigyin1/flist-mcp/security/advisories/new
+    about: Report suspected vulnerabilities privately.

flist_mcp-0.16.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Propose a focused improvement to the analysis or MCP contract.
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Describe the agent workflow or filelist problem this would solve.
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Proposed behavior
+      description: Include expected tool inputs and outputs when relevant.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

flist_mcp-0.16.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

flist_mcp-0.16.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+Describe the user-visible behavior and motivation.
+
+## Verification
+
+- [ ] `make check`
+- [ ] `make check-all` when Slang, discovery, graphs, examples, or real-world behavior changed
+- [ ] Documentation, MCP descriptions, Pydantic schemas, examples, and tests are synchronized
+- [ ] No generated artifacts, caches, downloaded repositories, or proprietary RTL are included

flist_mcp-0.16.0/.github/workflows/ci.yml

@@ -0,0 +1,122 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Quality gates
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install Python
+        run: uv python install 3.10
+      - name: Synchronize locked environment
+        run: uv sync --python 3.10 --frozen
+      - name: Run formatting, lint, typing, and complexity checks
+        run: make lock-check format-check lint typecheck complexity
+
+  unit-tests:
+    name: Unit tests and coverage
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install Python
+        run: uv python install 3.10
+      - name: Synchronize locked environment
+        run: uv sync --python 3.10 --frozen
+      - name: Run unit tests with branch coverage
+        run: make test
+      - name: Generate coverage XML
+        run: uv run --frozen coverage xml -o coverage.xml
+      - name: Upload coverage to Codecov
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        with:
+          use_oidc: true
+          files: ./coverage.xml
+          disable_search: true
+          flags: unit
+          fail_ci_if_error: true
+
+  real-world:
+    name: AXI and CVA6 integration
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install Python
+        run: uv python install 3.10
+      - name: Synchronize locked environment
+        run: uv sync --python 3.10 --frozen
+      - name: Restore real-world RTL checkouts
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: .realworld-cache
+          key: realworld-${{ runner.os }}-${{ hashFiles('tests/conftest.py', 'tests/test_*_integration.py') }}
+          restore-keys: |
+            realworld-${{ runner.os }}-
+      - name: Run pinned AXI and CVA6 tests
+        run: make test-realworld
+
+  package:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install Python
+        run: uv python install 3.10
+      - name: Synchronize locked environment
+        run: uv sync --python 3.10 --frozen
+      - name: Build wheel and source distribution
+        run: uv build
+      - name: Verify console entry point
+        run: unzip -p dist/*.whl '*/entry_points.txt' | grep -Fx 'flist-mcp = flist_mcp.mcp_main:main'

flist_mcp-0.16.0/.github/workflows/release.yml

@@ -0,0 +1,82 @@
+name: Release artifacts
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Verify tagged release
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Check out tagged commit
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install Python
+        run: uv python install 3.10
+      - name: Synchronize locked environment
+        run: uv sync --python 3.10 --frozen
+      - name: Run full verification suite
+        run: make check-all
+      - name: Build wheel and source distribution
+        run: uv build
+      - name: Verify artifact version matches tag
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          test -f "dist/flist_mcp-${version}-py3-none-any.whl"
+          test -f "dist/flist_mcp-${version}.tar.gz"
+      - name: Store verified artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: flist-mcp-${{ github.ref_name }}
+          path: dist/*
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download verified artifacts
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: flist-mcp-${{ github.ref_name }}
+          path: dist
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - name: Create release from the published tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: >-
+          gh release create "$GITHUB_REF_NAME"
+          --verify-tag --generate-notes
+          --title "flist-mcp ${GITHUB_REF_NAME#v}"

flist_mcp-0.16.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.realworld-cache/
+.venv/
+.vscode/
+build/
+dist/

flist_mcp-0.16.0/.python-version

@@ -0,0 +1 @@
+3.10

flist_mcp-0.16.0/AGENTS.md

@@ -0,0 +1,37 @@
+# Repository instructions for coding agents
+
+These instructions apply to the entire repository.
+
+## Environment and commands
+
+- Target CPython 3.10 and use `uv`; do not introduce another environment or dependency manager.
+- Run project tools through `uv run --frozen`. Keep `uv.lock` synchronized with `pyproject.toml`.
+- Use `make check` for every change. Use `make check-all` when changing Slang integration,
+  discovery, analysis, graph construction, examples, or real-world tests.
+- Do not weaken Ruff, Pylint, strict mypy, Xenon, warnings-as-errors, branch coverage, or CVA6
+  performance gates merely to make a change pass. Document a genuine reason for any adjustment.
+
+## Architecture and public contracts
+
+- Treat Slang as the sole source of SystemVerilog parsing, elaboration, diagnostics, dependency
+  closure, and topological ordering.
+- Do not parse RTL text with regular expressions or implement a separate dependency-order
+  algorithm.
+- Preserve the stateful protocol: iterative `analyze_top`, followed by `diagnose_top` and/or
+  `get_dependency_graph` after the top is ready.
+- Keep MCP descriptions self-contained. When a public argument or result changes, update the
+  Pydantic output models, tool descriptions, documentation, examples, and contract tests together.
+- Keep package files out of `source_order`; preserve Slang order within `package_order` and
+  `source_order`.
+- Keep warnings opt-in and undefined design macros advisory unless the public contract is
+  deliberately revised.
+
+## Repository hygiene
+
+- Prefer small typed helpers over broad suppressions. Add focused unit tests for conflict,
+  include, diagnostic, and graph edge cases.
+- Do not commit `.venv`, caches, downloaded real-world repositories, coverage data, or build
+  artifacts.
+- Keep examples under `docs/examples`, validate them against public output models, and state the
+  pinned design revision and call parameters used to produce them.
+- Preserve unrelated user changes and avoid destructive Git operations.

flist_mcp-0.16.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergey Aparin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flist_mcp-0.16.0/Makefile

@@ -0,0 +1,38 @@
+.PHONY: format format-check lint typecheck complexity test test-realworld lock-check check check-all
+
+UV_RUN := uv run --frozen
+RUFF := $(UV_RUN) ruff
+PYLINT := $(UV_RUN) pylint
+MYPY := $(UV_RUN) mypy
+PYTEST := $(UV_RUN) pytest
+XENON := $(UV_RUN) xenon
+
+format:
+	$(RUFF) format src tests
+	$(RUFF) check --fix src tests
+
+format-check:
+	$(RUFF) format --check src tests
+
+lint:
+	$(RUFF) check src tests
+	$(PYLINT) src tests
+
+typecheck:
+	$(MYPY) src tests
+
+complexity:
+	$(XENON) --max-absolute B --max-modules B --max-average A src
+
+test:
+	$(PYTEST) -m "not integration" --cov=flist_mcp --cov-branch
+
+test-realworld:
+	FLIST_MCP_REALWORLD=1 $(PYTEST) -m integration
+
+lock-check:
+	uv lock --check
+
+check: lock-check format-check lint typecheck complexity test
+
+check-all: check test-realworld

flist_mcp-0.16.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: flist-mcp
+Version: 0.16.0
+Summary: Slang-backed SystemVerilog filelist analysis over MCP
+Project-URL: Homepage, https://github.com/Bigyin1/flist-mcp
+Project-URL: Documentation, https://github.com/Bigyin1/flist-mcp/tree/main/docs
+Project-URL: Issues, https://github.com/Bigyin1/flist-mcp/issues
+Project-URL: Repository, https://github.com/Bigyin1/flist-mcp
+Author-email: Sergey Aparin <aparin.sv@phystech.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: filelist,mcp,slang,systemverilog,verilog
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.10
+Requires-Dist: mcp<3,>=2
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: pyslang==11.0.0
+Description-Content-Type: text/markdown
+
+# flist-mcp
+
+[![CI](https://github.com/Bigyin1/flist-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Bigyin1/flist-mcp/actions/workflows/ci.yml)
+[![Codecov](https://codecov.io/gh/Bigyin1/flist-mcp/graph/badge.svg)](https://codecov.io/gh/Bigyin1/flist-mcp)
+[![PyPI](https://img.shields.io/pypi/v/flist-mcp.svg)](https://pypi.org/project/flist-mcp/)
+[![GitHub tag](https://img.shields.io/github/v/tag/Bigyin1/flist-mcp?sort=semver&label=version)](https://github.com/Bigyin1/flist-mcp/tags)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![uv](https://img.shields.io/badge/package_manager-uv-de5fe9.svg)](https://docs.astral.sh/uv/)
+[![Ruff](https://img.shields.io/badge/code_style-Ruff-d7ff64.svg)](https://docs.astral.sh/ruff/)
+[![mypy: strict](https://img.shields.io/badge/mypy-strict-2a6db2.svg)](https://mypy-lang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+`flist-mcp` is a Slang-backed MCP server that helps coding agents construct SystemVerilog
+filelists. Given one or more top modules, it discovers the reachable compilation closure, returns
+package and source files in topological order, finds include roots, reports ambiguous definitions,
+and exposes diagnostics and focused dependency graphs.
+
+Slang remains the source of truth for parsing, elaboration, diagnostics, and dependency ordering.
+The server does not parse RTL with regular expressions, invent its own topological order, or emit a
+build-system-specific manifest.
+
+## Features
+
+- Iterative resolution of duplicate module, interface, and package definitions.
+- Automatic discovery of unique repository-local include roots.
+- Explicit resolution when several headers satisfy the same include path.
+- Separate topological `package_order` and `source_order` filelists.
+- Diagnostics, missing includes, undefined design macros, and unresolved external symbols.
+- `full`, elaborated `rtl`, and compact `external` dependency graph views.
+- Strict machine-readable MCP input and output schemas.
+
+## Quick start
+
+Install and start the latest PyPI release with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uvx flist-mcp
+```
+
+Example stdio MCP configuration using the published package:
+
+```json
+{
+  "mcpServers": {
+    "flist": {
+      "command": "uvx",
+      "args": ["flist-mcp"]
+    }
+  }
+}
+```
+
+For a reproducible client configuration, pin a release explicitly:
+
+```json
+{
+  "command": "uvx",
+  "args": ["--from", "flist-mcp==0.16.0", "flist-mcp"]
+}
+```
+
+## Platform requirements
+
+`flist-mcp` requires CPython 3.10 or newer. CI currently validates CPython 3.10 on Ubuntu. The
+server itself is Python, but `pyslang==11.0.0` is a native extension and determines platform
+availability. Upstream provides wheels for CPython 3.10 through 3.14 on:
+
+- Linux with glibc 2.27 or newer, on x86-64 and AArch64.
+- macOS 11 or newer, on Apple Silicon and Intel via universal2 wheels.
+- 64-bit Windows on x86-64.
+
+Prebuilt `pyslang` wheels are not available for Alpine/musl Linux, 32-bit systems, Windows ARM64,
+or other architectures; these platforms are outside the tested `flist-mcp` runtime matrix.
+
+Git is not required to analyze an existing source directory. It is needed only to clone this
+repository for development and by the real-world integration tests that fetch pinned RTL projects.
+
+## Agent flow
+
+1. Call `analyze_top(repository, top_modules)`.
+2. If it returns `needs_resolution`, select candidates from
+   `required_definition_conflicts` and `required_include_conflicts`, then call `analyze_top` again.
+3. When it returns `ready_for_diagnostics`, use its topologically sorted filelists.
+4. Call `diagnose_top()` for semantic diagnostics or `get_dependency_graph(view=...)` for a focused
+   graph. Both reuse one cached semantic analysis.
+
+Only one active top is stored in a server process. Changing the repository, top modules, or source
+globs starts a new flow.
+
+## Documentation
+
+- [Getting started and MCP configuration](docs/getting-started.md)
+- [Agent workflow and result semantics](docs/agent-workflow.md)
+- [Dependency graph views](docs/dependency-graphs.md)
+- [Development and architecture](docs/development.md)
+- [Versioning and release artifacts](docs/versioning.md)
+- [Current CVA6 examples](docs/examples/README.md)
+- [Contributing](docs/CONTRIBUTING.md)
+- [Security policy](docs/SECURITY.md)
+
+## Development
+
+Development requires Git and uv:
+
+```sh
+git clone https://github.com/Bigyin1/flist-mcp.git
+cd flist-mcp
+uv sync --python 3.10 --frozen
+make check
+make check-all
+```
+
+`make check` is network-free. `make check-all` additionally downloads pinned sparse checkouts of
+PULP AXI and CVA6 into the ignored `.realworld-cache` directory and runs the integration and
+performance suite.
+
+## License
+
+Licensed under the [MIT License](LICENSE).