ai.mrmarket/mrmarket-mcp

getting_started

Onboarding tour for mrmarket.ai — call this FIRST in a fresh session, or any time the user asks "what can you do?" / "how does this work?". Zero LLM cost, zero credits, returns a structured orientation packet (tools, capabilities, limits, examples, troubleshooting, help). Default scope ('overview') covers everything in a short tour. Optional `topic` deep-dives a single area without re-fetching the whole thing: - tools → tool-by-tool reference for query_data, describe_data, get_symbols, get_account_status, report_issue. - examples → 20+ verified working prompts grouped by use case (screens, rankings, comparisons, cohort-relative, time-series, event-vs-price). - limits → universe, freshness, what is NOT supported (intraday, options, news, backtests in one call). - cost → credit model, which tools are free, how to read `credits_remaining`. - troubleshoot → error_code → recipe (RATE_LIMITED, INSUFFICIENT_CREDITS, QUERY_NOT_UNDERSTOOD, empty result, wrong-looking answer). - help → links + how to reach support; preferred channel is `report_issue`. Use it to bootstrap your understanding of the server before asking real questions — that's the fastest path to a useful first answer for the user.

query_data

YOU ARE a research assistant helping a retail investor get answers from mrmarket.ai. You are NOT a database engineer. Ask questions the way a financial analyst would say them out loud — plain English, focused on intent. The server has a domain-trained financial expert that translates your question into the right methodology, picks appropriate thresholds, and documents every interpretation in the response so the user can see and correct what was assumed. Answers analytical financial questions about US-listed equities in a single call. Send the full natural-language question — not SQL. Returns structured rows + columns. CAPABILITIES — all handled in one call: - Top-N / bottom-N rankings by any metric - Multi-criteria stock screens (combine sector, ratios, growth thresholds, insider activity) - Computed financial metrics: ROIC, FCF, D/E, margins, ROE, ROA, dividend yield, growth rates - Derived metrics composed on the fly: any ratio of two fields, growth of any metric, rolling stats on any series — the data catalog lists ingredients, you may mix them - Period-over-period changes: QoQ, YoY, multi-year - Rolling averages, trend slopes, volatility, beta vs a benchmark, correlation, median/percentiles, quartile buckets, max drawdown, statistical measures - Multi-symbol comparisons and time-series trends - Sector/industry rollups and averages - Cohort-relative analysis (vs sector average, vs universe z-score) - Forward returns after events (earnings beats, insider buys) - Price charts with event overlays (earnings dates, insider transactions) - Consecutive-quarter screening (e.g., 4 quarters of growing FCF) EXAMPLES — notice how these read like a human asking, not a technical specification: - "Top 20 stocks by ROIC excluding financials" - "Companies with 4 consecutive quarters of growing free cash flow" - "Compare AAPL, MSFT, and GOOGL revenue over the last 5 years" - "Stocks whose ROIC is at least 1 standard deviation above their sector average" - "Average 30-day stock return after companies beat earnings by more than 10%" - "AAPL daily closes for the last 5 years with earnings dates overlaid" - "Top 20 quality compounders by 5-yr ROIC stability and margin trend" - "Find undervalued stocks with recent insider buying — low P/E, strong FCF, low debt" - "Average stock return 90 days after large CEO insider purchases" HOW TO PHRASE YOUR QUESTION — this matters for best results: Pass the user's question through with minimal rewording. The server's financial expert interprets casual language better than you can translate it: - "large purchase" → appropriate dollar threshold (documented in assumptions[]) - "90 days" → trading-day equivalent (documented in assumptions[]) - "CEO" → executive title matching - "growing" → positive AND increasing - "cheap" / "undervalued" → appropriate valuation thresholds - "Buffett screen" / "quality compounder" → recognized analytical frameworks DO: ✓ Preserve the user's intent and language faithfully ✓ Use directional terms: "low P/E", "strong cash flow", "high margins" ✓ Add thresholds ONLY when the user stated them explicitly ✓ Ask for aggregated answers when the user wants a summary ("average return after...") ✓ Combine multi-criteria screens into ONE question, not separate calls DON'T: ✗ Invent numeric thresholds the user didn't specify — the server picks sensible defaults and surfaces them in assumptions[] so the user can adjust ✗ Specify column lists — the server selects the most relevant columns automatically ✗ Convert calendar days to trading days — the server handles this ✗ Add metrics or time ranges the user didn't request — adds complexity and risk ✗ Use AND/OR boolean syntax — plain English works better ✗ Prefix with jargon like "Event study:" or "Screen:" — just ask the question GOOD: "Find undervalued stocks with recent insider buying — low P/E, strong FCF, low debt" BAD: "Screen for companies where insiders have made open-market stock purchases in the past 3 months AND P/E ratio below

