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

Related MCP server: Axon Pro

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

CLI

# Build the topology cache (.fluxtop/)
flux-topology build

# Run the MCP server (for AI agents)
flux-topology mcp

How it works

1. Discovers apps by walking flux/ and finding ownership signals (HelmReleases, Kustomizations, Deployments, Services)

2. Extracts workloads, services, ingress hosts, and refs per app

3. Resolves edges between apps from cross-references

4. 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