Metadata-Version: 2.4
Name: review-mcp
Version: 0.3.1
Summary: MCP server for managing .review folder and git operations
License: MIT
License-File: LICENSE
Keywords: mcp,code-review,git,model-context-protocol
Author: EckPhi
Author-email: EckPhi@users.noreply.github.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: gitpython (>=3.1,<4.0)
Requires-Dist: mcp[cli] (>=1.0,<2.0)
Requires-Dist: pyserial (>=3.5,<4.0)
Requires-Dist: python-gitlab (>=5.6,<6.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Project-URL: Homepage, https://github.com/EckPhi/review-python-mcp
Project-URL: Repository, https://github.com/EckPhi/review-python-mcp
Description-Content-Type: text/markdown

# 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:**
```bash
pip install review-mcp
```

2. **Or install from source:**
```bash
git clone https://github.com/yourusername/review-mcp.git
cd review-mcp
pip install .
```

3. **Or with Poetry (development):**
```bash
poetry install
```

### Prerequisites
- Python 3.10 or higher
- Git (for git operations)

## Usage

### Command Line

After installation, use the `review-mcp` command:

```bash
# 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:**
```bash
pip install review-mcp
```

2. **Add to Claude Desktop config** (`~/.claude/config.json`):
```json
{
  "mcp_servers": {
    "review": {
      "command": "review-mcp",
      "args": ["run"]
    }
  }
}
```

### VS Code Copilot Integration

1. **Install the server:**
```bash
pip install review-mcp
```

2. **Add to VS Code** (easiest method):

Use the VS Code CLI to add the MCP server:

```bash
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:

```json
{
  "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:

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

#### Workspace-Specific Configuration

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

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

Or use the CLI with workspace scope:

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

#### Advanced Configuration

**Using with virtual environment:**

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

Or in settings.json:
```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:**
```bash
# Check if review-mcp is accessible
review-mcp version

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

### Programmatic Usage

```python
from review_mcp import mcp

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

### Tool Usage Examples

```python
# 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

```python
# 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

```bash
# 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

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

### Code Formatting

```bash
# Format code
poetry run black review_mcp/ tests/

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

### Adding Dependencies

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

## Distribution

### Share with Your Team

1. **Publish to PyPI:**
```bash
poetry build
poetry publish
```

2. **Or build distribution files:**
```bash
poetry build
# Distributes .whl and .tar.gz files
```

3. **Team installation:**
```bash
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

