Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(mcp): forward offset through get_sec_filings and get_financial_statements

Lanre Shittue012bd14d503
diff --git a/agent/mcp_server.py b/agent/mcp_server.py
index 727723100..55f74159b 100644
--- a/agent/mcp_server.py
+++ b/agent/mcp_server.py
@@ -1861,6 +1861,7 @@ def get_sec_filings(
form: str | None = None,
metric: str | None = None,
limit: int = 20,
+ offset: int = 0,
) -> str:
"""Fetch U.S. SEC EDGAR filings or reported XBRL financials for a company.
@@ -1874,8 +1875,12 @@ def get_sec_filings(
form: Optional SEC form type filter (e.g. "10-K", "10-Q", "8-K").
metric: Optional XBRL us-gaap concept name (e.g. "Revenues").
limit: Maximum number of most-recent filings and metric points to return.
+ offset: Index of the first filing to return, newest first; defaults
+ to 0. Results are returned whole and only as many as fit one
+ response — read paging.total and paging.next_offset and call
+ again with that offset to continue.
"""
- params: dict[str, Any] = {"ticker": ticker, "limit": limit}
+ params: dict[str, Any] = {"ticker": ticker, "limit": limit, "offset": offset}
if form:
params["form"] = form
if metric:
@@ -1885,7 +1890,7 @@ def get_sec_filings(
@mcp.tool
-def get_financial_statements(code: str, statement: str = "indicators", period: str = "annual") -> str:
+def get_financial_statements(code: str, statement: str = "indicators", period: str = "annual", offset: int = 0) -> str:
"""Fetch a stock's financial statements or key per-period indicators.
Markets: A-share (.SH/.SZ/.BJ, via Sina), US (.US) and Hong Kong (.HK, via
@@ -1896,11 +1901,15 @@ def get_financial_statements(code: str, statement: str = "indicators", period: s
code: Single symbol with a market suffix (e.g. "600519.SH", "AAPL.US").
statement: "balance", "income", "cashflow", or "indicators".
period: "annual" or "quarter".
+ offset: Index of the first period to return, newest first; defaults
+ to 0. Periods are returned whole and only as many as fit one
+ response — read paging.total and paging.next_offset and call
+ again with that offset to continue.
"""
registry = _get_registry()
return registry.execute(
"get_financial_statements",
- {"code": code, "statement": statement, "period": period},
+ {"code": code, "statement": statement, "period": period, "offset": offset},
)
diff --git a/agent/tests/test_mcp_sec_financial_offset_paging.py b/agent/tests/test_mcp_sec_financial_offset_paging.py
new file mode 100644
index 000000000..ce379d127
--- /dev/null
+++ b/agent/tests/test_mcp_sec_financial_offset_paging.py
@@ -0,0 +1,80 @@
+"""get_sec_filings and get_financial_statements (MCP) must forward offset.
+
+Both tools are paged internally via fit_records(), which returns a
+paging.next_offset callers are expected to pass back in to continue reading.
+The MCP wrappers dropped that parameter on the way in, the same drift class
+PR #715 fixed for factor_analysis: a caller (including an LLM agent) that
+follows paging.next_offset from the tool's own response gets a TypeError, and
+otherwise has no way to reach anything past the first page.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from unittest.mock import patch
+
+import mcp_server
+from src.tools import sec_filings_tool as sft
+from src.tools.financial_statements_tool import FinancialStatementsTool
+from src.tools.sec_filings_tool import SecFilingsTool
+
+_sec = getattr(mcp_server.get_sec_filings, "fn", None) or getattr(
+ mcp_server.get_sec_filings, "__wrapped__", mcp_server.get_sec_filings
+)
+_fin = getattr(mcp_server.get_financial_statements, "fn", None) or getattr(
+ mcp_server.get_financial_statements, "__wrapped__", mcp_server.get_financial_statements
+)
+
+
+def test_get_sec_filings_wrapper_matches_tool_contract():
+ spec = SecFilingsTool.parameters
+ sig = inspect.signature(_sec)
+ missing = set(spec["properties"]) - set(sig.parameters)
+ assert not missing, f"MCP wrapper is missing parameters the tool declares: {missing}"
+
+
+def test_get_financial_statements_wrapper_matches_tool_contract():
+ spec = FinancialStatementsTool.parameters
+ sig = inspect.signature(_fin)
+ missing = set(spec["properties"]) - set(sig.parameters)
+ assert not missing, f"MCP wrapper is missing parameters the tool declares: {missing}"
+
+
+def _submissions_with_n_filings(n: int) -> dict:
+ return {
+ "cik": "320193",
+ "name": "Apple Inc.",
+ "filings": {
+ "recent": {
+ "form": ["10-K"] * n,
+ "accessionNumber": [f"0000320193-23-{i:06d}" for i in range(n)],
+ "filingDate": ["2023-11-03"] * n,
+ "reportDate": ["2023-09-30"] * n,
+ "primaryDocument": [f"aapl-{i}.htm" for i in range(n)],
+ "primaryDocDescription": ["10-K"] * n,
+ }
+ },
+ }
+
+
+def test_mcp_get_sec_filings_offset_reaches_the_second_page():
+ # SecFilingsTool caps the parsed filing pool at _MAX_LIMIT=40 regardless
+ # of the requested limit, so 40 (not more) is the realistic total here.
+ submissions = _submissions_with_n_filings(40)
+ with (
+ patch.object(sft, "cik_for", return_value="320193"),
+ patch.object(sft, "get_submissions", return_value=submissions),
+ ):
+ page1 = json.loads(_sec(ticker="AAPL", limit=40))
+ assert page1["ok"] is True
+ assert page1["paging"]["complete"] is False, "40 filings must not fit in one page"
+ next_offset = page1["paging"]["next_offset"]
+ assert next_offset, "page 1 must report a next_offset when truncated"
+
+ page2 = json.loads(_sec(ticker="AAPL", limit=40, offset=next_offset))
+
+ combined_ids = {f["accession_number"] for f in page1["data"]["filings"]} | {
+ f["accession_number"] for f in page2["data"]["filings"]
+ }
+ assert len(combined_ids) == 40, "paging through offset must recover every filing"