mcp-github-crunchtools 1.2.0__tar.gz → 1.3.1__tar.gz

{mcp_github_crunchtools-1.2.0 → mcp_github_crunchtools-1.3.1}/.specify/memory/constitution.md

@@ -1,8 +1,8 @@
 # mcp-github-crunchtools Constitution
 
-> **Version:** 1.2.0
+> **Version:** 1.3.0
 > **Ratified:** 2026-06-14
-> **Amended:** 2026-10-12
+> **Amended:** 2026-10-14
 > **Status:** Active
 > **Inherits:** [crunchtools/constitution](https://github.com/crunchtools/constitution) v1.24.0
 > **Profile:** MCP Server
@@ -15,9 +15,17 @@ restated here.
 
 ## Security Model Specifics
 
-- **Credentials:** `GITHUB_TOKEN` (required), held as `SecretStr`, read from
-  the environment only. `GitHubApiError` scrubs it from messages, and
-  `Config.__repr__()`/`__str__()` never expose it.
+- **Credentials:** `GITHUB_TOKEN`, held as `SecretStr`, read from the
+  environment only; required unless `GITHUB_ACCEPT_REQUEST_TOKEN` is on, in
+  which case an HTTP request's `Authorization: Bearer <token>` is used for
+  that request (strict format, malformed refused, never stored on the shared
+  client). `GitHubApiError` scrubs both tokens from messages, and
+  `Config.__repr__()`/`__str__()` never expose the token.
+- **Merge gate:** `merge_pull_request` merges only when every required
+  status check of the base branch (rulesets and classic protection) passes
+  on the head commit, pinned to that head; it fails closed when checks
+  cannot be read, and when none are required unless the caller passes
+  `allow_no_required_checks=True`.
 - **Input limits:** Pydantic models with `extra="forbid"`; issue and PR
   states are allowlisted (`open`, `closed`, `all`), as are merge methods
   (`merge`, `squash`, `rebase`); owner and repo names are
@@ -73,3 +81,4 @@ responses in `TestClientErrorHandling`.
 | 1.0.1 | 2026-09-25 | Inherit constitution v1.17.0 (Gatehouse gates) |
 | 1.1.0 | 2026-10-02 | Manifest under constitution v1.18.0: profile restatement removed, mcp-github specifics kept; `..` rule moved from file paths to git refs to match the code |
 | 1.2.0 | 2026-10-12 | Seven tools for pull requests, Actions runs and logs, and releases (spec 001): redirect handling, result caps, merge-method and SHA validation, releases tool group |
+| 1.3.0 | 2026-10-14 | Per-request token (`GITHUB_ACCEPT_REQUEST_TOKEN`) and the merge gate (spec 002) |

mcp_github_crunchtools-1.3.1/.specify/specs/002-request-token-merge-gate/spec.md

@@ -0,0 +1,132 @@
+# Specification: Per-Request Token and Merge Gate
+
+> **Spec ID:** 002-request-token-merge-gate
+> **Status:** Implemented
+> **Version:** 1.3.0
+> **Author:** crunchtools.com
+> **Date:** 2026-10-14
+
+## Overview
+
+Two changes, both about whose authority a call carries.
+
+1. **Per-request token.** GitHub's hosted MCP server takes the caller's
+   personal access token as `Authorization: Bearer <token>` on every HTTP
+   request and acts with it. Behind an opt-in, this server does the same, so
+   it can stand in for GitHub's server without the client changing.
+2. **Merge gate.** The token an agent merges with may belong to an
+   organization owner, and owners can bypass ruleset-required checks: GitHub
+   would merge a pull request whose checks failed. `merge_pull_request_tool`
+   now enforces the required checks itself.
+
+No tools are added; the count stays at 25.
+
+---
+
+## Per-Request Token
+
+| Setting | Incoming `Authorization` | Token used |
+|---------|-------------------------|------------|
+| `GITHUB_ACCEPT_REQUEST_TOKEN` off (default) | ignored | `GITHUB_TOKEN` (required) |
+| on, HTTP request with `Bearer <token>` | used | the request's token |
+| on, HTTP request without the header, or stdio | — | `GITHUB_TOKEN` |
+| on, no header and no `GITHUB_TOKEN` | — | none: error before any API call |
+| on, header present but malformed | refused | none: error, not forwarded |
+
+- The header is read with `fastmcp.server.dependencies.get_http_headers(include={"authorization"})`,
+  which returns `{}` outside an HTTP request.
+- Accepted form: `(?i:bearer) ` followed by 1 to 1024 characters in
+  `\x21`–`\x7e`, matched in full.
+- The token is chosen in `GitHubClient._send` for each call and passed as
+  that call's header. The shared `httpx.AsyncClient` has an `Authorization`
+  default only when `GITHUB_TOKEN` is set.
+- `errors.request_token` (a `ContextVar`) holds the request's token so that
+  `GitHubApiError` scrubs it; each MCP request runs in its own task context.
+- The job-log second hop (`get_redirected_tail`) still sends no token.
+
+## Merge Gate
+
+Before `PUT /repos/{owner}/{repo}/pulls/{n}/merge`:
+
+| Step | Request | Refuses when |
+|------|---------|--------------|
+| 1 | `GET .../pulls/{n}` | caller `sha` is not the head; head or base missing |
+| 2a | `GET .../rules/branches/{base}` (paged) | — |
+| 2b | `GET .../branches/{base}` (`protection.required_status_checks`) | any error, or `protected` with no `protection` shown |
+| 3 | — | no required checks, unless `allow_no_required_checks=True` |
+| 4 | `GET .../commits/{head}/check-runs` and `.../status` (paged) | a required check is missing, pending or failed |
+| 5 | `GET .../pulls/{n}` again | head or base changed since step 1 |
+| 6 | `PUT .../merge` with `sha` = head | (GitHub: 405, 409) |
+
+- A required check is `(context, app id or None)`. Rulesets give
+  `integration_id`; classic protection gives `checks[].app_id`, where -1
+  means any, or bare `contexts`.
+- The most recent check run of the context's name (highest id) decides; it
+  passes when completed with `success`, `skipped` or `neutral`. With an app
+  id, only that app's runs count. With no app id and no run, the commit
+  status of that context must be `success`.
+- Each list is read up to 10 pages of 100; more refuses the merge.
+- Refusals raise `MergeRefusedError` naming every offending check.
+
+---
+
+## Security Considerations
+
+- Token mix-up between concurrent callers: nothing request-specific is
+  stored on the shared client or in a global.
+- A malformed header never falls back to `GITHUB_TOKEN`: a caller that
+  meant to use its own token does not silently act as the server.
+- The gate fails closed on unreadable protection, missing checks, oversized
+  lists and branches without required checks.
+- Required reviews and other rules are not re-enforced; the bypass still
+  applies to them.
+
+---
+
+## Module Changes
+
+| File | Changes |
+|------|---------|
+| `config.py` | `GITHUB_ACCEPT_REQUEST_TOKEN`; `token` may be None |
+| `client.py` | `_incoming_token`, `_auth_headers`; conditional default `Authorization` |
+| `errors.py` | `request_token`, `scrub_tokens`, `MergeRefusedError` |
+| `tools/pull_requests.py` | Merge gate helpers; `allow_no_required_checks` |
+| `server.py` | `allow_no_required_checks` on `merge_pull_request_tool`; docstring |
+
+---
+
+## Testing Requirements
+
+- [x] stdio uses the env token; option off ignores the header (well-formed
+      or not); option on prefers the header; header absent falls back
+- [x] Request-token-only instance: no default `Authorization` on the client
+- [x] No token at all: error and no HTTP request
+- [x] Malformed headers refused and not sent: empty, no scheme, other
+      scheme, extra spaces, tab, control, DEL, non-ASCII, over-long
+- [x] Request token scrubbed from API and transport errors
+- [x] Five concurrent requests with different tokens each send their own
+      (real httpx client over a mock transport)
+- [x] Gate: all green merges pinned to head; failing, pending, missing;
+      newest status of a repeated context decides; unreadable rules, check
+      runs, statuses or PR never merge; the MCP tool forwards the flag;
+      head or base moving during the gate is refused;
+      status pending/failure/error; most recent run decides; app-bound
+      rule; no checks refused and allowed by flag; flag does not waive
+      existing checks; `sha` mismatch; protection 403; classic `checks`
+      and `contexts`; rulesets and classic combined; branch name encoded;
+      check runs, statuses and rules paginated; page cap refuses
+
+---
+
+## Dependencies
+
+- Depends on: 001-pr-merge-logs-release
+- Blocks: none
+
+---
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.3.0 | 2026-10-14 | Implemented |

{mcp_github_crunchtools-1.2.0 → mcp_github_crunchtools-1.3.1}/CHANGELOG.md

@@ -6,6 +6,47 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [1.3.1] - 2026-10-16
+
+### Fixed
+
+- A primary rate limit reported GitHub's `x-ratelimit-reset` epoch as the
+  wait ("Retry after 1792152901 seconds"). It now reports the seconds left
+  until the reset.
+
+## [1.3.0] - 2026-10-14
+
+### Added
+
+- `GITHUB_ACCEPT_REQUEST_TOKEN` (default off): over HTTP, act with the token
+  in each request's `Authorization: Bearer <token>` header, the way GitHub's
+  hosted MCP server takes it, falling back to `GITHUB_TOKEN`. With it on,
+  `GITHUB_TOKEN` is optional. A malformed header is refused, never
+  forwarded; a call with no token at all fails before reaching GitHub.
+  stdio is unchanged.
+- `merge_pull_request_tool` takes `allow_no_required_checks` (default
+  False).
+
+### Changed
+
+- `merge_pull_request_tool` enforces the base branch's required status
+  checks itself before merging: from rulesets and classic branch
+  protection, every required check must have a passing check run (success,
+  skipped or neutral) or a successful status on the head commit, or the
+  merge is refused with each offending check named. A branch with no
+  required checks is refused unless `allow_no_required_checks=True`, and a
+  branch protection that cannot be read is refused. Classic protection is
+  read from the branch itself, so no Administration permission is needed.
+  The merge is always pinned to the checked head SHA. It now needs Pull
+  requests: read and Commit statuses: read as well as Contents: write.
+
+### Security
+
+- An organization owner's token can bypass required checks on GitHub's
+  side; the merge gate closes that for this tool.
+- The request token is scrubbed from error messages like `GITHUB_TOKEN`,
+  and is passed per call, never stored on the shared HTTP client.
+
 ## [1.2.0] - 2026-10-12
 
 ### Added

{mcp_github_crunchtools-1.2.0 → mcp_github_crunchtools-1.3.1}/CLAUDE.md

@@ -44,7 +44,8 @@ claude mcp add mcp-github-crunchtools \
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `GITHUB_TOKEN` | Yes | — | GitHub Personal Access Token |
+| `GITHUB_TOKEN` | Yes, unless `GITHUB_ACCEPT_REQUEST_TOKEN` is on | — | GitHub Personal Access Token |
+| `GITHUB_ACCEPT_REQUEST_TOKEN` | No | off | Over HTTP, use each request's `Authorization: Bearer` token (falls back to `GITHUB_TOKEN`) |
 | `GITHUB_API_URL` | No | `https://api.github.com` | API base URL (set for GHES) |
 | `GITHUB_DEFAULT_ORG` | No | — | Default owner when a tool omits `owner` |
 | `SSL_CERT_FILE` | No | — | Custom CA bundle for self-hosted instances |
@@ -68,6 +69,14 @@ fresh run (via `workflow_dispatch`) and is the way to *force* a build —
 `rerun_*` only re-run an existing run and GitHub rejects runs older than 30
 days.
 
+`merge_pull_request_tool` enforces the base branch's required checks itself
+(rulesets and classic protection, fail closed) before it merges, pinned to
+the checked head SHA: an org owner's token can bypass the rules on GitHub's
+side. Do not weaken that gate.
+
+The per-request token goes into one call's headers and the `request_token`
+context variable in `errors.py`; never onto the shared httpx client.
+
 `get_failed_job_logs_tool` is the one tool that talks to a host other than the
 API: GitHub redirects a job log to a storage URL. `GitHubClient.get_redirected_tail`
 follows it with a separate client that has no token. Keep it that way.

{mcp_github_crunchtools-1.2.0 → mcp_github_crunchtools-1.3.1}/Containerfile

@@ -27,7 +27,7 @@ FROM quay.io/hummingbird/python:latest
 
 # Labels for container metadata
 LABEL name="mcp-github-crunchtools" \
-      version="1.2.0" \
+      version="1.3.0" \
       summary="Secure MCP server for GitHub issues, pull requests, Actions, releases, files, and search" \
       description="A security-focused MCP server for GitHub built on Red Hat UBI" \
       maintainer="crunchtools.com" \

{mcp_github_crunchtools-1.2.0 → mcp_github_crunchtools-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-github-crunchtools
-Version: 1.2.0
+Version: 1.3.1
 Summary: Secure MCP server for GitHub issues, pull requests, Actions, releases, files, and search
 Author: crunchtools.com
 License-Expression: AGPL-3.0-or-later
@@ -86,7 +86,7 @@ permission the tool needs (see [Token permissions](#token-permissions)).
 | `create_pull_request_tool` | Open a pull request, optionally as a draft (*write*) | Pull requests: write |
 | `update_pull_request_tool` | Edit, close or reopen a pull request; does not merge (*write*) | Pull requests: write |
 | `reply_to_review_comment_tool` | Reply in the thread of a diff comment (*write*) | Pull requests: write |
-| `merge_pull_request_tool` | Merge, squash or rebase a pull request, optionally only at an expected head SHA (*write*) | Contents: write |
+| `merge_pull_request_tool` | Merge, squash or rebase a pull request, only once the base branch's required checks are green on its head (see [The merge gate](#the-merge-gate)) (*write*) | Contents: write; Pull requests and Commit statuses: read |
 
 ### Actions (6 tools)
 
@@ -162,12 +162,39 @@ podman run -e GITHUB_TOKEN=your_token \
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `GITHUB_TOKEN` | Yes | — | GitHub Personal Access Token |
+| `GITHUB_TOKEN` | Yes, unless `GITHUB_ACCEPT_REQUEST_TOKEN` is on | — | GitHub Personal Access Token |
+| `GITHUB_ACCEPT_REQUEST_TOKEN` | No | off | `true`, `1` or `yes`: over HTTP, act with the token in each request's `Authorization: Bearer` header (see [Per-request token](#per-request-token)) |
 | `GITHUB_API_URL` | No | `https://api.github.com` | API base URL (set for GHES) |
 | `GITHUB_DEFAULT_ORG` | No | — | Default owner when a tool omits `owner` |
 | `SSL_CERT_FILE` | No | — | Custom CA bundle path, for self-hosted GHES with an internal CA |
 | `GITHUB_SSL_VERIFY` | No | `true` | Set `false` to disable TLS verification (not recommended) |
 
+### Per-request token
+
+GitHub's own hosted MCP server takes the caller's token on every HTTP
+request as `Authorization: Bearer <token>` and acts with it. With
+`GITHUB_ACCEPT_REQUEST_TOKEN=true` this server does the same, so a client
+configured for GitHub's server can point here instead with the same header.
+
+- Over the `streamable-http` or `sse` transport, a request carrying
+  `Authorization: Bearer <token>` is sent to GitHub with that token, for
+  that request only. Concurrent requests with different tokens each use
+  their own; the token is never stored on the shared client.
+- A request without the header falls back to `GITHUB_TOKEN`. With the option
+  on, `GITHUB_TOKEN` is optional: an instance without it serves only
+  requests that bring a token, and refuses the others before calling GitHub
+  ("No GitHub token for this request").
+- The header must be exactly `Bearer <token>` (scheme in any case, one
+  space, a token of printable ASCII with no spaces). Anything else is
+  refused, never forwarded, even when `GITHUB_TOKEN` is set.
+- The request token is scrubbed from error messages like `GITHUB_TOKEN` is.
+- With the option off (the default) an incoming Authorization header is
+  ignored, exactly as before. stdio has no request headers and always uses
+  `GITHUB_TOKEN`.
+
+The option makes the server act as whoever sends a token. Expose the HTTP
+port only to callers you would hand that token to anyway, behind TLS.
+
 ### Creating a GitHub Personal Access Token
 
 1. **Navigate to token settings**
@@ -192,11 +219,11 @@ For a fine-grained personal access token, the repository permissions are:
 | Metadata | every tool (GitHub grants it with any other permission) | — |
 | Contents | `get_file_content_tool`, `list_repo_tree_tool` | `merge_pull_request_tool`, `create_release_tool` |
 | Issues | `list_issues_tool`, `get_issue_tool` | `create_issue_tool`, `update_issue_tool`, `create_issue_comment_tool` |
-| Pull requests | `list_pull_requests_tool`, `get_pull_request_tool`, `get_pull_request_diff_tool`, `get_pull_request_checks_tool`, `list_pull_request_comments_tool` | `create_pull_request_tool`, `update_pull_request_tool`, `reply_to_review_comment_tool`, `create_issue_comment_tool` on a PR |
+| Pull requests | `merge_pull_request_tool`, `list_pull_requests_tool`, `get_pull_request_tool`, `get_pull_request_diff_tool`, `get_pull_request_checks_tool`, `list_pull_request_comments_tool` | `create_pull_request_tool`, `update_pull_request_tool`, `reply_to_review_comment_tool`, `create_issue_comment_tool` on a PR |
 | Actions | `list_workflow_runs_tool`, `get_workflow_run_tool`, `get_failed_job_logs_tool` | `trigger_workflow_tool`, `rerun_workflow_run_tool`, `rerun_failed_jobs_tool` |
-| Commit statuses | `get_pull_request_checks_tool` | — |
+| Commit statuses | `get_pull_request_checks_tool`, `merge_pull_request_tool` | — |
 
-`get_pull_request_checks_tool` reads check-runs, and GitHub's permission table
+`get_pull_request_checks_tool` and `merge_pull_request_tool` read check-runs, and GitHub's permission table
 for fine-grained tokens lists no permission for that endpoint. It is readable
 on public repositories; on a private repository use a classic token or a
 GitHub App token. The search tools likewise have no permission of their own:
@@ -212,9 +239,35 @@ Three things worth knowing before granting write:
   `.github/workflows/`, relative to the default branch, additionally needs
   Workflows: write; without it GitHub answers 404. Expect the same of a merge
   that brings workflow changes in.
-- **Branch rules still apply.** `merge_pull_request_tool` cannot merge past
-  required checks or reviews; GitHub answers 405 and the tool returns its
-  message.
+- **The merge gate checks required status checks itself**, below. Other
+  branch rules (required reviews, for instance) are left to GitHub, which
+  answers 405 when it refuses; a token that may bypass the rules gets past
+  them.
+
+### The merge gate
+
+An organization owner, or anyone on a ruleset's bypass list, can merge past
+failing required checks: GitHub merges a red pull request for such a token.
+So `merge_pull_request_tool` does not leave the checks to GitHub. Before it
+merges it:
+
+1. reads the pull request's base branch and head SHA, and refuses if `sha`
+   was given and the head has moved;
+2. collects the base branch's required status checks from its active
+   rulesets and its classic branch protection, read from the branch itself
+   so no Administration permission is needed. An error reading either, or a
+   protected branch whose protection is not shown, refuses the merge rather
+   than count as none;
+3. refuses if no check is required, unless `allow_no_required_checks=True`;
+4. requires, for every required check on the head commit, a completed check
+   run of that name concluding `success`, `skipped` or `neutral` (the most
+   recent run of the name decides), or a commit status of `success`. A rule
+   that names an app accepts only that app's check runs. A missing, pending
+   or failed check refuses the merge, and the error lists each one and why;
+5. reads the pull request again and refuses if its head or base changed
+   meanwhile (GitHub's merge call pins the head but not the base), then
+   merges with the head SHA pinned, so a later push makes GitHub refuse
+   (409) rather than merge code nobody checked.
 
 With a classic token, `repo` covers all of the above (`public_repo` for public
 repositories only), plus `workflow` for the workflow-file case.
@@ -282,6 +335,7 @@ Assistant: [calls list_pull_request_comments_tool with pull_number=5]
 Assistant: [calls reply_to_review_comment_tool with comment_id=..., body="fixed in abc1234"]
 Assistant: [calls get_pull_request_checks_tool with pull_number=5]
 Assistant: [calls merge_pull_request_tool with merge_method="squash", sha=<head_sha from the checks>]
+           (the tool checks the required checks again itself before merging)
 ```
 
 ### Read a File
@@ -307,7 +361,9 @@ This server was designed with security as a primary concern. See [SECURITY.md](S
 1. **Token Protection**
    - Stored as SecretStr (never accidentally logged)
    - Environment variable only (never in files or args)
-   - Sanitized from all error messages
+   - Optionally, a per-request token from the HTTP `Authorization` header,
+     used for that request only and never stored on the shared client
+   - Both sanitized from all error messages
 
 2. **Input Validation**
    - Pydantic models for write inputs
@@ -322,6 +378,8 @@ This server was designed with security as a primary concern. See [SECURITY.md](S
    - Response size limits (10MB)
    - Job-log downloads follow GitHub's redirect without the token, over
      HTTPS only, and keep just the tail (20MB download limit)
+   - Merges only when the required checks are green on the head commit,
+     even for a token GitHub would let bypass them
 
 4. **Automated CVE Scanning**
    - GitHub Actions scan dependencies

{mcp_github_crunchtools-1.2.0 → mcp_github_crunchtools-1.3.1}/README.md

@@ -60,7 +60,7 @@ permission the tool needs (see [Token permissions](#token-permissions)).
 | `create_pull_request_tool` | Open a pull request, optionally as a draft (*write*) | Pull requests: write |
 | `update_pull_request_tool` | Edit, close or reopen a pull request; does not merge (*write*) | Pull requests: write |
 | `reply_to_review_comment_tool` | Reply in the thread of a diff comment (*write*) | Pull requests: write |
-| `merge_pull_request_tool` | Merge, squash or rebase a pull request, optionally only at an expected head SHA (*write*) | Contents: write |
+| `merge_pull_request_tool` | Merge, squash or rebase a pull request, only once the base branch's required checks are green on its head (see [The merge gate](#the-merge-gate)) (*write*) | Contents: write; Pull requests and Commit statuses: read |
 
 ### Actions (6 tools)
 
@@ -136,12 +136,39 @@ podman run -e GITHUB_TOKEN=your_token \
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `GITHUB_TOKEN` | Yes | — | GitHub Personal Access Token |
+| `GITHUB_TOKEN` | Yes, unless `GITHUB_ACCEPT_REQUEST_TOKEN` is on | — | GitHub Personal Access Token |
+| `GITHUB_ACCEPT_REQUEST_TOKEN` | No | off | `true`, `1` or `yes`: over HTTP, act with the token in each request's `Authorization: Bearer` header (see [Per-request token](#per-request-token)) |
 | `GITHUB_API_URL` | No | `https://api.github.com` | API base URL (set for GHES) |
 | `GITHUB_DEFAULT_ORG` | No | — | Default owner when a tool omits `owner` |
 | `SSL_CERT_FILE` | No | — | Custom CA bundle path, for self-hosted GHES with an internal CA |
 | `GITHUB_SSL_VERIFY` | No | `true` | Set `false` to disable TLS verification (not recommended) |
 
+### Per-request token
+
+GitHub's own hosted MCP server takes the caller's token on every HTTP
+request as `Authorization: Bearer <token>` and acts with it. With
+`GITHUB_ACCEPT_REQUEST_TOKEN=true` this server does the same, so a client
+configured for GitHub's server can point here instead with the same header.
+
+- Over the `streamable-http` or `sse` transport, a request carrying
+  `Authorization: Bearer <token>` is sent to GitHub with that token, for
+  that request only. Concurrent requests with different tokens each use
+  their own; the token is never stored on the shared client.
+- A request without the header falls back to `GITHUB_TOKEN`. With the option
+  on, `GITHUB_TOKEN` is optional: an instance without it serves only
+  requests that bring a token, and refuses the others before calling GitHub
+  ("No GitHub token for this request").
+- The header must be exactly `Bearer <token>` (scheme in any case, one
+  space, a token of printable ASCII with no spaces). Anything else is
+  refused, never forwarded, even when `GITHUB_TOKEN` is set.
+- The request token is scrubbed from error messages like `GITHUB_TOKEN` is.
+- With the option off (the default) an incoming Authorization header is
+  ignored, exactly as before. stdio has no request headers and always uses
+  `GITHUB_TOKEN`.
+
+The option makes the server act as whoever sends a token. Expose the HTTP
+port only to callers you would hand that token to anyway, behind TLS.
+
 ### Creating a GitHub Personal Access Token
 
 1. **Navigate to token settings**
@@ -166,11 +193,11 @@ For a fine-grained personal access token, the repository permissions are:
 | Metadata | every tool (GitHub grants it with any other permission) | — |
 | Contents | `get_file_content_tool`, `list_repo_tree_tool` | `merge_pull_request_tool`, `create_release_tool` |
 | Issues | `list_issues_tool`, `get_issue_tool` | `create_issue_tool`, `update_issue_tool`, `create_issue_comment_tool` |
-| Pull requests | `list_pull_requests_tool`, `get_pull_request_tool`, `get_pull_request_diff_tool`, `get_pull_request_checks_tool`, `list_pull_request_comments_tool` | `create_pull_request_tool`, `update_pull_request_tool`, `reply_to_review_comment_tool`, `create_issue_comment_tool` on a PR |
+| Pull requests | `merge_pull_request_tool`, `list_pull_requests_tool`, `get_pull_request_tool`, `get_pull_request_diff_tool`, `get_pull_request_checks_tool`, `list_pull_request_comments_tool` | `create_pull_request_tool`, `update_pull_request_tool`, `reply_to_review_comment_tool`, `create_issue_comment_tool` on a PR |
 | Actions | `list_workflow_runs_tool`, `get_workflow_run_tool`, `get_failed_job_logs_tool` | `trigger_workflow_tool`, `rerun_workflow_run_tool`, `rerun_failed_jobs_tool` |
-| Commit statuses | `get_pull_request_checks_tool` | — |
+| Commit statuses | `get_pull_request_checks_tool`, `merge_pull_request_tool` | — |
 
-`get_pull_request_checks_tool` reads check-runs, and GitHub's permission table
+`get_pull_request_checks_tool` and `merge_pull_request_tool` read check-runs, and GitHub's permission table
 for fine-grained tokens lists no permission for that endpoint. It is readable
 on public repositories; on a private repository use a classic token or a
 GitHub App token. The search tools likewise have no permission of their own:
@@ -186,9 +213,35 @@ Three things worth knowing before granting write:
   `.github/workflows/`, relative to the default branch, additionally needs
   Workflows: write; without it GitHub answers 404. Expect the same of a merge
   that brings workflow changes in.
-- **Branch rules still apply.** `merge_pull_request_tool` cannot merge past
-  required checks or reviews; GitHub answers 405 and the tool returns its
-  message.
+- **The merge gate checks required status checks itself**, below. Other
+  branch rules (required reviews, for instance) are left to GitHub, which
+  answers 405 when it refuses; a token that may bypass the rules gets past
+  them.
+
+### The merge gate
+
+An organization owner, or anyone on a ruleset's bypass list, can merge past
+failing required checks: GitHub merges a red pull request for such a token.
+So `merge_pull_request_tool` does not leave the checks to GitHub. Before it
+merges it:
+
+1. reads the pull request's base branch and head SHA, and refuses if `sha`
+   was given and the head has moved;
+2. collects the base branch's required status checks from its active
+   rulesets and its classic branch protection, read from the branch itself
+   so no Administration permission is needed. An error reading either, or a
+   protected branch whose protection is not shown, refuses the merge rather
+   than count as none;
+3. refuses if no check is required, unless `allow_no_required_checks=True`;
+4. requires, for every required check on the head commit, a completed check
+   run of that name concluding `success`, `skipped` or `neutral` (the most
+   recent run of the name decides), or a commit status of `success`. A rule
+   that names an app accepts only that app's check runs. A missing, pending
+   or failed check refuses the merge, and the error lists each one and why;
+5. reads the pull request again and refuses if its head or base changed
+   meanwhile (GitHub's merge call pins the head but not the base), then
+   merges with the head SHA pinned, so a later push makes GitHub refuse
+   (409) rather than merge code nobody checked.
 
 With a classic token, `repo` covers all of the above (`public_repo` for public
 repositories only), plus `workflow` for the workflow-file case.
@@ -256,6 +309,7 @@ Assistant: [calls list_pull_request_comments_tool with pull_number=5]
 Assistant: [calls reply_to_review_comment_tool with comment_id=..., body="fixed in abc1234"]
 Assistant: [calls get_pull_request_checks_tool with pull_number=5]
 Assistant: [calls merge_pull_request_tool with merge_method="squash", sha=<head_sha from the checks>]
+           (the tool checks the required checks again itself before merging)
 ```
 
 ### Read a File
@@ -281,7 +335,9 @@ This server was designed with security as a primary concern. See [SECURITY.md](S
 1. **Token Protection**
    - Stored as SecretStr (never accidentally logged)
    - Environment variable only (never in files or args)
-   - Sanitized from all error messages
+   - Optionally, a per-request token from the HTTP `Authorization` header,
+     used for that request only and never stored on the shared client
+   - Both sanitized from all error messages
 
 2. **Input Validation**
    - Pydantic models for write inputs
@@ -296,6 +352,8 @@ This server was designed with security as a primary concern. See [SECURITY.md](S
    - Response size limits (10MB)
    - Job-log downloads follow GitHub's redirect without the token, over
      HTTPS only, and keep just the tail (20MB download limit)
+   - Merges only when the required checks are green on the head commit,
+     even for a token GitHub would let bypass them
 
 4. **Automated CVE Scanning**
    - GitHub Actions scan dependencies