{"id":48198012,"url":"https://github.com/davidarce/mcp-pr-agent","last_synced_at":"2026-04-04T18:17:26.879Z","repository":{"id":304807495,"uuid":"1020049754","full_name":"davidarce/mcp-pr-agent","owner":"davidarce","description":"MCP server that helps developers create better pull requests by analyzing code changes and suggesting appropriate templates.","archived":false,"fork":false,"pushed_at":"2025-07-15T16:05:28.000Z","size":80,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-15T21:04:24.856Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidarce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-15T09:07:13.000Z","updated_at":"2025-07-15T16:05:32.000Z","dependencies_parsed_at":"2025-07-15T22:26:36.160Z","dependency_job_id":"df322cdb-0f15-41e4-a8fb-c7fb41c16f4e","html_url":"https://github.com/davidarce/mcp-pr-agent","commit_stats":null,"previous_names":["davidarce/mcp-pr-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/davidarce/mcp-pr-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidarce%2Fmcp-pr-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidarce%2Fmcp-pr-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidarce%2Fmcp-pr-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidarce%2Fmcp-pr-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidarce","download_url":"https://codeload.github.com/davidarce/mcp-pr-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidarce%2Fmcp-pr-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31407955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-04T18:17:25.822Z","updated_at":"2026-04-04T18:17:26.868Z","avatar_url":"https://github.com/davidarce.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP PR Agent\n\nA comprehensive Model Context Protocol (MCP) server that helps developers create better pull requests by analyzing git repository changes, managing PR templates, providing intelligent template suggestions, and monitoring GitHub Actions workflows.\n\n## Features\n\n### 🔍 Git Analysis\n- **Change Detection**: Automatically detects modified, added, and deleted files\n- **Diff Generation**: Provides complete git diffs with intelligent truncation\n- **Commit History**: Shows relevant commit messages and statistics\n- **Branch Comparison**: Compares changes against any base branch (default: main)\n\n### 📝 Template Management\n- **Multiple Templates**: Supports 7 different PR template types\n- **Template Categories**: Bug fixes, features, documentation, refactoring, testing, performance, and security\n- **Content Management**: Stores and retrieves complete template content\n- **Customizable**: Easy to add or modify templates\n\n### 🤖 Intelligent Suggestions\n- **Smart Mapping**: Automatically suggests appropriate templates based on change analysis\n- **Context Awareness**: Considers file types, change patterns, and keywords\n- **Flexible Matching**: Supports multiple aliases for change types\n\n### 🚀 GitHub Actions Integration\n- **Webhook Server**: Receives and stores GitHub Actions events\n- **Workflow Monitoring**: Tracks workflow status and results\n- **CI/CD Analysis**: Provides insights into deployment and test results\n- **Event History**: Maintains history of GitHub Actions events\n\n## Installation\n\n### Prerequisites\n- Python 3.13+\n- [uv](https://docs.astral.sh/uv/) (Python package manager)\n- Git repository\n- MCP-compatible client (like Claude Code)\n- (Optional) GitHub repository for Actions integration\n\n### Setup\n1. Clone the repository:\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd mcp-pr-agent\n   ```\n\n2. Install dependencies using uv:\n   ```bash\n   uv sync\n   ```\n\n3. Run the MCP server:\n   ```bash\n   uv run server.py\n   ```\n\n4. (Optional) Run the GitHub webhook server for GitHub Actions integration:\n   ```bash\n   uv run webhook_server.py\n   ```\n   The webhook server runs on port 8000 by default and receives GitHub Actions events.\n\n## MCP Tools\n\n### 1. `analyze_file_changes`\nAnalyzes git repository changes and provides comprehensive diff information.\n\n**Parameters:**\n- `base_branch` (str, optional): Base branch to compare against (default: \"main\")\n- `include_diff` (bool, optional): Include full diff content (default: true)\n- `max_diff_lines` (int, optional): Maximum diff lines to include (default: 500)\n- `working_directory` (str, optional): Directory to run git commands in (default: auto-detected)\n\n**Returns:** JSON object containing:\n- `files_changed`: List of modified files with status\n- `statistics`: Diff statistics summary\n- `commits`: Recent commit messages\n- `diff`: Complete diff content (if requested)\n- `truncated`: Whether diff was truncated\n- `total_diff_lines`: Total number of diff lines\n\n**Example Usage:**\n```python\n# Basic usage\nresult = await analyze_file_changes()\n\n# Compare against develop branch\nresult = await analyze_file_changes(base_branch=\"develop\")\n\n# Get summary without full diff\nresult = await analyze_file_changes(include_diff=False)\n\n# Limit diff size\nresult = await analyze_file_changes(max_diff_lines=100)\n```\n\n### 2. `get_pr_templates`\nRetrieves all available PR templates with their content.\n\n**Parameters:** None\n\n**Returns:** JSON array of template objects containing:\n- `filename`: Template file name\n- `type`: Template category/type\n- `content`: Complete template content\n\n**Available Templates:**\n- **bug.md**: Bug Fix template\n- **feature.md**: New Feature template\n- **docs.md**: Documentation Update template\n- **refactor.md**: Code Refactoring template\n- **test.md**: Test Update template\n- **performance.md**: Performance Improvement template\n- **security.md**: Security Update template\n\n### 3. `suggest_template`\nAnalyzes change descriptions and suggests the most appropriate PR template.\n\n**Parameters:**\n- `changes_summary` (str): Description of what the changes do\n- `change_type` (str): Type of change (bug, feature, docs, refactor, test, etc.)\n\n**Returns:** JSON object containing:\n- `recommended_template`: Complete template object\n- `reasoning`: Explanation for the suggestion\n- `template_content`: Ready-to-use template content\n- `usage_hint`: Instructions for using the template\n\n**Supported Change Types:**\n- **Bug/Fix**: Maps to bug.md template\n- **Feature/Enhancement**: Maps to feature.md template\n- **Docs/Documentation**: Maps to docs.md template\n- **Refactor/Cleanup**: Maps to refactor.md template\n- **Test/Testing**: Maps to test.md template\n- **Performance/Optimization**: Maps to performance.md template\n- **Security**: Maps to security.md template\n\n### 4. `get_recent_actions_events`\nRetrieves recent GitHub Actions events received via webhook.\n\n**Parameters:**\n- `limit` (int, optional): Maximum number of events to return (default: 10)\n\n**Returns:** JSON array of GitHub Actions events with:\n- Event type and timestamp\n- Workflow run information\n- Repository details\n- Action outcomes\n\n### 5. `get_workflow_status`\nGets the current status of GitHub Actions workflows.\n\n**Parameters:**\n- `workflow_name` (str, optional): Specific workflow name to filter by\n\n**Returns:** JSON array of workflow status objects containing:\n- `name`: Workflow name\n- `status`: Current status (queued, in_progress, completed)\n- `conclusion`: Final result (success, failure, cancelled, etc.)\n- `run_number`: Workflow run number\n- `updated_at`: Last update timestamp\n- `html_url`: Link to workflow run\n\n## Template Structure\n\nEach template follows a consistent structure:\n\n```markdown\n## [Template Type]\n\n### Description\n\u003c!-- Brief description of the change --\u003e\n\n### [Template-specific sections]\n\u003c!-- Varies by template type --\u003e\n\n### Testing\n- [ ] Relevant tests added/updated\n- [ ] Manual testing completed\n\n### [Additional sections as needed]\n```\n\n### Customizing Templates\n\nTemplates are stored in the `templates/` directory. To add or modify templates:\n\n1. Create/edit `.md` files in the `templates/` directory\n2. Update `DEFAULT_TEMPLATES` in `server.py` if adding new templates\n3. Update `TYPE_MAPPING` for new change type aliases\n\n## Integration Examples\n\n### With Claude Code\n```python\n# Analyze current repository changes\nresult = mcp.call_tool(\"analyze_file_changes\", {\n    \"base_branch\": \"main\",\n    \"include_diff\": True\n})\n\n# Get all available templates\ntemplates = mcp.call_tool(\"get_pr_templates\", {})\n\n# Get template suggestion\nsuggestion = mcp.call_tool(\"suggest_template\", {\n    \"changes_summary\": \"Added user authentication system\",\n    \"change_type\": \"feature\"\n})\n```\n\n### Workflow Example\n1. **Analyze Changes**: Use `analyze_file_changes` to understand what was modified\n2. **Get Suggestions**: Use `suggest_template` to get appropriate template recommendations\n3. **Create PR**: Use the suggested template content to create a comprehensive PR description\n\n## GitHub Actions Integration\n\n### Webhook Setup\nTo enable GitHub Actions monitoring, you need to set up a webhook in your GitHub repository:\n\n1. **Start the webhook server**:\n   ```bash\n   uv run webhook_server.py\n   ```\n\n2. **Configure GitHub webhook**:\n   - Go to your repository Settings → Webhooks\n   - Add webhook with URL: `http://your-server:8000/webhook`\n   - Select \"Workflow runs\" events\n   - Set content type to \"application/json\"\n\n3. **Access GitHub Actions data**:\n   ```python\n   # Get recent events\n   events = mcp.call_tool(\"get_recent_actions_events\", {\"limit\": 5})\n   \n   # Check workflow status\n   status = mcp.call_tool(\"get_workflow_status\", {\"workflow_name\": \"CI\"})\n   ```\n\n### MCP Prompts\nThe server includes several pre-built prompts for GitHub Actions analysis:\n\n- `analyze_ci_results`: Comprehensive CI/CD results analysis\n- `create_deployment_summary`: Generate deployment status summaries\n- `generate_pr_status_report`: Complete PR status including CI/CD\n- `troubleshoot_workflow_failure`: Help debug failing workflows\n\n## Configuration\n\n### Environment Variables\n- `MCP_PR_AGENT_TEMPLATES_DIR`: Custom templates directory path\n- `MCP_PR_AGENT_DEFAULT_BRANCH`: Default base branch (default: \"main\")\n- `WEBHOOK_PORT`: Port for webhook server (default: 8000)\n\n### MCP Configuration (.mcp.json)\nThe project includes a `.mcp.json` configuration file for easy MCP client setup:\n\n```json\n{\n  \"mcpServers\": {\n    \"pr-agent-actions\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"server.py\"],\n      \"cwd\": \"/Users/David/Dev/mcp/mcp-pr-agent\"\n    }\n  }\n}\n```\n\n### Claude Code Integration\nAdd this MCP server to Claude Code using the following command:\n\n```bash\nclaude mcp add pr-agent -- uv --directory \u003cmcp-pr-agent-directory\u003e run server.py\n```\n\nReplace `\u003cmcp-pr-agent-directory\u003e` with the full path to your mcp-pr-agent directory.\n\n**Example:**\n```bash\nclaude mcp add pr-agent -- uv --directory /Users/username/projects/mcp-pr-agent run server.py\n```\n\n### Manual MCP Client Configuration\nFor other MCP clients, add to your configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"pr-agent\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/mcp-pr-agent\", \"run\", \"server.py\"]\n    }\n  }\n}\n```\n\n## Development\n\n### Running Tests\n```bash\nuv run pytest test_server.py -v\n```\n\n### Adding New Templates\n1. Create template file in `templates/` directory\n2. Add to `DEFAULT_TEMPLATES` dictionary\n3. Add type mappings to `TYPE_MAPPING`\n4. Update documentation\n\n### Error Handling\nThe server includes comprehensive error handling:\n- Git command failures\n- Missing repositories\n- Template file errors\n- Invalid parameters\n\n## Troubleshooting\n\n### Common Issues\n\n**\"Git error\" responses:**\n- Ensure you're in a git repository\n- Check that the base branch exists\n- Verify git is accessible in PATH\n\n**Empty results:**\n- Check if you're on the correct branch\n- Ensure there are changes to analyze\n- Verify the base branch comparison\n\n**Template not found:**\n- Ensure templates directory exists\n- Check template file permissions\n- Verify template files are properly formatted\n\n### Debug Information\nThe `analyze_file_changes` tool includes debug information in the `_debug` field:\n- Working directory paths\n- MCP roots detection\n- Server process information\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request using the appropriate template!\n\n## License\n\n[Add your license information here]\n\n## Support\n\n[Add support contact information here]","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidarce%2Fmcp-pr-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidarce%2Fmcp-pr-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidarce%2Fmcp-pr-agent/lists"}