Review MCP Server

A powerful MCP (Model Context Protocol) server for managing code review workflows with .review folder management and comprehensive read-only git operations.

Perfect for teams doing code reviews, collaborative analysis, and distributed development workflows.

Features

File Management Tools

• create_review_file — Create new files in .review folder
• read_review_file — Read files from .review folder
• update_review_file — Update existing files in .review folder
• delete_review_file — Delete files from .review folder
• list_review_files — List all files in .review folder

Temporary Directory Tools

• create_temp_dir — Create a new temporary directory (returns its path)
• write_temp_file — Write a file in a temporary directory
• read_temp_file — Read a file from a temporary directory

These tools are useful for workflows that require isolated, short-lived storage for intermediate files or scratch data. All paths are validated to prevent directory traversal.

Git Tools (Read-Only)

• git_log — Show recent commits (configurable count)
• git_status — Show repository status (branches, staged, unstaged changes)
• git_diff — Compare changes between refs, branches, or working directory
• git_show — Show details of a specific commit/branch/tag
• git_branch — List all branches with current branch marked
• git_remote — List all remotes and their URLs
• git_tag — List all tags in the repository
• git_blame — Show who changed each line in a file

Serial Tools

• serial_list_ports — List detected serial ports
• serial_open — Open a serial connection (COMx or /dev/tty*)
• serial_write — Send data with utf8/hex/base64 encoding
• serial_read — Read serial data with clean-mode options for automation
• serial_detect_prompt — Detect terminal prompt presence in last read buffer
• serial_status — Show connection metadata and byte counters
• serial_list_connections — Show all active serial connections
• serial_close — Close an open connection

Installation

For Teams (Recommended)

1. Install from PyPI:

pip install review-mcp

2. Or install from source:

git clone https://github.com/yourusername/review-mcp.git
cd review-mcp
pip install .

3. Or with Poetry (development):

poetry install

Prerequisites

• Python 3.10 or higher
• Git (for git operations)

Usage

Command Line

After installation, use the review-mcp command:

# Run with stdio transport (default)
review-mcp run

# Run with HTTP transport
review-mcp run --transport streamable-http

# Run on specific host/port
review-mcp run --transport streamable-http --host 0.0.0.0 --port 9000

# Show available tools
review-mcp info

# Show version
review-mcp version

Claude Desktop Integration

1. Install the server:

pip install review-mcp

2. Add to Claude Desktop config (~/.claude/config.json):

{
  "mcp_servers": {
    "review": {
      "command": "review-mcp",
      "args": ["run"]
    }
  }
}

VS Code Copilot Integration

1. Install the server:

pip install review-mcp

2. Add to VS Code (easiest method):

Use the VS Code CLI to add the MCP server:

code --add-mcp "{\"name\":\"review-mcp\",\"command\":\"review-mcp\",\"args\":[\"run\"]}"

3. Reload VS Code (Ctrl+Shift+P → "Developer: Reload Window")

4. Verify Installation:

   • Open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I)
   • Type @review-mcp or use review tools in your conversations
   • You should see the review-mcp tools available

Alternative: Manual Configuration

If you prefer to edit settings manually:

1. Open VS Code Settings (Ctrl+, or Cmd+,)
2. Search for "MCP Servers" or navigate to Extensions → GitHub Copilot → MCP Servers
3. Click "Edit in settings.json" and add:

{
  "github.copilot.chat.mcpServers": {
    "review-mcp": {
      "command": "review-mcp",
      "args": ["run"]
    }
  }
}

Alternative: Manual Configuration

If you prefer to edit settings manually:

1. Open VS Code Settings (Ctrl+, or Cmd+,)
2. Search for "MCP Servers" or navigate to Extensions → GitHub Copilot → MCP Servers
3. Click "Edit in settings.json" and add:

{
  "github.copilot.chat.mcpServers": {
    "review-mcp": {
      "command": "review-mcp",
      "args": ["run"]
    }
  }
}

Workspace-Specific Configuration

For project-specific configuration, add to .vscode/settings.json:

{
  "github.copilot.chat.mcpServers": {
    "review-mcp": {
      "command": "review-mcp",
      "args": ["run"],
      "env": {
        "CUSTOM_VAR": "value"
      }
    }
  }
}

Or use the CLI with workspace scope:

code --add-mcp "{\"name\":\"review-mcp\",\"command\":\"review-mcp\",\"args\":[\"run\"]}" --workspace

Advanced Configuration

Using with virtual environment:

# CLI method with full path
code --add-mcp "{\"name\":\"review-mcp\",\"command\":\"/path/to/venv/bin/review-mcp\",\"args\":[\"run\"]}"

Or in settings.json:

{
  "github.copilot.chat.mcpServers": {
    "review-mcp": {
      "command": "/path/to/venv/bin/review-mcp",
      "args": ["run"]
    }
  }
}

Troubleshooting VS Code Integration

Tools not showing up:

• Ensure review-mcp is in your PATH: which review-mcp (Unix) or where review-mcp (Windows)
• Try adding with full path: code --add-mcp "{\"name\":\"review-mcp\",\"command\":\"/full/path/to/review-mcp\",\"args\":[\"run\"]}"
• Check VS Code Output panel → GitHub Copilot for errors
• Reload VS Code window after adding the server

Permission errors:

• Windows: Make sure Python Scripts folder is in PATH
• Unix/Mac: Verify executable permissions: chmod +x $(which review-mcp)

Verify installation:

# Check if review-mcp is accessible
review-mcp version

# Check PATH location
where review-mcp    # Windows
which review-mcp    # Unix/Mac

Programmatic Usage

from review_mcp import mcp

