topos-mcp

Overview Schema Source Related Servers Discussions Admin

topos_evaluate_project

Score all supported source files in a project directory on the SIMPLE/COMPOSABLE/SECURE/NAVIGABLE lattice, returning a project rollup with paginated per-file results.

Instructions

Recursively score every supported source file in a directory on the SIMPLE / COMPOSABLE / SECURE / NAVIGABLE lattice, with a project rollup (side-effecting). Autodetects all supported languages (Python, Rust, JavaScript, TypeScript, C++, Go) in one walk — no language argument — and skips unsupported files. The rollup takes the project-wide minimum per dimension (weakest file floors it). Returns page-global named lists (hard_fails, leaf_composable_zeros, maintainability_giants) plus a paginated per-file table (gate failures first); page with limit / offset. Unless no_composable is set, generates/refreshes .gitnexus when missing or stale before scoring, same as topos_evaluate_file and the CLI's topos evaluate — coupling_available/warnings explain it when that isn't possible, without failing the evaluation. Do not call this for one file, or after a file already passed. It walks the tree. A person asks for the project rollup; an agent editing one file does not.

Input Schema

TableJSON Schema

Name	Required	Description
`path`	Yes	Directory to evaluate, walked recursively. Must resolve inside the trusted file root; paths outside it are refused. All supported languages are autodetected — no language argument is needed.
`allow`	No	Dangerous-call patterns to acknowledge for this run only.
`limit`	No	Per-file rows to return per page (1–500, default 25).
`offset`	No	Zero-based row offset for pagination; pass the response's `next_offset` to fetch the next page.
`verbose`	No	When true, include each file's raw metric values alongside scores.
`preferences`	No	Optional ranking of simple/composable/secure (best first). The top-ranked generator sets scorer priority; omit to default to SIMPLE priority.
`gitnexus_dir`	No	`.gitnexus` store under the MCP file root (default: `<file root>/.gitnexus`). Freshness and regeneration always use the file root as the project root; this only selects the store path inside it. If missing or stale, this tool generates/refreshes first (see `no_composable`). If generation isn't possible, COMPOSABLE is reported as unavailable rather than failing the whole evaluation.
`no_composable`	No	Skip GitNexus detection/generation; score SIMPLE/SECURE/NAVIGABLE only, exactly like a missing `.gitnexus` did before this tool started generating it automatically.
`include_security_findings`	No	When true, attach per-file SECURE findings to each entry; off by default to keep responses compact.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.5.0Aug 9, 2026

changedInput schema / $defs / GeneratorInput / enum

Previous value: -[
-  "simple",
-  "composable",
-  "secure"
-]New value: +[
+  "simple",
+  "composable",
+  "secure",
+  "navigable"
+]

changedInput schema / $defs / LatticeElement / description

Previous value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."

changedInput schema / $defs / LatticeElement / enum

Previous value: -[
-  "SLOP",
-  "SIMPLE",
-  "COMPOSABLE",
-  "SECURE",
-  "SIMPLE_COMPOSABLE",
-  "SIMPLE_SECURE",
-  "COMPOSABLE_SECURE",
-  "IDEAL"
-]New value: +[
+  "SLOP",
+  "SIMPLE",
+  "COMPOSABLE",
+  "SIMPLE_COMPOSABLE",
+  "SECURE",
+  "SIMPLE_SECURE",
+  "COMPOSABLE_SECURE",
+  "SIMPLE_COMPOSABLE_SECURE",
+  "NAVIGABLE",
+  "SIMPLE_NAVIGABLE",
+  "COMPOSABLE_NAVIGABLE",
+  "SIMPLE_COMPOSABLE_NAVIGABLE",
+  "SECURE_NAVIGABLE",
+  "SIMPLE_SECURE_NAVIGABLE",
+  "COMPOSABLE_SECURE_NAVIGABLE",
+  "IDEAL"
+]

changedInput schema / $defs / UserPreferencesInput / description

Previous value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."

changedInput schema / $defs / UserPreferencesInput / properties / ranking / description

Previous value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."

changedInput schema / properties / no_composable / description

Previous value: -"Skip GitNexus detection/generation; score SIMPLE/SECURE only,\nexactly like a missing `.gitnexus` did before this tool started\ngenerating it automatically."New value: +"Skip GitNexus detection/generation; score SIMPLE/SECURE/NAVIGABLE\nonly, exactly like a missing `.gitnexus` did before this tool\nstarted generating it automatically."

