The Topos MCP server provides AI agents with structural code quality metrics across three pillars — SIMPLE, COMPOSABLE, and SECURE — to evaluate, compare, inspect, and iteratively improve code quality.
Evaluate Code Quality
Score inline code, individual files, or entire projects/directories with topos_evaluate_code, topos_evaluate_file, or topos_evaluate_project. Returns a quality medal (GOLD → SLOP) with per-pillar scores. Supports Python, Rust, JavaScript, TypeScript, and C++.
Inspect Code Details
Use topos_inspect_code for per-function breakdowns of cyclomatic complexity, entropy, and the full quality verdict.
Assess Refactors & Changes
topos_assess_improvement — compare a baseline vs. proposed variant inline.
topos_assess_worktree_change — compare an in-place edited file against a git baseline (primary refactor loop tool).
topos_assess_changeset — assess multi-file changesets, detecting complexity relocation and project-level regressions.
topos_begin_refactor / topos_assess_snapshot — snapshot-based workflow for uncommitted/untracked files.
Structural Comparison
Compute AST tree-edit distance between code strings or files with topos_compare_code and topos_compare_files.
Test Coverage Analysis
Measure structural (UAST) and semantic (ECT) test coverage with topos_calculate_coverage.
Dependency Graph Management
Check status with topos_depgraph_status and generate the .gitnexus graph (required for COMPOSABLE scoring) with topos_generate_depgraph.
Preference & Lattice Utilities
topos_preference_walk — compute a preference-ordered relaxation walk through the 8-element quality lattice, helping agents gracefully downgrade goals under budget constraints.
topos_get_doc — retrieve Markdown documentation on agent contracts, lattice, metrics, preferences, and workflows.
All tools support preference rankings (simple/composable/secure), allow (acknowledge risky calls), verbose (raw metrics), and include_security_findings options.
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.
Related MCP server: mcp-skylos
One binary. Every supported agent harness. A clean way back out.
Use the verified release installer:
curl -fsSL https://docs.krv.ai/topos/install.sh | bashOr install with Homebrew:
brew install krv-labs/tap/toposPrefer 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.
topos install detects every supported MCP harness and lets you configure any—or all—of them from one interactive checklist:
topos install┌ 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)
└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."
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.
topos status
topos uninstallSee the agent setup guide for permissions, manual configuration, and troubleshooting.
topos evaluate . -rTopos 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.
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, process bottlenecks, and optional Graphify knowledge-graph findings.
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.
Measures · Category-theory foundations
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.
Component | Role |
Parses six languages and powers the native AST, CFG, CPG, PDG, and UAST representations. | |
Supplies the repository dependency graph scored by COMPOSABLE ( | |
Embedded in the MCP server for supplementary security findings; native CPG probes remain the SECURE scoring source. | |
Optional advisory orphan and fragile-edge detection via |
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.
OpenClaw / ClawHub: openclaw skills install @Krv-Labs/topos
Hermes: hermes skills tap add Krv-Labs/topos then hermes skills install Krv-Labs/topos/topos
MCP Registry name: io.github.Krv-Labs/topos
CLI reference: docs.krv.ai/topos/cli
Topos ships four ways:
GitHub Releases — the topos CLI binary (macOS/Linux), via install.sh or a direct release download.
PyPI — topos-mcp, a thin bin-wheel bundling the MCP server binary (pip install topos-mcp / uvx topos-mcp), zero Python runtime.
VS Code Marketplace — the Topos extension, bundling platform binaries.
Docker — a container image for Glama and other MCP-registry hosting.
Crate layout and adapter details: docs.krv.ai/topos/architecture.
Topos is used internally at Krv Labs to manage AI-agent code output. We welcome bugs, ideas, and contributions.
Bug? Open an issue
Idea? Start a discussion or open a PR
Collaborate? team@krv.ai
Full documentation · Measures and metrics · Engineering notes
Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Agentic code review, no signup to try: reality gates + frontier-model review, with veto.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Krv-Labs/topos'
If you have feedback or need assistance with the MCP directory API, please join our Discord server