Structural code-quality tools for AI coding agents.
io.github.Krv-Labs/topos MCP Server
The io.github.Krv-Labs/topos MCP server provides structural code-quality tooling for AI coding agents. It is described as “Structural code-quality tools for AI coding agents,” and the repository excerpt indicates it measures complexity as part of that structural analysis.
🛠️ Key Features
Structural code-quality tooling for AI coding agents
Measures complexity (from the repository excerpt)
🚀 Use Cases
Supporting AI coding agents with structural code-quality evaluation
Assessing code complexity during agent workflows
⚡ Developer Benefits
Structured code-quality data intended for use by AI coding agents
Complexity measurement exposed through the server tooling (per excerpt)
⚠️ Limitations
Available source content only confirms “complexity” and structural code-quality positioning; no explicit tool list or capabilities are provided in the excerpt.
Tool count and topics are not included in the provided data.
Coding agents produce working code quickly. The harder question is whether the result is still easy to understand, safe to change, and well-fitted to the rest of the repository. Quality is the new currency.
Topos computes that signal from program structure—not from an LLM review or a style opinion—and returns concrete failure locations and next actions. It is fast enough to sit inside the agent loop: measure, edit, verify, repeat.
Tests check behavior. Topos checks whether the implementation is built to keep changing.
Grounded in category theory, written in Rust.
Install and Quick Start
One binary. Every supported agent harness. A clean way back out.
On Homebrew 6+, that fully qualified one-liner auto-taps and trusts only this formula. If you brew tap krv-labs/tap first, run brew trust --formula krv-labs/tap/topos before brew install topos.
TIP
Prefer an editor-managed install? In VS Code or Cursor, search @mcp topos in the Extensions view or choose Install MCP server. This is an alternative to topos install: your editor installs and manages the Topos MCP server for you.
2. Connect your coding agents
topos install detects every supported MCP harness and lets you configure any—or all—of them from one interactive checklist:
bash
topos install
text
┌ Which agent integrations do you want to configure?
│
│ ↑↓ move · space toggle · a all · enter confirm · esc cancel
│
│ ❯ ○ Claude Code (detected)
│ ○ Claude Desktop (detected)
│ ● Codex CLI (✓ active)
│ ● Gemini CLI (✓ active)
│ ○ GitHub Copilot CLI (detected)
│ ○ Cursor (detected)
│ ○ VS Code (detected)
│ ○ Google Antigravity (detected)
│ ○ pi (detected)
│ ○ OpenCode (detected)
└
Restart the agents you configured, then ask:
"Use Topos to find this repository's worst structural problem, make one focused improvement, and verify the result."
IMPORTANT
Too many tools spray MCP servers across agent JSON files, scatter symlinks around your machine, then leave you to burn half a Claude session untangling the mess—or pull your own hair out doing it. Topos does not play that game. We follow a leave-no-trace policy: topos status shows every registration, while topos uninstall opens the same selector, previews exactly what will change, and removes everything Topos installed. If Topos makes it easy to do, it should be just as easy to undo.
bash
topos status
topos uninstall
See the agent setup guide for permissions, manual configuration, and troubleshooting.
3. Evaluate from the terminal
bash
topos evaluate . -r
Topos discovers Python, Rust, JavaScript, TypeScript, C++, and Go automatically. Pass --language only when you want to narrow the run.
See Installation for platform support and alternative install paths.
What Topos checks
Every file gets four independent verdicts:
SIMPLE — avoids unnecessary complexity using AST entropy and control-flow complexity.
COMPOSABLE — limits a file's outward dependency burden; broader coupling and stability metrics remain available for diagnosis.
SECURE — avoids dangerous API reachability and taint paths in the code property graph.
NAVIGABLE — stays shallow enough for an agent to read and change in one pass, using depth-weighted nesting divergence over the AST scope tree.
Those verdicts roll up into one memorable quality medal without hiding which pillar failed:
Medal
Criteria
🏆 PLATINUM
Passes all 4
🥇 GOLD
Passes 3 of 4
🥈 SILVER
Passes 2 of 4
🥉 BRONZE
Passes 1 of 4
❌ SLOP
Passes 0, or fails to parse
See the full metrics reference. Refactor guidance also surfaces control-flow cycles, load-bearing dependency edges, and process bottlenecks.
How the medal system is derived
The four pillars are pairwise incomparable and form a sixteen-element evaluation lattice (a 4-cube); PLATINUM is their intersection. Labels below abbreviate the pillars as Simple, Composable, Sc = Secure, Navigable.
Topos is a self-contained Rust CLI and MCP server. Analysis runs locally; your source code is not sent to an external model or hosted analysis service.
Embedded in the MCP server for supplementary security findings; native CPG probes remain the SECURE scoring source.
The result is one agent-facing contract over several structural lenses: one score to optimize, explicit evidence for each failure, and a verification loop that can tell a real improvement from cosmetic churn.
