fix: resolve CI/CD issues - all tests pass locally
This commit is contained in:
Developer
399
README.md
399
README.md
@@ -1,252 +1,273 @@
|
||||
# Auto README Generator CLI
|
||||
# MCP Server CLI
|
||||
|
||||
[](https://pypi.org/project/auto-readme-cli/)
|
||||
[](https://pypi.org/project/auto-readme-cli/)
|
||||
[](https://opensource.org/licenses/MIT/)
|
||||
|
||||
A powerful CLI tool that automatically generates comprehensive README.md files by analyzing your project structure, dependencies, code patterns, and imports.
|
||||
|
||||
## Features
|
||||
|
||||
- **Automatic Project Analysis**: Scans directory structure to identify files, folders, and patterns
|
||||
- **Multi-Language Support**: Supports Python, JavaScript, Go, and Rust projects
|
||||
- **Dependency Detection**: Parses requirements.txt, package.json, go.mod, and Cargo.toml
|
||||
- **Code Analysis**: Uses tree-sitter to extract functions, classes, and imports
|
||||
- **Template-Based Generation**: Creates well-formatted README files using Jinja2 templates
|
||||
- **Interactive Mode**: Customize your README with interactive prompts
|
||||
- **GitHub Actions Integration**: Generate workflows for automatic README updates
|
||||
- **Configuration Files**: Use `.readmerc` files to customize generation behavior
|
||||
A CLI tool that creates a local Model Context Protocol (MCP) server for developers, enabling custom tool definitions in YAML/JSON with built-in file operations, git commands, shell execution, and local LLM support for offline AI coding assistant integration.
|
||||
|
||||
## Installation
|
||||
|
||||
### From PyPI
|
||||
|
||||
```bash
|
||||
pip install auto-readme-cli
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### From Source
|
||||
Or from source:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/auto-readme-cli.git
|
||||
cd auto-readme-cli
|
||||
git clone <repository>
|
||||
cd mcp-server-cli
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Generate a README for your project
|
||||
1. Initialize a configuration file:
|
||||
|
||||
```bash
|
||||
auto-readme generate
|
||||
mcp-server config init -o config.yaml
|
||||
```
|
||||
|
||||
### Generate with specific options
|
||||
2. Start the server:
|
||||
|
||||
```bash
|
||||
auto-readme generate --input /path/to/project --output README.md --template base
|
||||
mcp-server server start --port 3000
|
||||
```
|
||||
|
||||
### Interactive Mode
|
||||
3. The server will be available at `http://127.0.0.1:3000`
|
||||
|
||||
## CLI Commands
|
||||
|
||||
### Server Management
|
||||
|
||||
```bash
|
||||
auto-readme generate --interactive
|
||||
# Start the MCP server
|
||||
mcp-server server start --port 3000 --host 127.0.0.1
|
||||
|
||||
# Check server status
|
||||
mcp-server server status
|
||||
|
||||
# Health check
|
||||
mcp-server health
|
||||
```
|
||||
|
||||
### Preview README without writing
|
||||
### Tool Management
|
||||
|
||||
```bash
|
||||
auto-readme preview
|
||||
# List available tools
|
||||
mcp-server tool list
|
||||
|
||||
# Add a custom tool
|
||||
mcp-server tool add path/to/tool.yaml
|
||||
|
||||
# Remove a custom tool
|
||||
mcp-server tool remove tool_name
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### generate
|
||||
|
||||
Generate a README.md file for your project.
|
||||
### Configuration
|
||||
|
||||
```bash
|
||||
auto-readme generate [OPTIONS]
|
||||
```
|
||||
# Show current configuration
|
||||
mcp-server config show
|
||||
|
||||
**Options:**
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `-i, --input DIRECTORY` | Input directory to analyze (default: current directory) |
|
||||
| `-o, --output FILE` | Output file path (default: README.md) |
|
||||
| `-I, --interactive` | Run in interactive mode |
|
||||
| `-t, --template TEMPLATE` | Template to use (base, minimal, detailed) |
|
||||
| `-c, --config FILE` | Path to configuration file |
|
||||
| `--github-actions` | Generate GitHub Actions workflow |
|
||||
| `-f, --force` | Force overwrite existing README |
|
||||
| `--dry-run` | Preview without writing file |
|
||||
|
||||
### preview
|
||||
|
||||
Preview the generated README without writing to file.
|
||||
|
||||
```bash
|
||||
auto-readme preview [OPTIONS]
|
||||
```
|
||||
|
||||
### analyze
|
||||
|
||||
Analyze a project and display information.
|
||||
|
||||
```bash
|
||||
auto-readme analyze [PATH]
|
||||
```
|
||||
|
||||
### init-config
|
||||
|
||||
Generate a template configuration file.
|
||||
|
||||
```bash
|
||||
auto-readme init-config --output .readmerc
|
||||
# Generate a configuration file
|
||||
mcp-server config init -o config.yaml
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Configuration File (.readmerc)
|
||||
|
||||
Create a `.readmerc` file in your project root to customize README generation:
|
||||
Create a `config.yaml` file:
|
||||
|
||||
```yaml
|
||||
project_name: "My Project"
|
||||
description: "A brief description of your project"
|
||||
template: "base"
|
||||
interactive: false
|
||||
server:
|
||||
host: "127.0.0.1"
|
||||
port: 3000
|
||||
log_level: "INFO"
|
||||
|
||||
sections:
|
||||
order:
|
||||
- title
|
||||
- description
|
||||
- overview
|
||||
- installation
|
||||
- usage
|
||||
- features
|
||||
- api
|
||||
- contributing
|
||||
- license
|
||||
llm:
|
||||
enabled: false
|
||||
base_url: "http://localhost:11434"
|
||||
model: "llama2"
|
||||
|
||||
custom_fields:
|
||||
author: "Your Name"
|
||||
email: "your.email@example.com"
|
||||
security:
|
||||
allowed_commands:
|
||||
- ls
|
||||
- cat
|
||||
- echo
|
||||
- git
|
||||
blocked_paths:
|
||||
- /etc
|
||||
- /root
|
||||
```
|
||||
|
||||
### pyproject.toml Configuration
|
||||
### Environment Variables
|
||||
|
||||
You can also configure auto-readme in your `pyproject.toml`:
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `MCP_PORT` | Server port |
|
||||
| `MCP_HOST` | Server host |
|
||||
| `MCP_LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) |
|
||||
| `MCP_LLM_URL` | Local LLM base URL |
|
||||
|
||||
```toml
|
||||
[tool.auto-readme]
|
||||
filename = "README.md"
|
||||
sections = ["title", "description", "installation", "usage", "api"]
|
||||
## Built-in Tools
|
||||
|
||||
### File Operations
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `file_tools` | Read, write, list, search, glob files |
|
||||
| `read_file` | Read file contents |
|
||||
| `write_file` | Write content to a file |
|
||||
| `list_directory` | List directory contents |
|
||||
| `glob_files` | Find files matching a pattern |
|
||||
|
||||
### Git Operations
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `git_tools` | Git operations: status, log, diff, branch |
|
||||
| `git_status` | Show working tree status |
|
||||
| `git_log` | Show commit history |
|
||||
| `git_diff` | Show changes between commits |
|
||||
|
||||
### Shell Execution
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `shell_tools` | Execute shell commands safely |
|
||||
| `execute_command` | Execute a shell command |
|
||||
|
||||
## Custom Tools
|
||||
|
||||
Define custom tools in YAML:
|
||||
|
||||
```yaml
|
||||
name: my_tool
|
||||
description: Description of the tool
|
||||
|
||||
input_schema:
|
||||
type: object
|
||||
properties:
|
||||
param1:
|
||||
type: string
|
||||
description: First parameter
|
||||
required: true
|
||||
param2:
|
||||
type: integer
|
||||
description: Second parameter
|
||||
default: 10
|
||||
required:
|
||||
- param1
|
||||
|
||||
annotations:
|
||||
read_only_hint: true
|
||||
destructive_hint: false
|
||||
```
|
||||
|
||||
## Supported Languages
|
||||
Or in JSON:
|
||||
|
||||
| Language | Markers | Dependency Files |
|
||||
|----------|---------|-----------------|
|
||||
| Python | pyproject.toml, setup.py, requirements.txt | requirements.txt, pyproject.toml |
|
||||
| JavaScript | package.json | package.json |
|
||||
| TypeScript | package.json, tsconfig.json | package.json |
|
||||
| Go | go.mod | go.mod |
|
||||
| Rust | Cargo.toml | Cargo.toml |
|
||||
```json
|
||||
{
|
||||
"name": "example_tool",
|
||||
"description": "An example tool",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"message": {
|
||||
"type": "string",
|
||||
"description": "The message to process",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"required": ["message"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Template System
|
||||
## Local LLM Integration
|
||||
|
||||
The tool uses Jinja2 templates for README generation. Built-in templates:
|
||||
Connect to local LLMs (Ollama, LM Studio, llama.cpp):
|
||||
|
||||
- **base**: Standard README with all sections
|
||||
- **minimal**: Basic README with essential information
|
||||
- **detailed**: Comprehensive README with extensive documentation
|
||||
```yaml
|
||||
llm:
|
||||
enabled: true
|
||||
base_url: "http://localhost:11434"
|
||||
model: "llama2"
|
||||
temperature: 0.7
|
||||
max_tokens: 2048
|
||||
```
|
||||
|
||||
### Custom Templates
|
||||
## Claude Desktop Integration
|
||||
|
||||
You can create custom templates by placing `.md.j2` files in a `templates` directory and specifying the path:
|
||||
Add to `claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-server": {
|
||||
"command": "mcp-server",
|
||||
"args": ["server", "start", "--port", "3000"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Cursor Integration
|
||||
|
||||
Add to Cursor settings (JSON):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"mcp-server": {
|
||||
"command": "mcp-server",
|
||||
"args": ["server", "start", "--port", "3000"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Shell commands are whitelisted by default
|
||||
- Blocked paths prevent access to sensitive directories
|
||||
- Command timeout prevents infinite loops
|
||||
- All operations are logged
|
||||
|
||||
## API Reference
|
||||
|
||||
### Endpoints
|
||||
|
||||
- `GET /health` - Health check
|
||||
- `GET /api/tools` - List tools
|
||||
- `POST /api/tools/call` - Call a tool
|
||||
- `POST /mcp` - MCP protocol endpoint
|
||||
|
||||
### MCP Protocol
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "initialize",
|
||||
"params": {
|
||||
"protocol_version": "2024-11-05",
|
||||
"capabilities": {},
|
||||
"client_info": {"name": "client"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Read a File
|
||||
|
||||
```bash
|
||||
auto-readme generate --template /path/to/custom_template.md.j2
|
||||
curl -X POST http://localhost:3000/api/tools/call \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "read_file", "arguments": {"path": "/path/to/file.txt"}}'
|
||||
```
|
||||
|
||||
## GitHub Actions Integration
|
||||
|
||||
Generate a GitHub Actions workflow to automatically update your README:
|
||||
### Example: List Tools
|
||||
|
||||
```bash
|
||||
auto-readme generate --github-actions
|
||||
curl http://localhost:3000/api/tools
|
||||
```
|
||||
|
||||
This creates `.github/workflows/readme-update.yml` that runs on:
|
||||
- Push to main/master branch
|
||||
- Changes to source files
|
||||
- Manual workflow dispatch
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
auto-readme-cli/
|
||||
├── src/
|
||||
│ └── auto_readme/
|
||||
│ ├── __init__.py
|
||||
│ ├── cli.py # Main CLI interface
|
||||
│ ├── models/ # Data models
|
||||
│ ├── parsers/ # Dependency parsers
|
||||
│ ├── analyzers/ # Code analyzers
|
||||
│ ├── templates/ # Jinja2 templates
|
||||
│ ├── utils/ # Utility functions
|
||||
│ ├── config/ # Configuration handling
|
||||
│ ├── interactive/ # Interactive wizard
|
||||
│ └── github/ # GitHub Actions integration
|
||||
├── tests/ # Test suite
|
||||
├── pyproject.toml
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Setting up Development Environment
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/auto-readme-cli.git
|
||||
cd auto-readme-cli
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
pytest -xvs
|
||||
```
|
||||
|
||||
### Code Formatting
|
||||
|
||||
```bash
|
||||
black src/ tests/
|
||||
isort src/ tests/
|
||||
flake8 src/ tests/
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## Changelog
|
||||
|
||||
See [CHANGELOG.md](CHANGELOG.md) for a list of changes.
|
||||
|
||||
---
|
||||
|
||||
*Generated with ❤️ by Auto README Generator CLI*
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user