mcp-ivolatility-data 0.1.5__py3-none-any.whl

ivol_mcp_core/__init__.py

@@ -0,0 +1,91 @@
+import argparse
+import os
+import sys
+from typing import Literal
+
+__all__ = ["main"]
+
+
+def main() -> None:
+    """
+    Main CLI entry point for the iVolatility MCP core server.
+    Accepts --transport CLI argument (falls back to MCP_TRANSPORT env var, then stdio).
+
+    Heavy dependencies (numpy, etc.) are imported lazily inside this
+    function so that ``uv run`` can finish installing packages and Python
+    can start before the 30-second MCP connection timeout fires.
+    """
+    from dotenv import load_dotenv
+
+    # Load environment variables from .env file if it exists
+    load_dotenv()
+
+    parser = argparse.ArgumentParser(description="iVolatility MCP server")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "streamable-http"],
+        default=None,
+        help="Transport protocol (default: stdio). Overrides MCP_TRANSPORT env var.",
+    )
+    args = parser.parse_args()
+
+    # CLI arg takes precedence over env var; default to stdio
+    if args.transport is not None:
+        transport: Literal["stdio", "sse", "streamable-http"] = args.transport
+    else:
+        supported_transports: dict[str, Literal["stdio", "sse", "streamable-http"]] = {
+            "stdio": "stdio",
+            "sse": "sse",
+            "streamable-http": "streamable-http",
+        }
+        mcp_transport_str = os.environ.get("MCP_TRANSPORT", "stdio")
+        transport = supported_transports.get(mcp_transport_str, "stdio")
+
+    # Check API key and print startup message.
+    # Startup messages go to stderr — stdout is the MCP protocol channel
+    # for stdio transport; non-JSON data there corrupts the handshake.
+    # IVOL_API_KEY is the canonical name; API_KEY is accepted as a fallback for
+    # consistency with the other iVolatility deliverables (workspace prompts,
+    # ivolai-dist .env). The specific name wins when both are set.
+    ivol_api_key = os.environ.get("IVOL_API_KEY", "") or os.environ.get("API_KEY", "")
+    if ivol_api_key:
+        print(
+            "Starting iVolatility MCP server with API key configured.", file=sys.stderr
+        )
+    else:
+        print(
+            "Warning: neither IVOL_API_KEY nor API_KEY environment variable is set.",
+            file=sys.stderr,
+        )
+
+    base_url = os.environ.get(
+        "IVOL_API_BASE_URL", "https://restapi.ivolatility.com"
+    ).rstrip("/")
+    # Endpoint index sources: OpenAPI REST spec (required) + prompt supplement (optional).
+    openapi_path = os.environ.get("IVOL_OPENAPI_PATH")
+    supplement_path = os.environ.get("IVOL_SUPPLEMENT_PATH")
+    # Instructions dir (the resalka): role + discovery + access rules in .md chunks.
+    instructions_dir = os.environ.get("IVOL_INSTRUCTIONS_DIR")
+
+    max_tables: int | None = None
+    max_rows: int | None = None
+    if os.environ.get("IVOL_MAX_TABLES"):
+        max_tables = int(os.environ["IVOL_MAX_TABLES"])
+    if os.environ.get("IVOL_MAX_ROWS"):
+        max_rows = int(os.environ["IVOL_MAX_ROWS"])
+
+    # Defer importing server until after env vars are read — this triggers
+    # loading numpy and other heavy deps.
+    from .server import run, configure_credentials
+
+    configure_credentials(
+        ivol_api_key,
+        base_url,
+        openapi_path=openapi_path,
+        supplement_path=supplement_path,
+        instructions_dir=instructions_dir,
+        max_tables=max_tables,
+        max_rows=max_rows,
+    )
+
+    run(transport=transport)

ivol_mcp_core/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

ivol_mcp_core/assembly.py

