ci: add MCP interface diff workflow for Everything server

[SamMorrowDrums]

Summary

Adds a GitHub Actions workflow that tracks public interface changes to the Everything MCP server. This provides clear visibility into how the reference implementation evolves over time—useful for SDK compliance validation, catching unintended regressions, and reviewing PRs that modify the server interface.

Motivation

The Everything server is the reference implementation that exercises all MCP protocol features. Changes to its public interface (tools, resources, prompts, capabilities) often signal:

• New protocol features being demonstrated
• SDK updates affecting server behavior
• Potential breaking changes

Currently there's no automated way to see these changes at a glance. This workflow surfaces them directly in the GitHub Actions summary.

Related discussion: modelcontextprotocol/inspector#1034 - Interest in using mcp-server-diff for SDK compliance testing with the Everything server.

What the workflow does

1. Triggers on PRs and pushes affecting src/everything/
2. Compares current branch against merge-base (PRs) or previous commit (pushes)
3. Generates a diff report showing changes to tools, resources, prompts, and capabilities
4. Supports manual workflow_dispatch for comparing any two refs (commits, tags, branches)

Example output

Here's a real diff between commit 737ce98 and the current HEAD of the Everything server:

--- base/initialize.json
+++ target/initialize.json

+ capabilities.tasks: {"cancel":{},"list":{},"requests":{"tools":{"call":{}}}}

--- base/tools.json
+++ target/tools.json

+ tools[simulate-research-query]: {"description":"Simulates a deep research operation..."}

This clearly shows the new Tasks capability and the simulate-research-query tool that were added.

Real-world example

See the MCP diff action in use on github/github-mcp-server - this workflow run shows interface changes from the "Generate server instructions in Inventory" PR.

Workflow features

• ✅ Minimal permissions (contents: read only)
• ✅ Pinned action versions with SHA references
• ✅ Path filtering - only runs when Everything server changes
• ✅ Manual trigger - compare any refs via workflow_dispatch
• ✅ Clear summary - results appear directly in GitHub Actions UI

Testing

The workflow uses SamMorrowDrums/mcp-server-diff which is also available as a CLI:

# Try it locally
npx mcp-server-diff@latest -b "node dist/index.js stdio" -t "node dist/index.js stdio" -o markdown

[SamMorrowDrums]

@cliffhall what do you think I'd need to do, or who do you think I'd need to ping to get this over the line (or get a definitive no)?

As mentioned offer is open to:

• make a trusted maintainer admin of the repo
• hand the repo to mcp org

https://discord.com/channels/1358869848138059966/1466125436932198483/1466211900160348394

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 1m 9s —— View job

---

PR Review: ci: add MCP interface diff workflow for Everything server

• Gather context and understand the request
• Read the workflow file
• Analyze for correctness, security, and best practices
• Post review feedback

---

Summary

The workflow is clean, focused, and follows most GitHub Actions best practices. The main considerations are around third-party action trust and a few minor improvements. Overall it's a reasonable addition if maintainers are comfortable taking a dependency on the external action.

---

Security

Permissions — contents: read only. Minimal and correct for what this workflow does.

Pinned SHAs — Both actions are pinned to commit SHAs, which is the right approach:

• actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 (v4.2.2) ✅
• SamMorrowDrums/mcp-server-diff@a5555e85d68eaa014a334ae7d12b73787f2c49cc (v2.3.5) ✅

Third-party action — the main concern: The action SamMorrowDrums/mcp-server-diff is authored by the same person submitting this PR. This is worth calling out explicitly for maintainers:

• It's not under the modelcontextprotocol or actions org, meaning this repo takes an ongoing maintenance dependency on an external project
• The SHA pin is good supply-chain hygiene, but updating requires manual tracking
• Maintainers should review the action source before merging to understand what code runs in your CI environment
• If this action becomes unmaintained or the author transfers/deletes the repo, the workflow breaks

This doesn't make it a hard blocker, but it's the key judgment call: is the visibility benefit worth an external runtime dependency on a non-org action? The PR author has offered to transfer the repo to the MCP org, which would resolve this concern entirely.

---

Correctness

Checkout fetch-depth: 0 — Correct. The diff action needs full history to find merge-base.

compare_ref empty string behavior (line 52): The behavior when compare_ref is '' is entirely delegated to the external action — the workflow has no fallback or documentation for what happens. The PR description says it uses merge-base for PRs and previous commit for pushes, but this is opaque from reading the workflow alone. A comment here would help future maintainers:

# When empty, mcp-server-diff uses merge-base for PRs and HEAD~1 for pushes
compare_ref: ${{ github.event.inputs.compare_ref || '' }}

start_command path (line 51): node src/everything/dist/index.js stdio runs relative to the checkout root. This is correct, but it's worth noting this path is hard-coded and would need updating if the server ever moves.

workflow_dispatch target_ref label (line 25): The description says "defaults to current branch if empty" which is accurate — the checkout step falls back to github.ref. Clear enough.

---

Minor Issues

No concurrency group — Without this, multiple pushes to a PR branch will queue duplicate runs rather than cancelling the superseded one. Fix this →:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

