Core MCP transport coverage push — 2026-05-31¶

ADR-0108 §1 research digest for the test/core-mcp-coverage-push branch.

Scope¶

Lift line coverage on core/src/mcp/ by adding a focused C test file (core/test/test_mcp_coverage.c) that exercises the dispatcher error envelopes, the lifecycle state-machine edges, and the transport-level error paths that the existing test_mcp_smoke.c does not reach.

No production code is changed.

Pre-state¶

core/src/mcp/ carries one C test (core/test/test_mcp_smoke.c, ~670 LOC) wired into the build under enable_mcp with the slow suite tag. That file pins the happy-path contract: init / start_stdio / close lifecycle, tools/list round-trip, tools/call for list_features, method-not-found error envelope, UDS round-trip, compute_vmaf real-score against the testdata 576x324 8-bit YUV pair, compute_vmaf 10-bit ramp, and the SSE GET /mcp/sse + POST /mcp/sse inline round-trip.

What it does not reach (baseline gcov, CPU-only build, all transports enabled):

The dispatcher number is the most worrying: ~42 % of dispatcher.c lines never run under the smoke harness, including the entire JSON-RPC error-envelope construction path that production clients land on the moment they send a malformed request.

Audit method¶

1. Cold-read every C file in core/src/mcp/ plus core/include/libvmaf/libvmaf_mcp.h.
2. For each entry point and helper, classify branches into:
3. happy path (smoke already covers),
4. input validation / error envelope (likely uncovered),
5. state-machine edge (double-start, stop-then-close, …),
6. transport-specific error path (overflow line, 404, malformed HTTP request line, oversized POST body, …).
7. Stage a gcov measurement against the smoke harness alone to confirm the qualitative classification matches gcov line numbers. Use the delta as the success metric for the new file.
8. Add tests until the dispatcher line coverage passes a 75 % gate (production-grade for an error-envelope-heavy TU).

What the new file covers (27 sub-tests)¶

Dispatcher (core/src/mcp/dispatcher.c)¶

Lifecycle (core/src/mcp/mcp.c)¶

stdio transport (core/src/mcp/transport_stdio.c)¶

SSE transport (core/src/mcp/transport_sse.c)¶

Post-state¶

Coverage delta:

transport_uds.c is unchanged: its happy-path round-trip (the only non-error path that doesn't share code with the stdio worker) is already covered by test_mcp_smoke.c::test_uds_roundtrip. The remaining uncovered UDS lines are inside serve_client's oversize-line branch, which mirrors stdio's overflow path verbatim; duplicating the test for UDS would be churn for no incremental confidence. Flagged for a follow-up sweep, not a blocker here.

transport_sse.c ticks up modestly (+3.56 pp): four new HTTP error-path tests but the bulk of uncovered lines are inside sse_emit_event and sse_extract_id — both marked __attribute__ ((unused)) and reserved for the v4 broadcast pattern. Not test-able through the public API in v3.

Decision matrix considered¶

Reproducer¶

CPU-only build with all MCP transports enabled, then build + run both MCP test executables:

cd core
meson setup build-mcp-coverage \
    -Denable_cuda=false -Denable_sycl=false -Denable_hip=false \
    -Denable_mcp=true \
    -Denable_mcp_stdio=true -Denable_mcp_uds=true -Denable_mcp_sse=enabled \
    -Denable_tests=true --buildtype=debug
ninja -C build-mcp-coverage
meson test -C build-mcp-coverage test_mcp_smoke test_mcp_coverage

Optional coverage measurement:

meson setup build-cov \
    -Denable_cuda=false -Denable_sycl=false -Denable_hip=false \
    -Denable_mcp=true \
    -Denable_mcp_stdio=true -Denable_mcp_uds=true -Denable_mcp_sse=enabled \
    -Denable_tests=true --buildtype=debug -Db_coverage=true
ninja -C build-cov
./build-cov/test/test_mcp_smoke
./build-cov/test/test_mcp_coverage
cd build-cov/src/libvmaf.so.3.0.0.p
for f in mcp_*.gcda; do
    base=$(basename $f .c.gcda | sed 's/^mcp_//')
    cov=$(gcov $f 2>&1 | grep -oP '\d+\.\d+(?=%)' | head -1)
    echo "$base: $cov%"
done

Known gaps deferred¶

1. UDS oversize-line overflow path — mirrors stdio verbatim; deferred to a sweep PR that consolidates the read_line helpers in transport_stdio.c + transport_uds.c into one shared TU.
2. SSE v4 broadcast pattern (sse_emit_event, sse_extract_id) — currently dead code, marked __attribute__((unused)); not test-able through the v3 public API.
3. compute_vmaf.c error branches inside score_yuv_pair (vmaf_init OOM, vmaf_model_load OOM, picture_alloc OOM) — fault-injection-style tests that require either malloc-poisoning or rebuilding with a shim. Deferred to a focused OOM-injection PR.
4. cJSON.c parser error branches — out of scope; cJSON ships its own test suite, the libvmaf coverage push targets fork-added code.
5. The pre-existing vmaf_mcp_stop() double-call bug (running flag set to 2 unconditionally on every entry → re-enters the join branch for prev==2 on the third call, joining an already-joined thread). Observed locally while staging the test; a focused fix PR will land separately so this coverage PR stays purely additive.

References¶

• core/src/mcp/dispatcher.c
• core/src/mcp/mcp.c
• core/src/mcp/transport_stdio.c
• core/src/mcp/transport_uds.c
• core/src/mcp/transport_sse.c
• core/src/mcp/compute_vmaf.c
• core/test/test_mcp_smoke.c
• core/include/libvmaf/libvmaf_mcp.h
• ADR-0108 — deep-dive deliverables rule
• ADR-0209 — embedded MCP scaffold
• ADR-0128 — MCP design / operational guardrails
• ADR-0332 — MCP SSE transport (mongoose replacement, plain POSIX)