@@ -0,0 +1,50 @@
+"""Instructions assembler — the connector's "resalka" (slicer), the inverse of
+the workspace split.py.
+
+Behaviour (role, endpoint-choosing rules, account/access rule, quirks) lives in
+small editable Markdown chunks under an instructions directory. This stitches
+them, in filename order, into the single server-instructions string the MCP
+client injects into its system context. Each connector (data / pod) ships its
+own instructions directory; the mechanism is shared here in core.
+"""
+
+from pathlib import Path
+
+
+def assemble_instructions(
+    instructions_dir: str | None, base: str = "", transport: str | None = None
+) -> str:
+    """Concatenate sorted ``*.md`` files in ``instructions_dir`` into one string.
+
+    ``base`` (optional) is placed first as a fallback/header. Missing directory
+    or no files → returns just ``base``.
+
+    Transport-specific chunks: guidance that is only true for one deployment
+    (e.g. export_data writes a LOCAL file only when the server runs on the
+    user's machine) lives in variant files. ``<name>.stdio.md`` is included
+    only for the stdio transport (local run, the default when ``transport`` is
+    None); ``<name>.remote.md`` only for network transports (sse /
+    streamable-http). Plain ``*.md`` chunks are always included.
+    """
+    mode = "stdio" if transport in (None, "stdio") else "remote"
+    parts: list[str] = []
+    if base and base.strip():
+        parts.append(base.strip())
+
+    if instructions_dir:
+        d = Path(instructions_dir)
+        if d.is_dir():
+            for f in sorted(d.glob("*.md")):
+                # Skip dotfiles / macOS AppleDouble sidecars (._*.md) that tar may
+                # carry along — they are binary and break UTF-8 decoding.
+                if f.name.startswith("."):
+                    continue
+                if f.name.endswith(".stdio.md") and mode != "stdio":
+                    continue
+                if f.name.endswith(".remote.md") and mode != "remote":
+                    continue
+                text = f.read_text(encoding="utf-8").strip()
+                if text:
+                    parts.append(text)
+
+    return "\n\n".join(parts)

ivol_mcp_core/constants.py

