Senti-MCP: Instructions file for Codex

AGENTS.md — senti-mcp-server

This file is the single source of truth for all AI agent instructions in this project. Cursor, Gemini, Codex CLI, Copilot CLI, and Claude Code all read it. CLAUDE.md is a thin pointer back to this file plus the Koni-Docs Integration block; on any conflict, this file wins.

Project purpose

An MCP server that lets a user's AI agent read and interact with Senti Quant through its Public API.

The API — https://api.sentitrade.xyz, OpenAPI 3.1 at /api/v1/openapi.json — exposes 29 operations across 22 paths, tagged Accounts, Brokers, Strategies, Performance, Trading, and Authoring. An MCP host cannot call it directly: something has to own the API key, present typed tools whose descriptions let a model choose correctly, and turn API errors into text a model can act on. This server is that something.

Current state: 2.9.0. 1.0.0 is the stable-surface cut and is tagged git-only; 1.0.1 is the version that carried it to the registry (CONTEXT D11, D12). Fourteen read tools are registered unconditionally in src/server.ts, and seven write tools — create_draft, update_draft, delete_draft, add_draft_attachment, update_draft_attachment, delete_draft_attachment and compile_draft — are registered only when SENTI_ENABLE_AUTHORING_WRITE is set, so a host that does not opt in sees the same fourteen it saw in 2.4.0. That closes EPIC-8: seven of the Authoring tag's eight write operations have a tool, register being the deliberate exception. The read tools: get_authoring_conventions, list_drafts, get_draft, list_draft_attachments, list_accounts, list_brokers, list_strategies, list_account_strategies, list_positions, list_pending_orders, list_deals, get_account_performance, get_performance_breakdowns, get_equity_timeseries — all 14 of the API's GET operations now have a tool, closing EPIC-7. list_accounts shipped first, in v0.1.0, tracked as US-2.2 and proven against the live API by US-2.3; the next five closed out sprint-2026-W33's Phase 1, tracked as US-2.4 through US-2.9; Phase 3 added the last four — get_account_performance in 1.1.0 (US-2.10), list_deals in 1.2.0 (US-2.11, the first paginated tool — one call is one request, and it never drains a cursor: CONTEXT D24), get_performance_breakdowns in 1.3.0 (US-2.12, the first tool that returns materially less than the API gave it — five cuts, and a notes line only for the two that lose something: CONTEXT D25), and get_equity_timeseries in 1.4.0 (US-2.13, whose downsample pins the first point, the last point and the deepest drawdown, ranked by magnitude because the API never declares the sign: CONTEXT D26). EPIC-2 closed done on 2026-08-12 with the read path complete — complete against the API as it stood that day. The API has since grown a new Authoring tag, which is what EPIC-7 exists to catch up to: get_authoring_conventions shipped in 2.1.0 (US-7.1), the first of that tag's four GET operations. It reads the platform's own MQL5 authoring contract — hard-safety constraints, trading-safety requirements, the static analyzer's forbidden-construct list, and the limits block an agent must read before generating source, since those five ceilings are also what size the cuts the remaining tools make. get_draft shipped in 2.2.0 (US-7.2), the second of that tag's four GET operations. It returns one draft's full source, compiler log and diagnostics, cut one way — attachment source is replaced with a byte count, undone by list_draft_attachments — and it is the module that owns DraftSchema and AttachmentSchema, which list_drafts and list_draft_attachments import rather than redeclare. list_drafts shipped in 2.3.0 (US-7.3), the third of that tag's four GET operations and the largest payload the API can produce — up to 10.3 MiB across 20 drafts. It cuts four things (source, attachment source, compile log, diagnostics) and notes all four in one sentence; measured live on 2026-08-20, 19,853 B → 1,898 B, 90.4% removed (CONTEXT D32) — until 2.9.0, when the cut moved to the server: the tool now asks for view=summary and returns the API's own DraftSummary, and notes is always empty (US-9.1, CONTEXT D49). list_draft_attachments shipped in 2.4.0 (US-7.4), the fourth and last of that tag's GET operations. It returns the indicator source get_draft leaves out, bounded by a 64 KiB budget rather than a truncation — the running total is checked after an attachment is added, not before, which is what caps the response at 64 KiB instead of admitting 127 KiB — and a filename filter that reads one attachment whole, including one the budget cut. This closes EPIC-7: all 14 of the API's GET operations now have a tool. The budget and the filename filter are proven only against synthetic sizes — the smoke account holds 4 drafts and 0 attachments in all 4 — and EPIC-7's close states that rather than letting a green suite imply otherwise.