trader-mcp/AGENTS.md

AGENTS.md

Role

TRADER-MCP is a strategy runtime.

It executes multiple independent trading strategies and converts their outputs into execution intents for exec-mcp.

---

Architecture

TRADER-MCP is structured in three layers:

1. Strategy Layer

   • runs pluggable strategies (grid, mean reversion, etc.)
   • produces trade intents

2. Runtime Layer

   • manages lifecycle of strategies (start/stop/configure)
   • isolates strategies from each other

3. Execution Layer

   • translates intents into exec-mcp commands
   • ensures format correctness

---

Control Authority

• hermes-mcp controls:

  • which strategies are active
  • strategy parameters
  • global risk posture

• trader-mcp must obey all hermes control signals

• trader-mcp must NOT override or reinterpret them

---

Core Invariants

• strategies are independent units
• no strategy may access others’ internal state
• trader-mcp does not define market stance
• execution is derived only from strategy outputs + Hermes constraints

---

Boundary Rules

• NO strategy selection logic (belongs to Hermes)
• NO direct exchange access
• NO market-data-driven decision making outside strategies
• NO cross-strategy coupling

Strategy Notes

• See strategies/AGENTS.md for shared strategy-folder rules and strategy-specific notes such as grid_trader shape and rebuild behavior.

Wiki References

• Trader MCP for the project-level overview.
• Grid Trader for the full-grid rebuild contract.
• Dumb Trader for the side-only execution contract.
• Trend Follower for the compatibility alias.
• Exposure Protector for the defensive rebalancing contract.
• Grid Trading, Mean Reversion, Inventory Rebalancing, and Side-Only Execution for the underlying concepts.

---

Failure Model

• strategy failures must be isolated
• system must continue running unaffected strategies
• invalid outputs must be rejected, not corrected silently

---

Local Environment

• before claiming a Python dependency is missing, source the repo-local .venv
• prefer running Python, pytest, and helper scripts through the activated .venv

Runtime Trace Inspection

• grid_trader does not write reseed events into a separate database table.
• The strategy appends trace lines to state["debug_log"] in strategies/grid_trader.py::_log(), and src/trader_mcp/strategy_engine.py::tick_strategy() persists that state into data/trader_mcp.sqlite3 via strategy_instances.state_json.
• To inspect a running instance's trace from the DB, read strategy_instances.state_json for the target strategy id and extract debug_log.
• The live file log is logs/trader_mcp.log; src/trader_mcp/logging_utils.py::log_event() writes the same grid ... messages there.

---

Interface Stability

Changes affecting:

• Hermes control signals
• execution intent format

are breaking and must be coordinated across MCPs.