exec-mcp/AGENTS.md

AGENTS.md

Scope

exec-mcp is the execution layer for Trader27. It owns exchange access, account metadata, balances, fees, market metadata, order placement, order lookup, and cancel flows.

How To Run

• Start the service with ./run.sh
• Restart with ./restart.sh
• Stop listeners with ./killserver.sh
• Run tests with ./tests.sh
• GET /health is the runtime health probe used by Docker

run.sh uses uvicorn app:app and will source .venv/bin/activate if present.

Code Boundaries

• Keep secrets in account_secrets; never expose them through dashboard or MCP responses.
• Keep account metadata and order lifecycle logic in repo.py, services_bitstamp.py, and services_orders.py.
• Keep Bitstamp-specific client behavior in bitstamp.py and websocket handling in bitstamp_private_ws.py.
• Keep schema changes compatible with the non-destructive bootstrap in storage.py.

Runtime Contracts

• venue_account_ref is the exchange-side account reference shown in the dashboard.
• client_id is optional on orders, stored locally, and used to filter open orders and recover tracked state.
• Bitstamp client instances are cached per account, and nonce generation must remain monotonic per credential scope.
• Background tasks refresh Bitstamp metadata and EUR/USD data, and the private websocket updates local order records.
• Public discovery tools should stay read-only; order placement and cancel paths are the execution surface.
• Reporting tools are snapshot-only: recent trades default to filled, support cancelled and all, and balance reporting reads stored balance_snapshots.

Editing Rules

• Prefer small, targeted changes.
• Do not invent new architecture or strategy semantics.
• When changing runtime behavior, update the relevant tests and docs in the same patch.
• If a test or cleanup path depends on the local SQLite DB, use a temp DB in tests instead of mutating shared state.
• For Docker runs, keep /app/data mounted so the SQLite file survives restarts.

Files To Read First

• README.md
• PROJECT.md
• src/exec_mcp/server.py
• src/exec_mcp/services_orders.py
• src/exec_mcp/services_bitstamp.py
• src/exec_mcp/bitstamp.py
• src/exec_mcp/storage.py