petems · petems · Oct 22, 2025 · Oct 17, 2025 · Oct 17, 2025 · Oct 17, 2025
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,6 +1,6 @@
 # Agent Development Guide
 
-This repository contains a **Model Context Protocol (MCP) server** that fetches GitHub PR review comments and generates markdown specifications. The application is built with modern Python tooling and follows strict development practices.
+This repository contains a **Model Context Protocol (MCP) server** that fetches and formats GitHub PR review comments. The application is built with modern Python tooling and follows strict development practices.
 
 > **⚠️ Critical Security Warning**: Before using this MCP server in any agent workflows, carefully read [SECURITY.md](SECURITY.md). This document contains essential warnings about the risks of automated implementation of PR comments, including potential security vulnerabilities and the need for human oversight.
 
@@ -121,7 +121,7 @@ Auto-resolves PR URL from current git repository context.
 uv sync --dev
 
 # Run server
-uv run python mcp_server.py
+uv run mcp-github-pr-review
 
 # Quality checks
 make lint          # uv run ruff check .
@@ -234,7 +234,7 @@ uv run pytest tests/test_integration.py::TestEndToEndWorkflow::test_complete_moc
 |------|---------|
 | Setup | `uv sync --dev` |
 | Quality Check | `make format && make lint && make test` |
-| Run Server | `uv run python mcp_server.py` |
+| Run Server | `uv run mcp-github-pr-review` |
 | Test Specific File | `uv run pytest tests/test_file.py -v` |
 | Fix Linting | `uv run ruff check --fix .` |
 | Format Code | `uv run ruff format .` |
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -37,7 +37,7 @@ uv run pytest tests/test_git_pr_resolver.py -v
 make compile-check
 
 # Run the MCP server
-uv run python mcp_server.py
+uv run mcp-github-pr-review
 
 # Pre-commit quality check (format, lint, type, syntax, test)
 uv run ruff format . && uv run ruff check --fix . && uv run mypy . && make compile-check && uv run pytest
@@ -48,11 +48,11 @@ uv run ruff format --check . && uv run ruff check . && uv run mypy . && make com
 
 ## Architecture Overview
 
-This is a Model Context Protocol (MCP) server that provides tools for fetching GitHub PR review comments and generating markdown specifications.
+This is a Model Context Protocol (MCP) server that provides tools for fetching and formatting GitHub PR review comments with resolution status and diff context.
 
 ### Core Components
 
-- **`ReviewSpecGenerator` class**: Main MCP server class that handles tool registration and execution
+- **`PRReviewServer` class**: Main MCP server class that handles tool registration and execution
 - **`fetch_pr_comments()` async function**: Core GitHub API integration with pagination, error handling, and retry logic
 - **`generate_markdown()` function**: Converts review comments to formatted markdown with dynamic code fencing
 - **`get_pr_info()` function**: URL parser for extracting owner/repo/PR number from GitHub URLs
@@ -87,7 +87,7 @@ Optional tuning parameters:
 
 ### File Structure
 
-- `mcp_server.py`: Main server implementation
+- `src/mcp_github_pr_review/server.py`: Main server implementation
 - `tests/`: Consolidated pytest suite and fixtures
   - `tests/conftest.py`: Common fixtures (HTTP client mock, git context, temp dirs, timeouts)
   - `tests/test_git_pr_resolver.py`: Unit tests for PR resolution utilities

diff --git a/README.md b/README.md
@@ -1,82 +1,22 @@
-# GitHub PR Review Spec Generator (MCP Server)
+# GitHub PR Review MCP Server
 
