flux-topology
An MCP server 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
Configure MCP
Add to your opencode.json:
{
"mcp": {
"flux-topology": {
"type": "local",
"command": ["flux-topology", "mcp"],
"enabled": true
}
}
}
The server reads from flux/ in the working directory. Run opencode from your
GitOps repo root.
Agent Skill
The bundled agent skill teaches AI agents when and how to use the MCP tools. Install it from skills.sh:
npx skills add seppaleinen/flux-topology-mcp
This gives your agent a workflow: start with fluxtop_map for an overview,
drill down with fluxtop_app_card, check blast radius with fluxtop_trace,
and find shared references with fluxtop_find_refs.
Tools
| Tool | Description |
|---|---|
fluxtop_map |
Top-level view: domains, hub apps by edge count, warnings |
fluxtop_trace |
BFS blast radius from any app with typed edges |
fluxtop_find_refs |
Regex search for references across all apps |
fluxtop_app_card |
Full card for one app: workloads, services, edges |
fluxtop_check_freshness |
Check if the topology cache is up to date |
CLI
# Build the topology cache (.fluxtop/)
flux-topology build
# Run the MCP server (for AI agents)
flux-topology mcp
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
No cluster access required. Pure static analysis of YAML files.
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.2.4.tar.gz.
File metadata
- Download URL: flux_topology-0.2.4.tar.gz
- Upload date:
- Size: 27.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
45d47f23881d6d316e9d22557c2bb0962e7b14b1fbd4c3c5c42b80c3391e451c
|
|
| MD5 |
58b7d64aa4dfae445d0d88dc59cacfab
|
|
| BLAKE2b-256 |
0100b2b0f120fd78eebdda74680b3d9e3215f52000ce3097f53b40e523c79617
|
Provenance
The following attestation bundles were made for flux_topology-0.2.4.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.2.4.tar.gz -
Subject digest:
45d47f23881d6d316e9d22557c2bb0962e7b14b1fbd4c3c5c42b80c3391e451c - Sigstore transparency entry: 2618107104
- Sigstore integration time:
-
Permalink:
seppaleinen/flux-topology-mcp@2a83400489816cea29bfa398e9b7e388f86a8790 -
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@2a83400489816cea29bfa398e9b7e388f86a8790 -
Trigger Event:
push
-
Statement type:
File details
Details for the file flux_topology-0.2.4-py3-none-any.whl.
File metadata
- Download URL: flux_topology-0.2.4-py3-none-any.whl
- Upload date:
- Size: 20.6 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 |
4d5564c00bcc112e9a2ca9607bcb349870b3100d96ccb38c158c8660a67cac22
|
|
| MD5 |
bca1d2644ec2a3f25458392b0c843f4d
|
|
| BLAKE2b-256 |
8afa446b8f93d530c4978d622a73f96d42b617f8a3afaa94736961398dd89df5
|
Provenance
The following attestation bundles were made for flux_topology-0.2.4-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.2.4-py3-none-any.whl -
Subject digest:
4d5564c00bcc112e9a2ca9607bcb349870b3100d96ccb38c158c8660a67cac22 - Sigstore transparency entry: 2618107200
- Sigstore integration time:
-
Permalink:
seppaleinen/flux-topology-mcp@2a83400489816cea29bfa398e9b7e388f86a8790 -
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@2a83400489816cea29bfa398e9b7e388f86a8790 -
Trigger Event:
push
-
Statement type:
