AST-Navigator-MCP

Overview Schema Source Related Servers Discussions Admin

Get File Structure (AST outline)

get_file_structure

Read-onlyIdempotent

Outline a JavaScript/TypeScript file's imports, classes, functions, and types with line ranges and signatures to reveal its API and dependencies without reading the whole file.

Instructions

Outline one JavaScript/TypeScript source file from its Tree-sitter syntax tree: imports (ESM, CommonJS require, re-exports), classes with their properties and methods, top-level functions (declarations, arrow functions, function expressions, CommonJS exports) and TypeScript interfaces / type aliases / enums, each with 1-based line ranges and signatures exactly as written.

Use it to learn a file's API and dependencies without reading the whole file, and to find which lines to read next. It does not return function bodies or nested local helpers.

Args:

filePath (string): file to analyse (.js .mjs .cjs .jsx .ts .mts .cts .tsx). Absolute path recommended.
responseFormat ('markdown' | 'json'): 'markdown' (default) is a compact outline; 'json' returns the full object.

Returns (structuredContent, identical to the 'json' text): { filePath, language, lineCount, hasSyntaxErrors, syntaxErrorLines[], imports[{ source, kind: esm|commonjs|re-export, typeOnly, specifiers[{ kind, name, importedName? }], line }], classes[{ name, exported, defaultExport, abstract, extends?, implements[], properties[{ name, static, readonly, visibility?, type?, line }], methods[{ name, kind: constructor|method|getter|setter, static, async, abstract, visibility?, signature, startLine, endLine }], startLine, endLine }], functions[{ name, kind: function|generator|arrow|function_expression|signature, async, exported, defaultExport, signature, startLine, endLine }], types[{ name, kind: interface|type_alias|enum, exported, startLine, endLine }] }

Examples:

"What does src/server.ts export?" -> { filePath: "/repo/src/server.ts" }
Need exact field values for code generation -> add responseFormat: "json"

Errors (isError=true, text starts with 'Error [CODE]'): FILE_NOT_FOUND, PERMISSION_DENIED, NOT_A_FILE, FILE_TOO_LARGE (> 2 MiB), PATH_OUTSIDE_ROOTS, INVALID_PATH. Unsupported extensions are rejected by input validation. If hasSyntaxErrors is true the outline is best-effort.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "filePath": "<filePath>"
    },
    "name": "get_file_structure"
  }
}

Input Schema

Name	Required	Description	Default
`filePath`	Yes	Source file to outline. Absolute path recommended, e.g. 'C:\repo\src\index.ts' or '/home/me/repo/src/index.ts'. Relative paths resolve against the server's first allowed root.
`responseFormat`	No	'markdown' (default): compact outline for reading. 'json': full structured data.	markdown

Output Schema

Name	Required	Description
`types`	Yes	TypeScript interfaces, type aliases and enums
`classes`	Yes
`imports`	Yes
`filePath`	Yes	Absolute path of the analysed file
`language`	Yes	Grammar used to parse the file
`functions`	Yes
`lineCount`	Yes
`hasSyntaxErrors`	Yes	Tree-sitter recovered from syntax errors; the outline may be incomplete
`syntaxErrorLines`	Yes	First lines where syntax errors were detected

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Oct 28, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: a 2 MiB size cap, the six error codes returned with isError=true, path-root restrictions, the accepted extension whitelist, and the important caveat that output is best-effort when hasSyntaxErrors is true. That is exactly the kind of operational detail annotations cannot convey.

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?

Well front-loaded: purpose and scope come first, then Args, Returns, Examples, and Errors in a scannable order. The main redundancy is the large Returns block, which restates an output schema that the agent already receives, and an Args section that repeats a 100%-covered schema — both partially waste budget, though the rest of the text earns its place.

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?

For a two-parameter read-only tool this is thorough: the agent knows what is extracted, what is deliberately omitted, which formats are available, what failures look like, and how to interpret partially broken files. With an output schema present, the detailed return-shape listing is optional rather than necessary, and nothing an agent needs to call it correctly is missing.

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% and already documents both parameters including the absolute-path recommendation, so the schema carries most of the load. The description still adds value the schema lacks: the explicit list of supported extensions (.js .mjs .cjs .jsx .ts .mts .cts .tsx) and the note that unsupported extensions are rejected at input validation.

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 and resource — 'Outline one JavaScript/TypeScript source file from its Tree-sitter syntax tree' — and enumerates exactly what is extracted (imports, classes, functions, types) with line ranges and signatures. It also bounds the resource to a single file and explicitly excludes function bodies and nested local helpers, which separates it from the repo-wide concerns of analyze_dependencies.

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

Usage Guidelines4/5

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

Gives a concrete when-to-use rationale: 'learn a file's API and dependencies without reading the whole file, and to find which lines to read next,' backed by two worked examples including the json variant for code generation. It never names an explicit alternative tool or a when-not-to-use condition, so routing against find_definition/analyze_dependencies is inferred rather than stated.

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

Deploy Server