feat(tools): expose backtest equity curve

The equity curve was fetched from the backend (ResultMap.getEquityCurve)
but silently discarded by the MCP layer — invisible to clients.

- New get_equity_curve tool returns the curve of a COMPLETED job as compact
  JSON with parallel arrays t[] (epoch-millis) and equity[] (account equity).
  Curves longer than maxPoints (default 500, max 5000) are downsampled,
  always preserving the first/last points and the global min/max so the worst
  drawdown and the peak survive the reduction.
- get_job_status gains an optional includeEquityCurve flag (default false)
  that appends the curve (downsampled to ~200 points) to the status summary.
- JSON is built without Jackson to avoid adding serialized types to the
  native image; api-client EquityPoint deserialization is already covered by
  reflect-config.

Bumps version to 0.4.0.

Author: mrmx

CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-06-16
+
+### Added ✨
+
+- **Equity curve access** — backtest results now expose the equity curve, which was previously fetched from the backend but silently discarded by the MCP layer.
+  - New **`get_equity_curve`** tool returns the curve of a COMPLETED job as compact JSON (parallel arrays `t[]` = epoch-millis timestamps, `equity[]` = account equity). Curves longer than `maxPoints` (default 500, max 5000) are downsampled, always preserving the first/last points and the global min and max (worst drawdown and peak).
+  - **`get_job_status`** gains an optional `includeEquityCurve` flag (default `false`) that appends the curve, downsampled to ~200 points, to the status summary.
+
 ## [0.3.3] — 2026-06-13
 
 ### Fixed 🐛

README.md

@@ -41,7 +41,7 @@ The installer detects your platform and picks the right delivery:
 Pin a version or override the destination:
 
 ```bash
-VERSION=0.3.3 INSTALL_DIR=~/.local/bin \
+VERSION=0.4.0 INSTALL_DIR=~/.local/bin \
   curl -fsSL https://raw.githubusercontent.com/QTSurfer/mcp-java/main/install.sh | bash
 ```
 

pom.xml

@@ -5,7 +5,7 @@
 
     <groupId>com.qtsurfer</groupId>
     <artifactId>mcp-java</artifactId>
-    <version>0.3.3</version>
+    <version>0.4.0</version>
     <packaging>jar</packaging>
     <name>qtsurfer-mcp-java</name>
 

src/main/java/com/qtsurfer/mcp/model/EquityPoint.java

@@ -0,0 +1,10 @@
+package com.qtsurfer.mcp.model;
+
+/**
+ * One sample of the running equity curve produced by a backtest.
+ *
+ * @param timestamp epoch milliseconds; the first point is anchored at the backtest {@code from},
+ *                  subsequent points carry the timestamp of each emitted yield event
+ * @param equity    running equity at this point ({@code initialCapital + cumulativePnl})
+ */
+public record EquityPoint(long timestamp, double equity) {}

src/main/java/com/qtsurfer/mcp/model/JobResult.java

@@ -1,8 +1,14 @@
 package com.qtsurfer.mcp.model;
 
+import java.util.List;
+
 /**
  * Execution metrics captured when a backtest job reaches COMPLETED state.
  * All numeric fields are nullable — they are absent when the strategy emitted no trades.
+ *
+ * <p>{@code equityCurve} is never null (empty when the run produced no yield events). It is
+ * not part of the default status summary; callers opt in via the {@code includeEquityCurve}
+ * flag on {@code get_job_status} or the dedicated {@code get_equity_curve} tool.
  */
 public record JobResult(
     Double pnlTotal,
@@ -15,5 +21,6 @@ public record JobResult(
     Double maxDrawdownPercent,
     Long signalCount,
     String hostName,
-    Double iops
+    Double iops,
+    List<EquityPoint> equityCurve
 ) {}

src/main/java/com/qtsurfer/mcp/service/SdkBacktestingService.java

@@ -7,6 +7,7 @@
 import com.qtsurfer.api.sdk.BacktestOptions;
 import com.qtsurfer.api.sdk.BacktestRequest;
 import com.qtsurfer.api.sdk.auth.AuthenticatedClient;
+import com.qtsurfer.mcp.model.EquityPoint;
 import com.qtsurfer.mcp.model.JobResult;
 import com.qtsurfer.mcp.model.JobStatus;
 import com.qtsurfer.mcp.model.JobSummary;
@@ -137,12 +138,17 @@ public Optional<JobSummary> getJobStatus(String jobId) {
   }
 
   private static JobResult toJobResult(ResultMap r) {
+    List<EquityPoint> curve = r.getEquityCurve() == null ? List.of()
+        : r.getEquityCurve().stream()
+            .filter(p -> p.getTimestamp() != null && p.getEquity() != null)
+            .map(p -> new EquityPoint(p.getTimestamp(), p.getEquity()))
+            .toList();
     return new JobResult(
         r.getPnlTotal(), r.getTotalTrades(), r.getWinRate(),
         r.getSharpeRatio(), r.getSortinoRatio(), r.getCagr(),
         r.getMaxDrawdown(), r.getMaxDrawdownPercent(),
         r.getSignalCount() != null ? r.getSignalCount().longValue() : null,
-        r.getHostName(), r.getIops());
+        r.getHostName(), r.getIops(), curve);
   }
 
   @Override

src/main/java/com/qtsurfer/mcp/tool/McpTools.java

@@ -7,12 +7,15 @@
 import com.qtsurfer.mcp.McpServerRunner;
 import com.qtsurfer.api.client.model.Exchange;
 import com.qtsurfer.api.client.model.InstrumentDetail;
+import com.qtsurfer.mcp.model.EquityPoint;
 import com.qtsurfer.mcp.model.JobResult;
 import com.qtsurfer.mcp.model.JobStatus;
 import com.qtsurfer.mcp.service.BacktestingService;
 
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
+import java.util.TreeSet;
 
 /**
  * Builds the five MCP tools that expose QTSurfer over the Model Context Protocol.
@@ -25,13 +28,21 @@ public final class McpTools {
 
   private McpTools() {}
 
+  /** Default sample cap for the inline equity-curve preview in {@code get_job_status}. */
+  private static final int PREVIEW_POINTS = 200;
+  /** Default sample cap for the dedicated {@code get_equity_curve} tool. */
+  private static final int DEFAULT_MAX_POINTS = 500;
+  /** Hard upper bound on points returned by {@code get_equity_curve}. */
+  private static final int MAX_POINTS_LIMIT = 5000;
+
   public static List<SyncToolSpecification> build(BacktestingService service, String apiUrl) {
     return List.of(
         version(apiUrl),
         listExchanges(service),
         listInstruments(service),
         submitBacktest(service),
         getJobStatus(service),
+        getEquityCurve(service),
         listJobs(service));
   }
 
@@ -163,22 +174,77 @@ private static SyncToolSpecification submitBacktest(BacktestingService service)
   private static SyncToolSpecification getJobStatus(BacktestingService service) {
     Tool tool = Tool.builder()
         .name("get_job_status")
-        .description("Get the current status of a submitted backtesting job.")
+        .description("Get the current status of a submitted backtesting job. "
+            + "Set includeEquityCurve=true to append the equity curve (downsampled to ~"
+            + PREVIEW_POINTS + " points) as compact JSON; use get_equity_curve for finer control.")
         .inputSchema(schema(
-            Map.of("jobId", prop("string", "Job ID returned by submit_backtest")),
+            Map.of(
+                "jobId", prop("string", "Job ID returned by submit_backtest"),
+                "includeEquityCurve", prop("boolean",
+                    "When true, append the equity curve (downsampled) to the result. Default false.")),
             List.of("jobId")))
         .build();
     return new SyncToolSpecification(tool,
         (exchange, request) -> {
-          String jobId = required(request.arguments(), "jobId");
+          Map<String, Object> args = request.arguments();
+          String jobId = required(args, "jobId");
+          boolean includeCurve = asBool(args == null ? null : args.get("includeEquityCurve"));
           return service.getJobStatus(jobId)
-              .map(j -> text(formatJobStatus(j.jobId(), j.instrument(), j.exchangeId(),
-                  j.status(), j.submittedAt(), j.result())))
+              .map(j -> {
+                String body = formatJobStatus(j.jobId(), j.instrument(), j.exchangeId(),
+                    j.status(), j.submittedAt(), j.result());
+                if (includeCurve && j.result() != null
+                    && j.result().equityCurve() != null && !j.result().equityCurve().isEmpty()) {
+                  body += "\n\nEquity curve:\n"
+                      + equityCurveJson(j.jobId(), j.result().equityCurve(), PREVIEW_POINTS);
+                }
+                return text(body);
+              })
               .orElse(text("Job not found: " + jobId
                   + ". Only jobs submitted in this session are tracked."));
         });
   }
 
