agents-md-generator
This server is an MCP tool that analyzes codebases using tree-sitter to generate or update AGENTS.md files—structured documentation for AI agents following the open agents.md standard. Key capabilities:
Generate or update
AGENTS.md: Orchestrates the full workflow by checking for an existing file, embedding architectural context and writing rules, and instructing the AI client to produce a standards-compliant AGENTS.md. Can be triggered viagenerate_agents_md.Deep codebase analysis:
scan_codebaseperforms AST-based analysis using tree-sitter, detecting public API surfaces (classes, functions, methods, interfaces), entry points, environment variables, naming conventions, dependency injection patterns, route controllers, layered architecture, and more. Also extracts project metadata like setup commands, dev/build/test workflows, CI pipeline info, and lint/format config.Incremental scanning: Efficiently re-analyzes only files with SHA-256 hash changes, including only changed public symbols, backed by a cache stored outside the project directory (e.g.,
~/.cache/agents-md-generator/).Chunked payload streaming: Large analysis results are retrieved in chunks via
read_payload_chunkto avoid MCP data size limits.Custom configuration: Behavior is customized through
.agents-config.json, supporting include/exclude glob patterns, language selection, output path, maximum file size, and project size profiles (small,medium,large) that tune internal compression thresholds.Architectural distillation: For large codebases, applies techniques like boilerplate suppression, low-entropy summarization, and semantic clustering to keep payloads manageable.
Multi-language support: Automatically detects and analyzes Python, C#, TypeScript, JavaScript, and Go projects.
AI integration: Provides deep codebase understanding for AI agents in tasks like code review, planning, Q&A, refactoring, and integrates with MCP-capable clients (Claude Code, Gemini CLI, Cursor, Windsurf).
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., "@agents-md-generatorGenerate the AGENTS.md for this project"
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.
agents-md-generator
MCP server that analyzes codebases with tree-sitter and generates AGENTS.md files.
Python · C# · TypeScript · JavaScript · Go
Installation · Usage · Configuration · How It Works · Contributing
Compatible with any MCP-capable client: Claude Code, Gemini CLI, Cursor, Windsurf, Codex CLI, and others.
The server exposes three tools with a clear separation of concerns:
generate_agents_md— main entry point. Runs the analysis pipeline internally, embeds writing rules into the payload, and returns chunked read instructions to your client.scan_codebase— standalone context tool for when you want deep codebase understanding without generating any file.read_payload_chunk— streams the payload back in chunks regardless of which tool produced it.
No large data travels over the MCP wire.
Table of Contents
Related MCP server: repomap-mcp
Installation
Requirements: Python 3.11+, Git, and any MCP-compatible client.
See INSTALLATION.md for the full guide including prerequisites and troubleshooting.
Option A — pip install + setup wizard (recommended)
pip install agents-md-generator
agents-md-generator setupThe setup wizard detects your installed clients, asks whether to configure globally or per-project, and patches the config files automatically. Supports Claude Code, Gemini CLI, Cursor, Windsurf, and Codex CLI.
Option B — uvx (no install needed)
If you have uv installed, uvx runs the package without a prior install step. Add the entry manually to your client's MCP config:
{
"mcpServers": {
"agents-md": {
"command": "uvx",
"args": ["agents-md-generator"]
}
}
}For Claude Code specifically:
claude mcp add agents-md -- uvx agents-md-generator
claude mcp adddefaults to--scope local(current project only). Add-s userto register it for all projects.
Usage
Once registered, ask your AI client:
"Generate the AGENTS.md for this project"
The client will call generate_agents_md automatically. To scan a different directory:
"Generate the AGENTS.md for the project at /path/to/project"
Tools
Tool | Purpose |
| Main entry point. Runs the pipeline internally, embeds writing rules into the payload, and returns chunked read instructions. Use this to create or update |
| Standalone context tool. Analyzes the codebase and returns a pure data payload with no |
| Streams the payload written by either tool in chunks until |
Tool Parameters
Parameter | Type | Default | Description |
| string |
| Path to the project root |
Parameter | Type | Default | Description |
| string |
| Path to the project root |
| boolean |
| Ignore cache and rescan everything. Defaults to |
Parameter | Type | Default | Description |
| string |
| Must match the path used in the preceding tool call |
| integer | — | Zero-based chunk index. Increment until |
What Gets Generated
The generated AGENTS.md follows the agents.md open standard. It is written as a README for AI agents, not as documentation for humans. Sections include:
Section | Contents |
Project Overview | Tech stack and top-level architecture shape |
Architecture & Data Flow | Detected layers or domains with data flow direction |
Conventions & Patterns | Naming rules, export contracts, import rules, how to add new entities end-to-end |
Environment Variables | Variables detected in source files and |
Setup Commands | Exact install and run commands from |
Development Workflow | Build, watch, and dev server commands |
Testing Instructions | Test commands and framework info (if detected) |
Code Style | Lint/format commands (if config files detected) |
Build and Deployment | CI pipeline info (if detected) |
Sections with no detected data are omitted entirely.
How Incremental Scanning Works
First run (cold start) — all git-tracked source files are parsed with tree-sitter and cached
Subsequent runs — only files whose SHA-256 hash changed since the last scan are re-parsed
Semantic diff — for modified files, only changed public symbols are included in the payload
No source changes? — the tool stops and asks whether you want to improve the existing
AGENTS.mdcontent anywayPrivate symbols and test file internals are excluded from both cache and payload — only the public API surface matters for
AGENTS.md
How Large Payloads Are Streamed
For large codebases the analysis payload can be too big to return inline over the MCP wire. The server handles this transparently through read_payload_chunk.
generate_agents_mdruns the pipeline internally, writes the payload to disk (includingAGENTS.mdwriting rules), and returnstotal_chunkswith read instructionsThe client calls
read_payload_chunk(project_path, chunk_index=0), then incrementschunk_indexuntilhas_moreis falseThe client concatenates all
datafields — the payload contains the rules and analysis data needed to writeAGENTS.mdThe payload file is automatically deleted after the last chunk is read
scan_codebaseruns the analysis and writes a pure data payload to diskSame chunked read via
read_payload_chunkThe client uses the payload for any purpose — code review, planning, Q&A
This flow is pure MCP — no filesystem access required from the client side. Any MCP-compatible client can follow it.
Cache and Payload Location
All runtime artifacts are stored outside your project, in the user cache directory:
~/.cache/agents-md-generator/<project-hash>/cache.json ← incremental scan cacheThe <project-hash> is a SHA-256 of the project's absolute path — unique per project. Nothing is written to your repository.
Note: The server also writes a temporary
payload.jsonto this directory during analysis, but it is managed entirely by theread_payload_chunktool and deleted automatically after the last chunk is read. You never need to access it directly.
Project Configuration
Create .agents-config.json at your project root to customize behavior. This file is optional — all fields have defaults, and you can commit it to share settings with your team.
{
"project_size": "medium",
"exclude": [
"**/node_modules/**",
"**/bin/**",
"**/obj/**",
"**/.git/**",
"**/dist/**",
"**/build/**",
"**/__pycache__/**",
"**/*.min.js",
"**/*.min.css",
"**/*.bundle.js",
"**/vendor/**",
"**/packages/**",
"**/.venv/**",
"**/venv/**",
"**/bower_components/**",
"**/app/lib/**",
"**/wwwroot/lib/**",
"**/wwwroot/libs/**",
"**/static/vendor/**",
"**/public/vendor/**",
"**/assets/vendor/**",
"**/site-packages/**"
],
"include": [],
"languages": "auto",
"agents_md_path": "./AGENTS.md",
"max_file_size_bytes": 1048576
}Options
Key | Default | Description |
|
| Project scale — tunes all internal caps and thresholds (see Project Size Profiles) |
| (see above) | Glob patterns to exclude from analysis |
|
| If non-empty, only analyze files matching these patterns |
|
|
|
|
| Output path for the generated file |
|
| Files larger than this are skipped (default: 1 MB) |
Environment Variables
Variable | Default | Description |
|
| Server log verbosity. Set to |
Project Size Profiles
The project_size setting controls how aggressively the payload is compressed. A single knob tunes all internal caps — methods per class, symbols per file, directory aggregation, route caps, tree depth, and impact filtering.
Profile | Lines (guidance) | Impact filter | Description |
| 0–15k | medium | Generous caps — nearly everything is included. Best for small projects where full visibility matters. |
| 15k–50k | medium | Balanced caps suitable for most projects. |
| 50k+ | high | Aggressive compression — only structural/breaking changes in diffs, more directory collapsing, tighter symbol caps. |
Constant | Small | Medium | Large |
Methods per class | 30 | 12 | 8 |
Symbols per file | 40 | 20 | 10 |
Dir aggregation threshold | 20 | 10 | 5 |
Files per layer (before overflow) | 15 | 8 | 5 |
Aggregation sample size | 5 | 4 | 3 |
Route controllers cap | 30 | 15 | 10 |
Routes per controller | 15 | 8 | 5 |
Go handlers cap | 15 | 8 | 5 |
Directory tree depth | 4 | 3 | 2 |
Impact filter | medium | medium | high |
What the Analysis Detects
Environment Variables
The server scans all source files for environment variable references using language-specific patterns:
Language | Pattern detected |
JavaScript / TypeScript |
|
Python |
|
Go |
|
Ruby |
|
Rust |
|
It also parses .env.example, .env.template, and .env.sample files at the project root.
Entry Points
Files named index, main, app, server, program, bootstrap, or startup (with any supported extension) are detected as entry points and annotated with their inferred role (e.g., "HTTP server bootstrap", "Electron main process").
Public API Surface
Tree-sitter parses each source file and extracts public symbols — classes, functions, methods, interfaces — filtering out private/protected members and underscore-prefixed symbols. For classes and structs, constructors (when they have parameters) and public properties are also included, revealing dependency injection patterns and data shapes. Interface methods are always included as they define the public contract. These are used to detect naming conventions, DI patterns, and export contracts across layers.
Architectural Distillation
For large codebases, the tool applies several heuristics to ensure the payload remains high-signal:
Boilerplate Suppression — common directories like
Migrations,bin,obj, andPropertiesare automatically flagged and collapsed in the project structure, preventing them from bloating the directory listing.Low-Entropy Summarization — files that primarily contain data structures (DTOs, Entities) with no logic methods are "minified". Instead of listing every property, the tool provides a high-level summary (e.g., "Contains 25 DTO classes").
Semantic Clustering — the aggregator groups these minified summaries at the directory level, allowing the consuming AI to understand entire data layers through a single line of signal.
Instruction Embedding — when called via
generate_agents_md, writing rules are embedded directly in the payload so the AI agent reads the "Rules of Engagement" before processing the code architecture. Directscan_codebasecalls return pure data with no mandate.
Credits
AGENTS.md format based on the open agents.md standard.
Licensed under the MIT License
Available Tools
3 toolsgenerate_agents_mdAIdempotent
Orchestrate the full AGENTS.md creation or update workflow.
Determines whether to create or update AGENTS.md by checking if the file already exists. Returns writing rules, the existing content (if any), and step-by-step instructions to scan the codebase and produce the final file.
Use this tool whenever the user asks to generate, create, update, or refresh AGENTS.md. For general codebase context without AGENTS.md generation, use scan_codebase + read_payload_chunk directly.
Args: params (GenerateAgentsMdInput): Input parameters containing: - project_path (str): Path to the project root (default: ".")
Returns: str: JSON with agents_md_path, agents_md_rules, existing_agents_md (if any), and step-by-step instructions for the agent to follow.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds context about checking file existence, return values, and workflow steps, but doesn't detail side effects beyond mutation.
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?
Description is well-structured with bullet points and front-loaded purpose. Could be slightly shorter but no wasted content.
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?
Given an output schema exists, description covers return shape and workflow steps adequately. Missing error handling details but sufficient for expected use.
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?
Input schema has thorough descriptions for params and project_path. Description merely repeats schema info (project_path default and purpose), adding no new meaning beyond what schema already provides.
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 'Orchestrate the full AGENTS.md creation or update workflow' and distinguishes from siblings by specifying when to use scan_codebase + read_payload_chunk instead.
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?
Explicitly says 'Use this tool whenever the user asks to generate, create, update, or refresh AGENTS.md' and provides alternative tools for general context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_payload_chunkARead-onlyIdempotent
Read a chunk of the analysis payload produced by scan_codebase.
Call this tool repeatedly starting at chunk_index=0, incrementing by 1 each time, until the response contains has_more=false. Concatenate all 'data' fields in order to reconstruct the full payload JSON.
The payload file is automatically deleted after the last chunk is read.
Args: params (ReadPayloadChunkInput): Input parameters containing: - project_path (str): Path to the project root (must match scan_codebase call). - chunk_index (int): Zero-based index of the chunk to retrieve.
Returns: str: JSON with fields: chunk_index, total_chunks, has_more (bool), data (str). On the last chunk (has_more=false), the payload file is deleted from disk.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'payload file is automatically deleted after the last chunk is read,' which contradicts annotations (readOnlyHint=true, idempotentHint=true) that imply no side effects. This is a serious inconsistency, misleading about destructiveness.
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 concise (~150 words) with clear sections (use, iteration, args, returns). Every sentence earns its place, no redundancy, and the most important info (usage pattern) is front-loaded.
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?
Given the presence of an output schema and the complex iterative workflow, the description fully explains how to use the tool in conjunction with scan_codebase, the chunking mechanism, and the file deletion. No gaps remain.
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?
Although the schema describes parameters, the description adds critical context: project_path must match scan_codebase call and chunk_index is zero-based. It also explains the return structure, adding value beyond the schema.
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 'Read a chunk of the analysis payload produced by scan_codebase,' identifying the specific verb and resource. It distinguishes from siblings (generate_agents_md, scan_codebase) by focusing on payload retrieval.
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?
Explicit usage guidance is provided: 'Call this tool repeatedly starting at chunk_index=0, incrementing by 1 each time, until the response contains has_more=false. Concatenate all data fields.' This leaves no ambiguity about the iterative workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
scan_codebaseAIdempotent
Scan and analyze a codebase with tree-sitter, producing a structured context payload.
Performs AST analysis, change detection, and caching. Writes the analysis payload to disk and returns instructions to retrieve it via read_payload_chunk. The payload contains pure architectural data — no AGENTS.md writing instructions.
Use this tool when you need deep codebase understanding for any task (code review, refactoring, planning, Q&A). To generate or update AGENTS.md specifically, use generate_agents_md instead — it orchestrates the full workflow automatically.
Supported languages: Python, C#, TypeScript, JavaScript, Go.
Args: params (ScanCodebaseInput): Input parameters containing: - project_path (str): Path to the project root (default: ".") - force_full_scan (bool): Ignore cache and rescan everything (default: True). Set to False only when called as part of an incremental update workflow.
Returns: str: JSON with total_chunks and instructions to call read_payload_chunk.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include idempotentHint=true and destructiveHint=false; the description adds valuable context about writing the analysis payload to disk, caching behavior, and explicitly confirms the payload is pure architectural data with no AGENTS.md instructions. This goes beyond the annotations without contradicting them.
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 yet comprehensive, with a clear structure: purpose, behavior, supported languages, arguments, and return value. It is slightly verbose but every section adds value, and the front-loaded purpose sentence aids quick scanning.
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 covers all essential aspects: purpose, side effects, supported languages, parameter semantics (though flawed), and return value instructions. It is sufficiently complete for a complex tool with nested parameters and an output schema, though the parameter default inconsistency weakens completeness.
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 description explains both parameters, but critically contradicts the schema on the default for force_full_scan: description says 'default: True' while schema states 'default: false'. This inconsistent guidance undermines the added semantics. Schema coverage is low (0% at top-level), but the nested descriptions exist, making the misstatement more harmful.
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 function with a specific verb and resource: 'Scan and analyze a codebase with tree-sitter, producing a structured context payload.' It distinguishes itself from siblings by explicitly directing users to generate_agents_md for AGENTS.md tasks and mentioning read_payload_chunk for retrieval.
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?
Provides explicit when-to-use ('when you need deep codebase understanding for any task') and when-not-to-use ('To generate or update AGENTS.md specifically, use generate_agents_md instead'). Also gives conditional guidance for force_full_scan, noting when to set it to False in incremental workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
1 tool update
v0.6.0- Changed
scan_codebase2 fields changed- changed
Input schema / $defs / ScanCodebaseInput / properties / force_full_scan / defaultPrevious value: -trueNew value: +false - changed
Input schema / $defs / ScanCodebaseInput / properties / force_full_scan / descriptionPrevious value: -"Force a full scan ignoring any existing cache. Defaults to True — direct calls always perform a full scan for complete context. Set to False only when called as part of an incremental update workflow (e.g. orchestrated by generate_agents_md)."New value: +"Force a full scan ignoring any existing cache. Defaults to False — incremental scans reuse the cache and only re-analyze changed files. Set to True only when the user explicitly requests a full rescan."
3 tool updates
v0.5.3- First observed
generate_agents_md - First observed
read_payload_chunk - First observed
scan_codebase
TDQS
Each tool has a clearly distinct purpose: scan_codebase produces analysis data, read_payload_chunk retrieves that data, and generate_agents_md orchestrates the full workflow. Descriptions explicitly cross-reference when to use each, eliminating ambiguity.
All tool names follow a consistent verb_noun snake_case pattern (scan_codebase, read_payload_chunk, generate_agents_md). The naming is predictable and aligns with the server's purpose.
Three tools is well-scoped for the server's narrow purpose of generating AGENTS.md. Each tool earns its place as part of a clear workflow, and there is no bloat or redundancy.
The tool set covers the full lifecycle: scanning the codebase, reading the payload, and orchestrating creation/update of AGENTS.md. Since generate_agents_md handles both create and update by checking existing content, there are no obvious gaps in the domain.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
MCP server for agentverse documentation, generated by doc2mcp.
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents structured code understanding and precise code intelligence via local indexing of AST, call graphs, and semantic search.764Apache 2.0
- AlicenseAqualityBmaintenanceAn MCP server that generates ranked, token-budgeted code structure maps using Tree-sitter AST analysis and PageRank, enabling AI agents to quickly understand unfamiliar codebases.253MIT
- AlicenseAqualityDmaintenanceMCP server that provides AI coding agents automatic access to AGENTS.md documentation from GitHub repositories, enabling understanding of codebase conventions and patterns.2Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that indexes your codebase using tree-sitter AST parsing and gives AI tools instant access to structural intelligence like dependency graphs, call trees, and dead code detection from a local SQLite database.MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/nushey/agents-md-generator'
If you have feedback or need assistance with the MCP directory API, please join our Discord server