Skip to main content
Glama
roman-zaglauer

OctoBot MCP Server

by roman-zaglauer
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Local

start_data_collection

Start a background OctoBot historical data collection job for a specified exchange and symbols, returning a job ID immediately. Poll job status to monitor progress and retrieve the resulting data files.

Instructions

Start a real OctoBot historical data collection run in the background and return immediately.

Not confirm-gated (ADR-0003/tool spec): starts a background download, never touches live trading, destroys no data, exposes no credentials -- same reasoning as start_backtest. Maps to POST /data_collector ?action_type=start_collector [V]. symbols must be non-empty. time_frames is optional (OctoBot collects its own default set when omitted). start_timestamp/end_timestamp are optional epoch milliseconds (confirmed both live and from source this session -- see this module's docstring).

To discover valid exchange/symbols values, use the existing get_all_symbols(exchange) tool (confirmed this session to return data identical to OctoBot's own data-collector-scoped symbol list, per FR-27 -- no separate get_available_symbols_for_collection tool exists here for that reason). For time_frames, use this module's own get_available_timeframes_for_collection(exchange).

Behavior (ADR-0007): creates a kind: "data_collection" job, acquires JobStore.data_collection_execution_lock -- a lock INDEPENDENT of backtest_execution_lock (NFR-15): a concurrent start_backtest + start_data_collection never block each other, but two concurrent start_data_collection calls do serialize (queueing, same as two concurrent backtests) -- then submits the start action and spawns a background watcher connecting to OctoBot's /data_collector Socket.IO namespace, mirroring start_backtest's watcher exactly (this session's own live round-trip confirmation is recorded in this module's docstring).

Output: {"job_id": str, "state": "queued"} -- always "queued" immediately (the background watcher has not yet run at all). Poll get_job_status(job_id) for progress_percent/eta_seconds; get_job_result(job_id) once state == "completed" returns {"exchange", "symbols", "time_frames", "start_timestamp", "end_timestamp", "message"} -- deliberately NO resulting filename (OctoBot itself names none anywhere in this flow, confirmed this session): call list_data_files() afterward to find the new file.

A confirmed OctoBot-side limitation, not a bug in this tool: a collection submitted for a nonexistent/invalid exchange name returns the SAME success response and the SAME "finished" status as a genuinely successful run (confirmed live this session, resolving open question #11) -- if list_data_files() doesn't show the expected new file after a "completed" job, the exchange/symbol/timeframe combination was likely invalid upstream, not a failure this server could have detected sooner. A collection that never progresses at all (staleness, NFR-3) is a separate, detectable case: its eta_confidence will show "low"/eta_seconds: null and it should be cancelled via cancel_job.

Supports progressToken (ADR-0002 decision point 3, reused via octobot_mcp.tools._shared._attach_progress_notifier) exactly like start_backtest.

Errors: DataCollectionStartFailedError wrapping OctoBot's own failure text -- confirmed messages include "Backtesting is disabled.", "Please select an exchange.", "Please select a trading pair.", any of _ensure_backtesting_limits's three possible messages (see this module's docstring -- source-confirmed text, not guessed), and "Can't collect data for {symbols} on {exchange} (Historical data collector is already running)" for OctoBot's own one-at-a-time guard. Raised from the background watcher (not this function), surfacing as the job's errors/state="failed" via get_job_status -- this function itself only raises synchronously for input validation caught before any job is created.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
symbolsYes
exchangeYes
time_framesNo
end_timestampNo
start_timestampNo

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full disclosure burden, and it does so thoroughly. It covers background execution, immediate return, lock semantics, watcher behavior, error propagation, known OctoBot-side limitations, and cancellation signals. There is no contradiction with annotations because none exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and is well-structured with clear sections. It is quite long and contains repeated references to session confirmations and docstrings that could be tightened, but the density of useful behavioral information justifies most of the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description provides a complete operational picture: immediate output shape, asynchronous job lifecycle, polling endpoints, final result contents, error messages, cancellation path, and a known upstream failure mode. An agent has everything it needs to invoke and monitor this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does. It explains that symbols must be non-empty, time_frames is optional with OctoBot's default set, start/end_timestamp are optional epoch milliseconds, and exchange values should be discovered via get_all_symbols. This adds meaning well beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Start a real OctoBot historical data collection run in the background and return immediately.' It clearly distinguishes this from backtesting, references the exact endpoint, and makes the tool's scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent how to discover valid values via get_all_symbols and get_available_timeframes_for_collection, when to poll get_job_status, when to read get_job_result, and when to cancel via cancel_job. It also clarifies the concurrency relationship with start_backtest, so an agent knows when this tool is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools