Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 🐛
Expand Down
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

<groupId>com.qtsurfer</groupId>
<artifactId>mcp-java</artifactId>
<version>0.21.2</version>
<version>0.22.0</version>
<packaging>jar</packaging>
<name>qtsurfer-mcp-java</name>

Expand Down Expand Up @@ -34,7 +34,7 @@
<maven.compiler.release>${java.version}</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<mcp.version>1.1.2</mcp.version>
<sdk.version>0.34.1</sdk.version>
<sdk.version>0.35.0</sdk.version>
<slf4j.version>2.0.16</slf4j.version>
<logback.version>1.5.11</logback.version>
<junit.version>5.11.4</junit.version>
Expand Down
14 changes: 14 additions & 0 deletions src/main/java/com/qtsurfer/mcp/service/BacktestingService.java
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -154,6 +155,19 @@ default String submitBacktest(
*/
Optional<JobSummary> 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<JobSummary> getJobStatus(String jobId, String exchangeId, DataSourceType type) {
return getJobStatus(jobId, exchangeId);
}

/**
* Ask the platform to stop a backtest submitted in this session.
*
Expand Down
27 changes: 17 additions & 10 deletions src/main/java/com/qtsurfer/mcp/service/SdkBacktestingService.java
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -552,10 +553,15 @@ public String submitBacktest(BacktestRequest sdkRequest) {

@Override
public Optional<JobSummary> getJobStatus(String jobId, String exchangeId) {
return getJobStatus(jobId, exchangeId, DataSourceType.TICKER);
}

@Override
public Optional<JobSummary> 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;
Expand All @@ -578,18 +584,19 @@ public Optional<JobSummary> 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<JobSummary> fromPlatform(String jobId, String exchangeId) {
private Optional<JobSummary> 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) {
Expand Down Expand Up @@ -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();
Expand All @@ -706,7 +713,7 @@ public Optional<BoundedEquityCurve> 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
Expand Down
54 changes: 46 additions & 8 deletions src/main/java/com/qtsurfer/mcp/tool/McpTools.java
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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",
Expand All @@ -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,
Expand All @@ -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<String, Object> params = parseBacktestParams(args.get("params"));
if (!params.isEmpty()) builder.params(params);
if (args.containsKey("storeSignals")) builder.storeSignals(optionalBoolean(args, "storeSignals", false));
Expand Down Expand Up @@ -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")))
Expand All @@ -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());
Expand Down Expand Up @@ -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 ------------------------------------------------------
Expand Down Expand Up @@ -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")))
Expand All @@ -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));
}
Expand Down Expand Up @@ -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. "
Expand Down Expand Up @@ -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");
Expand Down Expand Up @@ -2239,6 +2258,25 @@ private static void configureSweepSource(SweepRequest.Builder builder, Map<Strin
}
}

/** The schema entry for the kind of data a submitted run reads. */
private static Map<String, Object> 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<String, Object> 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<String, Object> values = objectMap(raw, "equityCurve");
if (values == null) return null;
Expand Down
Loading
Loading