{"id":"1e9a9816-e6b3-4710-bbb5-8f75692798b6","slug":"sample-mcp-git","kind":"mcp","name":"sample-mcp-git","summary":"","owner":"aws-samples","repoUrl":"https://github.com/aws-samples/sample-mcp-git","license":"MIT-0","licenseTier":"permissive","trust":"official","stars":2,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-08-10T05:27:07.000Z","addedAt":"2026-10-21T17:54:06.695Z","logoUrl":"https://avatars.githubusercontent.com/u/8931462?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T12:00:14.582Z","sample":false,"url":"https://conduits.dev/tools/sample-mcp-git","language":"Python","transports":["stdio"],"install":{"pypi":"git-pr-mcp-server"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Git PR MCP Server\n\nAn MCP (Model Context Protocol) server that gives AI coding agents real-time, read-only access to pull request data on a GitLab instance. Works with Claude Desktop, Cursor, GitHub Copilot, Kiro, and any MCP-compatible client.\n\nThis is a sample project intended for experimentation and as a reference implementation. See [SECURITY.md](SECURITY.md) for the security model and hardening guidance before using it beyond local experimentation.\n\n## What It Does\n\nAsk your AI agent questions about your team's PRs — no browser tab-switching:\n\n```\n\"Is anyone working on retry logic?\"              → search_pull_requests\n\"Show me the code changes in PR #42\"             → get_pr_diff\n\"Did CI pass?\"                                   → get_pipeline_status\n\"Who still needs to approve?\"                    → get_pr_approvals\n\"Any unresolved review threads?\"                 → get_pr_comments\n\"What's different between my branch and main?\"   → compare_branches\n\"Generate release notes since last Monday\"       → generate_release_notes\n```\n\n## Tools (10 total)\n\n| Tool | Description |\n|---|---|\n| `list_pull_requests` | List all open PRs in a repository |\n| `get_pull_request_details` | Get full metadata for a specific PR |\n| `filter_pull_requests` | Filter by author, status, labels, date range |\n| `get_pr_diff` | Get code diff — files changed, additions/deletions, unified diff content |\n| `get_pr_approvals` | Approval status — who approved, how many needed, merge-readiness |\n| `get_pr_comments` | Review discussions — unresolved threads, inline comments |\n| `get_pipeline_status` | CI/CD pipeline status — passed/failed/running, duration |\n| `search_pull_requests` | Full-text keyword search across PR titles and descriptions |\n| `compare_branches` | Compare two branches — commits ahead, files changed, commit messages |\n| `generate_release_notes` | Auto-generate categorized release notes from merged PRs in a date range |\n\n## Quick Start\n\n```bash\n# Clone and install\ngit clone <repo-url> git-pr-mcp-server\ncd git-pr-mcp-server\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\n\n# Configure\nexport GITLAB_URL=\"https://gitlab.example.com\"\nexport GITLAB_TOKEN=\"<your-gitlab-pat-with-read_api-scope>\"\n\n# Run\npython -m git_pr_mcp_server\n```\n\n## Configuration\n\nAll configuration is read from environment variables:\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `GITLAB_TOKEN` | yes | — | Personal access token, scoped to `read_api` only |\n| `GITLAB_URL` | no | `https://gitlab.example.com` | Base URL of your GitLab instance |\n| `SSO_SESSION_URL` | no | `https://your-sso-provider.example.com/api/session-status` | Endpoint that returns HTTP 200 while the SSO session is valid |\n| `SSO_COOKIE_PATH` | no | `~/.sso/cookie` | Netscape-format cookie file written by your SSO provider's CLI |\n| `GIT_PR_MCP_TRANSPORT` | no | `stdio` | `stdio` or `sse` |\n| `GIT_PR_MCP_LOG_LEVEL` | no | `info` | `debug`, `info`, `warn`, or `error` |\n\n### Authentication model\n\nThe server authenticates in two layers, which suits GitLab instances fronted by\na cookie-based SSO or reverse proxy:\n\n1. **Session cookies** — loaded from `SSO_COOKIE_PATH` and validated against\n   `SSO_SESSION_URL`. This satisfies the proxy in front of GitLab.\n2. **Personal access token** — read from `GITLAB_TOKEN`. This authenticates to\n   the GitLab API itself.\n\nIf your GitLab instance has no SSO proxy in front of it, point `SSO_SESSION_URL`\nat any endpoint on your instance that returns HTTP 200 for an authenticated\nsession, or adapt `SsoAuthManager` in `src/git_pr_mcp_server/auth_manager.py` to\nuse a token alone.\n\n## Connecting to Your AI Agent\n\nAdd this to your MCP client config (Claude Desktop, Cursor, Kiro, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"git-pr\": {\n      \"command\": \"/path/to/.venv/bin/python3\",\n      \"args\": [\"-m\", \"git_pr_mcp_server\"],\n      \"env\": {\n        \"GITLAB_URL\": \"https://gitlab.example.com\",\n        \"GITLAB_TOKEN\": \"<your-token>\"\n      }\n    }\n  }\n}\n```\n\n## Architecture\n\n```\nAI Agent (Claude / Copilot / Cursor / Kiro)\n  │  MCP JSON-RPC (stdio or SSE)\n  ▼\nFastMCP Server (10 tools)\n  │\n  ▼\nPR Service (pagination, filtering, diff processing, release notes)\n  │\n  ▼\nGit Provider Client (python-gitlab, 8 API methods)\n  │\n  ▼\nGitLab v4 API (read-only)\n```\n\nAll operations are read-only. Credentials are never exposed to the agent.\n\n## Security\n\n- Input validation (Pydantic + regex) on all 10 tools\n- Credential isolation (env vars + cookie file only)\n- Log redaction (key + value pattern matching)\n- Error sanitization (agent sees a generic message, logs have detail)\n- TLS enforced, HTTPS-only, 10s timeout\n- Read-only enforcement (no write tools, token needs `read_api` scope only)\n- Diff truncation (5KB per file to prevent memory exhaustion)\n\nSee [SECURITY.md](SECURITY.md) for the full security model, trust boundaries, and hardening guidance.\n\n## Running Tests\n\n```bash\nsource .venv/bin/activate\npytest -v\n```\n\n## Project Structure\n\n```\nsrc/git_pr_mcp_server/\n├── __main__.py              # Entry point\n├── server.py                # FastMCP server + 10 tool handlers\n├── pr_service.py            # Business logic\n├── git_provider_client.py   # python-gitlab wrapper (8 API methods)\n├── response_mapper.py       # GitLab MR → PR normalization\n├── auth_manager.py          # SSO session + PAT authentication\n├── rate_limiter.py          # Quota tracking + backoff\n├── logger.py                # Structured JSON + credential redaction\n├── models.py                # Pydantic data models\n└── schemas.py               # Input validation schemas\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). This project follows the\n[Amazon Open Source Code of Conduct](CODE_OF_CONDUCT.md).\n\n## License\n\nLicensed under the MIT-0 License. See [LICENSE](LICENSE).\n"}