Class TraceService

java.lang.Object
com.shaft.mcp.TraceService
@Service public class TraceService extends Object
MCP tools for persisted SHAFT trace discovery, reading, and deterministic failure analysis.

  • Constructor Details

    • TraceService

      public TraceService()
      Creates the default local MCP trace service.

  • Method Details

    • traceLatest

      @Tool(name="trace_latest", description="returns recent persisted SHAFT trace indexes from target/shaft-traces") public TraceService.McpTraceLatestResult traceLatest(int maxResults)
      Lists recent persisted SHAFT trace indexes under target/shaft-traces.
      Parameters:
      maxResults - maximum trace indexes to return
      Returns:
      recent trace index metadata

    • traceRead

      @Tool(name="trace_read", description="returns redacted SHAFT trace JSON from a trace path with explicit output bounds") public TraceService.McpTraceReadResult traceRead(String tracePath, int maxCharacters)
      Reads a persisted trace JSON file, trace ZIP, trace directory, or index path with bounded output.
      Parameters:
      tracePath - trace path inside the MCP workspace
      maxCharacters - maximum characters to return
      Returns:
      bounded redacted trace JSON content

    • traceSummarize

      @Tool(name="trace_summarize", description="returns a deterministic summary of a persisted SHAFT trace without AI") public TraceService.McpTraceSummary traceSummarize(String tracePath)
      Summarizes a persisted SHAFT trace deterministically without provider calls.
      Parameters:
      tracePath - trace path inside the MCP workspace
      Returns:
      deterministic failure summary

    • traceOpenViewer

      @Tool(name="trace_open_viewer", description="resolves (extracting from the trace ZIP if needed) the offline SHAFT Trace Report HTML viewer for a persisted trace") public TraceService.McpTraceViewerResult traceOpenViewer(String tracePath)
      Resolves (extracting from the trace ZIP if needed) the static offline "SHAFT Trace Report.html" viewer for a persisted trace -- the same time-travel timeline / action-list / DOM-snapshot / network / console viewer produced at trace-generation time, so callers (an IDE panel, a CI step, or a human) can open a real file path without re-deriving the HTML themselves.
      Parameters:
      tracePath - trace path inside the MCP workspace (directory, index.json, or ZIP)
      Returns:
      the resolved viewer HTML path and whether it had to be freshly extracted

    • reportMergeShards

      @Tool(name="report_merge_shards", description="merges N per-shard Allure/trace/doctor-intelligence blobs into one Allure result set plus a flaky-clustering speedboard HTML") public TraceService.McpMergeShardsResult reportMergeShards(List<String> shardBlobPaths, String outputDirectory)
      Merges N per-shard blobs (raw Allure results + optional traces + optional doctor ExecutionIntelligence, produced by independent -Dshaft.shard=N/M runs) into one Allure result set plus a timeline "speedboard" HTML and a cross-shard flaky-clustering summary. See ShardMerger for the merge semantics.
      Parameters:
      shardBlobPaths - shard blob root directories inside the MCP workspace, in merge order
      outputDirectory - merged output directory inside the MCP workspace; blank selects target/shaft-merged-report
      Returns:
      merged Allure results directory, speedboard path, and flaky-clustering summary

    • doctorAnalyzeTrace

      @Tool(name="doctor_analyze_trace", description="analyzes a persisted SHAFT trace and returns deterministic Doctor remediation guidance") public McpAnalysisReport doctorAnalyzeTrace(String tracePath, String backend)
      Analyzes a persisted SHAFT trace and returns the existing MCP Doctor remediation report shape.
      Parameters:
      tracePath - trace path inside the MCP workspace
      backend - optional backend label, playwright or webdriver
      Returns:
      deterministic MCP Doctor analysis and remediation snippets