setup_node: 'true' as string (line 47): Minor — passing 'true' as a quoted string rather than a boolean is fine for YAML action inputs (they're always strings), but it's slightly unusual. No real issue here.

if: always() on summary step (line 56): Good practice — ensures the summary context is appended even on failure.

---

Overall Assessment

The workflow is well-structured and serves a legitimate purpose. The gate on merging should be:

1. Maintainers should review SamMorrowDrums/mcp-server-diff source before accepting this dependency
2. Consider whether transferring the action repo to the MCP org is the right path (as the author offered), which would make this more maintainable long-term

If those concerns are addressed, the main code change is solid. The concurrency group is a nice-to-have improvement that could be added in a follow-up or in this PR.

[SamMorrowDrums]

Addressed the concurrency feedback in 4424981:

• Added a concurrency group keyed on workflow + ref with cancel-in-progress: true so superseded runs on the same PR/branch are cancelled.
• While re-verifying the action pin I noticed the previous SHA (a5555e8…) didn't actually exist in SamMorrowDrums/mcp-server-diff — repinned to the correct v2.3.5 commit f7e5e58a4b0c4f68a5827adad2292953bb1ab9ef.

[SamMorrowDrums]

Per @cliffhall's feedback about visibility, I've added a sticky PR comment so the diff shows up directly on the PR (commit ad5bf3f):

• Adds pull-requests: write permission.
• After the diff step, builds a comment body from conformance-report/CONFORMANCE_REPORT.md with the status summary up top and the full report tucked into a collapsed <details> block.
• Posts via marocchino/sticky-pull-request-comment@v3.0.4 (SHA-pinned) with a stable header key, so subsequent pushes update the same comment instead of spawning new ones.
• Guarded to same-repo PRs only — fork PRs still get the Actions summary and uploaded artifact, but won't try (and fail) to post a comment with a read-only token.

The action remains opt-in / non-failing on interface differences as before; this is purely about surfacing the report.

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 56s —— View job

---

PR Review: ci: add MCP interface diff workflow for Everything server

• Gather context and read the updated workflow
• Analyze the new changes since the last review (concurrency, release tags, sticky PR comment)
• Post review feedback

---

Summary

Since the last review, the workflow has picked up four changes — the concurrency group, the typescript-servers-* tag trigger, the sticky PR comment, and a corrected action SHA pin. All four are sound. The security posture is good and the fork-PR handling is correct. Remaining gate is unchanged: this is still a runtime dependency on a non-org third-party action (SamMorrowDrums/mcp-server-diff).

---

What's new since the last review — all good ✅

• Concurrency (38–40): keyed on github.workflow + github.ref with cancel-in-progress: true. Correct — superseded PR/branch runs are cancelled. Tag refs are unique so releases won't cancel each other.
• Corrected SHA pin (56): repinned to f7e5e58… after the previous a5555e8… was found not to exist. Good catch; SHA-pinning is the right hygiene.
• Release-tag trigger (17–18): typescript-servers-* push surfaces the cumulative interface delta per release. Reasonable.

Security — fork handling is correct ✅

This is the part most worth scrutiny, since the workflow both executes PR code (npm ci + build + node …/index.js stdio) and gained pull-requests: write. It's done safely:

• It uses the pull_request event (not pull_request_target), so for fork PRs the GITHUB_TOKEN is read-only and untrusted PR code can't abuse write scope.
• Both comment steps are guarded by github.event.pull_request.head.repo.full_name == github.repository (88, 116), so fork PRs skip the write-token comment entirely and fall back to the summary + artifact. This is the right pattern. 👍

Minor suggestions (non-blocking)

• status output coupling (95): the comment logic branches on steps.mcp_diff.outputs.status == "passed". If the action ever renames/removes that output, the empty string silently falls through to the "⚠️ changes detected" branch — a false alarm rather than a failure. Worth a brief comment noting the dependency on the action's status output contract.
• ${{ }} interpolation inside run: (95, 111): values like github.run_id, head.sha, and the action's status are spliced directly into the shell script. They're all trusted/SHA-shaped here so there's no real injection risk, but GitHub's own guidance is to pass them via env: and reference $VAR in the script. Pure best-practice tidy-up. Fix this →
• Build PR comment body on diff failure: this step has no if: always(), so a genuine build/run failure in the diff step skips the comment (and reviewers see nothing on the PR). That's a defensible default, but if you want a failure to be visible on the PR rather than only in the Actions tab, consider posting a "diff run failed" comment too.

Unchanged gate from the prior review

The one real decision for maintainers is still the external-action dependency. SamMorrowDrums/mcp-server-diff is authored by the PR submitter and lives outside the modelcontextprotocol/actions orgs. SHA-pinning mitigates supply-chain risk, but the repo takes an ongoing maintenance dependency, and the workflow breaks if the action is transferred/deleted. The author's standing offer to transfer the action into the MCP org would resolve this cleanly.

---

Verdict

Code-wise this is solid and ready. The remaining call is organizational (accepting/owning the external action), not technical. The minor items above are optional polish.
· branch add-everything-server-mcp-diff-workflow