@@ -0,0 +1,201 @@
+import re
+
+# Kept only for import-compatibility with index.py (the Massive markdown
+# builder, unused now that the index is built from OpenAPI + supplement).
+_DEFAULT_LLMS_FULL_TXT_URL = "https://restapi.ivolatility.com/api/openapi"
+
+_TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+# Aliases map abbreviations/synonyms a user might type to canonical terms that
+# appear in iVolatility endpoint names/descriptions/fields. Values can be a
+# single string or a list of strings. Terms must match real index vocabulary.
+ALIASES: dict[str, str | list[str]] = {
+    # ── implied volatility / IVX term structure ──
+    "iv": ["ivx", "implied"],
+    "impliedvol": ["ivx", "implied"],
+    "impliedvolatility": ["ivx", "implied"],
+    "volatility": ["ivx", "ivs", "hv"],
+    "vol": ["ivx", "ivs"],
+    "ivx": "ivx",
+    "term": ["ivx"],
+    "termstructure": ["ivx"],
+    "lean": ["ivx", "rawiv"],  # IV-lean signal: ivx OR options-rawiv source
+    # ── IV surface / skew ──
+    "surface": ["ivs"],
+    "ivsurface": ["ivs"],
+    "skew": ["ivs", "delta"],  # surfaced via ivs-by-delta
+    "smile": ["ivs"],
+    # ── IV rank / percentile ──
+    "ivr": ["ivx", "historical", "range"],
+    "ivrank": ["ivx", "historical", "range"],
+    "ivp": ["ivx", "percentile"],
+    "percentile": ["ivx", "ivp"],
+    # ── historical / realized vol ──
+    "hv": "hv",
+    "historicalvol": "hv",
+    "realized": "hv",
+    "realizedvol": "hv",
+    # ── options / chains ──
+    "option": "options",
+    "contract": "options",
+    "contracts": "options",
+    "chain": ["options", "rawiv", "param"],
+    "optionchain": ["options", "rawiv"],
+    "strike": "options",
+    "expiry": "options",
+    "expiration": "options",
+    "dte": "options",
+    "moneyness": ["options", "param"],
+    "rawiv": "rawiv",
+    "1545": ["1545"],
+    # ── NBBO / quotes ──
+    "nbbo": ["nbbo", "quote"],
+    "bid": ["nbbo", "quote"],
+    "ask": ["nbbo", "quote"],
+    "quote": ["nbbo", "quote"],
+    # ── greeks (functions + options) ──
+    "greek": ["greeks", "options"],
+    "greeks": ["options"],
+    "delta": ["bs_delta", "delta", "options"],
+    "gamma": ["bs_gamma", "options"],
+    "theta": ["bs_theta", "options"],
+    "vega": ["bs_vega", "options"],
+    "rho": ["bs_rho", "options"],
+    "vanna": ["bs_vanna", "options"],
+    "volga": ["bs_volga", "options"],
+    "vomma": ["bs_volga", "options"],
+    "charm": ["bs_charm", "options"],
+    "veta": ["bs_veta", "options"],
+    "color": ["bs_color", "options"],
+    "blackscholes": ["bs_price", "bs_delta"],
+    # ── prices / OHLC ──
+    "price": ["prices", "stock"],
+    "prices": ["prices", "stock"],
+    "close": "prices",
+    "ohlc": "prices",
+    "stock": ["stock", "prices"],
+    "stockprice": ["stock", "prices"],
+    # ── earnings ──
+    "earnings": ["earnings", "calendar"],
+    "eps": "earnings",
+    "impliedmove": ["earnings"],
+    # ── futures ──
+    "future": "futures",
+    "futures": "futures",
+    "fut": "futures",
+    # ── interest rates / yield / dividends ──
+    "yield": ["yield", "interest"],
+    "dividend": ["yield", "dividend"],
+    "rate": ["interest", "rates"],
+    "rates": ["interest", "rates"],
+    # ── fixed income / curves ──
+    "bond": ["bond", "fixedincome"],
+    "bonds": ["bond", "fixedincome"],
+    "fixedincome": ["fixedincome", "bond"],
+    "cashflow": ["cashflow"],
+    "msrb": ["msrb"],
+    "curve": ["curve", "discount", "zero"],
+    "curves": ["curve", "discount", "zero"],
+    # ── real-time / streaming ──
+    "realtime": ["rt", "realtime"],
+    "real-time": ["rt", "realtime"],
+    "live": ["rt", "realtime"],
+    "rt": ["rt", "realtime"],
+    "stream": ["websocket", "rtdl"],
+    "streaming": ["websocket", "rtdl"],
+    "websocket": ["websocket", "rtdl"],
+    "ws": ["websocket", "rtdl"],
+    # ── intraday ──
+    "intraday": ["intraday"],
+    "minute": ["intraday"],
+    "minutes": ["intraday"],
+    "bar": ["intraday"],
+    "bars": ["intraday"],
+    # ── account / entitlements ──
+    "account": ["account", "access"],
+    "access": ["account", "access"],
+    "tariff": ["account", "access"],
+    "tariffs": ["account", "access"],
+    "entitlement": ["account", "access"],
+    "entitlements": ["account", "access"],
+    "quota": ["account", "access"],
+    "limit": ["account", "access"],
+    "limits": ["account", "access"],
+    # ── discovery / reference ──
+    "symbol": ["underlying", "ticker"],
+    "symbols": ["underlying", "ticker"],
+    "ticker": ["underlying", "ticker", "tickers"],
+    "lookup": ["underlying", "series"],
+    "series": ["series"],
+    "calendar": ["calendar", "trading"],
+    "split": ["corp", "actions"],
+    "dividends": ["corp", "actions"],
+    "corporateactions": ["corp", "actions"],
+    # ── instrument metadata (underlying-info: stocks + futures) ──
+    "constituent": ["underlying"],
+    "constituents": ["underlying"],
+    "member": ["underlying"],
+    "members": ["underlying"],
+    "stockgroup": ["underlying"],
+    "etf": ["underlying", "ticker"],
+    "etfs": ["underlying", "ticker"],
+    "multiplier": ["futures", "underlying"],
+    "contractsize": ["futures", "underlying"],
+    "root": ["futures", "underlying"],
+    "roots": ["futures", "underlying"],
+}
+
+# Market keywords used to infer the market facet from a free-text query.
+# Values must match the `market` column values (x-tagGroup names) produced by
+# index_openapi.py / the supplement, so an inferred-market boost lands on the
+# right rows. Equities/Options is the default and intentionally has no keywords.
+_MARKET_KEYWORDS: dict[str, set[str]] = {
+    "Futures/Options": {
+        "future",
+        "futures",
+        "fut",
+        "commodity",
+        "commodities",
+    },
+    "RealTime Options": {
+        "realtime",
+        "streaming",
+        "websocket",
+        "rtdl",
+    },
+    "Fixed Income": {
+        "bond",
+        "bonds",
+        "fixedincome",
+        "cashflow",
+        "msrb",
+        "debt",
+    },
+    "Curves": {"curve", "curves", "discount", "zero"},
+    "Account": {"account", "tariff", "tariffs", "entitlement", "entitlements", "quota"},
+    "WebSocket": {"websocket", "wss", "subscribe"},
+}
+
+_BULLET_PARAM_RE = re.compile(r"^-\s+\*{0,2}(\w+)\*{0,2}\s*\(([^)]+)\)(?::\s*(.*))?$")
+
+_STRUCTURAL_SECTIONS = {"Query Parameters", "Response Attributes", "Sample Response"}
+
+# Uppercase 2-5 letter token pattern to detect ticker symbols in the
+# original-case query (fallback signal for the equities market).
+_UPPER_TICKER_RE = re.compile(r"\b([A-Z]{2,5})\b")
+
+# Uppercase tokens that look like tickers but are acronyms / non-tickers and
+# must NOT trigger a market-inference fallback.
+_TICKER_FALLBACK_EXCLUSIONS: set[str] = {
+    # technical / option jargon
+    "IV", "IVX", "IVS", "IVR", "IVP", "HV", "RV", "ATM", "OTM", "ITM",
+    "DTE", "OHLC", "OHLCV", "VWAP", "NBBO", "RT", "WS",
+    # asset-class / general acronyms
+    "FX", "ETF", "ETFS", "IPO", "API", "URL", "JSON", "HTTP", "ID", "AI",
+    "EOD", "OSI", "CSV", "ZIP",
+    # geo / regulatory / business
+    "USA", "UK", "EU", "GMT", "AM", "PM", "OK", "OTC",
+    "NYSE", "NASDAQ", "AMEX", "CME", "NYMEX", "CBOT", "EUREX",
+    "CEO", "CFO", "CTO", "COO", "FED", "SEC", "FDA", "GDP", "CPI", "IRS",
+    "P", "S",
+}

