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 "Deploy 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 when explicitly set 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.
Scans run in a separate process with stage progress notifications and a five-minute timeout. Cancellation stops the scan worker. Only one scan per project can run at a time in a server instance; use .agents-config.json to narrow repositories that exceed the time limit.
Generation always assembles a current snapshot, reusing cached symbols for unchanged source files. An interrupted generation can be retried even after its payload was consumed or another scan ran. The client remains responsible for writing AGENTS.md.
Serialized payloads are capped at 300,000 characters. Dropped analysis sections are recorded in metadata.degradations and metadata.truncated_sections. Existing AGENTS.md content and writing instructions are preserved; if these alone exceed the budget, the tool returns an error instead of truncating the document.
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: False).
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 declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description is consistent with that by disclosing that the tool writes the analysis payload to disk and returns instructions to fetch it via read_payload_chunk. It also discloses caching and change-detection behavior, which the annotations do not cover. It stops short of describing the write location, payload size limits, or failure modes for unsupported languages.
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?
Front-loaded with the core capability and the sibling routing in the first two paragraphs, with Args/Returns kept short. The 'Args:'/'Returns:' block is somewhat boilerplate, but every sentence is answerable and none is pure 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?
An output schema exists, so return-value detail is not required, yet the description still states the payload is retrieved in chunks via read_payload_chunk, which is the key follow-up action. Behavior, routing, and language coverage are all present; only the disk-write specifics and error handling are absent.
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 reported top-level schema coverage is 0% (the only property is a $ref), so the description carries the burden, and it does document both nested fields with defaults. However, the wording for force_full_scan largely duplicates the schema's own description, so it adds little semantic depth beyond restating cache-ignore behavior.
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?
States a specific verb+resource (scan/analyze a codebase with tree-sitter) and the concrete artifact produced (a structured context payload). It also names the sibling it is not (generate_agents_md) and lists supported languages, so an agent can distinguish it from the other two tools without opening any schema.
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 when-to-use ('deep codebase understanding for code review, refactoring, planning, Q&A') and an explicit when-not with the named alternative ('To generate or update AGENTS.md specifically, use generate_agents_md'). The routing decision is fully resolved in the text.
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.
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
Scored across 3 tools
The three tools have distinct roles: scan_codebase produces the payload, read_payload_chunk retrieves it, and generate_agents_md orchestrates. scan_codebase and generate_agents_md could initially look similar since both relate to codebase analysis, but the descriptions explicitly delineate when to use each, resolving the ambiguity well.
All names use snake_case with a verb-first convention (scan_codebase, generate_agents_md, read_payload_chunk), which is predictable and readable. read_payload_chunk adds an extra noun qualifier relative to the others, a minor deviation from a strict verb_noun pattern.
Three tools is slightly thin, but each earns its place in a narrow, well-defined workflow (scan → read → generate). There is no obvious redundancy, and the count matches the focused purpose of AGENTS.md generation.
The surface covers the full generation lifecycle: scanning with cache control, chunked payload retrieval, and a create-or-update orchestrator that also feeds the writing rules. Minor gaps exist (no explicit validation or standalone cache-management tool), but agents can complete the core workflow.
Maintenance
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.46 npm4Apache 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.254 npmMIT
- 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