WorkBuddy-QMT Bridge

A native, fail-closed trading bridge between WorkBuddy/MCP and the Python built into QMT.

Important Risk Notice

This project can trigger orders on simulated or real-money accounts. It is not investment advice and does not guarantee profit. The default mode is OBSERVE_ONLY. Any real-money deployment must first complete on-site acceptance of the target QMT version, broker counter, account fields, order returns, order cancellation, and recovery flows. The example mappings in the repository cannot be used directly for live trading.

Current Version

• Version: 0.3.0

• Phase: P1 LIMITED_AUTO software control surface complete

• MCP tools: 29

• Python: Worker requires 3.10 or higher

• QMT Adapter: compatible with the Python 3.6 environment built into QMT

• Runtime boundary: binds to 127.0.0.1 only, no dependency on xtquant

Project homepage: https://github.com/peppaboar95/workbuddy-qmt-bridge

"P1 complete" only means that the software-side structured authorization, quota reservation, state machine, circuit breaker, and Adapter re-verification have been implemented and passed local tests. It does not mean that any real-money counter has been accepted.

Related MCP server: lighter-mcp

Four Modes

SIM_SIGNAL is not "only generates signals but does not place orders." If it is incorrectly connected to a real-money counter, it can still call passorder, so the account and counter must be manually verified.

Security Design

• Two-phase commit with preview_trade and submit_trade_intent;

• Full hard risk control is re-executed at submission time and the risk decision fingerprint is compared;

• Both the Worker and the QMT Adapter check the account, mode, signature, TTL, and authorization generation;

• LIMITED_AUTO licenses are bound to account, security, action, strategy/rule version, trading window, order type, and multi-layer quotas;

• Quotas are atomically reserved, limiting per-order, cumulative amount, order count, frequency, concurrency, position exposure, drawdown, and consecutive failures;

• PRE_SUBMIT or SUBMIT_CALLED states are never automatically re-sent; unknown results remain SUBMIT_UNKNOWN;

• After a circuit breaker trip, recovery can only be done locally and safely returns to OBSERVE_ONLY;

• Credit auto-trading is off by default; new credit liabilities require additional explicit permission and on-site acceptance.

Installation

Regular users should first download the installation ZIP, the individual ZIP hash, and the total hash manifest from GitHub Releases:

• workbuddy-qmt-bridge-0.3.0.zip

• workbuddy-qmt-bridge-0.3.0.zip.sha256

• SHA256SUMS.txt

After verifying the hashes, unzip the ZIP and double-click "首次安装与配置.cmd". If you need to install the wheel manually, download:

• workbuddy_qmt_bridge-0.3.0-py3-none-any.whl

Windows PowerShell:

python -m pip install .\workbuddy_qmt_bridge-0.3.0-py3-none-any.whl
workbuddy-qmt setup

Development install from source:

git clone https://github.com/peppaboar95/workbuddy-qmt-bridge.git
cd workbuddy-qmt-bridge
python -m pip install -e .

From Read-Only to Trading

1. Run setup to create local configuration, keys, Worker token, and account isolation directories;

2. Deploy the generated qmt_adapter.py and qmt_adapter.json to the corresponding QMT strategy instance;

3. Stay in OBSERVE_ONLY and complete heartbeat, account, position, order, fill, and market data field collection;

4. Complete P0 mapping verification on the target simulated counter and sign the Profile;

5. In SIM_SIGNAL, verify minimum quantity, order placement, fills, order cancellation, restart, and unknown-result recovery;

6. For real-money scenarios, first use MANUAL_LIVE for small-amount acceptance;

7. Only create a LIMITED_AUTO P1 license when readiness has no blocking issues and the strategy boundary is clear.

The 1–60 minute time authorization in MANUAL_LIVE only waives per-order manual approval; every order must still be re-synced, previewed, and pass hard risk control. The LIMITED_AUTO license lasts at most 720 minutes, cannot cross trading days, and is constrained by the full strategy boundary and cumulative budget.

LIMITED_AUTO P1 Flow

1. Locally switch the Worker and the corresponding Adapter to LIMITED_AUTO;

2. Call check_limited_auto_readiness to confirm that the queue, snapshot, heartbeat, dead letters, and SUBMIT_UNKNOWN have no blocking issues;

3. Present the full license policy to the operator and call authorize_limited_auto after explicit confirmation;

4. Automated tasks continue to perform sync, preview, and submit for each trade;

5. Use get_limited_auto_status to observe remaining time, order count, amount budget, and pause reasons;

6. When health, drawdown, or consecutive-failure guards trigger, pause automatically; after conditions recover, only an explicit resume_limited_auto can resume;

7. Call revoke_limited_auto when finished. Revoking the license does not automatically cancel orders already placed on the broker side.

Verified and Not Yet Verified

Local incremental tests in this version cover:

• schema v1 to v2 migration;

• structured P1 license;

• preview, submit, and atomic quota reservation;

• strategy version binding;

• pause, resume, and authorization generation rotation;

• Adapter tamper-evident re-verification.

Still to be completed against the target environment:

• real QMT and broker build capability matrix;

• order, fill, remark, and cancellation returns from a real-money counter;

• Windows ACL, backup, recovery, and SUBMIT_UNKNOWN drills;

• six types of credit account actions, field dimensions, eligibility, quota, and liability rules;

• small-amount manual live acceptance.

Data and Privacy

runtime, database, WAL/SHM, logs, queues, execution logs, signed Profiles, keys, Worker tokens, account numbers, and local MCP configuration must not be committed to the repository or attached to Issues. Diagnostic materials must be desensitized first.

Documentation

• Release and installation: docs/README-RELEASE.zh-CN.md

• P1 validation notes: docs/P1-VALIDATION.zh-CN.md

• Configuration examples: examples/README.md

• Security policy: SECURITY.md

License

This project is licensed under the MIT License. See LICENSE for details.