This server lets you analyze and refactor Python codebases structurally using AST, without loading raw files into an LLM context.
Parse a Python file into an AST outline: docstrings, imports, classes, functions, variables, and line counts.
Retrieve all methods of a specific class with signatures, type annotations, line ranges, and docstrings.
Recursively search directories or files for classes, functions, methods, or variables by name.
Build an import dependency graph and output it as a Mermaid diagram string.
Audit docstring coverage across a codebase, including optional private items, and get missing docstring details.
Generate a structured refactoring prompt for a file via the refactor_code_summary prompt.
Access workspace statistics (files scanned, docstring coverage, missing counts) via the codeast://stats resource.
Analyzes Python codebases by extracting AST outlines, symbols, classes, methods, import dependency graphs, and docstring coverage.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@code-ast-mcp analyze the AST of src/utils.py"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
code-ast-mcp)
code-ast-mcp is an architectural Model Context Protocol (MCP) server built with Python's native Abstract Syntax Tree (ast) parser. It allows AI models (in Claude Desktop, Cursor, Antigravity, or custom MCP clients) to analyze Python codebase structures, search symbol definitions, build dependency graphs, audit docstring coverage, and refactor code without loading entire raw source files into LLM context windows.
🔗 Live Repository: https://github.com/m-sameerkhan/code-ast-mcp
🔗 Glama Registry: https://glama.ai/mcp/servers/m-sameerkhan/code-ast-mcp
analyze_file_ast(file_path: str)
Parses a .py file into a clean AST outline.
Extracts module docstrings, line counts, imports, top-level functions, classes, methods, and variables.
find_class_methods(file_path: str, class_name: str)
Locates a specific class and returns method signatures, type annotations, line ranges, and docstrings.
find_symbol(target_dir: str, symbol_name: str)
Recursively searches a directory for classes, functions, methods, or variable assignments matching symbol_name.
get_imports_graph(target_dir: str)
Scans Python files to build a dependency import map and outputs a Mermaid diagram string.
find_missing_docstrings(target_dir: str, include_private: bool = False)
Audits codebase docstrings and calculates overall docstring coverage percentage.
refactor_code_summary(file_path: str)
Generates a structured prompt instructing the LLM to review the AST outline of a file and propose refactoring, design pattern improvements, and documentation fixes.
codeast://stats
Live JSON resource providing workspace statistics (total files scanned, docstring coverage %, missing item counts).
Related MCP server: codeweave-mcp
Deploy code-ast-mcp to the Glama MCP Registry — Glama automatically clones your GitHub repo, builds it using the included Dockerfile, and hosts it with built-in OAuth 2.1, monitoring, and access control.
Go to glama.ai/mcp/servers.
Click "Add Server".
Authenticate with GitHub OAuth (you must have write access to the repo).
Submit the repository URL:
https://github.com/m-sameerkhan/code-ast-mcpGlama will auto-build using the Dockerfile and verify MCP compliance.
Once the build succeeds, your server will be live on the Glama registry.
https://glama.ai/mcp/servers/m-sameerkhan/code-ast-mcpNote: No manual hosting required — Glama handles building, deployment, and verification automatically.
Best for inspecting local Python projects directly on your machine in Claude Desktop, Cursor, or Antigravity.
git clone https://github.com/m-sameerkhan/code-ast-mcp.git
cd code-ast-mcp
# Virtual environment setup
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .claude_desktop_config.json / mcp_config.json):{
"mcpServers": {
"code-ast-mcp": {
"command": "python",
"args": [
"-m",
"code_ast_mcp.server"
],
"cwd": "/path/to/code-ast-mcp"
}
}
}pytestnpx @modelcontextprotocol/inspector python -m code_ast_mcp.servercode-ast-mcp/
├── code_ast_mcp/ # Core MCP package
│ ├── __init__.py # Package exports
│ ├── analyzer.py # Python AST parsing & static analysis engine
│ └── server.py # FastMCP server definition & tool handlers
├── tests/ # Test suite
│ └── test_analyzer.py # Unit tests with pytest
├── Dockerfile # Container image definition (used by Glama)
├── pyproject.toml # Packaging & metadata
└── requirements.txt # DependenciesMIT License. Created by m-sameerkhan.
Parse a Python file using Python's AST parser and return a detailed outline of its docstrings, imports, top-level classes, functions, variables, and line counts.
:param file_path: Path to the Python (.py) file to analyze.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations (readOnlyHint, destructiveHint) are provided, so the description must carry the full burden of disclosing side effects. It states 'parse' which implies a read-only operation, but it does not explicitly state that the file is not modified, nor does it mention authentication, rate limits, or other behavioral aspects. The description is vague about non-obvious behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action ('Parse a Python file') and then lists the elements of the returned outline. There is no unnecessary verbosity or repetition; every part contributes to the understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple (single parameter, clear output), and an output schema exists (though not detailed here). The description sufficiently conveys what the tool does and what the outline contains, so the user can predict the result. It does not cover error conditions or edge cases, but these are not critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter, 'file_path', with full coverage in the schema (name and type are provided). The description does not add extra meaning about the parameter, such as path format or constraints. Since schema coverage is high, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: parsing a Python file with AST and returning a detailed outline of its components (docstrings, imports, classes, functions, variables, line counts). It uses a specific verb ('parse') and resource ('Python file'), and distinguishes itself from sibling tools by offering a broad outline rather than focused analyses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not mention when to use this tool versus the sibling tools (e.g., find_class_methods, get_imports_graph). No explicit use cases, conditions, or alternatives are provided. Users must infer from the description that it is appropriate for a general overview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Locate a specific class within a Python file and retrieve all its methods, argument signatures, type annotations, line numbers, and docstrings.
:param file_path: Path to the Python file containing the class. :param class_name: Name of the target class to inspect.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | ||
| class_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden and does clearly state what is inspected and returned. However, it does not disclose error behavior (e.g., class not found) or explicitly note that this is a read-only AST-level inspection, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one purpose sentence followed by two param lines. Every sentence earns its place, with no filler or repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter inspection tool with an output schema, the description adequately covers purpose and parameter meanings. It omits usage alternatives and failure behavior, but the output schema handles return-structure documentation, so this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description gives meaningful one-sentence docs for both parameters: file_path and class_name. This adds value beyond the raw schema, though it could have included more nuance such as path resolution or whether class_name needs to be fully qualified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Locate') and resource ('a specific class within a Python file'), then enumerates exact outputs: methods, argument signatures, type annotations, line numbers, and docstrings. This clearly distinguishes it from sibling tools like analyze_file_ast and find_symbol, which have broader or different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool instead of analyze_file_ast or find_symbol, and no exclusions or prerequisites are provided. The use case is only implied by the description of locating a class and retrieving its methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit Python files in a directory to identify modules, classes, and functions that lack docstrings, calculating overall docstring coverage percentage.
:param target_dir: Directory path to audit. :param include_private: Whether to include private functions/methods (starting with '_').
| Name | Required | Description | Default |
|---|---|---|---|
| target_dir | Yes | ||
| include_private | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description gives no information about side effects, permissions, or whether the tool is read-only. The word 'Audit' implies non-destructive, but this is not explicit, and with no annotations, the burden falls entirely on the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb 'Audit' and the core functionality. It is well-structured and free of unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description conveys the main function and outcome (coverage percentage), it lacks detail on the output format, how the audit is performed, and what 'include_private' entails. This leaves gaps in understanding, given the simple schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for parameters (target_dir, include_private). The description mentions 'directory' indirectly but does not explain either parameter in detail, especially include_private. The description fails to compensate for the lack of schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to audit Python files for missing docstrings and calculate coverage percentage. It specifies the verb 'Audit', the resource 'Python files', and the scope (modules, classes, functions), distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, use cases, or exclusions, offering no explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recursively search a directory or file for classes, functions, methods, or variables matching the target symbol name.
:param target_dir: Directory path or file path to search. :param symbol_name: Name or partial name of the symbol to search for.
| Name | Required | Description | Default |
|---|---|---|---|
| target_dir | Yes | ||
| symbol_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It conveys recursive traversal, accepts both file and directory paths, performs partial-name matching, and searches for four symbol categories. This meaningfully reveals behavior beyond the schema, though it does not explicitly mention side-effect safety or whether hidden files/symlinks are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the core behavioral sentence appearing first. The parameter documentation adds value without redundancy, and every sentence contributes to understanding the tool's action or invocation parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a relatively simple two-parameter search tool, especially since an output schema is provided and return-value details need not be repeated. It lacks explicit alternative tool references, but given the output schema and simple parameter model, the description is largely complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema offers only parameter titles with 0% description coverage, so the description fully compensates. It clarifies that target_dir may be either a directory or file path, and that symbol_name can be a full name or partial fragment, giving the agent the exact operational meaning needed to invoke the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Recursively search') applied to a distinct resource ('directory or file') with a defined target ('classes, functions, methods, or variables'). It also identifies a key matching behavior (name or partial name), which sets it apart from sibling tools like find_class_methods or analyze_file_ast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use for finding symbols recursively across a directory or file, but it never explicitly states when to choose it over alternatives or when not to use it. The sibling tools are not mentioned, so the agent must infer the difference from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan all Python files in a directory to build an import dependency graph and output both a structured map and a Mermaid diagram definition.
:param target_dir: Path to the directory containing Python files.
| Name | Required | Description | Default |
|---|---|---|---|
| target_dir | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does state the core behavior and output types. However, it leaves important behavior unspecified, such as whether traversal is recursive, how non-Python or unreadable files are handled, and whether the operation is read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a param docstring, front-loaded with the primary action and outputs. No redundant wording or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool, the basics are covered (input directory and output format), and an output schema exists to define return values. Yet it omits traversal scope and edge-case behavior, and the absence of annotations leaves safety/prerequisite details unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the docstring provides direct semantics: target_dir is a path to a directory containing Python files. That fully compensates for the single parameter, though it does not add details like recursive traversal that might affect the parameter's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb+resource: scan Python files in a directory to build an import dependency graph, and names two concrete outputs (structured map, Mermaid diagram). This clearly differentiates it from sibling tools that analyze individual symbols, files, or docstrings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The scope 'all Python files in a directory' implies when to use it, contrasting with per-file or symbol-level tools, but there is no explicit when-not-to-use statement or named alternative. It also does not mention prerequisites like valid directory permissions or expected input type beyond a path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0analyze_file_astfind_class_methodsfind_missing_docstringsfind_symbolget_imports_graphEach tool has a distinct role: file outline, class methods, symbol search, import graph, and docstring audit. There is minor overlap because analyze_file_ast, find_class_methods, and find_symbol all inspect Python definitions, but their scopes differ enough to guide selection.
All tool names use snake_case and mostly follow a verb_target pattern. Three use find_, while analyze_file_ast and get_imports_graph deviate slightly, but the naming remains predictable and readable.
Five tools is a well-scoped size for an AST inspection server. Each tool serves a distinct static analysis workflow without redundancy or bloat.
The set covers file outlines, class methods, symbol lookup, import graphs, and docstring coverage, which handles most Python code-inspection needs. Minor gaps exist, such as a dedicated detail view for standalone functions or arbitrary AST node inspection, but they are not critical.
An MCP server that gives your AI access to the source code and docs of all public github repos
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/m-sameerkhan/code-ast-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
