├── .gitignore ├── .gitmodules ├── start-github.sh ├── .env.example ├── start-git.sh ├── README.md └── prompt.example /.gitignore: -------------------------------------------------------------------------------- 1 | mcp-servers/ 2 | prompt.md 3 | prompt.txt 4 | .env 5 | .DS_Store 6 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "mcp-servers"] 2 | path = mcp-servers 3 | url = https://github.com/Automattic/mcp-servers.git 4 | -------------------------------------------------------------------------------- /start-github.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | source $( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P )/.env 3 | 4 | export GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PERSONAL_ACCESS_TOKEN 5 | 6 | # Run the GitHub MCP server 7 | cd $( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P )/mcp-servers/src/github 8 | npx . -------------------------------------------------------------------------------- /.env.example: -------------------------------------------------------------------------------- 1 | # Your GitHub Personal Access Token. If you want reviews to come from 2 | # a different persona, create a new github account and add it as a contributor to your repo. 3 | GITHUB_PERSONAL_ACCESS_TOKEN={{YOUR_TOKEN_HERE}} 4 | 5 | # The project git repository path you are going to be reviewing (where the actual code is) 6 | # This should be the absolute path to the project, not a relative path using ./ or ~/ 7 | PROJECT_REPOSITORY_PATH={{YOUR_PATH_HERE}} -------------------------------------------------------------------------------- /start-git.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | PARENT_DIR=$( cd "$(dirname "${BASH_SOURCE[0]}")" ; pwd -P ) 3 | source $PARENT_DIR/.env 4 | 5 | # Run the Git MCP server with the project repository path 6 | cd $PARENT_DIR/mcp-servers/src/git 7 | rm -rf .venv 8 | uv run mcp-server-git --repository $PROJECT_REPOSITORY_PATH 9 | 10 | # Write the the PROJECT_REPOSITORY_PATH to the prompt.md file if it exists and is not already there 11 | if [ -f "$PARENT_DIR/prompt.md" ]; then 12 | if ! grep -q "repo_path" "$PARENT_DIR/prompt.md"; then 13 | echo -e "\n\nThe project repo_path is: $PROJECT_REPOSITORY_PATH" >> $PARENT_DIR/prompt.md 14 | fi 15 | fi 16 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Github PR Review Agent 2 | 3 | A friendly PR review agent for Github PRs on your projects. 4 | 5 | ## Requirements 6 | 7 | - [**uv**](https://docs.astral.sh/uv/getting-started/installation/) 8 | - [**npx**](https://docs.npmjs.com/cli/v8/commands/npx): Install using: `npm i -g npx` 9 | - [**cursor**](https://www.cursor.com/) 10 | 11 | Note: the agent uses custom modifications to the base MCP servers from Anthropic, this is why you need to install them and run locally. 12 | 13 | ## Setup 14 | 15 | 1. Clone the repository. 16 | 2. Inside the cloned repository run `git submodule update --init --recursive` to get the mcp-servers. 17 | 3. Run `npm install --prefix mcp-servers` to install mcp-servers dependencies. 18 | 4. Copy the `.env.example` file to `.env` and fill in the required values. You will need a Github personal access token. 19 | 5. Copy the `prompt.example` file to `prompt.md` file and make any changes you need. 20 | 6. Open Cursor (v0.45+) and go to `Cursor -> Settings -> Cursor Settings -> Features -> MCP Servers` 21 | 7. Add the following MCP servers: 22 | * **Git**: 23 | - Name: `Git` 24 | - Type: `Command` 25 | - Command: `bash [PATH_TO_REVIEW_AGENT_FOLDER]/start-git.sh` 26 | * **Github**: 27 | - Name: `GitHub` 28 | - Type: `Command` 29 | - Command: `bash [PATH_TO_REVIEW_AGENT_FOLDER]/start-github.sh` 30 | 8. Restart Cursor (or Developer: Reload Window) 31 | 9. Go back to the MCP Servers settings, hit the refresh button and confirm you see the tools for both the Git and GitHub servers. 32 | 10. Add the following to your Cursor rules for AI, be sure to update the path to folder: 33 | 34 | > When you see @@review used, always load the contents of this file first: [PATH_TO_REVIEW_AGENT_FOLDER]/prompt.md and follow the instructions. Use the PR URL given, or ask for a PR URL to use if there is none. 35 | 36 | ## Usage 37 | 38 | 1. Open the Cursor composer and select to use the "Agent". 39 | - Note: You do not need to be inside the project folder, however doing so will provide the agent with more context. 40 | 2. Type `@@review` and paste a link to a Github PR that has been opened for the project you pointed the `PROJECT_REPOSITORY_PATH` in `.env` to. 41 | 3. The agent will ask you to run a number of Github and Git MCP tools and gather the information it needs to review the PR. 42 | 4. The agent will then write a review of the PR and share it with you for approval. 43 | 5. Once you approve the review, the agent will post it as a comment on the PR. 44 | 45 | ## Notes 46 | 47 | * This will also work for other MCP supporting tools like Claude Desktop, or Goose. 48 | * ~The agent will only review the diff, it will not yet read the full PR description.~ The agent will now read your PR descriptions to guide its review. 49 | * The agent will not yet make any changes to the PR, it will only review the diff. 50 | 51 | ## Future Work 52 | 53 | * Continue experimenting with Goose CLI to see if this can be automated. I ran into tool calling issues with the canary branch. 54 | * Get the agent to read the full PR description and use that as context for the review. 55 | * Get the agent to follow testing instructions, and implement computer use to testing functionality. 56 | * Get the agent to auto-respond to comments on the PR asking for clarification. 57 | -------------------------------------------------------------------------------- /prompt.example: -------------------------------------------------------------------------------- 1 | You are a friendly, collaborative developer reviewing a teammate's code. Your goal is to provide helpful, constructive feedback in a casual and supportive way. 2 | 3 | Follow these steps for an accurate review: 4 | 5 | 1. Extract PR Info from the URL: 6 | * Get the owner, repo, and pull_number from the PR URL. 7 | * Get the PR information using this data and the appropriate Github tool. 8 | * This will give you the exact SHAs to compare. 9 | 10 | 2. Analyze PR Description and Testing Instructions: 11 | * Use the PR description from the previous step to understand the context and purpose of the changes. 12 | * Look for any testing instructions in the description, usually marked with headers like "Testing" or "How to Test". 13 | * Identify if the testing steps are UI/visual focused or functionality focused. 14 | * For UI changes, focus on understanding the intended visual or UX improvements. 15 | * For functional changes, note any specific scenarios or edge cases mentioned that should be reviewed carefully. 16 | * Check if there are any related issues or dependencies mentioned that provide additional context. 17 | * Consider how well the actual changes align with what's described in the PR description. 18 | 19 | 3. Get the details you need to review the PR changes 20 | * Use the 'git_diff' tool to see exactly what changed in this PR compared to the base branch. 21 | * Output the diff and use this for analysis. 22 | * If needed, search the codebase using the git repo path for any relevant context outside of the code changes in the PR. 23 | 24 | 4. Write a review: 25 | * The review message should always start with the following: 26 | - "> [!IMPORTANT] \n > This is an AI-generated review by https://github.com/Automattic/pr-review-agent/ \n\n" 27 | * Structure it like a casual conversation. 28 | * Keep the review to 1 to 3 items that can be improved. One big item with code examples is better than 3 minor items. 29 | * Don't mention an item unless there's something that can be improved about it and it's immediately actionable. 30 | * Provide code examples when it's useful. 31 | * Keep exclamation points to a minimum, while staying friendly. 32 | * Talk like you're chatting with a teammate. 33 | * Address any gaps between the PR description and the actual changes. 34 | * For UI/visual changes: 35 | - Acknowledge that you cannot verify the visual results 36 | - Review the technical implementation of UI changes (CSS, HTML structure, accessibility, etc.) 37 | * For functional changes: 38 | - If testing instructions were provided, verify the changes can be tested as described 39 | - If no testing instructions were provided, suggest what should be tested 40 | 41 | 5. Handling the Review: 42 | * Share the review text with the user for confirmation. 43 | * Ask the user for confirmation before posting the review. DO NOT post the review until you receive confirmation. 44 | * Once approved, post it as a comment using tool: 'add_issue_comment'. 45 | 46 | 6. Important Reminders: 47 | * Only review what's in the git diff using the base SHA from the PR. 48 | * Don't assume anything about code not shown. 49 | * Double-check the diff if you see unexpected changes like code being removed that doesn't make sense. 50 | * Version number conflicts usually mean trunk needs updating. 51 | * Ignore changes that look like they are generated. 52 | * Ignore the git repo path for anything other than git tool usage. 53 | --------------------------------------------------------------------------------