oq-mcp 0.1.0__tar.gz

oq_mcp-0.1.0/.gitignore

@@ -0,0 +1,82 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+wheels/
+develop-eggs/
+eggs/
+parts/
+sdist/
+var/
+*.manifest
+*.spec
+pip-log.txt
+pip-delete-this-directory.txt
+
+# uv
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+.cache
+
+# mypy / ruff
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb_checkpoints
+
+# Data / artifacts
+data/
+*.parquet
+*.duckdb
+*.duckdb.wal
+*.csv.gz
+*.zip
+.openquant/
+
+!packages/*/tests/fixtures/**
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# build artifacts
+dist/
+*.egg-info/

oq_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: oq-mcp
+Version: 0.1.0
+Summary: MCP server exposing OpenQuant India data, screeners, and honest backtests to LLM clients.
+Project-URL: Homepage, https://github.com/revorhq/openquant
+Project-URL: Repository, https://github.com/revorhq/openquant
+Project-URL: Issues, https://github.com/revorhq/openquant/issues
+Author: OpenQuant India Contributors
+License: Apache-2.0
+Keywords: claude,india,llm,mcp,nse,quant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: oq-backtest
+Requires-Dist: oq-core
+Requires-Dist: oq-data
+Requires-Dist: pandas>=2.0
+Description-Content-Type: text/markdown
+
+# oq-mcp
+
+MCP server exposing OpenQuant India data, screeners, and honest backtests to
+LLM clients like Claude Desktop.
+
+Tools: `get_prices`, `get_universe`, `screen_stocks`, `get_fundamentals_basic`,
+and the headline `run_backtest` tool — natural-language-parameterized
+backtests with honest Indian-market costs.
+
+```bash
+pip install oq-mcp
+```
+
+Configure in Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "openquant": { "command": "oq-mcp" }
+  }
+}
+```
+
+Then ask Claude: *"Backtest momentum on Nifty 500 with Zerodha costs since 2015."*
+
+Part of [OpenQuant India](https://github.com/revorhq/openquant) — honest, open
+source quant infrastructure for Indian markets. Apache 2.0.

oq_mcp-0.1.0/README.md

@@ -0,0 +1,27 @@
+# oq-mcp
+
+MCP server exposing OpenQuant India data, screeners, and honest backtests to
+LLM clients like Claude Desktop.
+
+Tools: `get_prices`, `get_universe`, `screen_stocks`, `get_fundamentals_basic`,
+and the headline `run_backtest` tool — natural-language-parameterized
+backtests with honest Indian-market costs.
+
+```bash
+pip install oq-mcp
+```
+
+Configure in Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "openquant": { "command": "oq-mcp" }
+  }
+}
+```
+
+Then ask Claude: *"Backtest momentum on Nifty 500 with Zerodha costs since 2015."*
+
+Part of [OpenQuant India](https://github.com/revorhq/openquant) — honest, open
+source quant infrastructure for Indian markets. Apache 2.0.

oq_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "oq-mcp"
+version = "0.1.0"
+description = "MCP server exposing OpenQuant India data, screeners, and honest backtests to LLM clients."
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+readme = "README.md"
+authors = [{ name = "OpenQuant India Contributors" }]
+keywords = ["mcp", "quant", "nse", "india", "llm", "claude"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "mcp>=1.0",
+    "pandas>=2.0",
+    "numpy>=1.24",
+    "oq-core",
+    "oq-data",
+    "oq-backtest",
+]
+
+[project.urls]
+Homepage = "https://github.com/revorhq/openquant"
+Repository = "https://github.com/revorhq/openquant"
+Issues = "https://github.com/revorhq/openquant/issues"
+
+[project.scripts]
+oq-mcp = "oq_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/oq_mcp"]

oq_mcp-0.1.0/src/oq_mcp/__init__.py

@@ -0,0 +1,28 @@
+"""MCP server exposing OpenQuant India data and honest backtests."""
+
+from __future__ import annotations
+
+from oq_mcp.cache import TTLCache
+from oq_mcp.screener import screen
+from oq_mcp.server import build_server
+from oq_mcp.tools import (
+    get_fundamentals_basic,
+    get_prices,
+    get_universe,
+    run_backtest,
+    screen_stocks,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TTLCache",
+    "__version__",
+    "build_server",
+    "get_fundamentals_basic",
+    "get_prices",
+    "get_universe",
+    "run_backtest",
+    "screen",
+    "screen_stocks",
+]

oq_mcp-0.1.0/src/oq_mcp/cache.py

@@ -0,0 +1,54 @@
+"""In-process TTL cache for upstream rate-limit friendliness.
+
+The cache is keyed on a hashable tuple and stores any picklable value.
+Entries expire after ``ttl_seconds``; lookups for expired entries are
+treated as misses. A small ``max_entries`` bound keeps memory predictable
+under heavy tool traffic (oldest entries are evicted FIFO).
+"""
+
+from __future__ import annotations
+
+import time
+from collections import OrderedDict
+from collections.abc import Hashable
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class TTLCache(Generic[T]):
+    def __init__(self, ttl_seconds: float = 300.0, max_entries: int = 1024) -> None:
+        if ttl_seconds < 0:
+            raise ValueError("ttl_seconds must be >= 0")
+        if max_entries < 1:
+            raise ValueError("max_entries must be >= 1")
+        self._ttl = float(ttl_seconds)
+        self._max = int(max_entries)
+        self._data: OrderedDict[Hashable, tuple[float, T]] = OrderedDict()
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def get(self, key: Hashable) -> T | None:
+        entry = self._data.get(key)
+        if entry is None:
+            return None
+        expires_at, value = entry
+        if expires_at < time.monotonic():
+            self._data.pop(key, None)
+            return None
+        self._data.move_to_end(key)
+        return value
+
+    def set(self, key: Hashable, value: T) -> None:
+        if key in self._data:
+            self._data.move_to_end(key)
+        self._data[key] = (time.monotonic() + self._ttl, value)
+        while len(self._data) > self._max:
+            self._data.popitem(last=False)
+
+    def clear(self) -> None:
+        self._data.clear()
+
+
+__all__ = ["TTLCache"]

oq_mcp-0.1.0/src/oq_mcp/screener.py

@@ -0,0 +1,131 @@
+"""Tiny screener DSL evaluated against a wide adjusted-price frame.
+
+Supported expressions (case-insensitive on the field name):
+
+* ``close > 100``
+* ``returns_20d > 0.05``
+* ``returns_252d >= 0.10``
+* ``pct_from_52w_high <= 0.05``  (within 5% of 52-week high)
+* ``pct_from_52w_low >= 0.20``
+* ``sma_50_above_sma_200``
+* ``volume > 100000``  (requires a volume frame)
+
+Multiple expressions can be combined with ``&`` (AND) or ``|`` (OR).
+Symbols missing data for the most-recent observation are dropped.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+import numpy as np
+import pandas as pd
+
+_NUMERIC_FIELDS = {
+    "close",
+    "volume",
+    "returns_5d",
+    "returns_20d",
+    "returns_60d",
+    "returns_252d",
+    "pct_from_52w_high",
+    "pct_from_52w_low",
+}
+_BOOLEAN_FIELDS = {"sma_50_above_sma_200"}
+
+_OP_RE = re.compile(r"^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*(<=|>=|==|<|>)\s*(-?\d+(?:\.\d+)?)\s*$")
+_BOOL_RE = re.compile(r"^\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*$")
+
+
+def _last(prices: pd.DataFrame, lookback: int) -> pd.Series:
+    if lookback <= 0 or lookback >= len(prices):
+        return pd.Series(index=prices.columns, dtype=float)
+    return prices.iloc[-1] / prices.iloc[-1 - lookback] - 1.0
+
+
+def _features(prices: pd.DataFrame, volume: pd.DataFrame | None) -> pd.DataFrame:
+    if prices.empty:
+        return pd.DataFrame()
+    last = prices.iloc[-1]
+    high_52w = prices.tail(252).max()
+    low_52w = prices.tail(252).min()
+    sma_50 = prices.tail(50).mean()
+    sma_200 = prices.tail(200).mean()
+    feats = pd.DataFrame(
+        {
+            "close": last,
+            "returns_5d": _last(prices, 5),
+            "returns_20d": _last(prices, 20),
+            "returns_60d": _last(prices, 60),
+            "returns_252d": _last(prices, 252),
+            "pct_from_52w_high": (high_52w - last) / high_52w,
+            "pct_from_52w_low": (last - low_52w) / low_52w,
+            "sma_50_above_sma_200": sma_50 > sma_200,
+        }
+    )
+    if volume is not None and not volume.empty:
+        feats["volume"] = volume.iloc[-1].reindex(feats.index)
+    return feats.replace([np.inf, -np.inf], np.nan)
+
+
+def _parse_atom(expr: str) -> tuple[str, str, float | bool]:
+    m = _OP_RE.match(expr)
+    if m:
+        field, op, num = m.group(1), m.group(2), float(m.group(3))
+        if field not in _NUMERIC_FIELDS:
+            raise ValueError(f"unknown numeric field: {field}")
+        return field, op, num
+    m = _BOOL_RE.match(expr)
+    if m:
+        field = m.group(1)
+        if field not in _BOOLEAN_FIELDS:
+            raise ValueError(f"unknown boolean field: {field}")
+        return field, "==", True
+    raise ValueError(f"could not parse screener expression: {expr!r}")
+
+
+def _apply(feats: pd.DataFrame, atom: tuple[str, str, float | bool]) -> pd.Series:
+    field, op, rhs = atom
+    series = feats[field]
+    if op == ">":
+        return series > rhs
+    if op == ">=":
+        return series >= rhs
+    if op == "<":
+        return series < rhs
+    if op == "<=":
+        return series <= rhs
+    if op == "==":
+        return series == rhs
+    raise ValueError(f"unknown operator: {op}")
+
+
+def screen(
+    prices: pd.DataFrame,
+    expressions: Iterable[str],
+    combine: str = "and",
+    volume: pd.DataFrame | None = None,
+    universe: Iterable[str] | None = None,
+) -> list[str]:
+    """Return the symbols passing every (or any) supplied expression."""
+    exprs = [e.strip() for e in expressions if e and e.strip()]
+    if not exprs:
+        raise ValueError("at least one expression is required")
+    if prices.empty:
+        return []
+    if universe is not None:
+        keep = [s for s in universe if s in prices.columns]
+        prices = prices[keep]
+        if volume is not None:
+            volume = volume[[c for c in volume.columns if c in keep]]
+    feats = _features(prices, volume)
+    masks = [_apply(feats, _parse_atom(e)) for e in exprs]
+    combined = masks[0].astype(bool)
+    op = combine.lower()
+    for m in masks[1:]:
+        combined = (combined & m) if op == "and" else (combined | m)
+    return sorted(combined[combined.fillna(False)].index.tolist())
+
+
+__all__ = ["screen"]

oq_mcp-0.1.0/src/oq_mcp/server.py

@@ -0,0 +1,134 @@
+"""FastMCP server wiring for the OpenQuant India tool set.
+
+Run over stdio for desktop MCP clients::
+
+    uv run oq-mcp
+
+or programmatically::
+
+    from oq_mcp.server import build_server
+    server = build_server()
+    server.run()
+
+Every tool is a thin pass-through to :mod:`oq_mcp.tools` so the underlying
+logic stays trivially testable without the MCP machinery.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from oq_mcp import tools
+
+logger = logging.getLogger(__name__)
+
+SERVER_INSTRUCTIONS = (
+    "OpenQuant India MCP server. Tools expose NSE EOD prices, "
+    "point-in-time index universes, a screener DSL, basic fundamentals, "
+    "and an honest, cost-aware backtester. All cost numbers are net of "
+    "Indian frictions (STT, brokerage, exchange, SEBI, GST, stamp duty, "
+    "slippage). Outputs are research artefacts, NOT investment advice."
+)
+
+
+def build_server(name: str = "openquant-india") -> FastMCP:
+    """Build a FastMCP instance with every OpenQuant tool registered."""
+    server = FastMCP(name=name, instructions=SERVER_INSTRUCTIONS)
+
+    @server.tool(
+        name="get_prices",
+        description="Return adjusted EOD prices for a single NSE symbol.",
+    )
+    def _get_prices(
+        symbol: str,
+        start: str | None = None,
+        end: str | None = None,
+        adjusted: bool = True,
+    ) -> dict[str, Any]:
+        return tools.get_prices(symbol, start=start, end=end, adjusted=adjusted)
+
+    @server.tool(
+        name="get_universe",
+        description="Return point-in-time members of an NSE index (Nifty 50/100/500).",
+    )
+    def _get_universe(index_name: str, as_of: str) -> dict[str, Any]:
+        return tools.get_universe(index_name, as_of=as_of)
+
+    @server.tool(
+        name="screen_stocks",
+        description=(
+            "Apply a list of screener expressions against the PIT universe. "
+            "Expressions: 'returns_252d > 0.10', 'pct_from_52w_high <= 0.05', "
+            "'sma_50_above_sma_200', 'close > 100'."
+        ),
+    )
+    def _screen_stocks(
+        expressions: Sequence[str],
+        index_name: str | None = None,
+        as_of: str | None = None,
+        lookback_days: int = 300,
+        combine: str = "and",
+    ) -> dict[str, Any]:
+        return tools.screen_stocks(
+            expressions,
+            index_name=index_name,
+            as_of=as_of,
+            lookback_days=lookback_days,
+            combine=combine,
+        )
+
+    @server.tool(
+        name="get_fundamentals_basic",
+        description="Return basic reference info (ISIN, series, last close/volume) for a symbol.",
+    )
+    def _get_fundamentals_basic(symbol: str) -> dict[str, Any]:
+        return tools.get_fundamentals_basic(symbol)
+
+    @server.tool(
+        name="run_backtest",
+        description=(
+            "Run an honest, cost-aware backtest. signals_source in "
+            "{momentum, mean_reversion, equal_weight}; costs in "
+            "{zerodha, upstox, fyers, dhan, full_service, zero}."
+        ),
+    )
+    def _run_backtest(
+        signals_source: str = "momentum",
+        index_name: str | None = None,
+        start: str | None = None,
+        end: str | None = None,
+        costs: str = "zerodha",
+        slippage_bps: float = 5.0,
+        initial_capital: float = 1_000_000.0,
+        lookback: int = 252,
+        top_k: int = 10,
+        schedule: str = "monthly",
+    ) -> dict[str, Any]:
+        return tools.run_backtest(
+            signals_source=signals_source,
+            index_name=index_name,
+            start=start,
+            end=end,
+            costs=costs,
+            slippage_bps=slippage_bps,
+            initial_capital=initial_capital,
+            lookback=lookback,
+            top_k=top_k,
+            schedule=schedule,
+        )
+
+    return server
+
+
+def main() -> None:
+    """Console-script entry point: serve over stdio."""
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
+    server = build_server()
+    server.run()
+
+
+__all__ = ["SERVER_INSTRUCTIONS", "build_server", "main"]

oq_mcp-0.1.0/src/oq_mcp/tools.py

@@ -0,0 +1,246 @@
+"""Pure-Python implementations of every MCP tool.
+
+These functions accept primitive arguments (so they serialise cleanly
+across the MCP wire) and return JSON-serialisable dicts. The MCP server
+in :mod:`oq_mcp.server` is a thin wrapper that adapts each function
+into a ``FastMCP`` tool. Keeping the logic here makes the tools easy to
+test offline without spinning up the server.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import oq_backtest as bt
+import oq_data
+import pandas as pd
+from oq_data.config import DataPaths, get_paths
+
+from oq_mcp.cache import TTLCache
+from oq_mcp.screener import screen
+
+_DEFAULT_CACHE: TTLCache[Any] = TTLCache(ttl_seconds=300.0, max_entries=256)
+
+
+def _resolve_paths(data_dir: str | Path | None) -> DataPaths:
+    return get_paths(data_dir) if data_dir else get_paths()
+
+
+def _coerce_date(value: str | date | None) -> date | None:
+    if value is None:
+        return None
+    if isinstance(value, date):
+        return value
+    return pd.to_datetime(value).date()
+
+
+def _series_to_records(df: pd.DataFrame) -> list[dict[str, Any]]:
+    if df.empty:
+        return []
+    out = df.copy()
+    if "date" in out.columns:
+        out["date"] = pd.to_datetime(out["date"]).dt.strftime("%Y-%m-%d")
+    return out.to_dict(orient="records")
+
+
+def get_prices(
+    symbol: str,
+    start: str | None = None,
+    end: str | None = None,
+    adjusted: bool = True,
+    data_dir: str | None = None,
+    cache: TTLCache[Any] | None = None,
+) -> dict[str, Any]:
+    """Return adjusted EOD prices for ``symbol`` between ``start`` and ``end``."""
+    paths = _resolve_paths(data_dir)
+    key = ("prices", symbol, start, end, adjusted, str(paths.root))
+    c = cache or _DEFAULT_CACHE
+    hit = c.get(key)
+    if hit is not None:
+        return hit
+    df = oq_data.prices(
+        symbol,
+        start=_coerce_date(start),
+        end=_coerce_date(end),
+        adjusted=adjusted,
+        paths=paths,
+    )
+    result = {
+        "symbol": symbol,
+        "adjusted": adjusted,
+        "rows": len(df),
+        "data": _series_to_records(df),
+    }
+    c.set(key, result)
+    return result
+
+
+def get_universe(
+    index_name: str,
+    as_of: str,
+    data_dir: str | None = None,
+    cache: TTLCache[Any] | None = None,
+) -> dict[str, Any]:
+    """Return PIT membership of ``index_name`` as of ``as_of`` (YYYY-MM-DD)."""
+    paths = _resolve_paths(data_dir)
+    key = ("universe", index_name, as_of, str(paths.root))
+    c = cache or _DEFAULT_CACHE
+    hit = c.get(key)
+    if hit is not None:
+        return hit
+    members = oq_data.universe(index_name, as_of, paths=paths)
+    result = {
+        "index": index_name,
+        "as_of": as_of,
+        "count": len(members),
+        "symbols": members,
+    }
+    c.set(key, result)
+    return result
+
+
+def screen_stocks(
+    expressions: Sequence[str],
+    index_name: str | None = None,
+    as_of: str | None = None,
+    lookback_days: int = 300,
+    combine: str = "and",
+    data_dir: str | None = None,
+) -> dict[str, Any]:
+    """Run the screener DSL over a (PIT) universe."""
+    paths = _resolve_paths(data_dir)
+    end = _coerce_date(as_of) or date.today()
+    start = end - pd.Timedelta(days=int(lookback_days) + 30)
+    if index_name:
+        members = oq_data.universe(index_name, end, paths=paths)
+    else:
+        members = oq_data.list_symbols(paths=paths)
+    if not members:
+        return {"count": 0, "symbols": [], "universe_size": 0, "as_of": end.isoformat()}
+    wide = oq_data.wide_prices(members, start=start, end=end, paths=paths)
+    matches = screen(wide, expressions, combine=combine, universe=members)
+    return {
+        "count": len(matches),
+        "symbols": matches,
+        "universe_size": len(members),
+        "as_of": end.isoformat(),
+        "expressions": list(expressions),
+        "combine": combine,
+    }
+
+
+def get_fundamentals_basic(
+    symbol: str,
+    data_dir: str | None = None,
+) -> dict[str, Any]:
+    """Return basic reference information for ``symbol``.
+
+    Phase 3 ships the *basic* contract only — symbol identity (ISIN,
+    series, exchange) plus the latest known close and traded volume.
+    Quarterly results and shareholding feeds land in a later phase.
+    """
+    paths = _resolve_paths(data_dir)
+    eod = oq_data.storage.read_prices(symbols=symbol, paths=paths)
+    if eod.empty:
+        return {"symbol": symbol, "found": False}
+    last = eod.iloc[-1]
+    master = oq_data.symbols.load_master(paths=paths)
+    info: dict[str, Any] = {
+        "symbol": symbol,
+        "found": True,
+        "isin": str(last.get("isin")) if pd.notna(last.get("isin")) else None,
+        "series": str(last.get("series")),
+        "last_date": pd.to_datetime(last["date"]).strftime("%Y-%m-%d"),
+        "last_close": float(last["close"]),
+        "last_volume": int(last["volume"]) if pd.notna(last["volume"]) else None,
+        "history_rows": len(eod),
+    }
+    if not master.df.empty:
+        match = master.df[(master.df["new_symbol"] == symbol) | (master.df["old_symbol"] == symbol)]
+        if not match.empty:
+            info["canonical_isin"] = str(match.iloc[-1]["isin"])
+    return info
+
+
+def run_backtest(
+    signals_source: str = "momentum",
+    index_name: str | None = None,
+    start: str | None = None,
+    end: str | None = None,
+    costs: str = "zerodha",
+    slippage_bps: float = 5.0,
+    initial_capital: float = 1_000_000.0,
+    lookback: int = 252,
+    top_k: int = 10,
+    schedule: str = "monthly",
+    data_dir: str | None = None,
+    symbols: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Run an honest backtest and return the tearsheet as a dict.
+
+    ``signals_source`` is one of ``momentum`` (default), ``mean_reversion``,
+    or ``equal_weight``. Universe is the PIT membership of ``index_name``
+    on ``end`` (or today) unless ``symbols`` is provided explicitly.
+    """
+    paths = _resolve_paths(data_dir)
+    end_d = _coerce_date(end) or date.today()
+    start_d = _coerce_date(start)
+    if symbols is not None:
+        syms = list(symbols)
+    elif index_name:
+        syms = oq_data.universe(index_name, end_d, paths=paths)
+    else:
+        syms = oq_data.list_symbols(paths=paths)
+    if not syms:
+        raise ValueError("no symbols available; ingest data or pass `symbols`")
+    prices_df = oq_data.wide_prices(syms, start=start_d, end=end_d, paths=paths)
+    if prices_df.empty:
+        raise ValueError("price frame is empty; check ingestion and date range")
+
+    src = signals_source.lower()
+    if src == "momentum":
+        sigs = bt.momentum_signal(prices_df, lookback=lookback, top_k=top_k, schedule=schedule)
+    elif src in {"mean_reversion", "mean-reversion", "reversion"}:
+        sigs = bt.mean_reversion_signal(
+            prices_df, lookback=max(lookback // 50, 2), bottom_k=top_k, schedule=schedule
+        )
+    elif src in {"equal_weight", "equal-weight", "equal"}:
+        sigs = bt.equal_weight(prices_df.columns, prices_df.index)
+    else:
+        raise ValueError(f"unknown signals_source: {signals_source!r}")
+
+    result = bt.backtest(
+        sigs,
+        prices_df,
+        costs=costs,
+        slippage=float(slippage_bps),
+        initial_capital=float(initial_capital),
+    )
+    summary = result.summary()
+    attribution = result.cost_attribution().to_dict()
+    return {
+        "signals_source": src,
+        "universe_size": len(prices_df.columns),
+        "period": {
+            "start": str(prices_df.index[0].date()),
+            "end": str(prices_df.index[-1].date()),
+        },
+        "costs": costs,
+        "slippage_bps": float(slippage_bps),
+        "initial_capital": float(initial_capital),
+        "summary": {k: float(v) for k, v in summary.items()},
+        "cost_attribution_inr": {k: float(v) for k, v in attribution.items()},
+        "tearsheet": result.tearsheet(),
+    }
+
+
+__all__ = [
+    "get_fundamentals_basic",
+    "get_prices",
+    "get_universe",
+    "run_backtest",
+    "screen_stocks",
+]

oq_mcp-0.1.0/tests/conftest.py

@@ -0,0 +1,61 @@
+"""Test fixtures for oq-mcp: a fully seeded tmp DataPaths with prices + a universe."""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pytest
+from oq_data import storage, universes
+from oq_data.config import DataPaths
+
+SYMBOLS = ["AAA", "BBB", "CCC", "DDD"]
+
+
+def _make_eod(symbols: list[str], n_days: int = 320, seed: int = 7) -> pd.DataFrame:
+    rng = np.random.default_rng(seed)
+    dates = pd.bdate_range(start="2023-01-02", periods=n_days)
+    rows: list[dict[str, object]] = []
+    for i, sym in enumerate(symbols):
+        rets = rng.normal(loc=0.0004 + i * 0.0001, scale=0.014, size=n_days)
+        rets[0] = 0.0
+        closes = 100.0 * np.cumprod(1.0 + rets)
+        for d, c in zip(dates, closes, strict=True):
+            rows.append(
+                {
+                    "date": d,
+                    "symbol": sym,
+                    "isin": f"INE000000{i:03d}",
+                    "series": "EQ",
+                    "open": c * 0.999,
+                    "high": c * 1.005,
+                    "low": c * 0.995,
+                    "close": c,
+                    "prev_close": c * 0.999,
+                    "volume": 100_000 + i * 1_000,
+                    "value": 100_000 * c,
+                    "trades": 500,
+                }
+            )
+    return pd.DataFrame(rows)
+
+
+@pytest.fixture
+def seeded_paths(tmp_path: Path) -> DataPaths:
+    paths = DataPaths(tmp_path)
+    paths.ensure()
+    df = _make_eod(SYMBOLS)
+    storage.write_eod(df, paths=paths)
+    entries = [
+        universes.UniverseEntry(
+            index_name="NIFTY 50",
+            symbol=sym,
+            isin=f"INE000000{i:03d}",
+            include_date=date(2023, 1, 2),
+        )
+        for i, sym in enumerate(SYMBOLS)
+    ]
+    universes.add_entries(entries, paths=paths)
+    return paths

oq_mcp-0.1.0/tests/test_cache.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import time
+
+import pytest
+from oq_mcp.cache import TTLCache
+
+
+def test_set_and_get_roundtrip() -> None:
+    c: TTLCache[int] = TTLCache(ttl_seconds=60.0, max_entries=8)
+    c.set(("a", 1), 42)
+    assert c.get(("a", 1)) == 42
+
+
+def test_miss_returns_none() -> None:
+    c: TTLCache[int] = TTLCache(ttl_seconds=60.0)
+    assert c.get("missing") is None
+
+
+def test_expiration() -> None:
+    c: TTLCache[int] = TTLCache(ttl_seconds=0.05)
+    c.set("k", 1)
+    time.sleep(0.1)
+    assert c.get("k") is None
+
+
+def test_eviction_fifo() -> None:
+    c: TTLCache[int] = TTLCache(ttl_seconds=60.0, max_entries=2)
+    c.set("a", 1)
+    c.set("b", 2)
+    c.set("c", 3)
+    assert c.get("a") is None
+    assert c.get("b") == 2
+    assert c.get("c") == 3
+
+
+def test_invalid_settings() -> None:
+    with pytest.raises(ValueError):
+        TTLCache(ttl_seconds=-1)
+    with pytest.raises(ValueError):
+        TTLCache(max_entries=0)
+
+
+def test_clear() -> None:
+    c: TTLCache[int] = TTLCache(ttl_seconds=60.0)
+    c.set("k", 9)
+    c.clear()
+    assert c.get("k") is None
+    assert len(c) == 0

oq_mcp-0.1.0/tests/test_screener.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import pytest
+from oq_mcp.screener import screen
+
+
+def _prices() -> pd.DataFrame:
+    rng = np.random.default_rng(3)
+    dates = pd.bdate_range("2024-01-02", periods=260)
+    cols = ["UP", "DOWN", "FLAT", "TINY"]
+    data = {
+        "UP": 100 * np.cumprod(1 + rng.normal(0.002, 0.01, 260)),
+        "DOWN": 100 * np.cumprod(1 + rng.normal(-0.002, 0.01, 260)),
+        "FLAT": 100 * np.ones(260),
+        "TINY": 0.5 * np.ones(260),
+    }
+    return pd.DataFrame(data, index=dates, columns=cols)
+
+
+def test_numeric_filter() -> None:
+    p = _prices()
+    out = screen(p, ["returns_252d > 0.10"])
+    assert "UP" in out
+    assert "DOWN" not in out
+
+
+def test_combine_and() -> None:
+    p = _prices()
+    out = screen(p, ["returns_252d > 0.05", "close > 5"], combine="and")
+    assert "TINY" not in out
+
+
+def test_combine_or() -> None:
+    p = _prices()
+    out = screen(p, ["close > 90", "close < 1"], combine="or")
+    assert "TINY" in out
+
+
+def test_boolean_field() -> None:
+    p = _prices()
+    out = screen(p, ["sma_50_above_sma_200"])
+    assert isinstance(out, list)
+
+
+def test_bad_expression_raises() -> None:
+    p = _prices()
+    with pytest.raises(ValueError):
+        screen(p, ["not a thing"])
+    with pytest.raises(ValueError):
+        screen(p, [])
+
+
+def test_empty_universe() -> None:
+    out = screen(pd.DataFrame(), ["close > 1"])
+    assert out == []
+
+
+def test_pct_from_52w_high() -> None:
+    p = _prices()
+    out = screen(p, ["pct_from_52w_high <= 0.50"])
+    assert isinstance(out, list)

oq_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import pytest
+from oq_data.config import DataPaths
+from oq_mcp import tools
+from oq_mcp.server import build_server
+
+
+def test_build_server_registers_all_tools() -> None:
+    server = build_server()
+    tool_list = pytest.importorskip("asyncio").run(server.list_tools())
+    names = {t.name for t in tool_list}
+    assert names == {
+        "get_prices",
+        "get_universe",
+        "screen_stocks",
+        "get_fundamentals_basic",
+        "run_backtest",
+    }
+
+
+def test_server_name_and_instructions() -> None:
+    server = build_server(name="oq-test")
+    assert server.name == "oq-test"
+    assert "OpenQuant India" in server.instructions
+
+
+async def test_call_get_universe_via_server(
+    seeded_paths: DataPaths, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("OPENQUANT_DATA_DIR", str(seeded_paths.root))
+
+    out = tools.get_universe("NIFTY 50", as_of="2024-06-01")
+    assert out["count"] == 4

oq_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import pytest
+from oq_data.config import DataPaths
+from oq_mcp import tools
+
+
+def test_get_prices_returns_rows(seeded_paths: DataPaths) -> None:
+    out = tools.get_prices("AAA", data_dir=str(seeded_paths.root))
+    assert out["symbol"] == "AAA"
+    assert out["rows"] > 0
+    assert out["adjusted"] is True
+    assert all("date" in r and "close" in r for r in out["data"][:3])
+
+
+def test_get_prices_caches(seeded_paths: DataPaths) -> None:
+    from oq_mcp.cache import TTLCache
+
+    cache: TTLCache = TTLCache(ttl_seconds=60.0)
+    out1 = tools.get_prices("AAA", data_dir=str(seeded_paths.root), cache=cache)
+    out2 = tools.get_prices("AAA", data_dir=str(seeded_paths.root), cache=cache)
+    assert out1 is out2
+
+
+def test_get_universe(seeded_paths: DataPaths) -> None:
+    out = tools.get_universe("NIFTY 50", as_of="2024-06-01", data_dir=str(seeded_paths.root))
+    assert out["index"] == "NIFTY 50"
+    assert out["count"] == 4
+    assert set(out["symbols"]) == {"AAA", "BBB", "CCC", "DDD"}
+
+
+def test_get_fundamentals_basic_found(seeded_paths: DataPaths) -> None:
+    out = tools.get_fundamentals_basic("BBB", data_dir=str(seeded_paths.root))
+    assert out["found"] is True
+    assert out["symbol"] == "BBB"
+    assert out["series"] == "EQ"
+    assert out["last_close"] > 0
+
+
+def test_get_fundamentals_basic_missing(seeded_paths: DataPaths) -> None:
+    out = tools.get_fundamentals_basic("ZZZ", data_dir=str(seeded_paths.root))
+    assert out["found"] is False
+
+
+def test_screen_stocks_runs(seeded_paths: DataPaths) -> None:
+    out = tools.screen_stocks(
+        ["close > 0"],
+        index_name="NIFTY 50",
+        as_of="2024-06-01",
+        data_dir=str(seeded_paths.root),
+    )
+    assert out["count"] >= 1
+    assert out["universe_size"] == 4
+
+
+def test_run_backtest_momentum(seeded_paths: DataPaths) -> None:
+    out = tools.run_backtest(
+        signals_source="momentum",
+        index_name="NIFTY 50",
+        start="2023-06-01",
+        costs="zerodha",
+        lookback=60,
+        top_k=2,
+        data_dir=str(seeded_paths.root),
+    )
+    assert out["signals_source"] == "momentum"
+    assert out["universe_size"] == 4
+    assert "net_cagr" in out["summary"]
+    assert "tearsheet" in out
+    assert isinstance(out["cost_attribution_inr"], dict)
+
+
+def test_run_backtest_equal_weight(seeded_paths: DataPaths) -> None:
+    out = tools.run_backtest(
+        signals_source="equal_weight",
+        index_name="NIFTY 50",
+        data_dir=str(seeded_paths.root),
+    )
+    assert out["summary"]["final_net_value"] > 0
+
+
+def test_run_backtest_unknown_source(seeded_paths: DataPaths) -> None:
+    with pytest.raises(ValueError):
+        tools.run_backtest(
+            signals_source="nope",
+            index_name="NIFTY 50",
+            data_dir=str(seeded_paths.root),
+        )
+
+
+def test_run_backtest_no_data(tmp_path) -> None:
+    with pytest.raises(ValueError):
+        tools.run_backtest(
+            signals_source="momentum",
+            index_name="NIFTY 50",
+            data_dir=str(tmp_path),
+        )