# Server is already initialized and ready to use
mcp.run(transport="stdio")

Tool Usage Examples

# File operations
create_review_file("analysis.md", "## Code Review\n\n- Point 1")
read_review_file("analysis.md")
update_review_file("analysis.md", "## Updated Review")
delete_review_file("analysis.md")
list_review_files()

# Temporary directory operations
temp_dir = create_temp_dir()
write_temp_file(temp_dir, "scratch.txt", "Temporary notes")
content = read_temp_file(temp_dir, "scratch.txt")

# Git operations
git_log(max_count=20)
git_status()
git_diff(from_ref="develop", to_ref="HEAD")
git_show(ref="HEAD~1")
git_branch()
git_remote()
git_tag()
git_blame(file="src/main.py")

# Serial operations
serial_list_ports()
open_result = serial_open(port="COM22", baud_rate=115200)
serial_write(connection_id, "help\n")
serial_read(connection_id, max_bytes=4096)
serial_close(connection_id)

Serial Scripting Mode

Firmware terminal output often includes ANSI color and cursor-control sequences intended for interactive terminals. For automation, serial_read defaults to clean mode so scripts receive parse-friendly text.

serial_read Parameters (Automation-Relevant)

• strip_ansi (bool, default true): remove ANSI/color/cursor escape sequences.
• trim_prompt (bool, default true): remove trailing prompt token from output.
• strip_command_echo (bool, default true): remove echoed command from response start.
• prompt (str, default "BASEIO>"): prompt token used for trimming and prompt detection.
• max_read_iterations (int, default 1): upper bound for polling loops when waiting for complete data.
• wait_for_ok (bool, default false): continue polling until OK appears or iteration limit is hit.

Clean vs Raw Example

# Clean output (default)
serial_write(connection_id, "status\r\n")
clean = serial_read(connection_id, max_bytes=4096)

# Raw terminal output (keeps ANSI/prompt/echo)
raw = serial_read(
    connection_id,
    max_bytes=4096,
    strip_ansi=False,
    trim_prompt=False,
    strip_command_echo=False,
)

Firmware ANSI Sequences Observed

• \x1b[37m: white text
• \x1b[32m: green text
• \x1b[33m: yellow text
• \x1b[1G: cursor to column 1
• \x1b[K: clear from cursor to end of line
• \x1b[8G: cursor to column 8

These are stripped in clean mode because they are presentation controls, not data.

Project Structure

review-mcp/
├── review_mcp/           # Main package
│   ├── __init__.py       # Package initialization
│   ├── __main__.py       # Python -m support
│   ├── server.py         # Core server with all tools
│   ├── cli.py            # CLI commands
├── tests/                # Test suite
│   ├── __init__.py
│   └── test_server.py    # 43 comprehensive tests
├── pyproject.toml        # Poetry configuration
├── poetry.lock           # Dependency lock file
├── README.md             # This file
└── .review/              # Created automatically (stores review files)

Security

• Path Traversal Prevention: File operations are restricted to .review folder only. Paths with .. or absolute paths are rejected.
• Read-Only Git: All git operations are read-only. No write operations (commit, push, merge) are exposed.
• File Validation: All file paths are validated to prevent escape from .review folder.
• Package Safety: Distributed as a verified package with secure dependencies.

Testing

# Run all tests
poetry run pytest

# Run with verbose output
poetry run pytest -v

# Run specific test class
poetry run pytest tests/test_server.py::TestFileManagement -v

# Run with coverage
poetry run pytest --cov=review_mcp tests/

The project includes 43 comprehensive tests covering:

• All file management operations
• All git operations
• Path validation and security
• Error handling and edge cases

Development

Setup Development Environment

git clone https://github.com/yourusername/review-mcp.git
cd review-mcp
poetry install

Code Formatting

# Format code
poetry run black review_mcp/ tests/

# Check code quality
poetry run ruff check review_mcp/ tests/

Adding Dependencies

poetry add new-package
poetry add --group dev pytest-new-plugin

Distribution

Share with Your Team

1. Publish to PyPI:

poetry build
poetry publish

2. Or build distribution files:

poetry build
# Distributes .whl and .tar.gz files

3. Team installation:

pip install review-mcp
# or if you have the file locally:
pip install review_mcp-0.1.0-py3-none-any.whl

Create a Private Package Index

For private team distribution, consider:

• Private PyPI server
• GitHub Packages
• AWS CodeArtifact
• JFrog Artifactory

Configuration

Environment Variables

No special environment variables required. Uses standard git configuration.

.review Folder

The .review folder is automatically created in your current working directory when needed. All review files are stored relative to this location.

Error Handling

All tools return descriptive error messages:

• Invalid file paths return path traversal errors
• Missing files return "not found" errors
• Repository errors return git-specific error messages
• All exceptions are caught and returned as error strings

Contributing

Contributions welcome! Please ensure:

1. All tests pass (poetry run pytest)
2. Code is formatted (poetry run black review_mcp/)
3. New features include tests
4. Documentation is updated

License

MIT License - See LICENSE file for details

Support

For issues, questions, or contributions:

• GitHub Issues: https://github.com/yourusername/review-mcp/issues
• GitHub Discussions: https://github.com/yourusername/review-mcp/discussions

Changelog

v0.1.0 (Current Release)

• ✅ File management in .review folder with path traversal prevention
• ✅ Git read-only operations (log, status, diff, show, branch, remote, tag, blame)
• ✅ Enhanced git_diff supporting branch/commit comparisons
• ✅ CLI with multiple transport modes (stdio, HTTP, SSE)
• ✅ Comprehensive test suite (43 tests, 100% passing)
• ✅ Full MCP protocol compliance
• ✅ Python package distribution ready