Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(mcp): expose Alpha Zoo tools

cgycorey3f6423906321
diff --git a/README.md b/README.md
index 8d8f4ece9..aa23b5ac1 100644
--- a/README.md
+++ b/README.md
@@ -1160,7 +1160,7 @@ with `--host` / `--port`.
</details>
-**MCP tools exposed (62):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`.
+**MCP tools exposed (64):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `alpha_zoo`, `alpha_bench`, `analyze_options`, `analyze_options_payoff`, `pattern_recognition`, `read_url`, `read_document`, `web_search`, `write_file`, `read_file`, `trading_connections`, `trading_select_connection`, `trading_check`, `trading_account`, `trading_positions`, `trading_orders`, `trading_quote`, `trading_history`, `list_swarm_presets`, `run_swarm`, `get_market_data`, `get_fund_flow`, `get_dragon_tiger`, `get_northbound_flow`, `get_margin_trading`, `get_block_trades`, `get_shareholder_count`, `get_lockup_expiry`, `get_sector_info`, `get_research_reports`, `get_stock_news`, `get_sec_filings`, `get_financial_statements`, `get_options_chain`, `get_stock_profile`, `screen_market`, `search_symbol`, `get_macro_series`, `iwencai_search`, `qveris_search`, `qveris_inspect`, `qveris_execute`, `get_institutional_holdings`, `etf_holdings`, `prediction_market`, `research_papers`, `get_swarm_status`, `get_run_result`, `list_runs`, `reap_stale_runs`, `retry_run`, `analyze_trade_journal`, `extract_shadow_strategy`, `run_shadow_backtest`, `render_shadow_report`, `scan_shadow_signals`.
### SWARM external MCP tools
@@ -1534,7 +1534,7 @@ Vibe-Trading/
├── agent/ # Backend (Python)
│ ├── cli/ # CLI package — interactive TUI + subcommands
│ ├── api_server.py # FastAPI server — runs, sessions, upload, swarm, SSE
-│ ├── mcp_server.py # MCP server — 62 tools for OpenClaw / Claude Desktop
+│ ├── mcp_server.py # MCP server — 64 tools for OpenClaw / Claude Desktop
│ │
│ ├── src/
│ │ ├── agent/ # ReAct agent core
diff --git a/agent/SKILL.md b/agent/SKILL.md
index 982fa27d0..859bcea1a 100644
--- a/agent/SKILL.md
+++ b/agent/SKILL.md
@@ -130,7 +130,7 @@ Comprehensive knowledge base covering:
Use `load_skill(name)` to access full methodology docs with code templates.
-## Available MCP Tools (58)
+## Available MCP Tools (60)
| Tool | Description | API Key |
|------|-------------|---------|
@@ -142,6 +142,8 @@ Use `load_skill(name)` to access full methodology docs with code templates.
| `update_research_goal_status` | Update goal lifecycle status | None |
| `backtest` | Run vectorized backtest engine | None* |
| `factor_analysis` | IC/IR analysis + layered backtest | None* |
+| `alpha_zoo` | Browse bundled alpha metadata and registry health | None |
+| `alpha_bench` | Benchmark one alpha or a complete zoo | None* |
| `analyze_options` | Black-Scholes price + Greeks | None |
| `analyze_options_payoff` | Multi-leg expiry payoff + spot/IV scenarios | None |
| `pattern_recognition` | Detect chart patterns (H&S, double top, etc.) | None |
diff --git a/agent/mcp_server.py b/agent/mcp_server.py
index cdadfcc1b..4d21c62bf 100644
--- a/agent/mcp_server.py
+++ b/agent/mcp_server.py
@@ -6,7 +6,7 @@ Zero API key required for HK/US/crypto research markets (yfinance, OKX,
AKShare are free). Trading connector tools are profile-scoped and require the
selected connector's own local app or OAuth setup.
-Surfaces 62 tools: skills, research goals, backtest/factor/options/pattern
+Surfaces 64 MCP tools: skills, research goals, backtest/factor/options/pattern
analysis, market data, fundamentals & capital-flow & news & discovery
(get_fund_flow / get_dragon_tiger / get_northbound_flow / get_margin_trading /
get_block_trades / get_shareholder_count / get_lockup_expiry / get_sector_info /
@@ -801,6 +801,72 @@ def factor_analysis(
)
+def alpha_zoo(
+ action: str,
+ alpha_id: str | None = None,
+ zoo: str | None = None,
+ theme: str | None = None,
+ universe: str | None = None,
+ limit: int = 50,
+) -> str:
+ """Browse the bundled Alpha Zoo registry.
+
+ Args:
+ action: ``list_alphas``, ``get_alpha``, or ``health``.
+ alpha_id: Alpha id required by ``get_alpha``.
+ zoo: Optional zoo filter for ``list_alphas``.
+ theme: Optional theme filter for ``list_alphas``.
+ universe: Optional universe filter for ``list_alphas``.
+ limit: Maximum number of alphas returned by ``list_alphas``.
+ """
+ registry = _get_registry()
+ params: dict[str, Any] = {"action": action, "limit": limit}
+ if alpha_id is not None:
+ params["alpha_id"] = alpha_id
+ if zoo is not None:
+ params["zoo"] = zoo
+ if theme is not None:
+ params["theme"] = theme
+ if universe is not None:
+ params["universe"] = universe
+ return registry.execute("alpha_zoo", params)
+
+
+def alpha_bench(
+ universe: str,
+ period: str,
+ alpha_id: str | None = None,
+ zoo: str | None = None,
+ top: int = 20,
+ output_dir: str | None = None,
+) -> str:
+ """Benchmark one Alpha Zoo alpha or a complete zoo on a universe.
+
+ Args:
+ universe: Universe to benchmark, such as ``sp500`` or ``csi300``.
+ period: ``YYYY-YYYY`` or ``YYYY-MM-DD/YYYY-MM-DD``.
+ alpha_id: Optional single alpha id; mutually exclusive with ``zoo``.
+ zoo: Optional zoo id; mutually exclusive with ``alpha_id``.
+ top: Number of top-ranked alphas to include in the report.
+ output_dir: Optional directory for the generated HTML report.
+ """
+ registry = _get_registry()
+ params: dict[str, Any] = {
+ "universe": universe,
+ "period": period,
+ "top": top,
+ }
+ if alpha_id is not None:
+ params["alpha_id"] = alpha_id
+ if zoo is not None:
+ params["zoo"] = zoo
+ if output_dir is not None:
+ params["output_dir"] = output_dir
+ return registry.execute("alpha_bench", params)
+
+
# ---------------------------------------------------------------------------
# Options pricing tool
# ---------------------------------------------------------------------------
diff --git a/agent/tests/test_mcp_alpha_zoo_contract.py b/agent/tests/test_mcp_alpha_zoo_contract.py
new file mode 100644
index 000000000..3a24575fa
--- /dev/null
+++ b/agent/tests/test_mcp_alpha_zoo_contract.py
@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import re
+from pathlib import Path
+
+import mcp_server
+from src.tools.alpha_bench_tool import AlphaBenchTool
+from src.tools.alpha_zoo_tool import AlphaZooTool
+
+
+_ALPHA_ZOO = getattr(mcp_server.alpha_zoo, "fn", None) or getattr(
+ mcp_server.alpha_zoo, "__wrapped__", mcp_server.alpha_zoo
+)
+_ALPHA_BENCH = getattr(mcp_server.alpha_bench, "fn", None) or getattr(
+ mcp_server.alpha_bench, "__wrapped__", mcp_server.alpha_bench
+)
+
+
+class _RecordingRegistry:
+ def __init__(self) -> None:
+ self.calls: list[tuple[str, dict]] = []
+
+ def execute(self, name: str, args: dict) -> str:
+ self.calls.append((name, args))
+ return '{"status":"ok"}'
+
+
+def test_wrapper_signatures_match_registered_contracts() -> None:
+ for wrapper, tool in (
+ (_ALPHA_ZOO, AlphaZooTool),
+ (_ALPHA_BENCH, AlphaBenchTool),
+ ):
+ signature = inspect.signature(wrapper)
+ assert set(signature.parameters) == set(tool.parameters["properties"])
+ required = {
+ name
+ for name, parameter in signature.parameters.items()
+ if parameter.default is inspect.Parameter.empty
+ }
+ assert required == set(tool.parameters["required"])
+
+
+def test_alpha_zoo_forwards_filters(monkeypatch) -> None:
+ registry = _RecordingRegistry()
+ monkeypatch.setattr(mcp_server, "_get_registry", lambda: registry)
+
+ _ALPHA_ZOO(
+ action="list_alphas",
+ zoo="alpha101",
+ theme="momentum",
+ universe="equity_us",
+ limit=25,
+ )
+
+ assert registry.calls == [
+ (
+ "alpha_zoo",
+ {
+ "action": "list_alphas",
+ "limit": 25,
+ "zoo": "alpha101",
+ "theme": "momentum",
+ "universe": "equity_us",
+ },
+ )
+ ]
+
+
+def test_alpha_bench_forwards_selection(monkeypatch) -> None:
+ registry = _RecordingRegistry()
+ monkeypatch.setattr(mcp_server, "_get_registry", lambda: registry)
+
+ _ALPHA_BENCH(
+ universe="sp500",
+ period="2018-2025",
+ zoo="alpha101",
+ top=10,
+ output_dir="/tmp/reports",
+ )
+
+ assert registry.calls == [
+ (
+ "alpha_bench",
+ {
+ "universe": "sp500",
+ "period": "2018-2025",
+ "top": 10,
+ "zoo": "alpha101",
+ "output_dir": "/tmp/reports",
+ },
+ )
+ ]
+
+
+def test_skill_inventory_matches_static_mcp_registration() -> None:
+ # Given the runtime MCP registration and the bundled SKILL inventory.
+ registered = {tool.name for tool in asyncio.run(mcp_server.mcp.list_tools())}
+ mirrored = {tool_cls.name for tool_cls in mcp_server._mirrored_tool_classes()}
+ static = registered - mirrored
+ skill_text = (Path(mcp_server.__file__).parent / "SKILL.md").read_text(encoding="utf-8")
+
+ # When the SKILL header and table are read.
+ header = re.search(r"^## Available MCP Tools \((\d+)\)$", skill_text, re.MULTILINE)
+
+ # Then they describe exactly the non-mirrored MCP surface.
+ assert header is not None
+ tool_section = skill_text[header.end() :].split("\n## ", maxsplit=1)[0]
+ listed = set(re.findall(r"^\| `([a-z_]+)` \|", tool_section, re.MULTILINE))
+ assert int(header.group(1)) == len(static)
+ assert listed == static
diff --git a/agent/tests/test_mcp_server_smoke.py b/agent/tests/test_mcp_server_smoke.py
index 2d430dd56..6d67281f4 100644
--- a/agent/tests/test_mcp_server_smoke.py
+++ b/agent/tests/test_mcp_server_smoke.py
@@ -60,6 +60,8 @@ REQUIRED_TOOL_NAMES = {
"trading_orders",
"trading_quote",
"trading_history",
+ "alpha_zoo",
+ "alpha_bench",
}