Changed1 schema field changedv0.4.4Aug 5, 2026

changedInput schema / properties / gitnexus_dir / description

Previous value: -"Path to a `.gitnexus` dependency-graph directory, for COMPOSABLE\nscoring. When omitted, it is auto-detected from the project root;\nif missing or stale, this tool generates/refreshes it first (see\n`no_composable`). If generation isn't possible (GitNexus not\ninstalled, generation failure), COMPOSABLE is reported as\nunavailable rather than failing the whole evaluation."New value: +"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness and regeneration always use the\nfile root as the project root; this only selects the store path\ninside it. If missing or stale, this tool generates/refreshes first\n(see `no_composable`). If generation isn't possible, COMPOSABLE is\nreported as unavailable rather than failing the whole evaluation."

Changed13 schema fields changedv0.4.0Jul 27, 2026

addedInput schema / $defs

Added value: +{
+  "GeneratorInput": {
+    "description": "Wire form of a generator name.",
+    "enum": [
+      "simple",
+      "composable",
+      "secure"
+    ],
+    "type": "string"
+  },
+  "LatticeElement": {
+    "description": "The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire.",
+    "enum": [
+      "SLOP",
+      "SIMPLE",
+      "COMPOSABLE",
+      "SECURE",
+      "SIMPLE_COMPOSABLE",
+      "SIMPLE_SECURE",
+      "COMPOSABLE_SECURE",
+      "IDEAL"
+    ],
+    "type": "string"
+  },
+  "UserPreferencesInput": {
+    "additionalProperties": false,
+    "description": "Strict ranking over simple, composable, and secure.",
+    "properties": {
+      "ranking": {
+        "description": "Permutation of simple/composable/secure, best first.",
+        "items": {
+          "$ref": "#/$defs/GeneratorInput"
+        },
+        "type": "array"
+      },
+      "target": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/LatticeElement"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Optional explicit target verdict."
+      }
+    },
+    "required": [
+      "ranking"
+    ],
+    "type": "object"
+  }
+}

addedInput schema / $schema

Added value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / properties / allow

