AGENTS.md Generator

agents-md-generator

MCP server that analyzes codebases with [tree-sitter](https://tree-sitter.github.io/) and generates [`AGENTS.md`](https://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

• Installation
• Option A — pip install + setup wizard
• Option B — uvx
• Usage
• Tools
• Tool Parameters
• What Gets Generated
• How Incremental Scanning Works
• How Large Payloads Are Streamed
• Cache and Payload Location
• Project Configuration
• Options
• Environment Variables
• Project Size Profiles
• What the Analysis Detects
• Credits

---

Installation

Requirements: Python 3.11+, Git, and any MCP-compatible client.

See [INSTALLATION.md](https://github.com/nushey/agents-md-generator/blob/main/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 setup

The 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 add defaults to --scope local (current project only). Add -s user to 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 Parameters

generate_agents_md

scan_codebase

read_payload_chunk

---

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:

Sections with no detected data are omitted entirely.

---

How Incremental Scanning Works

1. First run (cold start) — all git-tracked source files are parsed with tree-sitter and cached
2. Subsequent runs — only files whose SHA-256 hash changed since the last scan are re-parsed
3. Semantic diff — for modified files, only changed public symbols are included in the payload
4. No source changes? — the tool stops and asks whether you want to improve the existing AGENTS.md content anyway
5. Private 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_md flow

1. generate_agents_md runs the pipeline internally, writes the payload to disk (including AGENTS.md writing rules), and returns total_chunks with read instructions
2. The client calls read_payload_chunk(project_path, chunk_index=0), then increments chunk_index until has_more is false
3. The client concatenates all data fields — the payload contains the rules and analysis data needed to write AGENTS.md
4. The payload file is automatically deleted after the last chunk is read

scan_codebase flow (pure context, no AGENTS.md mandate)

1. scan_codebase runs the analysis and writes a pure data payload to disk
2. Same chunked read via read_payload_chunk
3. The 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 cache

The 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.json to this directory during analysis, but it is managed entirely by the read_payload_chunk tool 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.

Full default configuration

{

"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

Environment Variables

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.

| "small" | 0–15k | medium | Generous caps — nearly