Readme Gen MCP Server

🚀 README Generator MCP Server

A Model Context Protocol (MCP) server that enables LLMs to automatically generate comprehensive README files by analyzing project structures.

🚀 Quick Start

1. Install the necessary dependencies:

npm install

2. Build the server:

npm run build

3. Configure the server in your Claude Desktop or relevant CLI tools as described in the "🔧 Setup" section.
4. Start using the server to generate README files or analyze projects.

✨ Features

• Automatic Technology Detection: Identifies a wide range of technologies such as Node.js, TypeScript, Python, Rust, Go, Java, Docker, etc.
• Smart Project Analysis: Extracts metadata from package.json, dependencies, scripts, and configuration files.
• Directory Structure Scanning: Recursively traverses the project directory with configurable depth and intelligent ignore patterns.
• Rich README Generation: Creates professional READMEs with badges, emojis, proper sections, and code blocks.
• Flexible Template System: Comes with a predefined structure that includes both required and optional sections.
• Multi-language Support: Works well with various programming languages and frameworks.

📦 Installation

npm install

🔧 Setup

1. Build the server

npm run build

2. Configure Claude Desktop

Add this server to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "readme-generator": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/build/index.js"]
    }
  }
}

3. Restart Claude Desktop

After adding the configuration, restart Claude Desktop to load the MCP server.

Claude Code CLI

To add this MCP server to Claude Code CLI:

# With node (after build)
claude mcp add readme-generator --scope user -- node <path-to-project>/build/index.js

# With npx and TypeScript (development mode)
claude mcp add readme-generator --scope user -- npx -y tsx <path-to-project>/src/index.ts

Replace <path-to-project> with the absolute path to this MCP server.

Scope options:

• --scope user: Available in all your projects (recommended).
• --scope project: Shared with everyone in the project via .mcp.json.
• --scope local: Only for the current project.

Useful commands:

claude mcp list                    # Show all configured servers
claude mcp remove readme-generator # Remove the server
/mcp                              # Show server status in Claude Code

Gemini CLI

To add this MCP server to Gemini CLI, edit the configuration file:

• File location: ~/.config/gemini/settings.json

Add the server configuration:

{
  "mcpServers": {
    "readme-generator": {
      "command": "node",
      "args": ["<path-to-project>/build/index.js"]
    }
  }
}

Replace <path-to-project> with the absolute path to this MCP server.

Alternative with TypeScript (development mode):

{
  "mcpServers": {
    "readme-generator": {
      "command": "npx",
      "args": ["-y", "tsx", "<path-to-project>/src/index.ts"]
    }
  }
}

💻 Usage Examples

Basic Usage

# Quick README Generation
# Once the MCP server is configured in Claude Desktop, simply ask:
"Generate a README for my project at /home/user/my-awesome-app"

Advanced Usage

# Detailed Project Analysis
# For more control over the process:
"Analyze the project at /home/user/my-awesome-app and show me what you found"
# Review the analysis, then request:
"Now generate a README emphasizing the API documentation and deployment sections"

📚 Documentation

Available Scripts

npm run build

Compiles TypeScript and makes the output executable.

npm run watch

Watches for changes and recompiles automatically.

npm run prepare

Runs build automatically before npm publish.

Available MCP Tools

The server provides four tools for LLMs:

1. read_project_structure

Reads the directory structure of a project and returns a tree - like structure. Example:

{
  "path": "/home/user/my-project",
  "maxDepth": 3
}

2. read_file

Reads the contents of a specific file. Example:

{
  "path": "/home/user/my-project/package.json"
}

3. analyze_project

Analyzes a project directory and returns structured data including detected technologies, dependencies, scripts, and directory structure. Example:

{
  "projectPath": "/home/user/my-project"
}

4. generate_readme

Automatically generates a complete, professional README.md file for a project. Example:

{
  "projectPath": "/home/user/my-project"
}

🔧 Technical Details

1. Project Scanning: Recursively reads the project directory while ignoring directories like node_modules, .git, dist, build.
2. Technology Detection: Identifies technologies based on configuration files such as package.json, tsconfig.json, Cargo.toml, etc.
3. Metadata Extraction: Pulls information from package.json including scripts, dependencies, author, license.
4. Template Application: Uses a predefined template structure with required and optional sections.
5. README Generation: Creates a formatted README with badges, proper sections, code blocks, and professional styling.

📦 Project Structure

mcp/
  package-lock.json
  package.json
  src/
    index.ts
  tsconfig.json

🎨 Customization

Modify the README Template

Edit the README_TEMPLATE in src/index.ts:12 - 66 to customize sections:

const README_TEMPLATE = {
  sections: [
    {
      name: "Project Title",
      description: "The main title/name of the project",
      required: true,
    },
    {
      name: "Your Custom Section",
      description: "Description of what this section should contain",
      required: false,
    },
    // Add more sections as needed
  ],
};

Add Technology Detection

Extend the analyzeProject function in src/index.ts:126 - 214 to detect additional frameworks:

if (files.includes("docker-compose.yml")) {
  detectedTechnologies.push("Docker Compose");
  configFiles.push("docker-compose.yml");
}

After making changes, rebuild:

npm run build

📄 License

This project is licensed under the ISC License.

🤝 Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/my-feature.
3. Make your changes and test them.
4. Commit your changes: git commit -m 'Add my feature'.
5. Push to the branch: git push origin feature/my-feature.
6. Submit a pull request.

This README was generated using the README Generator MCP Server itself! 🎉