232 lines
5.3 KiB
Markdown
232 lines
5.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# Install from PyPI
|
|
pip install project-context-generator
|
|
|
|
# Or install from source
|
|
pip install -e .
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
contextgen info
|
|
```
|
|
|
|
### MCP Server Mode
|
|
|
|
Run as a Model Context Protocol server for AI tool integration:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
# 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:
|
|
|
|
```jinja2
|
|
# 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:
|
|
```jinja2
|
|
# {{ 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
|
|
|
|
```bash
|
|
# 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](LICENSE) for details.
|