diff --git a/CHANGELOG.md b/CHANGELOG.md
index affa1ae..a496c35 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
## [Unreleased]
+## [0.22.0] — 2026-10-25
+
+### Added ✨
+
+- `type` (`ticker`, the default, or `kline`) on `submit_backtest` and `submit_sweep`: a strategy that reads
+ candles can now be run from the MCP. A kline run over a `datasetId` needs a ready dataset version of
+ `type=klines`; a kline strategy submitted as a ticker run still ends `FAILED` with the platform's reason.
+ `get_job_status` and `get_equity_curve` take the same `type` for a job this session did not submit, as they
+ take `exchangeId`, because the platform addresses a result by exchange, type and job. A sweep remembers its
+ type for its curves.
+- Build against `sdk-java` 0.35.0.
+
## [0.21.2] — 2026-10-25
### Fixed 🐛
diff --git a/README.md b/README.md
index b713993..9733067 100644
--- a/README.md
+++ b/README.md
@@ -345,11 +345,12 @@ docker run -i --rm -e QTSURFER_APIKEY \
Once `get_dataset_upload` returns `READY`, inspect `type` with `get_dataset`, then submit a run with
`datasetId`; omit `exchangeId` and `instrument`, because MCP derives the reserved `exchangeId=user`.
-`datasetVersionId` pins a prior ready version. A run is prepared as ticker data, which accepts a
-dataset of either type; this tool cannot yet request a kline run, so a strategy that reads kline
-data ends `FAILED` with the platform's reason (the API itself runs kline backtests only over a
-version with `type=klines`). An uploaded version's type is inferred from its rows when ingest
-completes. `equityCurve` is accepted by both run tools and is
+`datasetVersionId` pins a prior ready version. A run is a ticker run unless it says `type: "kline"`,
+which a strategy that reads candles needs: a kline strategy submitted as a ticker run ends `FAILED`
+with the platform's reason. A kline run over a dataset requires the selected ready version to have
+`type=klines`; a ticker run accepts either. `submit_sweep` takes the same `type`, and
+`get_job_status` and `get_equity_curve` take it for a job this session did not submit, as they take
+`exchangeId`. An uploaded version's type is inferred from its rows when ingest completes. `equityCurve` is accepted by both run tools and is
passed through to the API.
### Import market history
diff --git a/pom.xml b/pom.xml
index 632cbe7..6f298f6 100644
--- a/pom.xml
+++ b/pom.xml
@@ -5,7 +5,7 @@
com.qtsurfer
mcp-java
- 0.21.2
+ 0.22.0
jar
qtsurfer-mcp-java
@@ -34,7 +34,7 @@
${java.version}
UTF-8
1.1.2
- 0.34.1
+ 0.35.0
2.0.16
1.5.11
5.11.4
diff --git a/src/main/java/com/qtsurfer/mcp/service/BacktestingService.java b/src/main/java/com/qtsurfer/mcp/service/BacktestingService.java
index 24342b8..cfdbd20 100644
--- a/src/main/java/com/qtsurfer/mcp/service/BacktestingService.java
+++ b/src/main/java/com/qtsurfer/mcp/service/BacktestingService.java
@@ -21,6 +21,7 @@
import com.qtsurfer.api.client.model.LiveSignalPage;
import com.qtsurfer.api.client.model.LiveStreamRevoked;
import com.qtsurfer.api.client.model.LiveStreamUrl;
+import com.qtsurfer.api.client.model.DataSourceType;
import com.qtsurfer.api.client.model.PublicLiveListResponse;
import com.qtsurfer.api.client.model.StartLiveRequest;
import com.qtsurfer.api.client.model.UpdateLiveRequest;
@@ -154,6 +155,19 @@ default String submitBacktest(
*/
Optional getJobStatus(String jobId, String exchangeId);
+ /**
+ * {@link #getJobStatus(String, String)} for a run of the given data type. The platform
+ * addresses a result by exchange, type and job, so a kline run read off the platform needs its
+ * type; a job submitted in this session is answered from local state and the type is unused.
+ * The default ignores the type, which is right for an implementation that holds no platform
+ * state of its own.
+ *
+ * @param type {@link DataSourceType#TICKER} or {@link DataSourceType#KLINE}, as the run was submitted
+ */
+ default Optional getJobStatus(String jobId, String exchangeId, DataSourceType type) {
+ return getJobStatus(jobId, exchangeId);
+ }
+
/**
* Ask the platform to stop a backtest submitted in this session.
*
diff --git a/src/main/java/com/qtsurfer/mcp/service/SdkBacktestingService.java b/src/main/java/com/qtsurfer/mcp/service/SdkBacktestingService.java
index 012bea1..2961758 100644
--- a/src/main/java/com/qtsurfer/mcp/service/SdkBacktestingService.java
+++ b/src/main/java/com/qtsurfer/mcp/service/SdkBacktestingService.java
@@ -6,6 +6,7 @@
import com.qtsurfer.api.client.model.Exchange;
import com.qtsurfer.api.client.model.EquityCurveResult;
import com.qtsurfer.api.client.model.CreateDatasetRequest;
+import com.qtsurfer.api.client.model.DataSourceType;
import com.qtsurfer.api.client.model.Dataset;
import com.qtsurfer.api.client.model.DatasetCreated;
import com.qtsurfer.api.client.model.DatasetImportCreated;
@@ -255,7 +256,7 @@ static boolean isCancellation(Throwable error) {
}
/** Session provenance required to address a retained curve through the SDK. */
- private record SessionSweep(Sweep sweep, String exchangeId) {}
+ private record SessionSweep(Sweep sweep, String exchangeId, DataSourceType type) {}
public SdkBacktestingService(AuthenticatedClient qts, String baseUrl) {
this(qts, baseUrl, null, null);
@@ -552,10 +553,15 @@ public String submitBacktest(BacktestRequest sdkRequest) {
@Override
public Optional getJobStatus(String jobId, String exchangeId) {
+ return getJobStatus(jobId, exchangeId, DataSourceType.TICKER);
+ }
+
+ @Override
+ public Optional getJobStatus(String jobId, String exchangeId, DataSourceType type) {
SessionJob job = jobs.get(jobId);
if (job == null) {
if (exchangeId == null || exchangeId.isBlank()) return Optional.empty();
- return fromPlatform(jobId, exchangeId);
+ return fromPlatform(jobId, exchangeId, type == null ? DataSourceType.TICKER : type);
}
ResultMap sdkResult = job.resultRef().get();
JobResult result = sdkResult != null ? toJobResult(sdkResult) : null;
@@ -578,18 +584,19 @@ public Optional getJobStatus(String jobId, String exchangeId) {
* carries no status code, so an unrecognised pair and a backend failure cannot be told apart
* from the response — the message names both possibilities rather than guessing one.
*
- * @throws RuntimeException when the platform does not answer for this job and exchange
+ * @throws RuntimeException when the platform does not answer for this job, exchange and type
*/
- private Optional fromPlatform(String jobId, String exchangeId) {
+ private Optional fromPlatform(String jobId, String exchangeId, DataSourceType type) {
BacktestOutcome outcome;
try {
- outcome = qts.getBacktestResult(exchangeId, jobId);
+ outcome = qts.getBacktestResult(exchangeId, type, jobId);
} catch (Exception e) {
throw new RuntimeException(
"The platform did not return job " + jobId + " on exchange " + exchangeId
- + ". A result is addressed by both, so either the job id is unknown or the"
- + " exchange is the wrong one — an id carried to the wrong exchange does not"
- + " name the same run. Details: " + rootMessage(e), e);
+ + " as a " + type.getValue() + " run. A result is addressed by exchange, type and job,"
+ + " so either the job id is unknown, or the exchange or the type is the wrong one —"
+ + " an id carried to the wrong exchange or type does not name the same run."
+ + " Details: " + rootMessage(e), e);
}
JobStatus status;
if (outcome instanceof BacktestOutcome.Completed) {
@@ -686,7 +693,7 @@ public ExecuteSweepAccepted submitSweep(SweepRequest request) {
} catch (Exception e) {
throw new RuntimeException("Sweep submission failed: " + rootMessage(e), e);
}
- sweeps.put(sweep.id(), new SessionSweep(sweep, request.exchangeId()));
+ sweeps.put(sweep.id(), new SessionSweep(sweep, request.exchangeId(), request.type()));
log.info("Submitted sweep {} ({} {} {} → {})", sweep.id(),
request.exchangeId(), request.instrument(), request.from(), request.to());
return sweep.getAccepted();
@@ -706,7 +713,7 @@ public Optional getSweepRunEquityCurve(
if (sessionSweep == null) return Optional.empty();
Sweep sweep = sessionSweep.sweep();
return Optional.of(qts.getBoundedSweepRunEquityCurve(
- sessionSweep.exchangeId(), sweep.requestId(), sweepId, runIx, maxResample));
+ sessionSweep.exchangeId(), sessionSweep.type(), sweep.requestId(), sweepId, runIx, maxResample));
}
@Override
diff --git a/src/main/java/com/qtsurfer/mcp/tool/McpTools.java b/src/main/java/com/qtsurfer/mcp/tool/McpTools.java
index 13b959c..9cb5f98 100644
--- a/src/main/java/com/qtsurfer/mcp/tool/McpTools.java
+++ b/src/main/java/com/qtsurfer/mcp/tool/McpTools.java
@@ -8,6 +8,7 @@
import com.qtsurfer.mcp.McpServerRunner;
import com.qtsurfer.api.client.model.Exchange;
import com.qtsurfer.api.client.invoker.ApiClient;
+import com.qtsurfer.api.client.model.DataSourceType;
import com.qtsurfer.api.client.model.DatasetImportRequest;
import com.qtsurfer.api.client.model.DatasetImportCexRequest;
import com.qtsurfer.api.client.model.DatasetImportDexRequest;
@@ -650,14 +651,15 @@ private static SyncToolSpecification submitBacktest(BacktestingService service)
.description("Compile a Java strategy and queue a backtesting run on QTSurfer. "
+ "Returns the job ID immediately — poll with get_job_status. "
+ "Provide either exchangeId plus instrument, or datasetId (the server derives exchangeId=user). "
- + "A run is prepared as ticker data and a dataset of either type is accepted for it; this tool "
- + "cannot request a kline run, so a strategy that reads kline data ends FAILED with the platform's reason. "
+ + "Set type=kline for a strategy that reads candles; the default, ticker, is for one that reads "
+ + "trades. A kline strategy submitted as a ticker run ends FAILED with the platform's reason, and a "
+ + "kline run over a datasetId needs a ready dataset version of type=klines (a ticker run accepts either). "
+ "Set storeSignals only for selected runs that need emitted signals: it is disabled by default "
+ "and retained signals consume the account's storage quota. "
+ "To try the same strategy at many parameter settings, use submit_sweep instead of "
+ "calling this in a loop.")
.inputSchema(schema(
- Map.of(
+ mapOf(
"strategyCode", prop("string",
"Complete Java source of the strategy class to compile and run"),
"exchangeId", prop("string",
@@ -670,7 +672,8 @@ private static SyncToolSpecification submitBacktest(BacktestingService service)
"to", prop("string", "Backtest end date, ISO-8601 (e.g. 2024-03-31)"),
"params", prop("object", "Optional scalar strategy properties for this one run; values are numbers, strings, or booleans"),
"storeSignals", prop("boolean", "Optional, false by default. Retain emitted signals for this run; consumes storage quota"),
- "equityCurve", prop("object", "Optional {resample,differential,outMode}; outMode is array, short or url")),
+ "equityCurve", prop("object", "Optional {resample,differential,outMode}; outMode is array, short or url"),
+ "type", dataTypeProp()),
List.of("strategyCode", "from", "to")))
.build();
return new SyncToolSpecification(tool,
@@ -680,6 +683,7 @@ private static SyncToolSpecification submitBacktest(BacktestingService service)
BacktestRequest.Builder builder = BacktestRequest.builder()
.strategy(required(args, "strategyCode")).from(required(args, "from")).to(required(args, "to"));
configureBacktestSource(builder, args);
+ builder.type(parseDataType(args));
Map params = parseBacktestParams(args.get("params"));
if (!params.isEmpty()) builder.params(params);
if (args.containsKey("storeSignals")) builder.storeSignals(optionalBoolean(args, "storeSignals", false));
@@ -717,6 +721,9 @@ private static SyncToolSpecification getJobStatus(BacktestingService service) {
"exchangeId", prop("string",
"Exchange the run was submitted against. Only needed for a job this session "
+ "did not submit; ignored for one it did."),
+ "type", prop("string",
+ "ticker (the default) or kline: the type the run was submitted with. Only needed "
+ + "for a job this session did not submit, like exchangeId; ignored for one it did."),
"includeEquityCurve", prop("boolean",
"When true, append the equity curve (downsampled) to the result. Default false.")),
List.of("jobId")))
@@ -728,7 +735,7 @@ private static SyncToolSpecification getJobStatus(BacktestingService service) {
String exchangeId = optional(args, "exchangeId");
boolean includeCurve = asBool(args == null ? null : args.get("includeEquityCurve"));
try {
- return service.getJobStatus(jobId, exchangeId)
+ return service.getJobStatus(jobId, exchangeId, parseDataType(args))
.map(j -> {
String body = formatJobStatus(j.jobId(), j.instrument(), j.exchangeId(),
j.status(), j.submittedAt(), j.result(), j.retryable(), j.statusDetail());
@@ -756,10 +763,11 @@ private static String jobNotFound(String jobId, String exchangeId) {
return "Job " + jobId + " was not submitted in this session, and no exchangeId was given, "
+ "so the platform could not be asked: a backtest result is addressed by exchange as "
+ "well as job id. Call again with exchangeId set to the exchange the run was submitted "
- + "against (e.g. 'binance') to look it up directly.";
+ + "against (e.g. 'binance') to look it up directly; a kline run also needs type='kline'.";
}
return "Job " + jobId + " was not submitted in this session and the platform returned nothing "
- + "for it on exchange " + exchangeId + ".";
+ + "for it on exchange " + exchangeId + ". A run is addressed by exchange, type and job id: "
+ + "if it was submitted with type=kline, pass type='kline'.";
}
// ---- cancel_backtest ------------------------------------------------------
@@ -810,6 +818,9 @@ private static SyncToolSpecification getEquityCurve(BacktestingService service)
"exchangeId", prop("string",
"Exchange the run was submitted against. Only needed for a job this session "
+ "did not submit; ignored for one it did."),
+ "type", prop("string",
+ "ticker (the default) or kline: the type the run was submitted with. Only needed "
+ + "for a job this session did not submit, like exchangeId; ignored for one it did."),
"maxPoints", prop("integer", "Max points to return (default " + DEFAULT_MAX_POINTS
+ ", max " + MAX_POINTS_LIMIT + "). The curve is downsampled if longer.")),
List.of("jobId")))
@@ -820,7 +831,13 @@ private static SyncToolSpecification getEquityCurve(BacktestingService service)
String jobId = required(args, "jobId");
String exchangeId = optional(args, "exchangeId");
int maxPoints = clamp(asInt(args.get("maxPoints"), DEFAULT_MAX_POINTS), 1, MAX_POINTS_LIMIT);
- var summary = service.getJobStatus(jobId, exchangeId);
+ DataSourceType type;
+ try {
+ type = parseDataType(args);
+ } catch (IllegalArgumentException e) {
+ return error(e.getMessage());
+ }
+ var summary = service.getJobStatus(jobId, exchangeId, type);
if (summary.isEmpty()) {
return text(jobNotFound(jobId, exchangeId));
}
@@ -913,6 +930,7 @@ private static SyncToolSpecification submitSweep(BacktestingService service) {
"datasetVersionId", prop("string", "Optional historical version of datasetId"),
"from", prop("string", "Sweep window start, ISO-8601 (e.g. 2024-01-01)"),
"to", prop("string", "Sweep window end, ISO-8601 (e.g. 2024-03-31)"),
+ "type", dataTypeProp(),
"params", Map.of(
"type", "object",
"description", "The grid: one axis per strategy property to vary, at least one. "
@@ -957,6 +975,7 @@ private static SyncToolSpecification submitSweep(BacktestingService service) {
.to(required(args, "to"))
.params(parseParams(args.get("params")));
configureSweepSource(builder, args);
+ builder.type(parseDataType(args));
String objective = optional(args, "objective");
if (objective != null) builder.objective(parseObjective(objective));
String sampler = optional(args, "sampler");
@@ -2239,6 +2258,25 @@ private static void configureSweepSource(SweepRequest.Builder builder, Map dataTypeProp() {
+ return prop("string",
+ "ticker (the default) for a strategy that reads trades, kline for one that reads candles. "
+ + "A kline run over a datasetId needs a ready dataset version of type=klines; a ticker run "
+ + "accepts either.");
+ }
+
+ /** The data type a tool call names; ticker when it names none. */
+ private static DataSourceType parseDataType(Map args) {
+ String raw = optional(args, "type");
+ if (raw == null) return DataSourceType.TICKER;
+ return switch (raw.toLowerCase(Locale.ROOT)) {
+ case "ticker" -> DataSourceType.TICKER;
+ case "kline" -> DataSourceType.KLINE;
+ default -> throw new IllegalArgumentException("type must be ticker or kline, got '" + raw + "'");
+ };
+ }
+
private static EquityCurveOptions parseBacktestCurve(Object raw) {
Map values = objectMap(raw, "equityCurve");
if (values == null) return null;
diff --git a/src/test/java/com/qtsurfer/mcp/tool/McpToolsTest.java b/src/test/java/com/qtsurfer/mcp/tool/McpToolsTest.java
index 392cf31..c3fc7e8 100644
--- a/src/test/java/com/qtsurfer/mcp/tool/McpToolsTest.java
+++ b/src/test/java/com/qtsurfer/mcp/tool/McpToolsTest.java
@@ -5,6 +5,7 @@
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.TextContent;
import com.qtsurfer.mcp.model.EquityPoint;
+import com.qtsurfer.api.client.model.DataSourceType;
import com.qtsurfer.mcp.model.DatasetImportStatus;
import com.qtsurfer.mcp.model.DatasetSummary;
import com.qtsurfer.mcp.model.JobResult;
@@ -469,6 +470,110 @@ public Optional getJobStatus(String jobId, String exchangeId) {
.contains("Retryable: true");
}
+ // ---- the data type of a run ---------------------------------------------------------
+
+ /** Records the request each submit tool hands to the service. */
+ private static final class RecordingStub extends BacktestingServiceStub {
+ com.qtsurfer.api.sdk.BacktestRequest backtest;
+ com.qtsurfer.api.sdk.SweepRequest sweep;
+ String statusExchange;
+ DataSourceType statusType;
+
+ @Override
+ public String submitBacktest(com.qtsurfer.api.sdk.BacktestRequest request) {
+ backtest = request;
+ return super.submitBacktest(request);
+ }
+
+ @Override
+ public com.qtsurfer.api.client.model.ExecuteSweepAccepted submitSweep(com.qtsurfer.api.sdk.SweepRequest request) {
+ sweep = request;
+ return super.submitSweep(request);
+ }
+
+ @Override
+ public Optional getJobStatus(String jobId, String exchangeId, DataSourceType type) {
+ statusExchange = exchangeId;
+ statusType = type;
+ return super.getJobStatus(jobId, exchangeId);
+ }
+ }
+
+ private static final String STRATEGY = "public class S extends AbstractTickerStrategy {}";
+
+ @Test
+ void submitBacktestIsATickerRunUnlessItAsksForKline() {
+ RecordingStub stub = new RecordingStub();
+ var server = McpTools.build(stub, "https://api.qtsurfer.net/v1");
+
+ callText(server, "submit_backtest", Map.of("strategyCode", STRATEGY, "exchangeId", "binance",
+ "instrument", "BTC/USDT", "from", "2026-08-01", "to", "2026-08-02"));
+ assertThat(stub.backtest.type()).isEqualTo(DataSourceType.TICKER);
+
+ callText(server, "submit_backtest", Map.of("strategyCode", STRATEGY, "datasetId", "ds_1",
+ "from", "2026-08-01", "to", "2026-08-02", "type", "kline"));
+ assertThat(stub.backtest.type()).isEqualTo(DataSourceType.KLINE);
+ assertThat(stub.backtest.exchangeId()).isEqualTo("user");
+
+ callText(server, "submit_backtest", Map.of("strategyCode", STRATEGY, "datasetId", "ds_1",
+ "from", "2026-08-01", "to", "2026-08-02", "type", "KLINE"));
+ assertThat(stub.backtest.type()).as("the name is not case-sensitive").isEqualTo(DataSourceType.KLINE);
+ }
+
+ @Test
+ void submitBacktestRefusesATypeItCannotRun() {
+ RecordingStub stub = new RecordingStub();
+ String text = callText(McpTools.build(stub, "https://api.qtsurfer.net/v1"), "submit_backtest",
+ Map.of("strategyCode", STRATEGY, "exchangeId", "binance", "instrument", "BTC/USDT",
+ "from", "2026-08-01", "to", "2026-08-02", "type", "funding"));
+
+ assertThat(text).contains("type must be ticker or kline").contains("funding");
+ assertThat(stub.backtest).as("nothing was submitted").isNull();
+ }
+
+ @Test
+ void submitSweepTakesTheSameType() {
+ RecordingStub stub = new RecordingStub();
+ var server = McpTools.build(stub, "https://api.qtsurfer.net/v1");
+ Map grid = Map.of("multiplier", Map.of("values", List.of(2, 3)));
+
+ callText(server, "submit_sweep", Map.of("strategyCode", STRATEGY, "datasetId", "ds_1",
+ "from", "2026-08-01", "to", "2026-08-02", "params", grid));
+ assertThat(stub.sweep.type()).isEqualTo(DataSourceType.TICKER);
+
+ callText(server, "submit_sweep", Map.of("strategyCode", STRATEGY, "datasetId", "ds_1",
+ "from", "2026-08-01", "to", "2026-08-02", "params", grid, "type", "kline"));
+ assertThat(stub.sweep.type()).isEqualTo(DataSourceType.KLINE);
+ }
+
+ @Test
+ void aRunFromAnotherSessionIsReadByItsType() {
+ RecordingStub stub = new RecordingStub();
+ var server = McpTools.build(stub, "https://api.qtsurfer.net/v1");
+
+ callText(server, "get_job_status", Map.of("jobId", "j1", "exchangeId", "user", "type", "kline"));
+ assertThat(stub.statusType).isEqualTo(DataSourceType.KLINE);
+ assertThat(stub.statusExchange).isEqualTo("user");
+
+ callText(server, "get_job_status", Map.of("jobId", "j1", "exchangeId", "user"));
+ assertThat(stub.statusType).as("a ticker read unless told otherwise").isEqualTo(DataSourceType.TICKER);
+
+ callText(server, "get_equity_curve", Map.of("jobId", "j1", "exchangeId", "user", "type", "kline"));
+ assertThat(stub.statusType).isEqualTo(DataSourceType.KLINE);
+ }
+
+ @Test
+ void theReadToolsRefuseATypeTheyCannotAddress() {
+ RecordingStub stub = new RecordingStub();
+ var server = McpTools.build(stub, "https://api.qtsurfer.net/v1");
+
+ assertThat(callText(server, "get_job_status", Map.of("jobId", "j1", "exchangeId", "user", "type", "x")))
+ .contains("type must be ticker or kline");
+ assertThat(callText(server, "get_equity_curve", Map.of("jobId", "j1", "exchangeId", "user", "type", "x")))
+ .contains("type must be ticker or kline");
+ assertThat(stub.statusType).as("nothing was read").isNull();
+ }
+
@Test
void getDatasetImportReportsWhyAReadFailedInsteadOfNotFound() {
BacktestingServiceStub stub = new BacktestingServiceStub() {