Initial commit: ReviewGuard MCP server

Author: sdirix

.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      minor-and-patch:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # 22 is the minimum consumer version (engines), 24 the recommended
+        # development version (.nvmrc).
+        node-version: [22, 24]
+    steps:
+      - uses: actions/checkout@v7
+
+      # check-latest avoids a stale runner tool cache serving a Node patch
+      # older than what npm 12 supports (e.g. 22.x before 22.22.2).
+      #
+      # package-manager-cache: false is required. setup-node auto-enables npm
+      # caching when it detects a lockfile, and that step runs npm config get
+      # cache with the runner's bundled npm 10/11, which fails the repository's
+      # devEngines check (npm >= 12) before the upgrade step below can run.
+      # Simply leaving the cache option unset is not enough because auto-caching
+      # is on by default.
+      - uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node-version }}
+          check-latest: true
+          package-manager-cache: false
+
+      # Runs outside the repository because the runner's bundled npm 11 would
+      # otherwise fail the repository's devEngines check (npm >= 12) before it
+      # can upgrade itself.
+      - name: Use npm 12 (required by devEngines)
+        run: npm install -g npm@12
+        working-directory: ${{ runner.temp }}
+
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run format:check
+      - run: npm run typecheck
+      - run: npm run build
+      - run: npm test
+
+      - name: Verify publishable package contents
+        run: npm pack --dry-run

.github/workflows/release.yml

@@ -0,0 +1,111 @@
+# Manual release: bumps the version, prepends auto-generated release notes to
+# CHANGELOG.md, tags, creates a GitHub release, and publishes to npm.
+#
+# Publishing uses npm trusted publishing (OIDC), so no npm token is stored in
+# the repository. One-time setup and the first manual publish are documented
+# in the repository wiki.
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release, e.g. 0.2.0 (tags v0.2.0)"
+        required: true
+        type: string
+
+concurrency: release
+
+permissions:
+  contents: write
+  id-token: write # npm trusted publishing (OIDC)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      VERSION: ${{ inputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Full history so release notes and the previous tag are found.
+          fetch-depth: 0
+
+      # package-manager-cache: false is required. setup-node auto-enables npm
+      # caching when it detects a lockfile, and that step runs npm config get
+      # cache with the runner's bundled npm 10/11, which fails the repository's
+      # devEngines check (npm >= 12) before the upgrade step below can run.
+      # Simply leaving the cache option unset is not enough because auto-caching
+      # is on by default.
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+          registry-url: "https://registry.npmjs.org"
+          package-manager-cache: false
+
+      # Runs outside the repository because the runner's bundled npm 11 would
+      # otherwise fail the repository's devEngines check (npm >= 12) before it
+      # can upgrade itself.
+      - name: Use npm 12 (required by devEngines and trusted publishing)
+        run: npm install -g npm@12
+        working-directory: ${{ runner.temp }}
+
+      - name: Validate version
+        run: |
+          if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::error::'$VERSION' is not plain X.Y.Z semver"
+            exit 1
+          fi
+          if git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null; then
+            echo "::error::tag v$VERSION already exists"
+            exit 1
+          fi
+
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run format:check
+      - run: npm run typecheck
+      - run: npm run build
+      - run: npm test
+
+      - name: Bump version
+        run: npm version --no-git-tag-version "$VERSION"
+
+      - name: Generate release notes and update CHANGELOG.md
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PREVIOUS_TAG=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null || true)
+          gh api "repos/${{ github.repository }}/releases/generate-notes" \
+            -f tag_name="v$VERSION" \
+            -f target_commitish="${{ github.sha }}" \
+            ${PREVIOUS_TAG:+-f previous_tag_name="$PREVIOUS_TAG"} \
+            --jq .body > /tmp/release-notes.md
+          {
+            echo "# Changelog"
+            echo
+            echo "## v$VERSION ($(date -u +%Y-%m-%d))"
+            echo
+            cat /tmp/release-notes.md
+            echo
+            tail -n +3 CHANGELOG.md
+          } > /tmp/changelog.md
+          mv /tmp/changelog.md CHANGELOG.md
+
+      - name: Commit, tag and push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add package.json package-lock.json CHANGELOG.md
+          git commit -m "chore: release v$VERSION"
+          git tag "v$VERSION"
+          git push origin "HEAD:$GITHUB_REF_NAME"
+          git push origin "v$VERSION"
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "v$VERSION" --title "v$VERSION" --notes-file /tmp/release-notes.md
+
+      - name: Publish to npm (trusted publishing, provenance attached)
+        run: npm publish

.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+coverage/
+*.tgz
+.env

.nvmrc

@@ -0,0 +1 @@
+24

.prettierignore

@@ -0,0 +1,4 @@
+dist/
+coverage/
+package-lock.json
+CHANGELOG.md

.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "printWidth": 100
+}

AGENTS.md

