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-generator Generate 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.
Inputs: params (required). Returns: result
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.
Inputs: params (required). Returns: result
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.
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.73 npm4Apache 2.0
- AlicenseAqualityCmaintenanceAn 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.224 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