flist-mcp

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:

uvx flist-mcp

Example stdio MCP configuration using the published package:

{
  "mcpServers": {
    "flist": {
      "command": "uvx",
      "args": ["flist-mcp"]
    }
  }
}

For a reproducible client configuration, pin a release explicitly:

{
  "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
• Agent workflow and result semantics
• Dependency graph views
• Architecture and component boundaries
• Quality gates and performance budgets
• Development environment and commands
• Versioning and release artifacts
• Current CVA6 examples
• Contributing
• Security policy

Development

Development requires Git and uv:

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.