Skip to main content
Glama

agents-md-generator

MCP server that analyzes codebases with tree-sitter and generates AGENTS.md files.

PyPI Python License: MIT MCP

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.

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

Purpose

generate_agents_md

Main entry point. Runs the pipeline internally, embeds writing rules into the payload, and returns chunked read instructions. Use this to create or update AGENTS.md.

scan_codebase

Standalone context tool. Analyzes the codebase and returns a pure data payload with no AGENTS.md mandate. Use this when you need architectural context for any other task.

read_payload_chunk

Streams the payload written by either tool in chunks until has_more is false.

Tool Parameters

Parameter

Type

Default

Description

project_path

string

"."

Path to the project root

Parameter

Type

Default

Description

project_path

string

"."

Path to the project root

force_full_scan

boolean

false

Ignore cache and rescan everything when explicitly set to true.

Parameter

Type

Default

Description

project_path

string

"."

Must match the path used in the preceding tool call

chunk_index

integer

Zero-based chunk index. Increment until has_more is false


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 .env.example

Setup Commands

Exact install and run commands from package.json, Makefile, etc.

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

  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.

  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

  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 <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.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.

{
  "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_size

"medium"

Project scale — tunes all internal caps and thresholds (see Project Size Profiles)

exclude

(see above)

Glob patterns to exclude from analysis

include

[]

If non-empty, only analyze files matching these patterns

languages

"auto"

"auto" detects all supported languages, or pass a list like ["typescript", "python"]

agents_md_path

"./AGENTS.md"

Output path for the generated file

max_file_size_bytes

1048576

Files larger than this are skipped (default: 1 MB)

Environment Variables

Variable

Default

Description

AGENTS_MD_LOG_LEVEL

INFO

Server log verbosity. Set to DEBUG to see per-file analysis details. Valid values: DEBUG, INFO, WARNING, ERROR

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

"small"

0–15k

medium

Generous caps — nearly everything is included. Best for small projects where full visibility matters.

"medium" (default)

15k–50k

medium

Balanced caps suitable for most projects.

"large"

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

process.env.VAR_NAME

Python

os.environ['VAR'], os.getenv('VAR')

Go

os.Getenv("VAR")

Ruby

ENV['VAR']

Rust

env!("VAR"), var("VAR")

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, and Properties are 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. Direct scan_codebase calls return pure data with no mandate.


Credits

AGENTS.md format based on the open agents.md standard.

Back to top

Licensed under the MIT License

Available Tools

3 tools
generate_agents_mdA
Idempotent

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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_chunkA
Read-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.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior1/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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_codebaseA
Idempotent

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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. 1 tool updatev0.6.0
    • Changedscan_codebase2 fields changed
      • changedInput schema / $defs / ScanCodebaseInput / properties / force_full_scan / default
        Previous value: -trueNew value: +false
      • changedInput schema / $defs / ScanCodebaseInput / properties / force_full_scan / description
        Previous 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."
  2. 3 tool updatesv0.5.3
    • First observedgenerate_agents_md
    • First observedread_payload_chunk
    • First observedscan_codebase

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives AI agents structured code understanding and precise code intelligence via local indexing of AST, call graphs, and semantic search.
    46 npm
    4
    Apache 2.0
  • A
    license
    A
    quality
    B
    maintenance
    An 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.
    2
    54 npm
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    MCP server that provides AI coding agents automatic access to AGENTS.md documentation from GitHub repositories, enabling understanding of codebase conventions and patterns.
    2
    Apache 2.0
  • A
    license
    Not graded
    quality
    D
    maintenance
    An 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