Added value: +{
+  "default": [],
+  "description": "Dangerous-call patterns to acknowledge for this run only.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / gitnexus_dir

Added value: +{
+  "default": null,
+  "description": "Path to a `.gitnexus` dependency-graph directory, for COMPOSABLE\nscoring. When omitted, it is auto-detected from the project root;\nif missing or stale, this tool generates/refreshes it first (see\n`no_composable`). If generation isn't possible (GitNexus not\ninstalled, generation failure), COMPOSABLE is reported as\nunavailable rather than failing the whole evaluation.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / include_security_findings

Added value: +{
+  "default": false,
+  "description": "When true, attach per-file SECURE findings to each entry; off by\ndefault to keep responses compact.",
+  "type": "boolean"
+}

addedInput schema / properties / limit

Added value: +{
+  "default": 25,
+  "description": "Per-file rows to return per page (1–500, default 25).",
+  "format": "uint",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / no_composable

Added value: +{
+  "default": false,
+  "description": "Skip GitNexus detection/generation; score SIMPLE/SECURE only,\nexactly like a missing `.gitnexus` did before this tool started\ngenerating it automatically.",
+  "type": "boolean"
+}

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Zero-based row offset for pagination; pass the response's\n`next_offset` to fetch the next page.",
+  "format": "uint",
+  "minimum": 0,
+  "type": "integer"
+}

removedInput schema / properties / params

Removed value: -{
-  "additionalProperties": false,
-  "description": "Arguments for ``topos_evaluate_project``.",
-  "properties": {
-    "allow": {
-      "description": "Dangerous-call patterns to acknowledge for this run only (e.g. `subprocess.run`), suppressing their SECURE penalty without changing stored preferences.",
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "gitnexus_dir": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Path to a `.gitnexus` dependency-graph directory, required for COMPOSABLE scoring. When omitted, it is auto-detected from the project root; if none is found, COMPOSABLE is reported as unavailable rather than failing."
-    },
-    "include_security_findings": {
-      "default": false,
-      "description": "When true, attach per-file SECURE findings (dangerous-call locations) to each entry; off by default to keep responses compact.",
-      "type": "boolean"
-    },
-    "limit": {
-      "default": 25,
-      "description": "Per-file rows to return per page (1–500, default 25).",
-      "maximum": 500,
-      "minimum": 1,
-      "type": "integer"
-    },
-    "offset": {
-      "default": 0,
-      "description": "Zero-based row offset for pagination; pass the response's `next_offset` to fetch the next page.",
-      "minimum": 0,
-      "type": "integer"
-    },
-    "path": {
-      "description": "Directory to evaluate, walked recursively. Must resolve inside the trusted file root; paths outside it are refused. All supported languages are autodetected — no language argument is needed.",
-      "minLength": 1,
-      "type": "string"
-    },
-    "preferences": {
-      "anyOf": [
-        {
-          "additionalProperties": false,
-          "description": "Strict ranking over simple, composable, and secure.",
-          "properties": {
-            "ranking": {
-              "description": "Permutation of simple/composable/secure, best first.",
-              "items": {
-                "description": "The three quality generators of ``G_qual``.",
-                "enum": [
-                  "simple",
-                  "composable",
-                  "secure"
-                ],
-                "type": "string"
-              },
-              "maxItems": 3,
-              "minItems": 3,
-              "type": "array"
-            },
-            "target": {
-              "anyOf": [
-                {
-                  "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
-                  "enum": [
-                    "SLOP",
-                    "SIMPLE",
-                    "COMPOSABLE",
-                    "SECURE",
-                    "SIMPLE_COMPOSABLE",
-                    "SIMPLE_SECURE",
-                    "COMPOSABLE_SECURE",
-                    "IDEAL"
-                  ],
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "default": null,
-              "description": "Optional explicit target verdict."
-            }
-          },
-          "required": [
-            "ranking"
-          ],
-          "type": "object"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Optional ranking of simple/composable/secure (best first). The top-ranked generator sets scorer priority; omit to default to SIMPLE priority."
-    },
-    "verbose": {
-      "default": false,
-      "description": "When true, include each file's raw metric values (entropy, complexity, instability) alongside the scores.",
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "path"
-  ],
-  "type": "object"
-}

addedInput schema / properties / path

Added value: +{
+  "description": "Directory to evaluate, walked recursively. Must resolve inside the\ntrusted file root; paths outside it are refused. All supported\nlanguages are autodetected — no language argument is needed.",
+  "type": "string"
+}

addedInput schema / properties / preferences

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/UserPreferencesInput"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Optional ranking of simple/composable/secure (best first). The\ntop-ranked generator sets scorer priority; omit to default to\nSIMPLE priority."
+}

addedInput schema / properties / verbose

Added value: +{
+  "default": false,
+  "description": "When true, include each file's raw metric values alongside scores.",
+  "type": "boolean"
+}

changedInput schema / required

Previous value: -[
-  "params"
-]New value: +[
+  "path"
+]

First observedv0.3.6Jul 2, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only give the coarse profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false); the description goes well beyond by disclosing the concrete side effect — generating/refreshing `.gitnexus` when missing or stale — and the graceful-degradation path (`coupling_available`/`warnings`, COMPOSABLE reported unavailable rather than failing). It also describes the rollup aggregation rule (project-wide minimum per dimension) and pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and scope, then the side effect, then the negative guidance. Every sentence carries information, though the description runs long and the middle section on `.gitnexus` behavior is dense enough that it could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by describing the return shape: page-global named lists (`hard_fails`, `leaf_composable_zeros`, `maintainability_giants`) plus a paginated per-file table with gate failures first, along with how to page. Combined with the side-effect and failure-mode disclosure, an agent has everything needed for this 9-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it clarifies that no language argument exists (all languages autodetected in one walk), explains the `limit`/`offset` paging contract in prose, and ties `no_composable` to the `.gitnexus` auto-generation behavior rather than leaving it as a bare flag.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource with scope: 'Recursively score every supported source file in a directory on the SIMPLE/COMPOSABLE/SECURE/NAVIGABLE lattice, with a project rollup'. It also names what it is not ('Do not call this for one file'), implicitly routing to topos_evaluate_file, so an agent can separate it from siblings without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-not guidance ('Do not call this for one file, or after a file already passed. It walks the tree') plus an intent-based selection rule ('A person asks for the project rollup; an agent editing one file does not'). The alternative (topos_evaluate_file / the CLI's `topos evaluate`) is named explicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

topos_evaluate_project

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools