CLean up docs and prompt

Author: karlclement

.env.example

@@ -8,13 +8,17 @@ GITHUB_APP_PRIVATE_KEY_PATH=./private-key.pem
 GITHUB_WEBHOOK_SECRET=your_webhook_secret
 GITHUB_REDIRECT_URI=http://localhost:5053/github/callback
 GITHUB_BASE_URL=https://github.com
+GITHUB_APP_CWD=/Users/username/project/your-repo
+
+# MCP Configuration
+MCP_AUTH_TOKEN=your_mcp_secret
+CRA_PUBLIC_URL=https://ngrok-your-url.app
 
 # Server Configuration
-PORT=5053
-DEBUG=true
-APP_BASE_URL=http://localhost:5053
+APP_BASE_URL=https://ngrok-your-url.app
+SERVER_PORT=5053
+SERVER_DEBUG=true
 
 # Amp Configuration
-AMP_TIMEOUT=60000
-AMP_SERVER_URL=ws://localhost:3001
-AMP_URL=http://localhost:3001
+AMP_TIMEOUT=300
+AMP_SERVER_URL=https://ampcode.com

README.md

@@ -9,6 +9,8 @@ A GitHub App for automated code reviews using Hono.js and Amp.
 - **Queue Management**: Efficient job queuing and processing
 - **Code Review**: AI-powered code analysis and feedback
 - **Check Runs**: Integration with GitHub's check runs API for status reporting
+- **MCP Server**: Model Context Protocol server for AI agent integration
+- **Dashboard**: Web interface for installation management
 
 ## Quick Start
 
@@ -21,7 +23,6 @@ A GitHub App for automated code reviews using Hono.js and Amp.
 2. **Environment Setup**
    ```bash
    cp .env.example .env
-   # Edit .env with your GitHub app credentials
    ```
 
 3. **Start Development Server**
@@ -30,9 +31,10 @@ A GitHub App for automated code reviews using Hono.js and Amp.
    ```
 
 4. **Install the App**
-   - Visit `http://localhost:5053/github/install`
+   - Visit `{APP_BASE_URL}/github/install` (e.g., `https://your-ngrok-url.app/github/install`)
    - Follow the GitHub App installation flow
    - Select repositories to enable code reviews
+   - Access dashboard at `{APP_BASE_URL}/github/dashboard/{installationId}`
 
 ## Configuration
 
@@ -45,46 +47,66 @@ A GitHub App for automated code reviews using Hono.js and Amp.
    - Repository: Contents (Read)
    - Repository: Metadata (Read)
 3. **Configure webhook settings:**
-   - Webhook URL: `https://your-domain.com/github/webhook`
-   - Subscribe to: Pull request events
+   - Webhook URL: `https://your-domain.com/github/webhook` (use your CRA_PUBLIC_URL)
+   - Subscribe to: Pull request events and Installation events
 4. **Generate and download a private key** from the app settings page
 
 ### Environment Variables
 
 #### GitHub App Configuration (Required)
 ```env
 # GitHub App ID (found in app settings)
-GITHUB_APP_ID=123456
+GITHUB_APP_ID=your_github_app_id
 
 # GitHub App name (used in installation URL)
 GITHUB_APP_NAME=your-app-name
 
 # GitHub App Client ID and Secret
-GITHUB_APP_CLIENT_ID=Iv1.abc123def456
-GITHUB_APP_CLIENT_SECRET=your_app_client_secret
+GITHUB_APP_CLIENT_ID=your_github_app_client_id
+GITHUB_APP_CLIENT_SECRET=your_github_app_client_secret
 
 # Private Key Setup (choose one option)
 # Option 1: Private key file path
 GITHUB_APP_PRIVATE_KEY_PATH=./private-key.pem
 
 # Option 2: Private key as environment variable (base64 encoded)
-GITHUB_APP_PRIVATE_KEY=LS0tLS1CRUdJTi...your_base64_encoded_key
+GITHUB_APP_PRIVATE_KEY=your_github_app_private_key_base64_encoded
 
-# Webhook secret (optional but recommended)
+# Webhook and redirect configuration
 GITHUB_WEBHOOK_SECRET=your_webhook_secret
+GITHUB_REDIRECT_URI=http://localhost:5053/github/callback
+GITHUB_BASE_URL=https://github.com
+
+# Working directory for the app (used by MCP server)
+GITHUB_APP_CWD=/Users/username/project/your-repo
+```
+
+#### MCP Configuration
+```env
+# MCP Server Authentication
+MCP_AUTH_TOKEN=your_mcp_secret
+
+# Public URL for webhooks (use ngrok or similar for development)
+CRA_PUBLIC_URL=https://ngrok-your-url.app
 ```
 
 #### Server Configuration
 ```env
+# Base URL for the application
+APP_BASE_URL=https://ngrok-your-url.app
+
 # Server settings
-PORT=5053
-DEBUG=true
-APP_BASE_URL=http://localhost:5053
-
-# Amp Configuration
-AMP_TIMEOUT=60000
-AMP_SERVER_URL=ws://localhost:3001
-AMP_URL=http://localhost:3001
+SERVER_PORT=5053
+SERVER_DEBUG=true
+```
+
+#### Amp Configuration
+```env
+# Amp timeout (in seconds)
+AMP_TIMEOUT=300
+
+# Amp server URL (use ampcode.com for hosted service)
+AMP_SERVER_URL=https://ampcode.com
 ```
 
 ### Private Key Setup
@@ -110,18 +132,71 @@ The GitHub App requires a private key for authentication. You have two options:
 - Use secure secret management in production
 - Restrict file permissions: `chmod 600 private-key.pem`
 
+### Configuration File (config.yml)
+
+The app uses a `config.yml` file for core configuration including the AI system prompt and tool definitions. This file contains:
+
+#### Key Configuration Sections:
+- **GitHub settings**: API endpoints, bot username, check run names
+- **Queue configuration**: Worker limits and retry settings
+- **Diff processing**: Chunk size limits for large diffs
+- **Amp integration**: Command settings and MCP server configuration
+- **System prompt**: The complete AI prompt template for code reviews
+- **Tool definitions**: Available MCP tools and their usage instructions
+
+#### Important Notes:
+- The system prompt in `config.yml` defines how the AI reviews code
+- Tool definitions specify which GitHub operations are available to the AI
+- Environment variables are interpolated using `${VARIABLE_NAME}` syntax
+- Modify the prompt template to customize review behavior and focus areas
+- The configuration supports both development and production deployment modes
+
+**Example customization:**
+To adjust review focus, modify the `prompt_template` section in `config.yml` to emphasize specific areas like security, performance, or coding standards.
+
 ## API Endpoints
 
+### Core Endpoints
 - `GET /` - Service information
 - `GET /health` - Health check
+- `GET /queue/status` - Queue status information
+- `GET /jobs/:jobId` - Job status information
+- `POST /test/review` - Test endpoint for review functionality
+
+### GitHub App Endpoints
 - `POST /github/webhook` - GitHub webhook endpoint
 - `GET /github/install` - Start GitHub App installation
 - `GET /github/callback` - GitHub App installation callback
 - `GET /github/dashboard/:installationId` - Installation dashboard
-- `GET /queue/status` - Queue status information
+
+### MCP Server Endpoints
+- `GET /mcp/tools/list` - List available MCP tools
+- `POST /mcp/tools/call` - Call an MCP tool
+- `GET /mcp/health` - MCP server health check
 
 ## Development
 
+### Local Development with ngrok
+
+For development, you'll need to expose your local server to the internet for GitHub webhooks to work:
+
+1. **Install ngrok**: `npm install -g ngrok` or download from [ngrok.com](https://ngrok.com)
+
+2. **Start your local server**:
+   ```bash
+   npm run dev
+   ```
+
+3. **Expose with ngrok** (in a separate terminal):
+   ```bash
+   ngrok http 5053
+   ```
+
+4. **Update your environment**:
+   - Copy the ngrok URL (e.g., `https://abc123.ngrok.io`)
+   - Update `CRA_PUBLIC_URL` and `APP_BASE_URL` in your `.env` file
+   - Update your GitHub App webhook URL to `{your-ngrok-url}/github/webhook`
+
 ### Build
 ```bash
 npm run build
@@ -137,13 +212,41 @@ npm run type-check
 npm run lint
 ```
 
+### MCP Server
+Run the standalone MCP server:
+```bash
+npm run mcp
+```
+
+Or build and run:
+```bash
+npm run mcp:build
+```
+
+## MCP Integration
+
+The app includes a Model Context Protocol (MCP) server that exposes GitHub operations as tools for AI agents and code editors like Cursor.
+
+### Available MCP Tools
+- `leave_general_comment` - Leave general comments on pull requests
+- `leave_inline_comment` - Leave inline comments on specific lines
+- `create_check_run` - Create or update check run status
+- `get_pr_info` - Get pull request details and optionally the diff
+- `trigger_review` - Start the code review process
+- `get_pr_comments` - Get all comments on a pull request
+
+### Usage with AI Agents
+The MCP server can be accessed via HTTP at `/mcp` endpoints or run as a standalone stdio server. See [`src/mcp/README.md`](src/mcp/README.md) for detailed configuration and usage instructions.
+
 ## Architecture
 
 - **Hono.js**: Fast web framework for the server
 - **GitHub API**: Integration with GitHub's REST API
 - **GitHub Apps**: Secure app installation and JWT authentication
 - **Job Queue**: Background processing for code reviews
 - **Amp**: AI-powered code analysis engine
+- **MCP Server**: Model Context Protocol server for AI agent integration
+- **Installation Management**: Persistent storage for GitHub App installations
 
 ## License
 

config.yml

@@ -69,6 +69,12 @@ amp:
     __TOOL_CONTENT__
 
     After you have completed the code review process:
+
+    Leave a general comment summarizing the review, including:
+    * A brief summary of the changes reviewed
+    * List out critical issues and blockers that need to be addressed
+    * Any high-level feedback or suggestions
+
     IMPORTANT: If you find any issues, include all of them in a JSON block at the end with the following format:
     ```json
     [

src/mcp/README.md

@@ -104,10 +104,15 @@ npm run mcp:build
 
 The server uses the same configuration as the main application. Make sure your `config.yml` and environment variables are properly set:
 
+### Environment Variables
+- `GITHUB_APP_ID` - GitHub App ID
+- `GITHUB_APP_PRIVATE_KEY` or `GITHUB_APP_PRIVATE_KEY_PATH` - GitHub App private key
 - `GITHUB_BASE_URL` - GitHub API URL (default: https://api.github.com)
-- `GITHUB_TOKEN` - GitHub access token
 - `MCP_AUTH_TOKEN` - Token for MCP server authentication (optional)
 
+### GitHub App Integration
+The MCP server works with GitHub App installations for authentication. When accessing repositories, it uses the GitHub App's installation tokens rather than personal access tokens.
+
 ## Integration with AI Agents
 
 ### Cursor Configuration
@@ -131,6 +136,25 @@ Add to your Cursor settings:
 }
 ```
 
+### Amp Integration
+
+The MCP server is automatically configured for use with Amp in `config.yml`:
+
+```yaml
+amp:
+  settings:
+    amp.mcpServers:
+      github:
+        command: "sh"
+        args: ["-c", "cd ${GITHUB_APP_CWD} && pnpm run mcp"]
+        env:
+          GITHUB_APP_CWD: "${GITHUB_APP_CWD}"
+          GITHUB_APP_ID: "${GITHUB_APP_ID}"
+          GITHUB_APP_PRIVATE_KEY_PATH: "${GITHUB_APP_PRIVATE_KEY_PATH}"
+```
+
+This allows Amp to automatically use the GitHub MCP tools during code reviews.
+
 ### Example Usage in Prompts
 
 ```
@@ -146,6 +170,18 @@ Repo: Hello-World
 PR Number: 123
 ```
 
+### Code Review Workflow
+
+The tools are designed to work together in a typical code review workflow:
+
+1. **Get Context**: `get_pr_info` to fetch PR details and optionally the diff
+2. **Check Existing Feedback**: `get_pr_comments` to see what's already been discussed
+3. **Leave Feedback**: 
+   - `leave_inline_comment` for specific line-level issues
+   - `leave_general_comment` for overall observations
+4. **Update Status**: `create_check_run` to mark the review as complete
+5. **Re-trigger if Needed**: `trigger_review` to restart the process
+
 ## Development
 
 The tools are organized in the `/src/mcp/tools/` directory: