Content
# UltraReview MCP Server
A Model Context Protocol (MCP) server that integrates Codex CLI, GitHub Copilot CLI, and Claude CLI with Claude Code for AI-powered code reviews and feedback.
## 🤖 VIBECODE FRIENDLY PROJECT
This project is **VIBECODE FRIENDLY** and welcomes contributions from LLMs (Large Language Models)!
- ✅ **LLM Pull Requests Welcome** - PRs generated by AI coding assistants are actively encouraged
- ✅ **AI-Generated Code Accepted** - We embrace code written by Claude, GPT, Copilot, and other AI tools
- ✅ **Human-AI Collaboration** - Perfect for testing AI coding capabilities and improving LLM workflows
- ✅ **Transparent Attribution** - Please include AI tool attribution in commits when applicable
This is an experimental space for exploring the future of human-AI collaborative development!
## ⚠️ IMPORTANT SAFETY WARNING
**USE AT YOUR OWN RISK** - This tool provides AI models with direct access to execute commands on your system through CLI tools. The AI models may:
- **Execute potentially dangerous commands** if given inappropriate permissions
- **Modify, delete, or create files** in your filesystem
- **Make network requests** or interact with external services
- **Install software** or modify system configurations
- **Access sensitive data** in your project directories
### Safety Recommendations
🔒 **Always run in isolated environments** (Docker containers, VMs, or sandboxed systems)
🔒 **Never use on production systems** or systems with sensitive data
🔒 **Review all generated commands** before execution when possible
🔒 **Use restrictive permission modes** and directory limitations
🔒 **Monitor AI outputs carefully** for unexpected or dangerous behavior
🔒 **Keep backups** of important work before using AI assistance tools
## Features
- Execute Codex CLI commands through MCP
- Execute GitHub Copilot CLI commands through MCP
- Execute Claude CLI commands through MCP
- Support for multiple models across all platforms
- Structured JSON output support
- Auto-approval and quiet modes
- Advanced tool permission management
- Integration with Claude Code
- **Comprehensive logging and debugging**
- File-based logging to `logs/` directory (daily rotation)
- Verbose debug mode for troubleshooting
- Uniform logging across all CLI handlers
- Request/response tracking with timestamps
## Prerequisites
- Python 3.10+
- [Codex CLI](https://github.com/codex-cli) installed and in PATH
- [GitHub Copilot CLI](https://github.com/github/gh-copilot) installed and in PATH
- [Claude CLI](https://claude.ai/code) installed and in PATH
- Claude Desktop or compatible MCP client
**⚠️ Note**: Each CLI tool has its own authentication requirements and safety considerations. Ensure you understand the permissions and capabilities of each tool before use.
## Installation
1. Install dependencies:
```bash
pip install -r requirements.txt
```
2. Make the server executable:
```bash
chmod +x server.py
```
## Configuration
Add to your Claude Desktop config:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"ultrareview": {
"command": "/home/user/dev/ultrareview-mcp/.venv/bin/python3",
"args": ["/home/user/dev/ultrareview-mcp/server.py"]
}
}
}
```
**Important:** Use the full absolute path to the venv Python interpreter and server.py file.
## Usage
In Claude Code, you can now use the MCP tools:
**Codex:**
```
"Ask Codex for feedback on this code"
"Ask Codex to review PR 81"
"Ask Codex for five words about apples"
```
**GitHub Copilot:**
```
"Ask Copilot for code suggestions"
"Ask Copilot to explain this function"
"Ask Copilot to optimize this algorithm"
```
**Claude CLI:**
```
"Ask Claude to analyze this codebase"
"Ask Claude for debugging help"
"Ask Claude to suggest architectural improvements"
```
The MCP server will execute the appropriate CLI command and return the results.
## Tool Parameters
### ask_codex
- **prompt** (required): The question or prompt for Codex
- **model** (optional): Model to use (uses CLI default if not specified)
- **full_auto** (optional): Auto-approve all edits and commands (workspace-write sandbox)
- **json** (optional): Print events to stdout as JSONL
- **output_schema** (optional): Path to JSON schema file for structured output
- **sandbox** (optional): Sandbox policy (read-only, workspace-write, danger-full-access)
- **working_directory** (optional): Directory to run Codex in
- **verbose** (optional): Enable verbose debugging output in response (default: false)
### ask_copilot
- **prompt** (required): The question or prompt for GitHub Copilot
- **model** (optional): Model to use (uses CLI default if not specified)
- **allow_all_tools** (optional): Allow all tools to run automatically without confirmation
- **allow_tool** (optional): List of specific tools to allow
- **deny_tool** (optional): List of specific tools to deny (takes precedence over allow_tool)
- **add_dir** (optional): List of directories to add to the allowed list for file access
- **log_level** (optional): Set the log level (error, warning, info, debug, all, default, none)
- **no_color** (optional): Disable all color output
- **verbose** (optional): Enable verbose debugging output in response (default: false)
### ask_claude
- **prompt** (required): The question or prompt for Claude CLI
- **model** (optional): Model to use (uses CLI default if not specified)
- **fallback_model** (optional): Enable automatic fallback to specified model when default model is overloaded (only works with print mode)
- **print_mode** (optional): Print response and exit (non-interactive mode) - defaults to True for MCP usage
- **output_format** (optional): Output format (uses CLI default if not specified) - only works with print mode
- **input_format** (optional): Input format (uses CLI default if not specified) - only works with print mode
- **permission_mode** (optional): Permission mode (acceptEdits, bypassPermissions, default, plan)
- **allowed_tools** (optional): List of tool names to allow (e.g. 'Bash(git:*)', 'Edit')
- **disallowed_tools** (optional): List of tool names to deny (e.g. 'Bash(git:*)', 'Edit')
- **add_dir** (optional): Additional directories to allow tool access to
- **append_system_prompt** (optional): Append a system prompt to the default system prompt
- **debug** (optional): Enable debug mode
- **verbose** (optional): Enable verbose debugging output in response (default: false)
- **dangerously_skip_permissions** (optional): Bypass all permission checks (recommended only for sandboxes)
## Examples
**Codex:**
```python
# Claude Code will call:
ask_codex(
prompt="Review this pull request and suggest improvements",
working_directory="/path/to/project"
)
# Which executes:
# codex exec "Review this pull request and suggest improvements" --cd /path/to/project
```
**GitHub Copilot:**
```python
# Claude Code will call:
ask_copilot(
prompt="Suggest improvements for this code",
allow_all_tools=True
)
# Which executes:
# copilot --prompt "Suggest improvements for this code" --allow-all-tools
```
**Claude CLI:**
```python
# Claude Code will call:
ask_claude(
prompt="Analyze this codebase for potential issues",
permission_mode="acceptEdits",
output_format="json"
)
# Which executes:
# claude --print "Analyze this codebase for potential issues" --permission-mode acceptEdits --output-format json
```
## Contributing
We welcome all contributions, especially from AI coding assistants! 🤖
### For LLM-Generated Contributions:
- Include AI tool attribution in commit messages (e.g., "Generated with Claude Code")
- Use the Co-Authored-By format: `Co-Authored-By: Claude <noreply@anthropic.com>`
- Feel free to submit PRs for bug fixes, features, documentation improvements, or optimizations
- No special approval process needed for AI-generated code
### Contribution Ideas:
- Additional CLI tool integrations (cursor, aider, etc.)
- Performance optimizations
- Error handling improvements
- Documentation enhancements
- Test coverage expansion
- Security improvements
## Logging and Debugging
The MCP server includes comprehensive logging and debugging capabilities:
### File Logging
All server activity is automatically logged to `logs/ultrareview-mcp-YYYYMMDD.log` with daily rotation. Logs include:
- Server startup and initialization
- Tool invocations with parameters
- Command execution details
- Success/failure status
- Error messages and stack traces
Log levels:
- **INFO**: General operational messages (tool calls, completions)
- **DEBUG**: Detailed execution information (commands, parameters, output sizes)
- **WARNING**: Non-fatal issues (command failures, unexpected conditions)
- **ERROR**: Fatal errors (missing commands, exceptions)
### Verbose Debug Mode
Enable verbose debugging by passing `verbose: true` to any tool:
```python
ask_codex(
prompt="Review this code",
verbose=True # Enable verbose debug output
)
```
When verbose mode is enabled, responses include:
- Full command executed
- Working directory
- System PATH
- All input arguments (JSON formatted)
- Subprocess return code
- Output lengths (stdout/stderr)
- Exception details and tracebacks (on errors)
This is especially useful when troubleshooting connection issues or unexpected behavior from the MCP client.
### Log Files
Log files are stored in the `logs/` directory (ignored by git):
- One file per day: `ultrareview-mcp-YYYYMMDD.log`
- Automatic rotation at midnight
- Timestamps in format: `YYYY-MM-DD HH:MM:SS`
- Console output only for ERROR level
## Development
Run the server directly:
```bash
python3 server.py
```
## Disclaimer
This software is provided "as is" without warranty of any kind. The authors and contributors are not responsible for any damage, data loss, security breaches, or other issues that may arise from using this tool. Users assume all responsibility for the actions performed by AI models through this MCP server.
By using this software, you acknowledge that:
- AI models can execute commands and modify files on your system
- You understand the risks associated with giving AI tools system access
- You will take appropriate precautions to protect your data and systems
- You will not hold the authors liable for any consequences of AI actions
## License
MIT
