Metadata-Version: 2.5
Name: flist-mcp
Version: 0.17.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.
- Stateless discovery of all repository root modules before selecting a top.
- 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. Optionally call `list_root_modules(repository)` to discover candidate entry modules.
2. Call `analyze_top(repository, top_modules)`.
3. If it returns `needs_resolution`, select candidates from
   `required_definition_conflicts` and `required_include_conflicts`, then call `analyze_top` again.
4. When it returns `ready_for_diagnostics`, use its topologically sorted filelists.
5. 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)
- [Architecture and component boundaries](docs/architecture.md)
- [Quality gates and performance budgets](docs/quality.md)
- [Development environment and commands](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
```

After the locked development environment is synchronized, `make check` uses the installed local
tools. `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).
