MCP Uploaded-Diff Code Reviews

Summary

The MCP uploaded-diff flow lets local coding agents ask Zeeq for an expert review before a pull request exists. The local agent uploads a raw git unified diff through a token-protected anonymous endpoint, then calls the MCP tool to run the same reviewer execution core used by GitHub pull request reviews.

This path is synchronous and ephemeral. It does not create CodeReviewRecord rows, acquire review locks, publish queue messages, or write GitHub comments. The review XML is returned directly to the MCP caller.

Flow

MCP tool create_upload_url
  -> authenticate MCP caller
  -> create jobId and encrypted uploadToken
  -> return PUT URL and curl --data-binary example

Local agent uploads git diff
  -> anonymous PUT /api/v1/code-review/mcp-diffs/{jobId}?token=...
  -> endpoint decrypts token and checks jobId, expiry, byte limit, UTF-8, and diff header
  -> storage writes {jobId}/diff.txt in CodeReviewDiffs with token organization id

MCP tool run_review
  -> decrypt uploadToken and recover jobId, organization id, and expiry
  -> read and parse uploaded diff
  -> map files to CodeReviewFileSnapshot
  -> resolve repository mapping by github owner/repo
  -> mapped: apply repository file filter and configured reviewer agents
  -> unmapped: use built-in principal software engineer reviewer
  -> build CodeReviewPromptInput
  -> execute ICodeReviewAgentExecutor
  -> validate XML
  -> delete uploaded diff in finally
  -> return instruction-wrapped XML to the caller

Shared Core

The GitHub and MCP paths share these code-review components:

The GitHub path wraps those pieces with durable pull request records, queue messages, artifact storage, and GitHub comment rendering. The MCP path wraps them with upload-token validation, temporary diff storage, and direct XML return.

Security Model

The MCP server itself is authenticated. Only authenticated MCP callers can create an upload URL.

The upload endpoint is anonymous by design because curl uploads are separate from the MCP transport. Trust comes from the encrypted upload token. The token carries the job id, creator id, organization id, expiry, and optional W3C trace context. It uses the same configured key material as review request links but a distinct purpose string, so request-link tokens and upload tokens cannot be redeemed across purposes.

The upload endpoint rejects missing or invalid tokens, route job ids that do not match the token, expired tokens, empty bodies, invalid UTF-8, oversized bodies, and bodies without a diff --git header. The organization id used for storage writes comes from the token, not from storage metadata or request headers.

Storage And Cleanup

Uploaded diffs are stored through IStorageProvider<PostgresStorageWriteOptions> in StorageContainer.CodeReviewDiffs at {jobId}/diff.txt.

Re-uploading to the same job path overwrites the previous diff. This makes retry simple: if a review run consumes the diff or fails, the caller can upload the same path again while the token is still valid.

ExpertCodeReviewRunner deletes the uploaded diff in finally with CancellationToken.None after every run attempt. This includes success, validation errors after reading the diff, agent execution failures, and caller cancellation. Uploaded-but-never-run cleanup is intentionally deferred to a future background cleanup worker.

Repository Resolution

run_review receives ownerQualifiedRepoName from the MCP caller.

If ICodeRepositoryStore.FindActiveAsync("github", ownerQualifiedRepoName) returns a repository, the MCP review uses that repository's organization id, file filter, and configured reviewer agents.

If no repository mapping exists, the review still runs with CodeReviewerAgentResolver.CreateDefaultRuntimeAgent() and the organization id from the upload token. This fallback keeps local pre-PR reviews useful even when Zeeq has not yet been configured for the repository.