-![Demo](docs/demo.gif)
+![Demo](docs/assets/demo.gif)
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=pr-review-spec&config=eyJjb21tYW5kIjoidXYiLCJhcmdzIjpbInJ1biIsInB5dGhvbiIsIm1jcF9zZXJ2ZXIucHkiXX0%3D) [<img alt="Install in VS Code (uv)" src="https://img.shields.io/badge/Install%20in%20VS%20Code-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22pr-review-spec%22%2C%22command%22%3A%22uv%22%2C%22args%22%3A%5B%22run%22%2C%22python%22%2C%22mcp_server.py%22%5D%7D)
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=pr-review&config=eyJjb21tYW5kIjoidXYiLCJhcmdzIjpbInJ1biIsIm1jcC1naXRodWItcHItcmV2aWV3Il19) [<img alt="Install in VS Code (uv)" src="https://img.shields.io/badge/Install%20in%20VS%20Code-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22pr-review%22%2C%22command%22%3A%22uv%22%2C%22args%22%3A%5B%22run%22%2C%22mcp-github-pr-review%22%5D%7D)
 
-This is a Model Context Protocol (MCP) server that allows a large language model (LLM) like Claude to fetch review comments from a GitHub pull request and generate markdown specifications.
+This is a Model Context Protocol (MCP) server that allows a large language model (LLM) like Claude to fetch and format review comments from a GitHub pull request.
 
 > **⚠️ Security Notice**: Please read [SECURITY.md](SECURITY.md) for important security considerations, especially regarding agentic workflows and automated implementation of PR comments.
 
-## Prerequisites
+## Documentation & Quickstart
 
-- Python 3.9 or higher
-- [uv](https://docs.astral.sh/uv/) - modern Python package manager (recommended)
-
-## Setup
-
-### Option 1: Using UV (Recommended)
-
-1. **Install UV (if not already installed):**
-   ```bash
-   # On macOS and Linux
-   curl -LsSf https://astral.sh/uv/install.sh | sh
-
-   # On Windows
-   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
-
-   # Or with pip
-   pip install uv
-   ```
-
-2. **Clone the repository:**
-   ```bash
-   git clone <repository_url>
-   cd <repository_directory>
-   ```
-
-3. **Install dependencies:**
-   ```bash
-   # Install production dependencies
-   uv pip install -e .
-
-   # Install development dependencies
-   uv pip install -e ".[dev]"
-
-   # Or install all dependencies in one command
-   uv sync --all-extras
-   ```
-
-4. **Set up environment variables:**
-   - Create a `.env` file and add your GitHub personal access token:
-     ```bash
-     echo "GITHUB_TOKEN=your_github_token_here" > .env
-     ```
-
-### Option 2: Using Traditional pip (Legacy)
-
-1. **Clone the repository:**
-   ```bash
-   git clone <repository_url>
-   cd <repository_directory>
-   ```
-
-2. **Create and activate virtual environment:**
-   ```bash
-   python -m venv venv
-   source venv/bin/activate  # On Windows: venv\Scripts\activate
-   ```
-
-3. **Install dependencies:**
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-4. **Set up environment variables:**
-   - Create a `.env` file and add your GitHub personal access token:
-     ```bash
-     echo "GITHUB_TOKEN=your_github_token_here" > .env
-     ```
+- **Prerequisites**: Python 3.10+, [`uv`](https://docs.astral.sh/uv/)
+- **Quickstart**: `uv add mcp-github-pr-review && mcp-github-pr-review`
+- Full documentation lives in [`docs/`](docs/index.md) and is published via [MkDocs](https://www.mkdocs.org/). Key entry points:
+  - [Quickstart](docs/getting-started/quickstart.md)
+  - [Installation](docs/getting-started/installation.md)
+  - [Remote hosting with `uv`](docs/guides/remote-uv-endpoint.md)
+  - [MCP manifest guidance](docs/reference/mcp-manifest.md)
 
 ## Enterprise GitHub Support
 
@@ -156,7 +96,7 @@ pytest
 pytest -v
 
 # Run specific test file
-pytest test_mcp_server.py
+pytest tests/test_integration.py
 
 # Run tests with coverage (install pytest-cov first)
 pytest --cov=. --cov-report=html
@@ -180,19 +120,16 @@ To start the MCP server, run the following command in your terminal:
 
 ```bash
 # Using the installed script (after pip install -e .)
-mcp-github-pr-review-spec-maker
-
-# Or run directly
-python mcp_server.py
+mcp-github-pr-review
 
 # With UV
-uv run python mcp_server.py
+uv run mcp-github-pr-review
 
 # Or use the helper script (uv-first)
 ./run-server.sh                 # starts via `uv run`
 ./run-server.sh --sync          # sync deps first
 ./run-server.sh --log           # also write logs/logs/mcp_server.log
-./run-server.sh --register      # register with Claude CLI as `pr-review-spec`
+./run-server.sh --register      # register with Claude CLI as `pr-review`
 ./run-server.sh --codex         # configure Codex CLI to use this server
 ```
 
@@ -218,24 +155,24 @@ Run these from the repo root so `$(pwd)` points to this project.
 
 ```bash
 # Minimal (pass env vars if needed)
-claude mcp add pr-review-spec -s user -- \
-  uv run --project "$(pwd)" -- python mcp_server.py
+claude mcp add pr-review -s user -- \
+  uv run --project "$(pwd)" -- mcp-github-pr-review
 
 # Example with env var (GitHub token)
-claude mcp add pr-review-spec -s user -e GITHUB_TOKEN="$GITHUB_TOKEN" -- \
-  uv run --project "$(pwd)" -- python mcp_server.py
+claude mcp add pr-review -s user -e GITHUB_TOKEN="$GITHUB_TOKEN" -- \
+  uv run --project "$(pwd)" -- mcp-github-pr-review
 ```
 
 #### Codex CLI
 
 Append to `~/.codex/config.toml`:
 
 ```toml
-[mcp_servers.pr-review-spec]
+[mcp_servers.pr-review]
 command = "uv"
-args = ["run", "python", "mcp_server.py"]
+args = ["run", "mcp-github-pr-review"]
 
-[mcp_servers.pr-review-spec.env]
+[mcp_servers.pr-review.env]
 # Optional – provide your token here, or rely on your shell environment
 # GITHUB_TOKEN = "your_github_token_here"
 PATH = "/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:$HOME/.local/bin:$HOME/.cargo/bin:$HOME/bin"
@@ -250,9 +187,9 @@ Edit `~/.gemini/settings.json` and add:
 ```json
 {
   "mcpServers": {
-    "pr-review-spec": {
+    "pr-review": {
       "command": "uv",
-      "args": ["run", "python", "mcp_server.py"]
+      "args": ["run", "mcp-github-pr-review"]
     }
   }
 }

diff --git a/SECURITY.md b/SECURITY.md
@@ -1,12 +1,12 @@
 # Security Considerations
 
-This document outlines the security design decisions, hardening measures, and important safety considerations for the GitHub PR Review Spec Generator MCP server.
+This document outlines the security design decisions, hardening measures, and important safety considerations for the GitHub PR Review MCP Server.
 
 ## File Creation Removal
 
 ### Background
 
-This MCP server originally included functionality to create markdown specification files on disk via a `create_review_spec_file` tool. This feature was intentionally removed due to security complexity and concerns.
+This server originally included functionality to create markdown files on disk via a `create_review_spec_file` tool. This feature was intentionally removed due to security complexity and concerns.
 
 ### Security Rationale
 

diff --git a/UV_COMMANDS.md b/UV_COMMANDS.md
@@ -21,7 +21,7 @@ uv run pytest
 uv run pytest -v
 
 # Run the MCP server
-uv run python mcp_server.py
+uv run mcp-github-pr-review
 ```
 
 ## Quick Quality Check

diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
@@ -0,0 +1,33 @@
+# Architecture Overview
+
+The MCP server orchestrates three subsystems:
+
+1. **Transport layer** (`mcp` framework): handles stdio protocol negotiation and tool invocation.
+2. **GitHub client** (`httpx`): fetches pull-request review comments with retry and pagination safeguards.
+3. **Git workspace resolver** (`dulwich`): maps the active git repository to a PR URL when one is not provided.
+
+![Architecture Diagram](../assets/demo.gif)
+
+## Execution Flow
+
+1. MCP host calls `fetch_pr_review_comments`.
+2. Server resolves the PR URL using the `git_pr_resolver` module when necessary.
+3. HTTP requests retrieve review comments, applying concurrency and rate limiting.
+4. Comments are transformed into a markdown document.
+5. Response returns to the host in the requested format (Markdown or JSON).
+
+## Concurrency Model
+
+The server is asynchronous, relying on `asyncio` to keep HTTP operations non-blocking. HTTP calls use `httpx.AsyncClient` with circuit breakers for GitHub throttling.
+
+## Error Handling
+
+- Expected HTTP failures (401, 403, 404) surface as structured MCP errors for agent awareness.
+- Transient errors trigger retries with exponential backoff and jitter.
+- Uncaught exceptions are logged with stack traces but masked from remote clients to avoid information leakage.
+
+## Extensibility
+
+- Add new MCP tools by registering their schema in `src/mcp_github_pr_review/server.py` and implementing async handlers under `tools/`.
+- Comment formatting templates live in the server code. Extend the `generate_markdown()` function for new output formats.
+- Logging integrates with standard `logging` instrumentation. Add adapters to stream to JSON or observability backends.
diff --git a/docs/demo.cast → docs/assets/demo.cast b/docs/demo.cast → docs/assets/demo.cast
diff --git a/docs/demo.gif → docs/assets/demo.gif b/docs/demo.gif → docs/assets/demo.gif
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,8 @@
+# Changelog
+
+Document notable changes per release. Follow [Keep a Changelog](https://keepachangelog.com/) format.
+
+## [Unreleased]
+
+- Initial migration to MkDocs documentation structure.
+- Planned PyPI packaging with console entry point.
diff --git a/docs/contributing/index.md b/docs/contributing/index.md
@@ -0,0 +1,37 @@
+# Contributing Guide
+
+Follow this workflow to submit improvements or bug fixes.
+
+## Prerequisites
+
+- Python 3.10+
+- `uv` package manager
+- `pre-commit`
+
+## Local Setup
+
+```bash
+uv sync --dev
+uv run --extra dev pre-commit install
+uv run --extra dev pre-commit install --hook-type commit-msg
+```
+
+## Development Loop
+
+```bash
+uv run ruff format .
+uv run ruff check --fix .
+uv run mypy .
+make compile-check
+uv run pytest
+```
+
+## Conventional Commits
+
+Commit messages must follow [Conventional Commits](https://www.conventionalcommits.org/). Hooks enforce this automatically.
+
+## Opening a Pull Request
+
+1. Ensure the full quality pipeline passes.
+2. Update documentation in `docs/` and `CHANGELOG.md` when behaviour changes.
+3. Link related issues and request review from maintainers.
diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md
@@ -0,0 +1,29 @@
+# Configuration
+
+The MCP server reads configuration from environment variables or a `.env` file in the working directory. Use these controls to tune pagination limits, HTTP behaviour, and GitHub endpoints.
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `GITHUB_TOKEN` | ✅ | — | GitHub personal access token scoped to read pull-request comments. |
+| `GH_HOST` | ❌ | `github.com` | GitHub Enterprise hostname. Automatically derives REST/GraphQL endpoints. |
+| `GITHUB_API_URL` | ❌ | `https://{GH_HOST}/api/v3` | Override REST endpoint when the default convention is incorrect. |
+| `GITHUB_GRAPHQL_URL` | ❌ | `https://{GH_HOST}/api/graphql` | Override GraphQL endpoint. |
+| `PR_FETCH_MAX_PAGES` | ❌ | `50` | Maximum pages fetched per PR to prevent runaway pagination. |
+| `PR_FETCH_MAX_COMMENTS` | ❌ | `2000` | Cap on total review comments collected. |
+| `HTTP_PER_PAGE` | ❌ | `100` | GitHub page size. Must be between 1 and 100. |
+| `HTTP_MAX_RETRIES` | ❌ | `3` | Retry budget applied to transient HTTP failures. |
+
+Store secrets using `.env` in development and delegate to your secrets manager or CI variables in production:
+
+```bash
+GITHUB_TOKEN=ghp_...
+PR_FETCH_MAX_COMMENTS=1000
+```
+
+## Logging configuration
+
+Set `LOG_LEVEL` (`DEBUG`, `INFO`, `WARNING`, `ERROR`; default `INFO`) to control verbosity. Logs are written to stderr by default and can be directed to a file using the `--log-file` CLI flag.
+
+## MCP Manifest overrides
+
+When packaging for MCP directories, you can bundle default configuration inside `mcp.json`. See [MCP Manifest](../reference/mcp-manifest.md) for schema guidance.