Skip to main content
Glama
Sign In
reforge-mcp

reforge-mcp

by Codewithaiyan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

scan_repo

Read-onlyIdempotent

Scan a repository’s source files for dead code, duplicates, oversized modules, and dependencies to gather findings before planning code changes.

Instructions

Scan source files for dead code, duplicates, oversized modules, and dependencies. Use when: you need repository-wide findings before planning changes. Don't use when: you only need source lines from a known file (use get_chunk instead).

Returns {summary, dead_code, duplicates, god_files, dep_graph, subprojects}. Summary includes file/symbol/line counts, languages, parse_failures and unscanned-source counts. Findings carry file paths and 1-indexed lines; dep_graph has nodes, {from, to} edges, circular paths, external_imports, unresolved_relative_imports and package_imports counts. A missing/non-directory root or a path-validation failure returns error, empty findings/graph and a zero summary, without subprojects. Lists are capped at 200 items, duplicate groups at 50 and their locations at 10; shortened lists gain _total, with truncated listing shortened top-level/graph lists. Summary counts remain complete. In a nonempty Git index, only tracked files are analysed; outside Git, all eligible files are.

Input Schema

NameRequiredDescriptionDefault
languagesNoOptional case-insensitive language filter: python, javascript, typescript, go, kotlin. Default null (or []) scans all supported languages; unknown names are ignored. Example: ['python', 'typescript'].
root_pathYesExisting source directory to scan; prefer an absolute path, e.g. /work/app. Relative paths resolve from the server working directory.
include_testsNoDefaults to true. Currently accepted for compatibility but does not filter test files: both true and false include them.

Output Schema

NameRequiredDescriptionDefault
errorNo
summaryYes
dead_codeYes
dep_graphYes
god_filesYes
truncatedNo
duplicatesYes
subprojectsNo
dead_code_totalNo
god_files_totalNo
duplicates_totalNo
subprojects_totalNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.4.5
    • addedInput schema / properties / include_tests / description
      Added value: +"Defaults to true. Currently accepted for compatibility but does not filter test files: both true and false include them."
    • addedInput schema / properties / languages / description
      Added value: +"Optional case-insensitive language filter: python, javascript, typescript, go, kotlin. Default null (or []) scans all supported languages; unknown names are ignored. Example: ['python', 'typescript']."
    • addedInput schema / properties / root_path / description
      Added value: +"Existing source directory to scan; prefer an absolute path, e.g. /work/app. Relative paths resolve from the server working directory."
    • removedOutput schema / additionalProperties
      Removed value: -true
    • addedOutput schema / properties
      Added value: +{
+  "dead_code": {
+    "items": {
+      "properties": {
+        "file": {
+          "type": "string"
+        },
+        "line": {
+          "type": "integer"
+        },
+        "symbol": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "symbol",
+        "file",
+        "line"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "dead_code_total": {
+    "type": "integer"
+  },
+  "dep_graph": {
+    "properties": {
+      "circular": {
+        "items": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "type": "array"
+      },
+      "circular_total": {
+        "type": "integer"
+      },
+      "edges": {
+        "items": {
+          "properties": {
+            "from": {
+              "type": "string"
+            },
+            "to": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "from",
+            "to"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "edges_total": {
+        "type": "integer"
+      },
+      "external_imports": {
+        "type": "integer"
+      },
+      "nodes": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "nodes_total": {
+        "type": "integer"
+      },
+      "package_imports": {
+        "type": "integer"
+      },
+      "unresolved_relative_imports": {
+        "type": "integer"
+      }
+    },
+    "required": [
+      "nodes",
+      "edges",
+      "circular"
+    ],
+    "type": "object"
+  },
+  "duplicates": {
+    "items": {
+      "properties": {
+        "hash": {
+          "type": "string"
+        },
+        "locations": {
+          "items": {
+            "properties": {
+              "file": {
+                "type": "string"
+              },
+              "line": {
+                "type": "integer"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "file",
+              "line",
+              "name"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "locations_total": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "hash",
+        "locations"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "duplicates_total": {
+    "type": "integer"
+  },
+  "error": {
+    "type": "string"
+  },
+  "god_files": {
+    "items": {
+      "properties": {
+        "exports": {
+          "type": "integer"
+        },
+        "file": {
+          "type": "string"
+        },
+        "lines": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "file",
+        "lines",
+        "exports"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "god_files_total": {
+    "type": "integer"
+  },
+  "subprojects": {
+    "items": {
+      "properties": {
+        "language": {
+          "type": "string"
+        },
+        "root": {
+          "type": "string"
+        },
+        "test_command": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "root",
+        "language",
+        "test_command"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  },
+  "subprojects_total": {
+    "type": "integer"
+  },
+  "summary": {
+    "properties": {
+      "imported_modules": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "languages_detected": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "parse_failures": {
+        "type": "integer"
+      },
+      "total_classes": {
+        "type": "integer"
+      },
+      "total_files": {
+        "type": "integer"
+      },
+      "total_functions": {
+        "type": "integer"
+      },
+      "total_imports": {
+        "type": "integer"
+      },
+      "total_lines": {
+        "type": "integer"
+      },
+      "unscanned_by_extension": {
+        "additionalProperties": {
+          "type": "integer"
+        },
+        "type": "object"
+      },
+      "unscanned_source_files": {
+        "type": "integer"
+      },
+      "untracked_files_skipped": {
+        "type": "integer"
+      }
+    },
+    "required": [
+      "total_files",
+      "total_functions",
+      "total_lines",
+      "languages_detected"
+    ],
+    "type": "object"
+  },
+  "truncated": {
+    "additionalProperties": {
+      "type": "integer"
+    },
+    "type": "object"
+  }
+}
    • addedOutput schema / required
      Added value: +[
+  "summary",
+  "dead_code",
+  "duplicates",
+  "god_files",
+  "dep_graph"
+]
  2. Changed1 schema field changedv0.4.3
    • removedInput schema / properties / max_depth
      Removed value: -{
-  "default": 10,
-  "type": "integer"
-}
  3. Addedv0.2.9

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: it discloses the truncation caps (200 items, 50 duplicate groups, 10 locations), the <key>_total companion fields, the guarantee that summary counts stay complete, the Git-index-only-tracked-files rule, and the degraded error response for a bad root. These are non-obvious behaviors an agent could not infer from annotations.

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 purpose, then a when/when-not pair, then return shape, then edge cases and caps — a logical order with no filler sentences. It loses a point for density: the truncation sentence ('shortened lists gain <key>_total, with truncated listing shortened top-level/graph lists') is syntactically tangled and would benefit from restructuring.

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

Completeness4/5

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

For a three-parameter, read-only analysis tool this covers purpose, alternatives, failure modes, and truncation, leaving little an agent needs missing. Since an output schema exists, the detailed return-field enumeration and summary-contents description are partly redundant, which keeps it just short of a 5.

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

Parameters3/5

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

Schema description coverage is 100%, so root_path, languages, and include_tests are already fully documented in the schema, including the include_tests no-op caveat. The description adds indirect meaning by explaining that Git index state changes which files under root_path are analysed, but it adds no new detail about the parameter values themselves. Baseline 3 applies.

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 ('Scan source files') and enumerates exactly what is detected: dead code, duplicates, oversized modules, dependencies. It also explicitly positions itself against the sibling get_chunk, so an agent can distinguish the two without opening a schema.

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?

Provides an explicit 'Use when' (repository-wide findings before planning changes) and an explicit 'Don't use when' that names the alternative tool (get_chunk) and the condition selecting it. This is the strongest form of routing guidance available.

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

Deploy Server

Other Tools