+  // ---- get_equity_curve ---------------------------------------------------
+
+  private static SyncToolSpecification getEquityCurve(BacktestingService service) {
+    Tool tool = Tool.builder()
+        .name("get_equity_curve")
+        .description("Return the equity curve of a COMPLETED backtest as compact JSON: parallel "
+            + "arrays t[] (epoch-millis timestamps) and equity[] (account equity). Curves longer "
+            + "than maxPoints are downsampled, always preserving the first/last points and the "
+            + "global min and max (worst drawdown and peak).")
+        .inputSchema(schema(
+            Map.of(
+                "jobId", prop("string", "Job ID returned by submit_backtest"),
+                "maxPoints", prop("integer", "Max points to return (default " + DEFAULT_MAX_POINTS
+                    + ", max " + MAX_POINTS_LIMIT + "). The curve is downsampled if longer.")),
+            List.of("jobId")))
+        .build();
+    return new SyncToolSpecification(tool,
+        (exchange, request) -> {
+          Map<String, Object> args = request.arguments();
+          String jobId = required(args, "jobId");
+          int maxPoints = clamp(asInt(args.get("maxPoints"), DEFAULT_MAX_POINTS), 1, MAX_POINTS_LIMIT);
+          var summary = service.getJobStatus(jobId);
+          if (summary.isEmpty()) {
+            return text("Job not found: " + jobId
+                + ". Only jobs submitted in this session are tracked.");
+          }
+          JobResult result = summary.get().result();
+          if (result == null) {
+            return text("Job " + jobId + " has no results yet (status: "
+                + summary.get().status() + ").");
+          }
+          List<EquityPoint> curve = result.equityCurve();
+          if (curve == null || curve.isEmpty()) {
+            return text("Job " + jobId + " produced no equity curve "
+                + "(the strategy may have emitted no yield events).");
+          }
+          return text(equityCurveJson(jobId, curve, maxPoints));
+        });
+  }
+
   // ---- list_jobs ----------------------------------------------------------
 
   private static SyncToolSpecification listJobs(BacktestingService service) {
@@ -263,8 +329,84 @@ private static String formatJobStatus(String jobId, String instrument, String ex
     return sb.toString().stripTrailing();
   }
 
+  // ---- equity curve -------------------------------------------------------
+
+  /**
+   * Render an equity curve as compact JSON with parallel arrays (smaller than an array of
+   * objects). Curves longer than {@code maxPoints} are downsampled.
+   */
+  private static String equityCurveJson(String jobId, List<EquityPoint> curve, int maxPoints) {
+    List<EquityPoint> sampled = downsample(curve, maxPoints);
+    StringBuilder t = new StringBuilder();
+    StringBuilder eq = new StringBuilder();
+    for (int i = 0; i < sampled.size(); i++) {
+      if (i > 0) {
+        t.append(',');
+        eq.append(',');
+      }
+      t.append(sampled.get(i).timestamp());
+      eq.append(sampled.get(i).equity());
+    }
+    return "{\"jobId\":\"" + jobId + "\",\"unit\":\"epoch_ms\""
+        + ",\"points\":" + sampled.size()
+        + ",\"totalPoints\":" + curve.size()
+        + ",\"downsampled\":" + (sampled.size() < curve.size())
+        + ",\"t\":[" + t + "]"
+        + ",\"equity\":[" + eq + "]}";
+  }
+
+  /**
+   * Downsample to ~{@code maxPoints} via uniform striding, always keeping the first and last
+   * points and the global min/max so the worst drawdown and the peak survive the reduction.
+   */
+  private static List<EquityPoint> downsample(List<EquityPoint> curve, int maxPoints) {
+    int n = curve.size();
+    if (maxPoints <= 0 || n <= maxPoints) return curve;
+    int minI = 0, maxI = 0;
+    for (int i = 1; i < n; i++) {
+      double e = curve.get(i).equity();
+      if (e < curve.get(minI).equity()) minI = i;
+      if (e > curve.get(maxI).equity()) maxI = i;
+    }
+    TreeSet<Integer> idx = new TreeSet<>();
+    idx.add(0);
+    idx.add(n - 1);
+    idx.add(minI);
+    idx.add(maxI);
+    double stride = (double) (n - 1) / (maxPoints - 1);
+    for (int k = 0; k < maxPoints; k++) {
+      idx.add((int) Math.round(k * stride));
+    }
+    List<EquityPoint> out = new ArrayList<>(idx.size());
+    for (int i : idx) {
+      out.add(curve.get(i));
+    }
+    return out;
+  }
+
   // ---- helpers ------------------------------------------------------------
 
+  private static boolean asBool(Object v) {
+    if (v instanceof Boolean b) return b;
+    return v != null && "true".equalsIgnoreCase(v.toString().trim());
+  }
+
+  private static int asInt(Object v, int defaultValue) {
+    if (v instanceof Number n) return n.intValue();
+    if (v != null) {
+      try {
+        return Integer.parseInt(v.toString().trim());
+      } catch (NumberFormatException ignored) {
+        // fall through to default
+      }
+    }
+    return defaultValue;
+  }
+
+  private static int clamp(int v, int lo, int hi) {
+    return Math.max(lo, Math.min(hi, v));
+  }
+
   private static CallToolResult text(String content) {
     return CallToolResult.builder().addTextContent(content).build();
   }

src/test/java/com/qtsurfer/mcp/McpServerIT.java

@@ -38,15 +38,16 @@ void serverInfoIsCorrect() {
   }
 
   @Test
-  void registersExactlySixTools() {
-    assertThat(runner.getServer().listTools()).hasSize(6);
+  void registersExactlySevenTools() {
+    assertThat(runner.getServer().listTools()).hasSize(7);
   }
 
   @Test
   void allExpectedToolsPresent() {
     List<String> names = runner.getServer().listTools().stream().map(Tool::name).toList();
     assertThat(names).containsExactlyInAnyOrder(
-        "version", "list_exchanges", "list_instruments", "submit_backtest", "get_job_status", "list_jobs");
+        "version", "list_exchanges", "list_instruments", "submit_backtest",
+        "get_job_status", "get_equity_curve", "list_jobs");
   }
 
   @Test