ivol_mcp_core/formatters.py

@@ -0,0 +1,189 @@
+import json
+import csv
+import io
+from typing import Any
+
+
+def strip_response_metadata(json_text: str, exclude_keys: set) -> str:
+    """Strip metadata keys from a JSON response string.
+
+    Parses the JSON, removes top-level keys in exclude_keys, and re-serializes.
+    """
+    data = json.loads(json_text)
+    if isinstance(data, dict):
+        for key in exclude_keys:
+            data.pop(key, None)
+    return json.dumps(data)
+
+
+def extract_records(data: str | dict | list) -> list[dict]:
+    """Extract and flatten records from raw JSON input.
+
+    Takes raw JSON input (string or parsed), extracts the records list
+    (handling 'results', 'last', list, and single-object cases), flattens
+    each record via _flatten_dict, and returns a list of flat dicts.
+
+    Args:
+        data: JSON string, dict, or list.
+
+    Returns:
+        List of flattened dictionaries.
+    """
+    if isinstance(data, str):
+        try:
+            data = json.loads(data)
+        except json.JSONDecodeError:
+            return []
+
+    # Track whether "results" was a proper list — if so, the record count is
+    # authoritative and we should not re-interpret a single result's nested
+    # lists as the "real" row data.
+    results_was_list = False
+
+    if isinstance(data, dict) and isinstance(data.get("data"), list):
+        # iVolatility envelope: {status, query, data: [...]}. The rows live in
+        # "data"; treat it like a proper results list.
+        records = data["data"]
+        results_was_list = True
+    elif isinstance(data, dict) and "results" in data:
+        results_value = data["results"]
+        if isinstance(results_value, list):
+            records = results_value
+            results_was_list = True
+        elif isinstance(results_value, dict):
+            records = [results_value]
+        else:
+            records = [results_value]
+    elif isinstance(data, dict) and "last" in data:
+        records = [data["last"]] if isinstance(data["last"], dict) else [data]
+    elif isinstance(data, list):
+        records = data
+        results_was_list = True
+    else:
+        records = [data]
+
+    # If we got a single record containing list-of-dicts values AND it did
+    # NOT come from a proper results list, those inner lists are the real
+    # row data.  This handles API responses like:
+    #   {"tickers": [{...}, ...]}                (snapshots / gainers)
+    #   {"underlying": {...}, "values": [...]}   (technical indicators via
+    #       "results" as a dict, not a list)
+    #   {"dividends": [...], "splits": [...]}    (hypothetical multi-list
+    #       responses — rows from every list are emitted and tagged with
+    #       a ``_source`` column so downstream can disambiguate)
+    if len(records) == 1 and isinstance(records[0], dict) and not results_was_list:
+        record = records[0]
+        list_of_dict_keys = [
+            k
+            for k, v in record.items()
+            if isinstance(v, list) and v and isinstance(v[0], dict)
+        ]
+        if list_of_dict_keys:
+            chosen = set(list_of_dict_keys)
+            # Carry every sibling value into the child rows.  Sibling lists
+            # (of any kind) are stringified rather than silently dropped —
+            # this matches _flatten_dict's treatment of list values.
+            parent_fields: dict[str, Any] = {}
+            for pk, pv in record.items():
+                if pk in chosen:
+                    continue
+                if isinstance(pv, dict):
+                    for fk, fv in _flatten_dict(pv, pk).items():
+                        if not isinstance(fv, (dict, list)):
+                            parent_fields[fk] = fv
+                elif isinstance(pv, list):
+                    parent_fields[pk] = str(pv)
+                else:
+                    parent_fields[pk] = pv
+            # Emit rows from every list-of-dicts key.  When multiple such
+            # keys exist, tag each row with its source so overlapping
+            # column names (e.g. "date" in both dividends and splits) do
+            # not collide ambiguously downstream.
+            tag_source = len(list_of_dict_keys) > 1
+            new_records: list = []
+            for key in list_of_dict_keys:
+                for item in record[key]:
+                    if isinstance(item, dict):
+                        row = {**parent_fields, **item}
+                        if tag_source:
+                            row["_source"] = key
+                        new_records.append(row)
+                    else:
+                        # Preserve non-dict list entries; the final
+                        # flattening step wraps them as {"value": ...}.
+                        new_records.append(item)
+            records = new_records
+
+    flattened_records = []
+    for record in records:
+        if isinstance(record, dict):
+            flattened_records.append(_flatten_dict(record))
+        else:
+            flattened_records.append({"value": str(record)})
+
+    return flattened_records
+
+
+def json_to_csv(json_input: str | dict | list) -> str:
+    """
+    Convert JSON to flattened CSV format.
+
+    Args:
+        json_input: JSON string or dict. If the JSON has a 'results' key containing
+                   a list, it will be extracted. Otherwise, the entire structure
+                   will be wrapped in a list for processing.
+
+    Returns:
+        CSV string with headers and flattened rows
+    """
+    flattened_records = extract_records(json_input)
+
+    if not flattened_records:
+        return ""
+
+    # Get all unique keys across all records (for consistent column ordering)
+    all_keys = []
+    seen = set()
+    for record in flattened_records:
+        if isinstance(record, dict):
+            for key in record.keys():
+                if key not in seen:
+                    all_keys.append(key)
+                    seen.add(key)
+
+    output = io.StringIO()
+    writer = csv.DictWriter(output, fieldnames=all_keys, lineterminator="\n")
+    writer.writeheader()
+    writer.writerows(flattened_records)
+
+    return output.getvalue()
+
+
+def _flatten_dict(
+    d: dict[str, Any], parent_key: str = "", sep: str = "_"
+) -> dict[str, Any]:
+    """
+    Flatten a nested dictionary by joining keys with separator.
+
+    Args:
+        d: Dictionary to flatten
+        parent_key: Key from parent level (for recursion)
+        sep: Separator to use between nested keys
+
+    Returns:
+        Flattened dictionary with no nested structures
+    """
+    items = []
+    for k, v in d.items():
+        new_key = f"{parent_key}{sep}{k}" if parent_key else k
+
+        if isinstance(v, dict):
+            # Recursively flatten nested dicts
+            items.extend(_flatten_dict(v, new_key, sep=sep).items())
+        elif isinstance(v, list):
+            # Convert lists to comma-separated strings
+            items.append((new_key, str(v)))
+        else:
+            items.append((new_key, v))
+
+    return dict(items)