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.

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/daveri/flux-topology-mcp.git
cd flux-topology-mcp
pip install -e ".[dev]"
pytest

License

MIT