fetch_page

Fetch the NEXT page of a large query_data result — FREE (zero credits, runs no new query). Only use this when a prior query_data (or fetch_page) response had `truncated: true` and a `pagination.next_cursor`. When to call: the user genuinely needs MORE of the raw rows than page 1 returned. If a summary, ranking, or the first rows already answer the question — or you only needed an aggregate (the response carries a full-dataset `summary` on page 1) — you are DONE; do NOT paginate. Pass the cursor string from `pagination.next_cursor` VERBATIM — do not edit or truncate it. Keep calling fetch_page with each new `next_cursor` until it is null. Snapshots live ~15 minutes; if the cursor has expired, re-run the original question.

describe_data

Data catalog — zero cost. Use BEFORE query_data when you're unsure what data is available or whether a specific field or metric is supported. The catalog lists RAW INGREDIENTS; query_data accepts RECIPES. Any field can be combined with any other in one question — ratios of two fields, growth of any metric, rolling stats, group medians, cohort-relative z-scores, benchmark-relative betas. A metric missing from the catalog by name is still answerable if it's computable from the fields (the overview's `composition` section lists the patterns). Scopes: - overview → list all data categories (prices, financials, earnings, insider transactions, etc.) + coverage depth + key fields + computed metrics + composition patterns. Good first call. - category → full field list for one data category. Pass entity with the category name: 'Stock Prices', 'Income Statements', 'Earnings', etc. - computed_metrics → pre-defined computed metrics (ROIC, FCF yield, D/E, ROE, ROA, margins, growth/CAGR, volatility, drawdown, beta, z-score, median…). - search → keyword search across field names, categories, computed metrics, and composition patterns. Pass search_term: 'volatility', 'capex', etc.

get_symbols

Fast company/sector/industry lookup. Sub-50ms, zero LLM cost. Use to resolve names → tickers, list sector members, or get the full universe before fanning out query_data calls (e.g., for backtests or per-symbol price pulls). Actions: search | list_sectors | list_industries | by_sector | by_industry | all.

get_account_status

Account snapshot — zero LLM cost, no credits charged. Returns which mrmarket.ai account this MCP connection is authorized as (email), the plan tier, the current credit balance (and subscription vs top-up split), and per-tier query limits. Use this to (a) confirm the expected account is connected — a mismatch here explains an unexpected "out of credits", and (b) check the credit balance before running a batch of queries.

No parameters.

recent_queries

List the user's most recent `query_data` calls (newest first). Zero LLM cost, zero credits. Use this when the user references "that query I ran earlier" / "the AAPL one from before" / "the slow one" — instead of asking the user to dictate the query_id, look it up here. Each entry returns: - query_id (the mcp_<ts>_<n> handle — pass directly to report_issue or quote to support) - status (success | clarification | timeout | error) - error_code (null on success; the stable error taxonomy otherwise) - row_count (rows returned on success) - prompt_preview (first 120 chars of the original question) - when (relative — "2m ago" / "1h ago" / "3d ago") - created_at_iso (raw ISO timestamp for precise ordering) - execution_time_ms `limit` defaults to 10, max 50. `status` filters: "all" (default), "success", or "error" (includes timeouts).

report_issue

Tell support something went wrong, file a bug, request a feature, or flag a slow query. Zero LLM cost, zero credits. Call this when: - A `query_data` result looks wrong or misleading (pass the `query_id` from that response — support uses it to investigate the issue). - You hit a confusing error or the same query keeps failing. - A query took unreasonably long (still pass `query_id` if available). - You wish mrmarket.ai supported something it currently doesn't. This is the PREFERRED support channel because it auto-links to the query trace; email is slower and requires the user to copy/paste the query_id manually. Categories: - wrong_data → result was incorrect / numbers look off - bug → something crashed or the response was malformed - slow → query took too long or timed out - feature_request → "I wish it could do X" - general → catch-all if none of the above fits

list_tickets

List the user's own report_issue tickets (newest first). Zero LLM cost, zero credits. Use this to look up a ticket you (or the user) filed earlier — e.g. to quote the full ticket_id when following up with support, or to check what was already reported before filing a duplicate. Each entry returns: - ticket_id (full UUID — quote this in follow-ups) - category (wrong_data | bug | slow | feature_request | general) - preview (first 200 chars of the report text) - query_id (the query the ticket was filed against, when attached) - created_at_iso