MCP Server

Active

BSD-3-Clause

Topos MCP Server

io.github.Krv-Labs/topos

Structural code-quality analysis for AI coding agents—measure complexity, coupling, and cognitive load.

What is the Topos MCP server?

The Topos MCP server is a structural code-quality tool that measures complexity, coupling, risky data flows, and agent cognitive load across Python, Rust, JavaScript, TypeScript, C++, and Go. It assigns concrete quality verdicts (SLOP to PLATINUM) based on four independent pillars—SIMPLE, COMPOSABLE, SECURE, and NAVIGABLE—and integrates directly into coding agents to guide focused refactoring.

Topos evaluates code structure using abstract syntax trees, control-flow graphs, and code property graphs to identify quality bottlenecks without relying on LLM review. It runs locally, sits inside the agent loop, and provides explicit failure locations and next actions. Use it to ensure AI-generated code remains maintainable, safe to change, and well-fitted to your repository.

How to install Topos

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "topos": {
      "command": "uvx",
      "args": [
        "topos-mcp"
      ]
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

evaluate — Analyze a repository or file for structural code quality across four pillars (SIMPLE, COMPOSABLE, SECURE, NAVIGABLE) and return a quality medal (PLATINUM, GOLD, SILVER, BRONZE, or SLOP).
pr-recap — Generate a structural before/after quality card for a pull request's changed files without requiring an LLM.
depgraph generate — Generate and analyze the repository dependency graph to score COMPOSABLE metrics.
install — Interactively detect and configure Topos integration with supported MCP harnesses (Claude Desktop, VS Code, Cursor, GitHub Copilot CLI, and others).
status — Display all Topos registrations across configured agent harnesses.
uninstall — Remove Topos from all configured agent harnesses with a preview of changes.

Use cases

Evaluate AI-generated code for structural quality before merging pull requests.
Identify and refactor the worst structural problems in a repository with concrete guidance.
Verify that code improvements actually reduce complexity, coupling, or cognitive load rather than just cosmetic changes.
Integrate code-quality checks into agent workflows to ensure maintainability alongside functional correctness.
Diagnose dangerous API reachability and taint paths in the code property graph.

Topos MCP server FAQ

What is Topos?

Topos is a structural code-quality tool for AI coding agents. It measures complexity, coupling, risky data flows, and cognitive load across Python, Rust, JavaScript, TypeScript, C++, and Go, then assigns a quality medal (PLATINUM, GOLD, SILVER, BRONZE, or SLOP) with explicit failure locations.

Is Topos free?

Yes. Topos is open-source and available via GitHub Releases, PyPI (topos-mcp), Homebrew, and the VS Code Marketplace. Analysis runs locally on your machine.

How do I install Topos in Cursor or Claude?

Run `topos install` to interactively detect and configure Topos across all supported agent harnesses, including Cursor, Claude Desktop, VS Code, and GitHub Copilot CLI. Alternatively, search `@mcp topos` in VS Code Extensions or use the Install MCP server option.

Does Topos require authentication or send code to external services?

No. Topos is self-contained, runs locally, and does not send your source code to any external model or hosted service.

What languages does Topos support?

Topos analyzes Python, Rust, JavaScript, TypeScript, C++, and Go. It auto-detects the language; you can narrow the run with `--language` if needed.

How do I uninstall Topos?

Run `topos uninstall` to open an interactive selector, preview exactly what will be removed, and cleanly uninstall from all configured agent harnesses.

README (reference)

Source of truth, from the repository.

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/topos-logo-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/topos-logo.svg"> <img src="https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/topos-logo.svg" alt="Topos" width="400"> </picture> <h3 align="center">the agent harness for structural code quality</h3> Topos measures complexity, coupling, risky data flows, and agent cognitive load, then gives your agent a concrete target—from SLOP to PLATINUM. <a href="#what-topos-checks"><img src="https://raw.githubusercontent.com/Krv-Labs/topos/main/docs/source/_static/topos-lattice-badge.svg" alt="Topos self-evaluation: SIMPLE, COMPOSABLE, SECURE, NAVIGABLE results for the core crates"></a> <a href="https://github.com/mcp/Krv-Labs/topos"><img src="https://img.shields.io/badge/VS_Code-Install_MCP-007ACC?logo=visualstudiocode&logoColor=white" alt="Install Topos MCP in VS Code"></a> <a href="https://pypi.org/project/topos-mcp/"><img src="https://img.shields.io/pypi/v/topos-mcp?color=3776AB&logo=python&logoColor=ffd43b" alt="PyPI"></a> <a href="https://github.com/Krv-Labs/topos/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Krv-Labs/topos" alt="License"></a> <a href="https://glama.ai/mcp/servers/Krv-Labs/topos"><img src="https://glama.ai/mcp/servers/Krv-Labs/topos/badges/score.svg" alt="Topos MCP server"></a> <a href="https://clawhub.ai/krv-labs/skills/topos"><img src="https://img.shields.io/badge/%F0%9F%A6%9E_ClawHub-topos-F97316" alt="ClawHub"></a>  <a href="#install-and-quick-start">Install</a> · <a href="#what-topos-checks">What it checks</a> · <a href="#under-the-hood">Under the hood</a> · <a href="https://docs.krv.ai/topos/">Docs</a> · <a href="https://github.com/Krv-Labs/topos/issues">Issues</a>

Why Topos

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.

1. Install the CLI

Use the verified release installer:

curl -fsSL https://docs.krv.ai/topos/install.sh | bash

Or install with Homebrew:

brew install krv-labs/tap/topos

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:

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)
│   ○ 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.
topos status
topos uninstall

