flux-topology
A CLI + agent skill that builds a dependency and topology graph of a Kubernetes/FluxCD GitOps repository by static analysis, so AI agents can reason about service relationships without cluster access.
Install
pip install flux-topology
Optional — install the agent skill from skills.sh:
npx skills add seppaleinen/flux-topology-mcp
No MCP server is required. Run the CLI from your GitOps repo root; it reads
from flux/ in the working directory.
Subcommands
| Command | Description |
|---|---|
build [dir] [--force] |
Build the topology cache (.fluxtop/) |
map [dir] [--json] |
Top-level view: domains, hub apps by edge count, warnings |
trace <app> [dir] [--direction out|in|both] [--depth N] [--json] |
BFS blast radius from any app with typed edges |
find-refs <pattern> [dir] [--json] |
Regex search for references across all apps |
app-card <app> [dir] [--json] |
Full card for one app: workloads, services, edges |
check-freshness [dir] [--json] |
Check if the topology cache is up to date (never rebuilds) |
[dir] defaults to .. A directory is resolved to its flux/ subdirectory
when present; otherwise the directory itself is treated as the flux root.
Exit codes
| Code | Meaning |
|---|---|
0 |
Found / fresh |
1 |
Stale, corrupt, not-found, or invalid input |
2 |
Usage error (argparse) |
3 |
No cache (check-freshness only) |
CLI examples
# Build the topology cache (.fluxtop/)
flux-topology build
# Rebuild even when the cache is fresh
flux-topology build --force
# Human-readable overview
flux-topology map
# Machine-readable output
flux-topology map --json
# Blast radius: what depends on this app? (depth 5)
flux-topology trace apps/backend --direction in
# Find every app referencing a shared resource
flux-topology find-refs "postgres-rw\.postgres\.svc\."
# Full card for one app
flux-topology app-card apps/radarr
# Freshness check (exit codes 0/1/3)
flux-topology check-freshness
How it works
- Discovers apps by walking
flux/and finding ownership signals (HelmReleases, Kustomizations, Deployments, Services) - Extracts workloads, services, ingress hosts, and refs per app
- Resolves edges between apps from cross-references
- Caches everything in
.fluxtop/— rebuilt only when source files change
Hybrid freshness
The cache is checked against a fingerprint of all YAML files on every query:
- No cache —
map/trace/find-refs/app-cardauto-build once and then answer normally.check-freshnessinstead reportsNO CACHE(exit 3) and never rebuilds. - Fresh — the cache matches the working tree; queries answer from it.
- Stale / corrupt — queries surface a notice and exit 1 without
rebuilding, so results are never silently outdated. Rebuild explicitly with
flux-topology build --force, or justbuild(which also rebuilds when the fingerprint no longer matches).
Deployment note (dotfiles env)
The always-on flux-topology MCP server was removed from the shared MCP list
in the user's dotfiles environment (Stow-managed). The tool is now used
on-demand via the CLI + skill. Re-push the rewritten skill via skills.sh.
Development
git clone https://github.com/seppaleinen/flux-topology-mcp.git
cd flux-topology-mcp
pip install -e ".[dev]"
pytest
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file flux_topology-0.3.1.tar.gz.
File metadata
- Download URL: flux_topology-0.3.1.tar.gz
- Upload date:
- Size: 41.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b19aea033a9c3f57cbbd6d7800c0606d0a3ea8ae3140155db248995bf8900a5a
|
|
| MD5 |
1496ab1fe41b636721979058177f1510
|
|
| BLAKE2b-256 |
84b6052dc1d26066a033daae88c8e9e76c0232ff190fcf4fddb71e0458cfc7b4
|
Provenance
The following attestation bundles were made for flux_topology-0.3.1.tar.gz:
Publisher:
release.yml on seppaleinen/flux-topology-mcp
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
flux_topology-0.3.1.tar.gz -
Subject digest:
b19aea033a9c3f57cbbd6d7800c0606d0a3ea8ae3140155db248995bf8900a5a - Sigstore transparency entry: 2841563753
- Sigstore integration time:
-
Permalink:
seppaleinen/flux-topology-mcp@764475d8bfa59fe8646efb966e2853fe0fb52c79 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/seppaleinen
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@764475d8bfa59fe8646efb966e2853fe0fb52c79 -
Trigger Event:
push
-
Statement type:
File details
Details for the file flux_topology-0.3.1-py3-none-any.whl.
File metadata
- Download URL: flux_topology-0.3.1-py3-none-any.whl
- Upload date:
- Size: 23.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8454d0c911820fe08f43bf2e5d5e15a289db18bb809b19338935f47c054989b5
|
|
| MD5 |
2e4f2e38110d8f2f1bc6233f89693deb
|
|
| BLAKE2b-256 |
529800ec7acc5e33e89b1e142284b0d2d9ae6ad06f1d844a56de6cfd13d79969
|
Provenance
The following attestation bundles were made for flux_topology-0.3.1-py3-none-any.whl:
Publisher:
release.yml on seppaleinen/flux-topology-mcp
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
flux_topology-0.3.1-py3-none-any.whl -
Subject digest:
8454d0c911820fe08f43bf2e5d5e15a289db18bb809b19338935f47c054989b5 - Sigstore transparency entry: 2841563779
- Sigstore integration time:
-
Permalink:
seppaleinen/flux-topology-mcp@764475d8bfa59fe8646efb966e2853fe0fb52c79 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/seppaleinen
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@764475d8bfa59fe8646efb966e2853fe0fb52c79 -
Trigger Event:
push
-
Statement type:
