For Agents¶

The Agent Loop

Give any MCP-compatible coding agent a live feed of Topos verdicts so it can evaluate and iterate on its own output.

Topos lets you set the quality target while the agent handles the loop: measure, change, verify, stop when the target or budget is reached.

MCP Setup¶

Start with the path your agent will actually use. The install path should be short; troubleshooting belongs after the client is registered.

Choose an agent path¶

VS Code / Cursor extension

If you use VS Code or an MCP-capable Cursor build, install the Marketplace extension instead of hand-editing MCP JSON:

Topos: Code Quality Targets for Agents

The extension registers a topos-mcp server provider, resolves a bundled, cached, local, or downloaded Topos runtime, and starts topos mcp for agent mode. Topos still runs locally; the editor owns server registration and trust prompts.

Agent CLIs

Run setup from the repository root you want Topos to evaluate. Prefer the CLI-native registration path for your agent so the host owns trust, lifecycle, and status checks.

Manual JSON

Use this for Cursor JSON, Windsurf, or another MCP client that accepts a stdio server configuration.

Add this server configuration in your client’s MCP settings:

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

Setting Preferences¶

A preference ranking is a strict total order over the three quality pillars: simple, composable, and secure. Topos uses the ranking to compute a relaxation walk: the sequence of lattice targets an agent should try when IDEAL is not reachable within the available time or token budget.

Use it when you care about the order of tradeoffs. For example, ["simple", "composable", "secure"] tells the agent to preserve simplicity first, then composability, then security if all three cannot be improved at once.

Rank	Primary Focus	Optimizes toward
1 (Top)	Mandatory	The property that must be achieved first.
2 (Middle)	Aspirational	The secondary goal; forms the “ideal intersection” with Rank 1.
3 (Bottom)	Pragmatic	The final property needed to reach `IDEAL`.

Example Ranking: (SIMPLE, COMPOSABLE, SECURE)

Aspirational target: The agent first tries to reach IDEAL (all three pillars pass).
Pragmatic fallback: If progress stalls, the agent diverts to SIMPLE_COMPOSABLE (the intersection of the top two).

MCP Tools¶

Topos registers sixteen MCP tools. Evaluation, inspection, assessment, coverage, and depgraph tools take a single params object. topos_get_doc takes a direct topic argument.

Most evaluation and assessment tools accept optional preferences with a strict ranking (for example {"ranking": ["simple", "composable", "secure"]}).

Structured responses may include:

agent_contract: Outcome-first guidance: next_tool, next_actions, blocked_by, verification_gates, and risk_flags. Prefer these fields over parsing markdown prose. Common blocked_by values include missing_gitnexus_dir, stale_gitnexus_dir, invalid_gitnexus_dir, and parse_failures.
metric_locations: On topos_evaluate_file and topos_inspect_code, maps failing complexity gates (cfg.cyclomatic, ast.max_function_complexity) to concrete source spans with qualified_name, kind, line range, and nesting info.
suggestions: Actionable fix hints for failing pillars; markdown includes a checklist when present.

Core Evaluation¶

topos_evaluate_file({"params": {"filepath": ..., "preferences": ..., "gitnexus_dir": ..., "include_security_findings": ..., "allow": ..., "verbose": ...}}): Classifies a file on disk. Pass gitnexus_dir to enable the COMPOSABLE pillar and reach higher badges like IDEAL. Missing or rejected GitNexus configuration is reported in warnings, agent_contract.blocked_by, and the COMPOSABLE pillar interpretation. Returns metric_locations for failing complexity gates.
topos_evaluate_code({"params": {"code": ..., "language": ..., "preferences": ..., "allow": ..., "verbose": ...}}): Classifies a raw code string (SIMPLE and SECURE only).
topos_evaluate_project({"params": {"path": ..., "preferences": ..., "gitnexus_dir": ..., "limit": ..., "offset": ..., "include_security_findings": ..., "allow": ..., "verbose": ...}}): Python project rollup with progress reporting and pagination. Returns worst-scoring files first. Use aggregate_floor_verdict for the codebase floor and worst_files / guidance for the next action.
topos_inspect_code({"params": {"code": ..., "filepath": ..., "language": ..., "preferences": ..., "top_n_functions": ..., "allow": ..., "verbose": ...}}): Detailed metric breakdown: top-N functions by complexity (with line numbers and qualified_name), entropy details, and full metric table. Provide exactly one of code or filepath.