See the agent setup guide for permissions, manual configuration, and troubleshooting.

3. Evaluate from the terminal

topos evaluate . -r

Topos discovers Python, Rust, JavaScript, TypeScript, C++, and Go automatically. Pass --language only when you want to narrow the run.

Reviewing a pull request instead? topos pr-recap 5 gives a structural before/after card for the PR's changed files — no LLM, fully reproducible.

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.

<details> <summary>How the medal system is derived</summary>

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

</details>

Under the hood

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
tree-sitter	Parses six languages and powers the native AST, CFG, CPG, PDG, and UAST representations.
GitNexus	Supplies the repository dependency graph scored by COMPOSABLE (`topos depgraph generate`). Requires `npm install -g gitnexus@1.6.8`.
Sighthound	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.

More ways to use Topos

OpenClaw / ClawHub: openclaw skills install @Krv-Labs/topos
Hermes: hermes skills tap add Krv-Labs/topos then hermes skills install Krv-Labs/topos/topos
Agent Plugins: point a compatible client at agent-plugin/ (spec)
MCP Registry name: io.github.Krv-Labs/topos
CLI reference: docs.krv.ai/topos/cli

Distribution

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.

Contributing

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

Related MCP servers

io.github.KryptosAI/agent-observability

Active

Trace AI agent execution: every tool call, every error, every dollar. Open source, local-first.

JavaScript

MIT

View repository →

io.github.KryptosAI/mcp-observatory

Active

MCP security scanner. CI-native testing, attack simulation, health scoring, and SARIF.

TypeScript

MIT

View repository →

io.github.KryptosAI/mcp-seatbelt

Active

MCP runtime security proxy. Blocks dangerous AI agent tool calls with a policy engine.

TypeScript

MIT

View repository →

Krystal Voice Caller

Maintained

Drive a Krystal Voice Caller tenant from Claude, Cursor, or any MCP-aware agent.

Python

MIT

View repository →

KrystalView Analytics

Active

Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.

Python

MIT

View repository →

MailFathom

Active

Security-first, self-hosted email archive with search, cited answers, and sending for AI agents.

Apache-2.0

View repository →