@@ -0,0 +1,33 @@
+For everything not covered here, the human-facing docs are authoritative: see
+`README.md` for modes, tools, flags, and usage, and `CONTRIBUTING.md` for the
+development setup, the script list, and the release process.
+
+## Project overview
+
+ReviewGuard MCP (npm package `@eclipsesource/review-guard-mcp`, binary
+`review-guard-mcp`, MCP server name `review-guard`) is a TypeScript MCP server
+that lets AI agents work on GitHub PR reviews behind a safety boundary. In the
+default **pending mode** agents read PR discussion context and create draft
+(pending) reviews but cannot submit them. In the opt-in **submit mode**
+(`--allow-submit`) an agent may also submit the review, restricted to an allowed
+action set and always prefixed with a fixed disclaimer. Two transports: stdio
+(for IDE-managed lifetime) and HTTP (remote server).
+
+## Architecture
+
+- **`src/github.ts`**: `GitHubReviewClient` class. The ONLY file that touches GitHub APIs. Uses GraphQL for resolved review-thread context and mutations, and REST for review summaries and general PR comments. Review-thread comments (GraphQL `reactionGroups`) and conversation comments (REST `reactions`) expose a normalized `reactions` map (content -> count, e.g. `THUMBS_DOWN`) so agents can see downvotes. Thread `isResolved`/`resolvedBy` are also returned. Safety boundary: comment/thread mutations exclude the `event` field, a post-creation tripwire verifies `PENDING` state (its error message tells the agent to stop and alert the human, since many MCP clients do not surface tool errors), and write operations are limited to the authenticated user's review. Submission is gated: `submitReview` (the only place `submitPullRequestReview` is called) refuses any action not in the `allowSubmit` set passed to the constructor, and always prefixes the review body with the fixed `submitBody` (an optional caller `additionalBody` is appended below it, never replacing it). Thread resolution is gated too: `resolveReviewThread` runs only when `allowResolve` is set AND the thread's first comment is authored by the authenticated user (it refuses others' threads), so a bot can tidy up its own now-fixed findings but not close anyone else's conversations. PR scoping is enforced here too: when the client is constructed with a `scope` (owner/repo/PR), every public method calls `assertInScope` and refuses input targeting a different PR/repo, and `resolveReviewThread` verifies the thread's PR matches the scope. This is the authoritative boundary. The server-side schema change is convenience on top of it.
+- **`src/server.ts`**: `createMcpServer(client)` factory. Registers `get_pr_review_context`, `list_pending_review`, `add_review_comments`, `modify_review_comment`, and `delete_pending_review` with Zod schemas. Additionally registers `submit` **only when** `client.allowedSubmitActions` is non-empty (its `action` enum is restricted to that set), and `resolve_review_thread` **only when** `client.resolveEnabled` (started with `--allow-resolve`). When `client.scopedPullRequest` is set, the PR tools omit their `owner`/`repo`/`pull_number` arguments and act on the scoped PR implicitly. Shared by both transports.
+- **`src/stdio.ts`**: Stdio transport entry point. Connects the MCP server to stdin/stdout for IDE-managed lifetime (Theia, VS Code).
+- **`src/http.ts`**: HTTP transport. A plain `node:http` server exposing stateless Streamable HTTP at `/mcp` (POST only, GET/DELETE return 405, other paths 404). No web framework: the MCP transport parses the request body and enforces the Host header itself. Receives `{ port, host }` from the entry point and binds that address (default `127.0.0.1`). Validates the Host header of incoming requests (DNS rebinding protection): loopback aliases only for a loopback bind, plus the bind address and the container-runtime host names (`host.docker.internal`, `host.containers.internal`) for a non-loopback bind.
+- **`src/index.ts`**: Thin dispatcher. Parses the CLI via `parseCliOptions`, resolves the GitHub token, applies the default submit disclaimer, creates the client, then delegates to `--stdio` or HTTP mode.
+- **`src/args.ts`**: `parseCliOptions`, the single place that knows every CLI flag. Accepts `--flag value` and `--flag=value`. Throws `CliUsageError` on unknown flags, missing values, or duplicates (the entry point prints it and exits non-zero), so a typo'd hardening flag (e.g. the `--repo`/`--pr` scope) can never be silently ignored.
+- **`test/`**: vitest suite. `args.test.ts` covers CLI validation. `github.test.ts` covers the safety gates (submit refusal, fixed-body prefixing, scope assertion, own-thread resolve, PENDING tripwire) with mocked `gql`/`octokit` internals. `server.test.ts` covers tool registration and dispatch over an in-memory MCP transport. Changes to the safety boundary must keep this coverage. `test/integration/review-guard.itest.ts` is a manual end-to-end suite (`npm run test:integration`, own config in `vitest.integration.config.ts`) that drives every tool against a real GitHub repository with two accounts and verifies the results through direct API reads. It is excluded from `npm test` and CI, setup is documented in CONTRIBUTING.md.
+
+## Key conventions
+
+- ESM (`"type": "module"` in package.json), NodeNext module resolution
+- Strict TypeScript. ESLint (type-checked) and Prettier are enforced in CI, so run `npm run lint` and `npm run format` before committing
+- No em dashes and no semicolons in prose. This applies to docs, code comments, and user-facing strings. Write plain sentences instead
+- Tool errors returned as `{ isError: true }` content, not thrown
+- Server binds to `127.0.0.1` by default, or the one specific address given with `--host`. Unspecified addresses (`0.0.0.0`, `::`) are refused at CLI parsing. The HTTP transport validates the Host header (DNS rebinding protection)
+- `submitPullRequestReview` lives ONLY in `submitReview` and runs ONLY when `allowSubmit` is non-empty and the requested action is in it. Do not add submission anywhere else, do not bypass the `allowSubmit` gate. The `submitBody` prefix stays server-controlled: a caller may pass `summary` (the `submit` tool) which is APPENDED below the prefix, but the prefix is always present and can never be replaced or removed.

CHANGELOG.md

@@ -0,0 +1 @@
+# Changelog

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md