[SPEC] MCP Handler Oracle Verification — Prove MCP Plugin Matches Service-Layer Behavior (Phase 3)

[michael-conrad]

Problem

The testing pipeline (Phases 0-2, #12) establishes service oracle tests and HTTP probe results that define what "correct behavior" means for each GitBucket service method and API route. But the MCP plugin (not yet implemented) will call those same service methods internally — and there is no verification that the plugin's MCP handlers produce results equivalent to the service-layer oracles.

Without this verification, the MCP plugin could silently diverge from GitBucket's actual behavior, and the key value proposition (bypassing broken REST endpoints by calling services directly) cannot be proven.

Dependency

Blocked on MCP plugin implementation. This spec cannot be implemented until MCP tool handlers exist. Phase 3 consumes the oracle test outputs from #12 Phase 0 as its source of truth.

Approach

Phase 3: MCP Handler Oracle Verification

For each MCP tool handler, prove that its output matches the corresponding service-layer oracle result. This closes the verification loop:

Phase 0: Service oracle → "What correct behavior IS"
Phase 1: Route discovery → "What routes exist"
Phase 2: HTTP probe → "What REST endpoints actually work"
Phase 3: MCP verification → "Does the plugin match the oracle?"

Mechanism:

• MCP handlers run inside the same in-JVM test context as Phase 0 service tests
• Each MCP tool handler test:
  1. Calls the MCP handler with known inputs (same inputs as Phase 0 oracle)
  2. Calls the corresponding service method directly with the same inputs
  3. Asserts handler output == service method output
• Test infrastructure reuses Phase 0's ServiceSpecBase pattern and fixture factories

MCP Handler → Service Method Mapping:

MCP Tool	Internal Service	Oracle Source
gitbucket_create_issue	IssueService.insertIssue()	IssuesServiceSpec
gitbucket_get_issue	IssueService.getIssue()	IssuesServiceSpec
gitbucket_update_issue	IssueService.updateIssue()	IssuesServiceSpec
gitbucket_close_issue	IssueService.updateIssue() (state change)	IssuesServiceSpec
gitbucket_reopen_issue	IssueService.updateIssue() (state change)	IssuesServiceSpec
gitbucket_add_comment	Comment API	IssuesServiceSpec
gitbucket_get_comments	Comment API	IssuesServiceSpec
gitbucket_list_issues	IssueService + Slick queries	IssuesServiceSpec
gitbucket_search_issues	Slick DB query	IssuesServiceSpec
gitbucket_add_labels	LabelService	LabelServiceSpec
gitbucket_replace_labels	LabelService	LabelServiceSpec
gitbucket_remove_label	LabelService	LabelServiceSpec
gitbucket_create_label	LabelService	LabelServiceSpec
gitbucket_delete_label	LabelService	LabelServiceSpec

Cross-validation for broken REST endpoints:

• For endpoints where REST API is broken (e.g., PATCH /issues/{n} returns 404):
  • Prove MCP handler succeeds where REST fails
  • Prove MCP handler output == service method output
  • This validates the core value proposition: MCP bypasses broken REST

Success Criteria

1. Every MCP tool handler has a dedicated test asserting handler output == service method output
2. For every broken REST endpoint (identified in Phase 2 probe results), there is a test proving the MCP handler succeeds where REST fails
3. MCP tests reuse Phase 0 fixture factories and ServiceSpecBase infrastructure — no duplicated test setup
4. MCP test coverage reaches 100% of implemented MCP tools

Out of Scope

• MCP protocol transport testing (stdio/SSE transport layer)
• MCP tool discovery and registration testing
• Performance benchmarks
• REST API fixes