Refactor & Iterate¶

topos_assess_worktree_change({"params": {"filepath": ..., "baseline_ref": "HEAD", "preferences": ..., "gitnexus_dir": ..., "include_security_findings": ..., "allow": ...}})

Default edit-in-place loop. Compares the working-tree file to a git baseline (git show <baseline_ref>:<path>). Edit the file, then call this — no snapshot or pasted source required.

topos_begin_refactor({"params": {"filepath": ..., "preferences": ..., "gitnexus_dir": ...}})

Captures the current file as a baseline snapshot before editing. Returns a snapshot_id. Use for untracked files or uncommitted baselines that git cannot serve.

topos_assess_snapshot({"params": {"snapshot_id": ..., "filepath": ..., "include_security_findings": ..., "allow": ...}})

Compares the current on-disk file to a snapshot from topos_begin_refactor.

topos_assess_improvement({"params": {"filepath": ..., "current_code": ..., "proposed_code": ..., "proposed_filepath": ..., "language": ..., "preferences": ..., "gitnexus_dir": ..., "include_security_findings": ..., "allow": ...}})

Side-by-side variant assessment. Provide exactly one of filepath or current_code and exactly one of proposed_code or proposed_filepath.

Anti-gaming check: if scores improved but AST edit distance is near zero, it returns SUSPICIOUS_NO_STRUCTURAL_CHANGE.

When SECURE fails, file-level assessment includes security_findings with the dangerous callee, line, and source snippet.

topos_assess_changeset({"params": {"files": [...], "baseline_ref": "HEAD", "preferences": ..., "gitnexus_dir": ..., "include_security_findings": ..., "allow": ...}})

Multi-file / module-split assessment (read-only). Each file is compared to the git baseline; new files have no baseline. Returns per-file verdicts, a project rollup (aggregate_before / aggregate_after), and flags complexity_relocated_within_file and project_regression. When COMPOSABLE is blocked, call topos_generate_depgraph first, then re-assess.

topos_preference_walk({"params": {"ranking": ..., "target": ..., "current": ...}})

Returns the concrete relaxation walk (sequence of Quality Badges) the agent should follow to reach the target from its current state.

Dependency Graph¶

topos_depgraph_status({"params": {"gitnexus_dir": ...}}): Read-only .gitnexus state: missing, present, stale, load_error, schema_mismatch, or invalid_dir (a bad gitnexus_dir override). Staleness is anchored to the commit the graph was built from (falling back to file mtimes for graphs built before that marker existed), so a regenerate reliably clears stale. Never shells out.
topos_generate_depgraph({"params": {"directory": ...}}): Runs gitnexus analyze and writes .gitnexus/. Side-effecting and approval-gated. Requires the gitnexus CLI (npm install -g gitnexus).

Structure & Coverage¶

topos_compare_files({"params": {"source": ..., "target": ...}}): AST edit distance (topological drift) between two files on disk.
topos_compare_code({"params": {"source_code": ..., "target_code": ..., "language": ...}}): AST edit distance (topological drift) between two code strings.
topos_calculate_coverage({"params": {"put_files": ..., "test_files": ..., "language": ..., "k": ..., "include_unknown": ..., "coverage_threshold": ...}}): Calculates structural test coverage (UAST declaration matching and k-gram recall). Coverage is a separate signal; it does not change the SIMPLE / COMPOSABLE / SECURE lattice verdict.

Agent Knowledge¶

topos_get_doc(topic): Retrieves Topos documentation (agent-contract, workflows, lattice, metrics, preferences, or priority) as Markdown. Use it when the client does not expose MCP resource fetching to the model.

MCP Prompt¶

topos_refactor_until_ideal(filepath, priority, max_iterations, preferences): Returns a compact refactor-loop prompt with the baseline measure call, inspection call, improvement-assessment call, and acceptance gates. Use it when a client exposes MCP prompts directly.

MCP Resources¶

Topos exposes these Markdown resources. Clients may surface them as browsable resources, attachable context, or direct agent context depending on host support:

topos://docs/agent-contract — compact outcome-first loop contract and done gates
topos://docs/workflows — expanded review → plan → refactor → re-measure guide
topos://docs/lattice — the 8-element Quality Badge lattice
topos://docs/metrics — every metric key, pillar, and threshold
topos://docs/priority — priority profiles (simple / composable / secure)
topos://docs/preferences — strict generator rankings and preference walks