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

true

Ignore cache and rescan everything. Defaults to true — direct calls always perform a full scan.

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.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters2/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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. 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.4/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivityMaintained
ResponsivenessSyncing

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

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

Latest Blog Posts

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