# MCP PR Workflow Server

**MCP server that connects AI assistants to GitHub PRs, CI, and Slack — with guardrails.**
Built in TypeScript for teams that want automated PR triage and deployment notifications without giving an LLM unbounded access to repos or chat.

---
<img width="1152" height="720" alt="mcp-pr-workflow-server" src="https://github.com/user-attachments/assets/da360d3e-33f3-49c4-8ce8-e93c27d2e323" />
<img width="1152" height="720" alt="mcp-pr-workflow-server (1)" src="https://github.com/user-attachments/assets/7db4c5da-b5d9-45d5-a632-fef6e0a360a1" />





## At a glance


|                 |                                                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Problem**     | PR review, CI follow-up, and Slack alerts are repetitive; AI can help, but only if integrations are scoped and safe.                     |
| **Solution**    | An MCP server that exposes PR/CI/Slack actions as typed tools, with validation, allowlists, and secret redaction on every outbound path. |
| **Stack**       | TypeScript · MCP SDK · Octokit · Slack Web API · Zod                                                                                     |
| **Quality**     | 84 unit tests across 11 files · Vitest · typed tool dispatch                                                                             |
| **Run locally** | `npm install && npm test && npm run build && npm start`                                                                                  |


---



## What this demonstrates

- **Integration design** — Third-party APIs (GitHub, Slack) wrapped as a small, testable tool surface for LLM clients.
- **Security-by-default** — Repo allowlists, channel allowlists, input validation, prompt-injection checks, and secret redaction before anything leaves the process.
- **Reliable server behavior** — Unknown tools and validation failures return MCP errors (`isError: true`) instead of crashing the server.
- **Separation of concerns** — Tool registration, request dispatch, security, and resources live in focused modules with dedicated tests.
- **MCP fluency** — Tools, resources, and prompts implemented against the Model Context Protocol spec.

---



## Architecture

```mermaid
flowchart LR
  Client[AI Client / Claude Desktop] -->|stdio MCP| Server[MCP Server]
  Server --> Dispatch[runtime.dispatchToolCall]
  Dispatch --> PR[PR Tools]
  Dispatch --> CI[CI Tools]
  Dispatch --> Slack[Slack Tools]
  Dispatch --> Issues[Issue Tools]
  PR --> GitHub[GitHub API]
  CI --> GitHub
  Issues --> GitHub
  Slack --> SlackAPI[Slack Web API]
  Dispatch --> Security[validation · allowlist · sanitize]
  Security --> Dispatch
```



**Request flow:** Client calls a tool → input is validated → repo/channel allowlists are enforced → external API runs → response is sanitized → result returned (or structured error).

---



## Security model

Designed for least privilege when an LLM can trigger side effects:


| Control                      | Behavior                                                                                                        |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Repository allowlist**     | GitHub tools only run against repos in `ALLOWED_REPOS`.                                                         |
| **Slack channel allowlist**  | Posts are limited to `SLACK_CHANNEL_ID`; mismatched `channel_id` args are rejected.                             |
| **Input validation**         | Owner, repo, PR numbers, titles, and message lengths validated before use.                                      |
| **Prompt injection defense** | User-supplied PR text, issue bodies, Slack messages, and prompt args scanned for instruction-override patterns. |
| **Secret redaction**         | Tokens and sensitive patterns stripped from PR comments, Slack messages, and tool responses.                    |
| **No credential leakage**    | Env vars and channel IDs are never returned via tools or resources.                                             |


Startup fails fast if required configuration is missing or invalid.

---



## Tools & resources


| Tool                       | Purpose                                        |
| -------------------------- | ---------------------------------------------- |
| `analyze_file_changes`     | Classify PR diff (features, fixes, docs, etc.) |
| `suggest_template`         | Recommend a PR template from analysis          |
| `analyze_ci_results`       | Summarize GitHub Actions run status            |
| `update_pr_status`         | Post a sanitized comment on a PR               |
| `send_slack_notification`  | Send a validated Slack message                 |
| `notify_deployment_status` | Deployment success/failure alert               |
| `create_follow_up_issue`   | Open a GitHub issue from PR context            |



| Resource                   | Purpose                      |
| -------------------------- | ---------------------------- |
| `team://config/guidelines` | Team PR guidelines           |
| `team://config/escalation` | CI failure escalation policy |


---



## Quick start

```bash
git clone <repo-url>
cd MCP-PR-Workflow-Server
npm install
cp .env.example .env   # fill in tokens and allowlists
npm test                 # 84 tests
npm run build
npm start
```



### Environment
Retrieve GITHUB_TOKEN from https://github.com/settings/personal-access-tokens.
Repository permissions:
 Read access to actions, code, and metadata
 Read and Write access to deployments, issues, and pull requests
```bash
GITHUB_TOKEN=github...
SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_ID=C12345678
ALLOWED_REPOS=your-org/your-repo,another-org/another-repo
```



### Claude Desktop
1. Open Claude Desktop and click your profile name or the menu to open Settings.
2. Go to the Developer tab and click Edit Config. This opens the claude_desktop_config.json file.
3. Add your MCP server details inside the mcpServers JSON object. 

```json
{
  "mcpServers": {
    "pr-workflow": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-PR-Workflow-Server/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_CHANNEL_ID": "C12345678",
        "ALLOWED_REPOS": "your-org/your-repo"
      }
    }
  }
}
```

---



## Project layout

```
src/
├── index.ts              # MCP server + handler registration
├── runtime.ts            # Startup checks + tool dispatch
├── tools/                # GitHub, CI, Slack, issue tools
├── resources/            # Team config resources
├── prompts/              # Workflow prompts
└── security/             # Validation, allowlists, sanitization
```