Helium MCP Server - News, Markets & AI

Returns sources active within the last 36 days with >100 articles analyzed, sorted by
avg_social_shares descending. The response also includes total, offset, limit, has_more,
and one shared bias_score_methodology block.

Each entry contains:
- source_name, slug_name, page_url
- articles_analyzed: total articles analyzed for this source
- avg_social_shares: average social shares per article (proxy for reach/influence)
- emotionality_score (0-10): average emotional intensity of the writing
- prescriptiveness_score (0-10): how much the source tells readers what to think/do
- bias_values: dict mapping classifier key → integer source weighted display score
  (-50 to +50 for bipolar, 0 to +50 for unipolar). Keys use the same canonical
  names as get_bias_from_url where a source aggregate is available, but article scores use
  -10 to +10 or 0 to 10. Compare direction directly; normalize before comparing magnitude.

  Political / ideological (bipolar: neg=left pole, pos=right pole):
    'liberal conservative bias'      neg=liberal, pos=conservative
    'populist elitist bias'           neg=populist, pos=elitist
    'libertarian authoritarian bias' neg=libertarian, pos=authoritarian
    'dovish hawkish bias'            neg=dovish, pos=hawkish
    'establishment bias'             neg=anti-establishment, pos=pro-establishment

  Credibility / quality (bipolar):
    'overall credibility'            neg=low credibility, pos=high credibility
    'integrity bias'                 neg=low integrity, pos=high integrity
    'article intelligence'           neg=low intelligence, pos=high intelligence
    'delusion bias'                  neg=truth-seeking, pos=delusional
    'objective subjective bias'      neg=objective, pos=subjective
    'objective sensational bias'     neg=objective, pos=sensational
    'descriptive prescriptive bias'  neg=descriptive, pos=prescriptive
    'bearish bullish bias'           neg=bearish, pos=bullish
    'interesting'                    neg=boring, pos=interesting
    'emotional bias'                 neg=negative tone, pos=positive tone
    'rational irrational bias'       neg=rational, pos=irrational
    'corporate bias'                 neg=anti-corporate, pos=pro-corporate
    'science superstition bias'      neg=scientific, pos=superstitious
    'individualist collectivist bias' neg=individualist, pos=collectivist

  Unipolar bias dimensions (higher = more of that trait):
    'opinion bias'                   opinion vs informative
    'political bias'                 political content
    'fearful bias'                   fear-based framing
    'overconfidence bias'            overconfidence
    'gossip bias'                    gossip
    'manipulation bias'              manipulative framing
    'ideological bias'               ideological rigidity
    'conspiracy bias'                conspiracy content
    'double standard bias'           double standards
    'virtue signal bias'             virtue signaling
    'oversimplification bias'        oversimplification
    'appeal to authority bias'       appeal to authority
    'begging the question bias'      question-begging
    'victimization bias'             victimization framing
    'terrorism bias'                 terrorism content
    'marxism bias'                   Marxist framing
    'islamist bias'                  Islamist framing
    'anti-semitism bias'             anti-Jewish framing
    'anti-lgbt bias'                 anti-LGBT framing
    'racism bias'                    racist framing
    'anti-enlightenment bias'        regressive, anti-liberal content
    'scapegoat bias'                 scapegoating
    'hypocrisy bias'                 hypocrisy
    'suicidal empathy bias'          suicidal-empathy framing
    'cruelty bias'                   cruelty
    'woke bias'                      woke framing
    'written by AI'                  AI-written likelihood
    'immature bias'                  immaturity
    'circular reasoning bias'        circular reasoning
    'covering the response bias'     covering-the-response tactic
    'spam bias'                      spam-like content
    'advertising bias'               advertorial or promotional content
    'speculation bias'               speculation or forecasting

Tip: use get_source_bias for full narrative descriptions and recent articles on a specific source.
Tip: bias_values use shared canonical names where available. Source and article score scales
differ, so normalize magnitudes.
get_source_bias exposes the same canonical keys in bias_values and retains emoji-prefixed
bias_scores only for backward compatibility.

