project-context-generator/README.md

Project Context Generator CLI

A CLI tool that analyzes codebases and generates comprehensive context files for AI coding assistants. It automatically detects tech stacks, extracts coding conventions, and produces structured JSON/YAML output that can be fed to AI tools like Claude or Copilot for instant codebase understanding.

Features

• Auto-detect project structure and tech stack - Identifies 15+ programming languages and popular frameworks
• Extract coding conventions - Detects naming styles, indentation, quote preferences, and documentation patterns
• Generate AI-friendly context files - Outputs structured JSON or YAML with all project information
• Customizable templates - Choose from minimal, standard, or comprehensive templates, or create your own
• MCP server integration - Run as a Model Context Protocol server for dynamic AI tool integration
• Generate setup instructions - Automatically creates installation and running commands based on detected package managers

Installation

# Install from PyPI
pip install project-context-generator

# Or install from source
pip install -e .

Quick Start

# Analyze current directory and output JSON
contextgen generate

# Analyze specific project with YAML output
contextgen generate --format yaml --output context.yaml

# Generate with standard template (Markdown)
contextgen render --template standard

# Show quick project overview
contextgen info

# List available templates
contextgen templates

# Run as MCP server for AI tool integration
contextgen mcp --project /path/to/project

Usage

Generate Command

Generate a context file for your project:

# Output to stdout (default)
contextgen generate

# Specify output file
contextgen generate --output context.json

# Choose format (json or yaml)
contextgen generate --format yaml

# Analyze a specific directory
contextgen generate --project /path/to/my/project

Render Command

Render context using customizable templates:

# Use standard template
contextgen render --template standard

# Use comprehensive template
contextgen render --template comprehensive

# Use minimal template
contextgen render --template minimal

# Custom template directory
contextgen render --template-dir /path/to/templates --template mytemplate.j2

# Save to file
contextgen render --template standard --output README.md

Info Command

Get a quick overview of your project:

contextgen info

MCP Server Mode

Run as a Model Context Protocol server for AI tool integration:

# Start MCP server
contextgen mcp --project /path/to/project

The MCP server exposes these tools:

• get_project_overview - Get project overview information
• get_file_context - Get context for a specific file
• get_conventions - Get coding conventions
• search_structure - Search project structure
• get_full_context - Get complete project context

Configuration

Create a .contextgenrc file in your project root:

# Project path (defaults to current directory)
project: /path/to/project

# Patterns to ignore during analysis
ignore_patterns:
  - .git
  - __pycache__
  - node_modules
  - .venv
  - venv
  - dist
  - build

# Output settings
output:
  format: yaml
  template: standard

# Analysis settings
analysis:
  max_files_per_type: 100
  include_hidden: false

# MCP server settings
mcp:
  enabled: false

Templates

Three built-in templates are available:

Minimal

Brief overview with key information only.

Standard

Balanced output with tech stack, structure, conventions, and setup instructions.

Comprehensive

Full detailed analysis including all detected information with AI assistant tips.

Custom Templates

Create custom templates using Jinja2 syntax. Available variables:

# Project Information
{{ project.name }}
{{ project.description }}
{{ project.path }}
{{ timestamp }}

# Analysis Results
{{ analysis.primary_language }}
{{ analysis.languages }}
{{ analysis.frameworks }}
{{ analysis.build_tools }}
{{ analysis.full_stack }}

# Project Structure
{{ structure.total_files }}
{{ structure.total_dirs }}
{{ structure.key_files }}
{{ structure.file_tree }}

# Coding Conventions
{{ conventions.naming }}
{{ conventions.style }}
{{ conventions.documentation }}

# Setup Instructions
{{ setup.install_commands }}
{{ setup.run_commands }}
{{ setup.test_commands }}
{{ setup.environment_variables }}

Example custom template:

# {{ project.name }}

Language: {{ analysis.primary_language }}
Frameworks: {% for fw in analysis.frameworks %}{{ fw.name }} {% endfor %}

Supported Languages

Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, PHP, Swift, Kotlin, Scala, HTML, CSS, JSON, YAML, XML, Shell, Markdown, SQL, Vue, Svelte

Supported Frameworks

Django, Flask, FastAPI, React, Vue, Next.js, Express, Spring, Gin, Rails, Laravel, Angular, Svelte, Phoenix, NestJS

Development

# Clone the repository
git clone https://github.com/yourusername/project-context-generator.git
cd project-context-generator

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v --cov=src/contextgen

# Run unit tests only
pytest tests/unit/ -v

# Run integration tests only
pytest tests/integration/ -v

License

MIT License - see LICENSE for details.