OpenInvest
OpenInvest is a self-hosted investment decision and bookkeeping MCP server for AI agents: it tracks portfolios, runs an auditable multi-role investment committee, manages strategy/rebalance/alerts, and maintains trade/news/decision ledgers.
Inspect portfolio status, cash, holdings, P&L, performance, pending fund orders, and setup health.
Read strategy targets, tracked assets, insights, recent trades/verdicts, discipline ledger, decision adoption, and quality alerts.
Get live market prices for gold, FX, NDQ.AX, VIX, and 10Y Treasury; run what-if P&L scenarios.
Generate rebalance plans against target allocations without placing orders.
Explain past committee decisions with transcripts and confidence lookups.
Run the 4-role committee directly or prepare/submit an agent-run committee transcript.
Record executed or declined verdicts for adoption tracking.
Ingest and queue finance news, manage RSS news sources, and trigger holding-relevant committee re-runs.
Assemble daily reports and list pending committee re-runs.
Bookkeep trades and cash events: buy/sell, deposits/withdrawals, dividends/interest, fees/taxes, splits, return of capital, existing positions, and off-exchange fund orders.
Set stock/cash and per-asset targets, track/untrack assets, and configure price/day-move/drawdown alerts.
Integrates with Hermes Agent as a plugin, allowing Hermes to leverage OpenInvest's multi-agent investment committee and auditable decision trails.
openInvest
A self-hosted investment decision engine built for modern AI agents. Multi-agent information isolation and cross-challenge protocol, providing an auditable decision trail (Audit Trail).
๐ Full Architecture Wiki ยท ๐จ๐ณ ไธญๆ็
What is OpenInvest?
OpenInvest is a self-hosted investment decision engine built for modern AI agents.
It provides a verifiable investment committee, evidence-based reasoning, long-horizon backtesting, and auditable decision records. Instead of replacing Claude Code, Codex, Hermes, or OpenClaw, OpenInvest is designed to power them.
Related MCP server: Decker
Account Performance & PnL
Benchmark Portfolio: The system introduces 8 standard control benchmarks across 4 quadrants (AI advisors / Mutual funds / Wealth management / Broad market index). For details on the comparison methodology and data cleaning logic, see docs/wiki/README.md.
Research & Falsification
System Self-Disclosure: This system is an auditing tool to eliminate human investment cognitive biases and enforce reasoning transparency, not a return-amplifying black box. Latest automated audit (docs/verdict_accuracy.md): Directional verdicts (excluding HOLD) have a true hit rate of 42.2% (n=56, below random); HOLD accounts for 56% of all decisions. The system's value lies in transparency and discipline (mostly staying inactive, low turnover), not directional prediction. Detailed log stream can be found in docs/verdict_accuracy.md.
This project systematically attempts to falsify its own edge and publishes negative results as-is. The deterministic features the committee reads, and the timing signals around them, were tested against pre-registered statistical gates โ none survived as tradable alpha.
Test | Result | Verdict |
Q1 cross-sectional stock picking | 6 features, mean-IC 0.025โ0.067, Holm-corrected p=0.397 | No significant stock-picking signal |
M1 multivariate GBM (out-of-sample) | mean OOS IC +0.003, p=0.925 | Feature combination doesn't help either โ no signal |
Q2 gold MA200 trend | p_holm=0.016, significant โ but | Statistically significant, economically untradable |
Per-asset multi-signal families | 3 assets ร 4 signal families ร parameter grid = 24 variants per asset; after costs + DSR deflation, none passes DSR > 0.95 | No tradable signal in any family |
Positive control | A cheating perfect-foresight timing signal scores DSR = 1.00 | The harness can detect a real signal |
Methodology: Newey-West HAC t-statistics, Deflated Sharpe Ratio (Bailey & Lรณpez de Prado 2014, re-derived equation by equation), Holm correction, zero lookahead, and LLM training-cutoff probes.
Details: experiments/signal-eval/README.md ยท docs/verdict_accuracy.md ยท ADR-022 ยท ADR-023
Product Philosophy
Most AI investment assistants try to become better chatbots. OpenInvest instead builds a transparent, verifiable, and auditable decision engine that plugs into personal agents such as Claude Code, Codex, Hermes, and OpenClaw โ every improvement in those agents automatically makes OpenInvest more capable.
The division of labor is deliberate: your agent handles long-term memory, natural conversation, and user understanding; OpenInvest handles the verifiable investment committee, evidence-based reasoning, long-horizon backtesting, and auditable decision records.
User
โ
โโโโโโโโโโโโโดโโโโโโโโโโโโ
โผ โผ
Your Agent OpenInvest
(User Understanding) (Market Understanding)
โ โ
โโโโโโโโโโโโโฌโโโโโโโโโโโโ
โผ
Better Investment DecisionsYour agent knows you. OpenInvest knows investing.
Avoiding User Ownership
OpenInvest intentionally avoids "owning" the user. Most AI products try to own everythingโmemory, persona, chat history, and workspaces. OpenInvest takes a back seat. It exposes clean APIs, CLI commands, and agent skills (Claude Code / Codex / Hermes / OpenClaw), letting your primary agent manage the conversation and context while OpenInvest powers the underlying investment intelligence.
Features
Multi-Agent Investment Committee: Isolated analysis and round-rebuttal debate.
Coordinator-Worker Architecture: Prevents context contamination and role hallucination.
Information Isolation: Rigidly blocks quant and risk analysts from out-of-boundary contexts.
Auditable Decision Trail: Clean logs showing exactly "why" each decision was made.
Markdown-as-a-Database: Frontmatter (YAML) + Markdown (Body) as the single source of truth.
Long-Horizon Backtesting: Built-in test harness with lookahead bias protections.
Dreaming-Based Memory Consolidation: Nightly memory distillation to prevent context drift.
Self-Hosted / Zero-Cost: Powered directly by your local agent's reasoning resources.
Agent Skill: Lightweight plugin for Claude Code / Codex / Hermes / OpenClaw, with interactive bootstrap wizard.
Automated Deployment: GitHub Actions workflow to run the committee and email reports daily.
Quick Start
1. Integrate with your agent (Recommended)
Add the lightweight skill from your agent's plugin registry. The host agent will automatically pull the core code and align dependencies on first run:
# Claude Code
/plugin marketplace add longsizhuo/openInvest
/plugin install invest@openinvest
# Codex
codex plugin marketplace add longsizhuo/openInvest
codex plugin add invest@openinvest
# Hermes Agent (official plugin catalog)
hermes plugins install openinvest --enable
# older Hermes without the catalog: hermes plugins install longsizhuo/openInvest/plugin --enable
# OpenClaw
openclaw plugins install clawhub:openinvestAny other MCP client: register the MCP server from step 2 below (full walkthrough in the agent tutorial).
2. Standalone โ MCP server or CLI (no clone needed)
The backend ships on PyPI; ~/openInvest holds only your data:
# MCP (any MCP client; add --http for a remote streamable-HTTP server โ BETA)
claude mcp add openinvest -e INVEST_HOME=~/openInvest -- uvx openinvest-mcp
# or plain CLI
INVEST_HOME=~/openInvest uvx openinvest statusSend set up invest (or ๅธฎๆๅๅงๅ invest) to any skill-enabled AI terminal. The system will trigger an interactive bootstrap wizard to guide you through:
Detecting the
memory/state storage path and.envconfiguration.5-dimensional profiling (Legal name, Risk capacity, Debt structure, Initial holdings, and optional keys).
Running static data migration to immediately generate your first asset exposure memo.
๐ก Zero-Cost Execution: In skill interactive mode, the committee's underlying reasoning relies entirely on the host agent's (e.g. Claude Code) reasoning pipeline. No third-party API Key is consumed. You only need to configure an API key when setting up automated crons or calling independent Web APIs.
For self-hosting details, see docs/QUICK_START.md. (The bundled Web GUI was retired on 2026-07-05 โ all capabilities are exposed via CLI/MCP; a standalone frontend may return later.)
3. Serverless Self-Hosting (GitHub Actions)
Run the committee automatically via GitHub Actions and receive daily digest emails.
โ ๏ธ Fork must be set to Private: State files (holdings, verdicts) will be committed back to your fork. Public forks will leak your private financial information.
Fork this repository and change its visibility to Private (Settings -> Visibility).
Run
set up investlocally to generate the initialmemory/folder, then commit and push it to your private fork:git add -f memory/ && git commit -m "chore: init memory state" && git pushIn your fork's Settings -> Secrets and variables -> Actions, add the following Secrets:
LLM_API_KEY(orDEEPSEEK_API_KEY): API key to run the committee.EMAIL_SENDER/EMAIL_PASSWORD: Gmail address + App Password.DIGEST_EMAIL_TO: Recipient email address.
Enable Workflows under the Actions tab. The workflow runs automatically at 10:00 AM (Beijing time) daily; you can also manually trigger
daily-reportvia Run workflow.
Architecture & Multi-Agent Orchestration
openInvest does not run a mock debate in a single LLM session. The system enforces an Information Isolation Contract at the core/committee/ layer, orchestrating 4 independent LLM processes in a directed acyclic graph (DAG):
[ Macro Data Injection ]
โ
โผ 1. Macro Alignment Context
โโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Macro Strategist โ (VIX / Interest rate spread / Currency momentum)
โโโโโโโโโโโโโโโฌโโโโโโโโโโโโโ
โ
โผ 2. Async Multi-Dimensional Scrutiny (Async DAG)
โโโโโโโโโโโโโโโดโโโโโโโโโโโโโ
โผ โผ
โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ
โ Quant Analyst โ โ Risk Officer โ
โ (RSI / Momentum) โ โ (Concentration) โ
โ โ โ โ
โ ๐ No Holdings โ โ ๐ No Indicators โ
โโโโโโโโโโโฌโโโโโโโโโ โโโโโโโโโโโฌโโโโโโโโโ
โ โ
โโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโ
โ
โผ 3. Round 2 Rebuttal & Cross-Challenge
โ Mutual feedback loop for signal correction
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Chief Investment Officer (CIO) โ
โโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโ
โ
โผ 4. Deterministic State Persistence
[ BUY / ACCUMULATE / HOLD / TRIM / SELL ]Macro Strategist: Assesses the global macro landscape (VIX, yield curve spread, core currency matrix) to establish the portfolio's risk threshold.
Quant Analyst: A pure mathematical momentum and technical indicator filter. Strictly blocked from knowing portfolio holdings to eliminate human attachment and loss-aversion biases.
Risk Officer: Focuses entirely on tail risks (drawdown buffers, concentration limits, solvency multipliers). Strictly blocked from technical indicators to make objective asset exposure rulings.
Round 2 Rebuttal: Quant and Risk analysts are fed each other's Round 1 reports in Round 2, challenging boundaries until signals converge or safety valves trigger.
CIO (Chief Investment Officer): Synthesizes the audited reports and outputs a structured
Verdict(BUY / ACCUMULATE / HOLD / TRIM / SELL) with a confidence level. No auto-order execution occurs; final action remains strictly up to the human auditor.
Key trade-offs behind this design are recorded as ADRs in docs/wiki/adr/ (24 to date), including rulings that overturned our own earlier designs โ ADR-007 retired the few-shot CIO route, and ADR-009 rejected TA-style analyst agents after a pre-registered experiment.
Core Design
Coordinator-Worker Pattern: Workers operate in isolated namespaces. Boundary constraints are hardcoded at the framework layer in Python to prevent attention contamination in large multi-role prompts.
Markdown-as-a-Database: The system uses Frontmatter (YAML) + Markdown (Body) as the single source of truth. Leveraging
fcntl.flockprocess file locks and temporary atomic file replacement, it provides a tamper-proof investment audit trail natively tracked by Git.Three-Phase Dreaming Consolidation: Distills daily decisions against actual market outcomes nightly (Light Sleep $\rightarrow$ REM $\rightarrow$ Deep Sleep) to consolidate long-term insights, preventing Large Language Model (LLM) context drift over long execution spans.
Configuration
The system defaults to DeepSeek endpoints and supports any standard OpenAI-compatible API. LLM provider setup and all tunable runtime overrides (ADR-017) are documented in docs/wiki/22-configuration.md.
Disclaimers & Backtest Limitations
No Financial Advice: This system is a decision-support tool powered by LLMs. Output memos represent simulated reasoning based on deterministic data and do not constitute asset allocation advice.
Backtest Time-Lock & Lookahead Guard: The backtest engine (
scripts/backtest_runner.py) has a hardcoded safety valve: it rejects backtests fordecision_date > 2024-06-30by default (override with--allow-lookahead). Since mainstream foundation models have training cutoff dates around mid-2024, backtesting on later intervals introduces severe Lookahead Bias (model pre-training leakage). Parameter tuning, Optuna sweeps, and prompt optimization must run strictly on historical windows prior to June 30, 2024.
Acknowledgments
Jawz: Thank you for supporting openInvest's continued development.
Tencent Cloud: Thank you for supporting openInvest's continued development.
Equibles โ Optional data provider for A-share and Hong Kong financial statements, and a daily-price fallback when Yahoo Finance is unreachable. Yahoo Finance stays the default; set your own free
EQUIBLES_API_KEYto turn it on (setup).Xiaomi MiMo โ Special thanks to MiMo Quantitative Lab for sponsoring production-grade high-performance LLM inference (powering
mimo-v2.5-prolong-horizon sweeps).OpenClaw Dreaming Guide โ Theoretical foundation for the three-phase sleep-cycle memory distillation framework.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Available Tools
42 toolsadd_news_sourceAIdempotent
Add an RSS/Atom feed to the crawler's source list. The URL must be http(s) on a public host (fetched directly, not via HTTP(S)_PROXY), and is live-probed before saving โ a URL that doesn't parse as a feed is rejected. Idempotent: re-adding an existing URL returns the existing entry. Capped so the list can't grow unbounded.
Use when someone says "follow 's news" / "ๅ ไธชๆฐ้ปๆบ".
Inputs: url (required), name (required). Returns: result
buyADestructive
Record a buy in the local ledger: adds to an existing position with weighted-average cost, or opens a new position for an unseen symbol. This bookkeeps a trade the user already placed with their broker โ openInvest never places real orders.
Confirm symbol, units, and price with the user before calling; this
moves ledger cash. A position the user already held before using
openInvest is not a purchase: record it with record_existing_position.
Off-exchange China mutual funds (FUND:<6 digits>) settle T+1 or later
at the NAV of the pricing day: use place_fund_order +
confirm_fund_order instead (buy books them as instantly filled and
total assets dip by the amount until the real confirmation).
Args:
symbol: yfinance ticker (e.g. "AAPL", "510300.SS"). Gold = "GC=F", booked in
CNY per gram only (units = grams, currency "CNY", kind "metal", unit_label "ๅ
").
units: Quantity bought; must be > 0.
price: Execution price per unit, in currency.
currency: Currency of price; omitted = the existing position's currency (CNY if new).
kind: Asset kind tag: "equity", "etf", "metal" (gold), "crypto", "bond", "fund", "other".
unit_label: Human display label for units (default "่ก", i.e. shares).
idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns: Updated position summary, or {"status": "error", "error": ...}.
Inputs: price (required), units (required), symbol (required), kind, +4 more. Returns: result
cancel_fund_orderADestructive
Cancel an in-transit off-exchange fund order that was never executed
(the user withdrew it on the fund platform): the amount returns to ledger
cash. Only orders still in transit can be cancelled โ a confirmed order
already holds shares (use sell to book a redemption).
Confirm with the user before calling; this moves ledger cash.
Args: order_id: The in-transit order to cancel.
Returns: Cash returned and new balance, or {"status": "error", "error": ...}.
Inputs: order_id (required). Returns: result
collect_newsB
Capture fixed news providers and durable per-source coverage, without a model call.
Capture is not proof of source truth or completed normalization. Incomplete windows remain pending; never infer a quiet market from this failure.
Inputs: since. Returns: result
committee_reviewARead-onlyIdempotent
Retrieve unchanged original transcript and issued verification packet; never completes work.
Inputs: context_id (required). Returns: result
confirm_fund_orderADestructive
Second leg of an off-exchange fund purchase: turn an in-transit order
into shares at the pricing day's NAV (units = (amount - fee) / nav; average
cost updates, cash unchanged). The fund_confirm job does this
automatically every weekday evening, so call it manually only to supply a
NAV / fee yourself or to confirm early.
Safe to call twice: an order that is already confirmed returns {"status": "already_confirmed"} (a cancelled one {"status": "cancelled"}) and nothing changes. If the pricing-day NAV is not published yet the result is {"status": "pending_nav"} and the order stays in transit.
Args: order_id: The order to confirm. nav: Unit NAV; omit to use the published NAV of the pricing day. fee: Subscription fee in CNY (default 0).
Returns: Units added, NAV used and new average cost, or {"status": "error", "error": ...}.
Inputs: order_id (required), fee, nav. Returns: result
daily_reportA
Assemble today's daily report (portfolio, verdicts, performance,
holdings digest) and return it as full_report Markdown for you to deliver.
Agent mode (keyless backend): run prepare_committee โ roles โ
submit_committee for every target asset FIRST; this tool then only reads
today's submitted verdicts โ nothing is re-run by a backend model. Assets
without a submitted verdict are listed in missing_verdicts: treat any
entry there as a failure and report it. Backend mode: runs the backend
committee itself (needs a backend LLM key, takes minutes).
Inputs: no named parameters. Returns: result
decisionsARead-only
Get the unified decision ledger: every committee verdict joined with rule interventions, the user's actual executions or refusals (with reasons), and post-hoc outcome data โ plus an adoption-rate summary.
Answers "how often did I follow the advice", "which recommendations did
I skip", and "what did the safety rules rewrite". Read-only. Filter by
symbol / verdict to answer questions about one asset or one kind of
call; the list is capped at limit (newest first) so a year of history
doesn't flood the context โ count and summary still cover every match.
Args: days: Look-back window in days (default 90). symbol: Only decisions on this ticker (case-insensitive). verdict: Only decisions with this verdict. limit: Max decisions listed (default 20; 0 = all).
Returns:
Object with count (all matches), returned (listed), summary
(adoption rate and aggregates over all matches), and decisions
(newest first; each entry has decision_id, verdict, confidence,
intervention, executed flag, matched trades, and outcome).
Inputs: days, limit, symbol, verdict. Returns: result
depositADestructive
Record a cash deposit into the ledger, in any currency. Bookkeeping only โ no real payment system is connected.
Args: currency: ISO-style currency code, e.g. "CNY", "USD", "AUD". amount: Amount to add; must be > 0. idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns: Updated cash balances, or {"status": "error", "error": ...}.
Inputs: amount (required), currency (required), idempotency_key. Returns: result
disciplineARead-only
Get the committee's discipline ledger: how often it chose inaction (HOLD ratio), how many impulsive user trades its rules intercepted, and the counterfactual money saved/lost by those interventions (ADR-023: the system's proven value is discipline and transparency, not alpha).
Use when the user asks "what has the committee blocked" or "is this tool actually helping". Read-only.
Returns:
Object with summary (structured stats) and markdown (the same
ledger pre-rendered for direct display to the user).
Inputs: no named parameters. Returns: result
doctorARead-only
Health check, the first call of a session (same output as run.sh doctor,
for agents without shell access): is onboarding done, and which optional
pieces are missing.
status is "ready" when memory (user / strategy / portfolio) is initialized,
or "needs_setup" when it is not (or portfolio.md is still the v1 format) โ
only then hand over to the invest-setup skill. A missing LLM key or mail
credentials never makes it "needs_setup": those checks entries are marked
optional_for_coordinator / optional_for_email. The Coordinator path
(prepare_committee + subagents) works without a key; only the Direct path
(run_committee, cron) needs one, see direct_ready.
Read-only; makes one short HTTP probe to the configured LLM endpoint when a key is set.
Returns:
Object with status, version, coordinator_ready, direct_ready,
next_step, and checks (name / status / detail / hint per check).
Inputs: no named parameters. Returns: result
event_historyCRead-only
Read qualified current events and source evidence. This is not a scan watermark or a duplicate veto.
Inputs: hours, limit. Returns: result
explain_decisionARead-only
Get the full reasoning behind one committee verdict: the complete 4-role debate transcript with the CIO memo, plus the path-probability snapshot the CIO saw at decision time.
Use when the user asks "why was today's verdict HOLD" or wants to audit a past decision. Read-only.
Args:
decision_id: "/", e.g. "2026-07-03/GC=F" โ exactly as
returned in the decisions tool output.
Returns:
Object with verdict, confidence (the CIO's self-reported number, kept
for the record), confidence_lookup (show this to the user instead:
how similar verdicts (live + paper fleet) turned out 30 days later), alloc_cny,
transcript_markdown (render this to the user), and path_snapshot
(may be null).
Inputs: decision_id (required). Returns: result
historyARead-only
Get the most recent trade records and committee verdict history.
Use when the user asks "what did I buy recently" or "what did the committee decide lately". Read-only.
Args: n: Maximum number of recent trades to return (default 10).
Returns:
Object with trades (each with symbol, direction, units, price,
timestamp, status) and recent committee verdict records.
Inputs: n. Returns: result
ingest_eventAIdempotent
Feed a finance news item you (the host agent) found into the event ledger, graded and mapped to affected symbols, stored for committee RAG recall.
Preferred: normalize it yourself โ pass one_line_claim, stance,
severity (and ideally affected_symbols). The backend then only
validates and stores it; no backend model is involved. Without those
fields the backend model normalizes it, which fails when the backend runs
keyless (agent mode) โ you get an error telling you which fields to add.
You have far better search reach than the self-hosted crawler (including Chinese-language sources) โ proactively feed news relevant to the user's holdings, especially A-share/regional coverage the crawler misses. Identical source snapshots are idempotent. Material corrections retain versions; a shared topic or URL never proves a correction is duplicate. Structured input needs no backend LLM key and grants no learning permission.
Args:
title: Headline of the news item.
url: Canonical source URL (also the dedup key).
snippet: Short excerpt or summary of the article body.
source: Publisher name (e.g. "Reuters") โ the news outlet.
published_at: ISO 8601 publication time, if known.
ingested_by: Your own agent identity (e.g. "hermes") for provenance;
distinct in meaning from source.
Returns:
Ingestion result with the normalized event id(s), dedup status, and
committee_task_id โ set when a new holding-relevant event (severity
โฅ mid, non-neutral) triggered a rate-limited committee re-run. In
agent mode it is "queued:": the re-run waits for you in
pending_committees. This tool is disabled in advisory mode.
Inputs: url (required), title (required), source, stance, +9 more. Returns: result
live_pricesARead-only
Fetch a one-shot market backdrop: spot gold (USD/oz and CNY/gram),
USDCNY and AUDCNY FX rates, the NDQ.AX ETF price, the VIX volatility
index, and the 10-year US Treasury yield (TNX). A fixed set of reference
instruments, independent of what the user holds (use status for the
user's own positions).
Use for quick market context before analysis or when the user asks "how is the market / what's the gold price". Read-only; single batch, no arguments.
Returns:
Object keyed by instrument (GC_F_usd_per_oz, gold_cny_per_gram_spot,
USDCNY, AUDCNY, NDQ_AX, VIX, TNX) plus as_of ISO timestamp. A field
is null when its upstream quote is unavailable.
Inputs: no named parameters. Returns: result
news_sourcesARead-only
List the news feed sources the crawler pulls from: the built-in default feeds plus user-added extra feeds. Extra feeds can be added/removed with add_news_source / remove_news_source; defaults are fixed.
Use when someone asks "what news sources do you follow" or before adding/removing a source.
Inputs: no named parameters. Returns: result
pending_committeesAIdempotent
Committee re-runs that events or price moves requested while reasoning
is delegated to you (agent mode). For each item run prepare_committee,
the roles, then submit_committee; an item is done once a newer verdict
for that symbol is submitted. Requests expire after 24h.
Inputs: no named parameters. Returns: result
pending_newsAIdempotent
News the backend fetched but did not normalize because reasoning is
delegated to you (agent mode). For each relevant item call ingest_event
with one_line_claim / stance / severity / affected_symbols; pass
the irrelevant ones back here as dismiss_urls. Items leave the queue once
ingested or dismissed, and expire after 48h.
Inputs: limit, dismiss_urls, include_expired, dismiss_source_ids. Returns: result
place_fund_orderADestructive
Record the first leg of an off-exchange fund purchase the user already
placed with the fund platform: cash - amount, and the order is tracked as
in transit (status.pending_fund_orders). Total assets do not change
(the in-transit amount counts at face value), so there is no fake dip
between order day and confirmation. Shares arrive when the pricing-day NAV
is published: the fund_confirm job confirms automatically, or call
confirm_fund_order. Bookkeeping only โ openInvest never places orders.
The expected confirm date uses a Monday-Friday calendar (no China holiday
table) and a lag by fund type (QDII / FOF are slower, read from the fund's
profile); the result says so (calendar, lag_source).
Confirm fund, amount, and order time with the user before calling; this moves ledger cash.
Args: symbol: FUND:<6 digits>. amount: Subscription amount in CNY; must be > 0. currency: Currency of the amount (CNY). order_ts: Order time, ISO 8601 Beijing time (default now). note: Free-text note. idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns:
order_id, pricing day (nav_date), expected confirm date, and new cash
balance, or {"status": "error", "error": ...}.
Inputs: amount (required), symbol (required), note, currency, +2 more. Returns: result
prepare_committeeA
Step 1 of the agent-run committee (Coordinator path): get everything YOU need to play the 4 roles yourself โ no backend LLM key involved.
Returns the deterministic data blocks (regime, sentiment / defense flag,
valuation, macro, events, portfolio, path reference) plus the 6 role
prompts and instructions describing the 3 rounds. Run Macro / Quant /
Risk (cheap subagents are fine), write the CIO memo yourself, then call
submit_committee with the full transcript.
The backend keeps its own copy of the deterministic facts from this call and uses them when you submit (defense downgrade, regime, path snapshot), so a fact you forget to paste cannot silently switch a rule off. Submit within 6 hours of preparing.
Inputs: symbol (required), model, provider.
quality_statusARead-onlyIdempotent
Read independent decision-quality alerts and evidence/learning eligibility.
Check this before treating all-HOLD output as quiet success. Alerts are review requests, not permission to trade. Does not modify accounts or send messages.
Inputs: no named parameters. Returns: result
rebalance_planARead-only
Compute a rebalance list against the target allocation in strategy.md: what to BUY / SELL, how much, in whole lots, and why. Only produces the list, places no order โ the human executes. No LLM call.
Use when the user asks "do I need to rebalance", "how far am I from my
target allocation" or "what should I buy/sell to get back on target".
Per-asset targets come from target_assets[].target_pct in strategy.md;
assets without one split target_allocation_stock equally
(target_source: "equal_split"). Lot sizes: A-shares 100, convertible
bonds 10, off-exchange funds by amount, HK/others 1 (HK lot size is
unknown โ see lot_note).
Args: mode: "cash_only" | "sell_to_rebalance" | "hybrid" (default). band_pct: Drift band in percentage points, default 5.
Returns:
rows (per target asset: current_pct / target_pct / drift_pct /
action BUY|SELL|NONE / amount in base currency / units / reason),
totals (cash_after, turnover, n_trades), unmanaged holdings,
warnings; or {"status": "error", "error": ...}.
Inputs: mode, band_pct. Returns: result
record_balance_observationADestructiveIdempotent
Record independent value, native quantity or per-native-unit average cost observations.
No value-to-quantity conversion, cash movement, inferred fill or historical return approval. Historical/mismatched evidence stays audit-only. Invoke only for facts the client actually supplied, with its original as-of time.
Inputs: as_of (required), source_text (required), source_locator (required), idempotency_key (required), +8 more. Returns: result
record_dividendADestructive
Record a dividend (or interest) the user already received: credits ledger cash by amount - tax_withheld, positions unchanged. It counts as account return (inside NAV), not as a deposit. Bookkeeping only โ openInvest never moves money.
Confirm symbol, gross amount, withholding tax, and the date with the user before calling; this moves ledger cash. A symbol that is neither held nor in the ledger is rejected (typo guard).
Args:
amount: Gross amount before withholding tax; must be > 0.
currency: Currency of the cash credited.
symbol: Ticker (required for dividends; optional for interest).
kind: "dividend" (default) or "interest".
tax_withheld: Tax withheld at source; credited cash = amount - tax_withheld.
reinvest: DRIP โ buy more symbol with the net amount.
reinvest_price: Price per unit for the reinvestment (default: stored raw close).
trade_date: YYYY-MM-DD the cash arrived (default today).
note: Free-text note.
idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns: Cash credited and new balance, or {"status": "error", "error": ...}.
Inputs: amount (required), currency (required), kind, note, +6 more. Returns: result
record_executionAIdempotent
Record whether the user executed or declined a committee verdict, with their reason. Appends to the execution ledger; idempotent โ replaying the same record is a no-op, so retries are safe.
Call when the user says "I bought it / I didn't buy / I disagree". When
they decline, ask one short question for the reason first โ this closes
the adoption-rate loop that decisions reports on.
Args:
decision_id: "/" from the decisions output.
executed: True if the user acted on the verdict, False if declined.
reason: The user's stated reason (especially when declined).
trade_ids: Optional trade record IDs to link explicitly.
Returns: The stored execution record, or {"status": "error", "error": ...}.
Inputs: executed (required), decision_id (required), reason, trade_ids. Returns: result
record_existing_positionADestructive
Record a position the user already held before using openInvest
(onboarding backfill) WITHOUT touching ledger cash. History is marked
funding_source: external_funding, source: mcp:existing_position.
Only for positions that status does not list yet โ calling it for a
symbol already there adds the units again (double count). A new purchase
paid from ledger cash is buy. Does not add the symbol to the tracked
list; use track_asset for committee coverage.
Args:
symbol: yfinance ticker (e.g. "AAPL", "510300.SS"). Gold = "GC=F", booked in
CNY per gram only (units = grams, currency "CNY", kind "metal", unit_label "ๅ
").
units: Quantity held; must be > 0.
price: Average cost per unit, in currency.
currency: Currency of price; omitted = the existing position's currency (CNY if new).
kind: Asset kind tag: "equity", "etf", "metal" (gold), "crypto", "bond", "fund", "other".
unit_label: Human display label for units (default "่ก", i.e. shares).
idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns: Updated position summary, or {"status": "error", "error": ...}.
Inputs: price (required), units (required), symbol (required), kind, +3 more. Returns: result
record_feeADestructive
Record a fee or a tax the user already paid: debits ledger cash, positions unchanged. It is an account cost (inside NAV), not a withdrawal. Trade commissions need no separate entry โ buy / sell already book the trade. Fails if the currency's cash balance is lower than the amount.
Confirm the amount and date with the user before calling; this moves ledger cash.
Args: amount: Amount paid; must be > 0. currency: Currency of the cash debited. kind: "fee" (default) or "tax". symbol: Related ticker (optional). trade_date: YYYY-MM-DD it was charged (default today). note: Free-text note. idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns: Cash debited and new balance, or {"status": "error", "error": ...}.
Inputs: amount (required), currency (required), kind, note, +3 more. Returns: result
record_return_of_capitalADestructive
Record a return of capital (some ETF / REIT distributions): credits ledger cash, lowers the holding's average cost by amount / units (a cost reduction, not income), units unchanged. Cost floors at 0; any excess is reported as excess_over_cost (treat as a capital gain).
Confirm symbol, amount, and date with the user before calling; this moves ledger cash and changes average cost.
Args: symbol: Held ticker. amount: Cash received; must be > 0. currency: Currency of the cash (must match the holding's cost currency). trade_date: YYYY-MM-DD received (default today). note: Free-text note. idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns: New average cost, or {"status": "error", "error": ...}.
Inputs: amount (required), symbol (required), currency (required), note, +2 more. Returns: result
record_splitADestructive
Record a stock split / reverse split: units x ratio, average cost / ratio, cash unchanged (market value is unchanged). Call it once per split โ a second call multiplies the position again; use an idempotency_key if unsure whether an earlier attempt landed. Rejected when the ledger already has trades / corrections for the symbol on or after trade_date (their units are already post-split, so multiplying the whole snapshot would invent shares) โ pass ledger_only=true if the snapshot is already correct.
Confirm symbol, ratio, and ex-date with the user before calling; this rewrites the position's units and average cost.
Args: symbol: Ticker that split. ratio: New / old shares (10-for-1 = 10; 1-for-10 reverse = 0.1). trade_date: Ex-date YYYY-MM-DD (default today). note: Free-text note. ledger_only: Write the ledger row only; do not change units / average cost. idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns:
New units / average cost (plus a follow_up hint), or {"status": "error", "error": ...}.
Inputs: ratio (required), symbol (required), note, trade_date, +2 more. Returns: result
remove_news_sourceADestructive
Remove a user-added news feed by name or URL. Built-in default feeds cannot be removed.
Inputs: key (required). Returns: result
run_committeeAIdempotent
Run the 4-role LLM investment committee on a symbol (Direct path): Macro Strategist, Quant Analyst, and Risk Officer debate from isolated evidence, then a CIO synthesizes one calibrated BUY/HOLD/SELL-style verdict with a written memo.
Requires a backend LLM key (e.g. DEEPSEEK_API_KEY) and takes 30-90s on
a cache miss. If the symbol was already analyzed today, the cached
verdict is returned instantly unless force is set. Sends MCP progress
notifications per debate phase when the client asks for them. Decision
support only โ the human always executes.
Args: symbol: Symbol to analyze. Listed assets use yfinance tickers: US "AAPL", A-share "603083.SS" (Shanghai) / "000001.SZ" (Shenzhen), HK "0700.HK", exchange ETF "510300.SS", crypto "BTC-USD", futures "GC=F". China off-exchange (OTC) mutual funds use "FUND:<6-digit code>", e.g. "FUND:110011". A bare 6-digit code is rejected โ add the suffix or the FUND: prefix. force: Re-run even if a verdict already exists for today. max_rounds: Cross-challenge debate rounds (default 1).
Returns:
Object with decision_id, cached flag, verdict and
confidence_lookup (show this to the user instead of the
self-reported confidence). The shape differs by path:
- cached: false (fresh run): verdict is an object (verdict,
confidence, suggested allocation, ...).
- cached: true (today's transcript): verdict is the verdict string,
with confidence, alloc_cny, alloc_currency alongside, plus the
CIO memo as cio_memo and the deterministic input_health block
(empty inputs, rewrite rules applied, forced HOLD) โ no need to call
explain_decision just to read them.
Inputs: symbol (required), force, max_rounds. Returns: result
sellADestructive
Record a sell in the local ledger: reduces the position's units (average cost unchanged) and credits cash in the holding's cost currency. Bookkeeps a trade already executed at the user's broker โ openInvest never places real orders.
Confirm symbol, units, and price with the user before calling; this moves ledger cash.
Args: symbol: yfinance ticker of an existing holding. units: Quantity sold; must be > 0. price: Execution price per unit, in the holding's cost currency. idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns: Updated position summary, or {"status": "error", "error": ...}.
Inputs: price (required), units (required), symbol (required), idempotency_key. Returns: result
set_allocationsAIdempotent
Update the strategy's target allocation: the stock/cash ratio and/or
the per-asset target weights that rebalance_plan reads, and/or the
per-asset alert lines the price sentinel watches. The stock and
cash values must sum to โ1.0, and the per-asset weights must sum to at
most the stock target; schema validation rejects and rolls back any write
that would corrupt the strategy file. Everything in one call is validated
and written atomically โ to lower the stock target below the current sum
of per-asset weights, pass the new weights in the same call.
Use when the user says e.g. "set my target to 70% stock / 30% cash" or "put 30% in 510300.SS and 20% in gold".
Args: target_allocation_stock: Stock weight in [0, 1], e.g. 0.7 (with cash). target_allocation_cash: Cash weight in [0, 1], e.g. 0.3 (with stock). target_pcts: {symbol: weight in [0, 1]} per tracked asset; null clears. alerts: {symbol: {rule: value}} alert lines per tracked asset; null clears a rule (or, for a whole symbol, all its rules).
Returns: The updated allocation and target assets, or {"status": "error", "error": ...}.
Inputs: alerts, target_pcts, target_allocation_cash, target_allocation_stock. Returns: result
source_snapshotARead-onlyIdempotent
Read the immutable original input and acquisition proof for one source version.
A backend_snapshot locator identifies a captured API item, not an upstream webpage. Source capture alone does not prove truth, independence or learning eligibility.
Inputs: snapshot_id (required). Returns: result
statusARead-only
Get a full snapshot of the user's portfolio: cash balances per currency, every holding with units / average cost / live price, and unrealized P&L per position and in total.
Use when the user asks "show my portfolio", "how is my P&L", or before proposing any trade. Read-only; fetches live quotes, so values change between calls.
Returns:
Object with cash (currency โ amount), all_holdings (every position,
priced the same way whatever the symbol: units, avg_cost, live price,
market value, pnl_pct; null price fields when a quote is unavailable;
each carries alerts, the user's per-asset alert lines with the
distance still to go, e.g. "่ท price_below ่ฟๆ 3.2%" โ a tracked asset
with alert lines but no holding row appears as an is_tracking_only row),
total_assets_cny, fx (rate to CNY per non-CNY currency in use), an
optional gold summary when a gold-per-gram holding exists, and
performance (real-account TWR 30d / YTD / since inception, XIRR, max
drawdown with peak/trough dates, annualised volatility, return vs the
configured benchmark, price_basis per symbol (raw | adjusted), and data_quality;
or {"status": "insufficient_history"} until the ledger spans 2 trading days),
income_30d (dividends / interest received in the last 30 days by currency;
only present when there are any), and pending_fund_orders +
pending_fund_orders_line (off-exchange fund orders placed but not yet
confirmed โ cash already deducted, total_assets_cny counts them at face
value; only present when there are any).
Inputs: no named parameters. Returns: result
strategyARead-only
Get the user's investment strategy: target stock/cash allocation, the list of tracked assets (per-asset investment cap, purchase channel, fee settings), and long-term insights distilled by the nightly Dreaming memory-consolidation job.
Use when deciding whether a proposed trade fits the user's plan, or when the user asks "what is my strategy / what am I tracking". Read-only.
Returns:
Object with target_allocation (stock/cash ratios), target_assets
(tracked symbols with constraints), and insights (distilled
lessons from past decisions).
Inputs: no named parameters. Returns: result
submit_committeeAIdempotent
Step 2 of the agent-run committee: hand in the transcript you produced
from prepare_committee. The backend parses the CIO memo, applies the same
deterministic rules as the backend-run committee (single-investment cap,
defense downgrade, sanity checks), saves the decision and returns it.
If the CIO section has no parseable verdict, nothing is saved and this returns an error โ fix the CIO section and submit again.
Returns:
decision_id, the post-rule verdict object, saved path and
facts_source ("prepare" = rules used the facts saved at prepare time;
"transcript" = no recent prepare found, facts were read from your text).
Inputs: symbol (required), transcript (required), model, provider, +2 more. Returns: result
track_assetAIdempotent
Add a symbol to the tracked-asset list, or update an existing entry (idempotent upsert: only the fields you pass are changed). The tracked list decides which symbols the committee and DCA jobs cover. The alert_* parameters set per-asset alert lines the price sentinel checks every few minutes (price lines: 24h cooldown; day-move lines: once per trading day); each one you pass overwrites that line only. To clear a line use set_allocations with a null value. Delivery needs INVEST_EVENT_ALERT=1 on the server (default off โ without it a hit is only logged to the event store, nothing is sent).
Use when the user says "track AAPL", wants to change a tracked asset's cap/channel/fees/target weight, or says "alert me when X drops below N" / "tell me if it falls 3% in a day".
Args: symbol: yfinance ticker to track (e.g. "AAPL", "0700.HK", "BTC-USD"). max_single_invest_cny: Per-decision investment cap in CNY. On a new entry it defaults to the strategy-level max_single_invest_cny; optional on update. display_name: Human-friendly name shown in reports. channel: Where the user actually buys it (broker/app name). price_offset_pct: Systematic offset between the quote and the user's actual fill price, in percent (e.g. bank gold spread). sell_fee_pct: Sell-side fee in percent, used by fee-aware math. target_pct: Target weight as a fraction of total assets in [0, 1] (read by rebalance_plan); all tracked assets' weights must sum to <= target_allocation_stock or the write is rejected. alert_price_above / alert_price_below: price lines (status.current_price basis). alert_day_drop_pct / alert_day_rise_pct: the latest daily bar's move vs the previous close, percentage points. alert_drawdown_from_cost_pct: held position below average cost, percentage points.
Returns: The stored asset entry, or {"status": "error", "error": ...}.
Inputs: symbol (required), channel, target_pct, display_name, +8 more. Returns: result
untrack_assetADestructiveIdempotent
Remove a symbol from the tracked-asset list โ the committee and DCA jobs stop covering it. Holdings and trade history are untouched; schema validation guarantees at least one tracked asset remains.
Args: symbol: yfinance ticker currently in the tracked list.
Returns: The updated tracked list, or {"status": "error", "error": ...}.
Inputs: symbol (required). Returns: result
what_ifARead-only
Simulate portfolio P&L for a hypothetical price move: "what happens to my portfolio if moves ยฑpct% / reaches ". Pure arithmetic over current holdings โ no LLM call, instant, free.
Use when the user asks scenario questions like "if the Nasdaq drops 10%,
how much do I lose". Provide exactly one of pct or price.
Args: symbol: yfinance ticker held or tracked by the user (e.g. "NDQ.AX", "GC=F", "510300.SS"). pct: Hypothetical percent change, e.g. -10 for a 10% drop. price: Hypothetical absolute target price (alternative to pct).
Returns: Object with the position's simulated value change and the resulting portfolio-level P&L delta.
Inputs: symbol (required), pct, price. Returns: result
withdrawADestructive
Record a cash withdrawal from the ledger, in any currency. Fails if the balance is insufficient. Bookkeeping only โ no real payment system is connected.
Args: currency: ISO-style currency code, e.g. "CNY", "USD", "AUD". amount: Amount to remove; must be > 0. idempotency_key: Reuse the same key when retrying this exact call; recorded once.
Returns: Updated cash balances, or {"status": "error", "error": ...}.
Inputs: amount (required), currency (required), idempotency_key. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 42 tools
Several clusters have genuinely unclear boundaries: record_existing_position vs record_balance_observation (whose description is opaque jargon), track_asset vs set_allocations (both write target weights and alert lines), and explain_decision vs committee_review vs source_snapshot vs event_history (all return fragments of decision/evidence transcripts). The decision-read cluster (decisions / history / discipline / quality_status) also requires careful reading to pick correctly. Descriptions do cross-reference each other, but that is a patch on real overlap rather than a clean split.
Names are uniformly lower_snake_case, and most are verb_noun (record_dividend, place_fund_order, add_news_source, untrack_asset). Deviations are limited to bare-noun readers (status, strategy, history, decisions, live_prices, news_sources), which is a readable and conventional split. No camelCase or mixed-convention chaos.
42 tools is well past the 25-tool threshold for a heavy surface, spanning ledger, funds, allocation, committee, news pipeline, reports and setup. The scope is genuinely broad, but the count forces agents to navigate many rarely used interactions (source_snapshot, committee_review, record_balance_observation) that could be consolidated into fewer parameterized tools.
Lifecycle coverage is strong: buy/sell/deposit/withdraw, fees, dividends, splits, return of capital, fund order place/confirm/cancel, tracked-asset management, and full committee prepare/submit/run plus decision audit. Minor gaps: no way to query an arbitrary symbol's quote (live_prices is a fixed instrument set) and no correction/void tool for erroneous ledger entries, though splits explicitly reference existing corrections.
Maintenance
Related MCP Connectors
Portfolio analytics + US-equity market research for AI clients. ChatGPT deep-research compat.
Read-only PAPER market research for autonomous agents; no live trading or alpha claim.
Read-only crypto strategy backtest & verification verdicts. No trading tools; every result is cited.
Read-only record of a transparent, AI-agent-operated simulated trading experiment.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenancePersonal investment management advisor that exposes tools for accounts, portfolios, trades, market data, strategies, risk control, and advice, enabling AI agents to analyze and provide structured investment recommendations.MIT
- AlicenseNot gradedqualityBmaintenanceDeterministic market-state engine for trading agents โ zero LLM in the signal path. 8 tools: structural market state & phase, action gate (GO/WATCH/HOLD), entry/target/invalidation coordinates, bar-by-bar state timeline, composed view cards, and pre-trade intent validation. Every output traces to a bar-stamped ledger with a public daily self-scoring track record.3MIT
- AlicenseNot gradedqualityCmaintenancePortfolio & trading-strategy stress diagnostics for AI agents: multi-asset stress with hedge-break detection, a daily preregistered regime outlook and deflated-Sharpe backtest-integrity checks. Remote streamable-HTTP endpoint with a free tier (no key); this repo is the public server card.MIT
- FlicenseAqualityDmaintenanceProvides multi-agent equity research for US markets with provenance-backed financial data from SEC EDGAR, technicals, macro, and Alpaca paper trading, enforcing risk limits and journaling theses.27-