Args:
    limit: Sources to return (1-1000, default 200).
    offset: Number of sources to skip for pagination (default 0).

Use this when you have a direct link to an article and want to know its political leaning,
credibility, emotionality, and other bias dimensions — without needing to know the source name first.

On success (found=true), returns:
- article_id, classification_id, requested_url, matched_url, title, source, date, link, category
- teaser: article excerpt
- summary: one-sentence AI summary
- context: AI-generated context for the article
- extracted_data: structured quantitative/qualitative facts extracted from the article
- raw_data: legacy serialized form of extracted_data
- bias_description: narrative description of this specific article's bias
- bias_values: dict of per-dimension article scores using canonical plain-text keys,
  e.g. {"liberal conservative bias": 4, "overall credibility": 7, "emotional bias": -5, ...}
  Article scores use -10 to +10 for bipolar dimensions and 0 to 10 for unipolar dimensions.
  Positive values lean toward the second pole of each dimension (conservative, authoritarian, etc.).
- bias_analysis_status: 'evidence_ready', 'evidence_unverified', 'evidence_partial',
  'scored_legacy', or 'pending'
- bias_dimensions when include_evidence=true: each dimension's score, scale, evidence status,
  claim, verbatim evidence, counterevidence, confidence, and rationale. Quotes include
  verification method and exact character offsets when raw-text matching succeeds.
  Dimension evidence_status is one of: verified, provided_unchecked, quote_mismatch,
  metadata_incomplete, metadata_only, or missing.
- bias_analysis: contract/schema/model/prompt provenance, generation and review status,
  input scope/hash/size, analysis target, quote-verification method, explicit missingness
  and evidence coverage, and case-specific limitations
- total_shares: total social shares
- wayback_link: Wayback Machine archive URL if available
- image: article image URL if available

On failure (found=false, HTTP 404):
- found: false
- message: explanation string
The URL is automatically queued for ingestion; retry after ~24 hours.

Tip: if you want source-level bias (not article-level), use get_source_bias instead.
Tip: bias_values keys here use plain-text format (e.g. 'liberal conservative bias') shared
with the other bias tools where that dimension is available.

Args:
    url: Full article URL, e.g. 'https://www.nytimes.com/2024/01/01/us/politics/example.html'.
    include_evidence: Include claim-level evidence and limitations. Defaults to true.

Returns the complete options chain including all expirations and contracts,
with bid, ask, mid prices, greeks, and Helium's proprietary model values
(helium_theo, helium_pitm, should_i_buy, should_i_sell, terminal_buy_pl,
terminal_sell_pl, etc.) baked into each contract.

Returns:
- symbol, date, data_source ('recent' or 's3')
- num_expirations: number of distinct expiration dates
- total_contracts: total number of option contracts
- option_chain: dict keyed by expiration index, each value is a list of option contracts

Each contract includes fields like: putCall, symbol, description, bid, ask, mark,
mid_price, strikePrice, expirationDate, daysToExpiration, delta, gamma, theta, vega,
impliedVolatility, openInterest, volume, helium_theo, helium_pitm, should_i_buy,
should_i_sell, terminal_buy_pl, terminal_sell_pl, and more.

Args:
    symbol: Ticker symbol, e.g. 'AAPL', 'TSLA', 'SPY'.
    date: Date in YYYY-MM-DD format, e.g. '2026-04-10'.

Helium trains per-symbol regression models on historical options data. This tool
looks up the most recent available options chain for the symbol (today or up to
5 days back), finds the exact contract matching strike/expiration/type, and runs
it through that model to produce a predicted fair-value price.

Returns:
- symbol: the ticker
- strike: the strike price used
- expiration: the expiration date used
- option_type: 'call' or 'put'
- predicted_price: Helium's model-predicted option price in dollars
- prob_itm: probability of expiring in the money (0.0–1.0), or null if model unavailable
- options_data_date: the date of the options chain snapshot the model was run on
  (so you know how fresh the underlying market data is)

Throws an error if no options chain data is available for the symbol within the past 5 days,
or if the exact contract (strike/expiration/type combination) does not exist in that chain.

