petems · petems · Oct 17, 2025 · Oct 17, 2025 · coderabbitai · Oct 17, 2025
diff --git a/AGENTS.md b/AGENTS.md
@@ -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-spec-maker
 
 # 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-spec-maker` |
 | 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-spec-maker
 
 # 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
@@ -87,7 +87,7 @@ Optional tuning parameters:
 
 ### File Structure
 
-- `mcp_server.py`: Main server implementation
+- `src/mcp_github_pr_review_spec_maker/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)
 
-![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-spec&config=eyJjb21tYW5kIjoidXYiLCJhcmdzIjpbInJ1biIsIm1jcC1naXRodWItcHItcmV2aWV3LXNwZWMtbWFrZXIiXX0%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%22mcp-github-pr-review-spec-maker%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.
 
 > **⚠️ 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-spec-maker && mcp-github-pr-review-spec-maker`
+- 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 test_src/mcp_github_pr_review_spec_maker/server.py
 
 # Run tests with coverage (install pytest-cov first)
 pytest --cov=. --cov-report=html
@@ -182,11 +122,8 @@ To start the MCP server, run the following command in your terminal:
 # Using the installed script (after pip install -e .)
 mcp-github-pr-review-spec-maker
 
-# Or run directly
-python mcp_server.py
-
 # With UV
-uv run python mcp_server.py
+uv run mcp-github-pr-review-spec-maker
 
 # Or use the helper script (uv-first)
 ./run-server.sh                 # starts via `uv run`
@@ -219,11 +156,11 @@ 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
+  uv run --project "$(pwd)" -- mcp-github-pr-review-spec-maker
 
 # 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
+  uv run --project "$(pwd)" -- mcp-github-pr-review-spec-maker
 ```
 
 #### Codex CLI
@@ -233,7 +170,7 @@ Append to `~/.codex/config.toml`:
 ```toml
 [mcp_servers.pr-review-spec]
 command = "uv"
-args = ["run", "python", "mcp_server.py"]
+args = ["run", "mcp-github-pr-review-spec-maker"]
 
 [mcp_servers.pr-review-spec.env]
 # Optional – provide your token here, or rely on your shell environment
@@ -252,7 +189,7 @@ Edit `~/.gemini/settings.json` and add:
   "mcpServers": {
     "pr-review-spec": {
       "command": "uv",
-      "args": ["run", "python", "mcp_server.py"]
+      "args": ["run", "mcp-github-pr-review-spec-maker"]
     }
   }
 }

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-spec-maker
 ```
 
 ## 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 specification via the `specs` templates.
+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_spec_maker/server.py` and implementing async handlers under `tools/`.
+- Spec generation templates live in `specs/`. Use Markdown with frontmatter metadata 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`) to control verbosity. Logs are written to stderr by default and can be directed to a file using the `--log-file` CLI flag.
+
+### MPC Manifest overrides
-### MPC Manifest overrides
+### MCP Manifest overrides
-### MPC Manifest overrides
+### MCP Manifest overrides
+
+When packaging for MPC directories, you can bundle default configuration inside `mcp.json`. See [MCP Manifest](../reference/mcp-manifest.md) for schema guidance.
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
@@ -0,0 +1,44 @@
+# Installation
+
+The MCP server is published as the Python package `mcp-github-pr-review-spec-maker`. You can install it using `uv`, pip, or integrate it directly into a project that manages dependencies through `pyproject.toml`.
+
+## Install with `uv`
+
+```bash
+# Add the package to your environment
+uv add mcp-github-pr-review-spec-maker
+
+# Or install with extras required for development
+uv add mcp-github-pr-review-spec-maker[dev]
+```
+
+## Install with `pip`
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install mcp-github-pr-review-spec-maker
+```
+
+## Verify the Entry Point
+
+After installation, the console script `mcp-github-pr-review-spec-maker` becomes available:
+
+```bash
+mcp-github-pr-review-spec-maker --help
+```
+
+This entry point wraps `uv run python -m mcp_github_pr_review_spec_maker.server` when installed from PyPI.
+
+## Using as a Dependency
+
+If you are bundling the MCP server inside another project, declare it in your `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+  "mcp-github-pr-review-spec-maker>=0.2.0",
+]
+```
+
+The server can then be imported as `mcp_github_pr_review_spec_maker` for programmatic integration or CLI invocation.
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
@@ -0,0 +1,44 @@
+# Quickstart
+
+Follow this quickstart to run the MCP server locally with `uv` in under ten minutes.
+
+## Prerequisites
+
+- Python 3.10 or later
+- [`uv`](https://docs.astral.sh/uv/) package manager (recommended)
+- GitHub personal access token with **read** access to pull requests
+
+## Install and Run
+
+```bash
+# Clone the project
+uvx git clone https://github.com/petersouter/mcp-github-pr-review-spec-maker.git
+cd mcp-github-pr-review-spec-maker
+
+# Install runtime dependencies and the editable package
+uv sync
+
+# Provide credentials
+echo "GITHUB_TOKEN=ghp_your_token" > .env
+
+# Launch the MCP server over stdio
+uv run mcp-github-pr-review-spec-maker
+```
+
+Once the server is running, connect it from your preferred MCP host (Claude Desktop, Codex CLI, Cursor, etc.). For tailored integration steps, visit [Editor Integrations](../guides/editor-integrations.md).
+
+## Verify a Connection
+
+Use the built-in health command to ensure connectivity:
+
+```bash
+claude mcp call pr-review-spec list-tools
+```
+
+Expected response includes `fetch_pr_review_comments` and `resolve_open_pr_url`.
+
+## Next Steps
+
+1. Review [Security Requirements](../security/index.md) before enabling automated agents.
+2. Configure `PR_FETCH_MAX_*` environment limits if your repositories have high comment volume.
+3. Explore [Remote Hosting with `uv`](../guides/remote-uv-endpoint.md) to serve the MCP process over TLS.