Args:
    symbol: Ticker symbol, e.g. 'AAPL', 'SPY'.
    strike: Strike price as a number, e.g. 150.0.
    expiration: Expiration date as 'YYYY-MM-DD', e.g. '2026-06-20'.
    option_type: Must be 'call' or 'put'.

Returns:
- source_name, slug_name, page_url
- source_match: original query and deterministic match method
- articles_analyzed: total articles in the bias database for this source
- last_updated: source-profile aggregation timestamp
- avg_social_shares: average social shares per article
- emotionality_score (0-10): how emotional the writing is
- prescriptiveness_score (0-10): how much the source tells readers what to think/do
- bias_values: canonical plain-text source-level weighted display scores (-50 to +50 bipolar,
  0 to +50 unipolar). Keys match the article tools; these are directional source summaries,
  not raw article-score averages.
- bias_scores: legacy emoji-prefixed display scores
- bias_score_methodology: scope and evidence caveats for aggregate scores
- bias_description: clean-text, AI-generated overall bias summary narrative
- bias_description_metadata: generation time, automated review status, and evidence scope
- bias_description_html: optional website HTML when include_html=true
- liberal_conservative_description: narrative on political leaning
- libertarian_authoritarian_description: narrative on authority stance
- signature_phrases: words/phrases uniquely overrepresented vs other sources
- signature_negative_phrases: uniquely negative/alarming phrases
- most_shared_phrases: phrases in their most viral articles
- most_emotional_phrases: phrases used in their most emotional articles
- pays_for_traffic_keywords: keywords this source buys ads for
- similar_sources: sources with the most similar bias profile
- most_different_sources: sources with the most different bias profile
- trends_graph_url: URL to a chart of this source's coverage volume over time
- bias_plot_urls: dict of 2D bias scatter plot image URLs (political_lib_auth, subjective_objective, informative_opinion, oversimplification_factful) — only present when available
- recent_articles: list of most recent articles with full article fields, bias_values,
  analysis status, and optional self-contained bias_dimensions and bias_analysis.
  Evidence quotes include verification method and exact character offsets when available.
- recent_evidence_coverage: reconciled counts for verified, unverified, partial,
  legacy-scored, and pending articles, plus evidence-bearing count and verified ratio

Throws an error if the source is not found.

Args:
    source: Source name, slug, or domain (e.g. 'Fox', 'reuters', 'bbc.co.uk').
            Partial names are accepted only when they identify one source; ambiguous input returns candidates.
    recent_articles: Number of recent articles to include (1-50, default 10).
    include_evidence: Include per-article claims, verbatim evidence, counterevidence,
                      confidence, rationale, and limitations. Defaults to false to keep
                      multi-article source payloads compact.
    include_html: Also return the original website-formatted source narrative. Defaults to false.

Returns:
- ticker, name, type (e.g. 'stock', 'etf', 'crypto'), industry
- latest_price, page_url
- bullish_case, bearish_case, potential_outcomes, takeaway, analysis_date (AI-generated)
- price_forecast_days, price_forecast_percent, price_forecast_lower/upper_bound_percent (model price forecast)
- future_uncertainty_urls: dict with image URLs for future_uncertainty, term_structure, volatility_surface, return_profile (when available)
- future_uncertainty_last_updated, term_structure_last_updated
- iv_rank_percentile (0-100, IV rank over past year)
- long_vol_call, long_vol_put, short_vol_call, short_vol_put: full option pack dicts (when available)

Throws an error if the ticker is not recognized.

Args:
    ticker: Ticker symbol, e.g. 'AAPL', 'AMZN', 'BTC', 'ETH', 'SPY'.

Returns two ranked lists — short_volatility (sell premium / theta strategies) and
long_volatility (buy premium / gamma strategies) — each containing up to `limit` tickers.

Each entry has the same fields as get_ticker:
- ticker, name, latest_price, page_url
- bullish_case, bearish_case, potential_outcomes, takeaway, analysis_date (AI-generated, when available)
- price_forecast_days, price_forecast_percent, price_forecast_lower/upper_bound_percent (when available)
- iv_rank_percentile (0-100, IV rank over past year, when available)
- short_vol_call, short_vol_put: best short volatility option packs (when available)
- long_vol_call, long_vol_put: best long volatility option packs (when available)

Sort options:
- "helium_rank" (default): Helium AI edge score — best overall expected value
- "odds_of_profit": Highest probability of profit
- "historical_performance": Best annualized historical P&L across backtested trades
- "reward_to_risk": Best reward-to-risk ratio
- "smallest_max_loss": Strategies with the smallest maximum possible loss

Args:
    sort: Ranking method (default "helium_rank"). One of: 'helium_rank', 'odds_of_profit',
          'historical_performance', 'reward_to_risk', 'smallest_max_loss'.
    limit: Number of results per strategy type (1-20, default 5).

Unlike search_news (which returns individual RSS articles), this returns Helium's own
synthesized stories: each one draws from multiple sources and includes an AI-written
summary, takeaway, context, evidence breakdown, potential outcomes, and relevant tickers.

Returns a list of stories, each with:
- title, simple_title, date, category
- page_url: full URL to the story on heliumtrades.com
- image: story image URL (when available)
- summary: Helium's synthesized overview
- takeaway: key conclusion
- context: background context
- evidence: numbered evidence items
- potential_outcomes: forward-looking outcomes with probabilities
- relevant_tickers: related stock tickers
- num_sources: number of source articles synthesized
- rank: search relevance score

Args:
    query: Search keywords (required).
    limit: Max results (1-50, default 10).
    category: Filter by category. One of: 'tech', 'politics', 'markets', 'business', 'science'.
    days_back: Only include stories from the last N days. 0 means no date filter.

Returns matching memes ranked by relevance. Each result includes:
- id, caption, ocr (text extracted from the image)
- image: full URL to the meme image
- source: origin platform (e.g. 'reddit')
- num_likes: likes/upvotes on the original post
- date, is_video, rank

Args:
    query: Search keywords (required). Matched against OCR text and captions.
    limit: Max results (1-100, default 20).
    days_back: Only include memes from the last N days. 0 means no date filter (default).

Returns a list of matching articles. Each article includes:
- article_id, classification_id, title, source, date, link, category, rank, total_shares, summary
- bias_values: dict of per-dimension bias scores using plain-text keys (e.g. 'liberal conservative bias'),
  same schema as get_bias_from_url and get_all_source_biases (when available)
- bias_analysis_status: 'evidence_ready', 'evidence_unverified', 'evidence_partial',
  'scored_legacy', or 'pending'
- bias_dimensions when include_evidence=true: a self-contained object joining each score,
  scale, evidence status, claim, evidence, counterevidence, confidence, and rationale.
  Quotes include verification method and exact character offsets when raw-text matching succeeds.
  Dimension evidence_status is one of: verified, provided_unchecked, quote_mismatch,
  metadata_incomplete, metadata_only, or missing.
- bias_analysis: contract/schema/model/prompt provenance, generation and review status,
  input scope/hash/size, limitations, quote-verification method, and explicit evidence coverage
- context: AI-generated contextual background for the article (when available)
- extracted_data: structured quantitative/qualitative facts extracted from the article
- raw_data: legacy serialized form of extracted_data

Args:
    query: Search keywords (required).
    limit: Max results (1-100, default 20).
    source: Filter by source name, e.g. 'CNN', 'Reuters'.
    category: Filter by category. One of: 'trending', 'tech', 'markets', 'politics',
              'business', 'science', 'memes'.
    days_back: Only include articles from the last N days. 0 means no date filter. Default: 720 (2 years).
    min_shares: Minimum total social shares.
    sort: Sort order. One of: 'rank' (relevance, default), 'date' (newest), 'shares' (most shared).
    include_evidence: Include claim-level evidence, counterevidence, confidence, rationale, and limitations.
                      Defaults to false to keep search payloads compact.
    only_analyzed: Return only articles with valid canonical bias scores.