magiqa-mcp 0.1.0__tar.gz

magiqa_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: magiqa-mcp
+Version: 0.1.0
+Summary: MCP server for MagiQa Options: covered calls, cash-secured puts, spreads, iron condors and options scanners for AI assistants
+Author-email: Magiqa <info@magiqa.us>
+License: MIT
+Project-URL: Homepage, https://options.magiqa.us
+Project-URL: Documentation, https://options.magiqa.us/documentation
+Project-URL: Source, https://github.com/Avetik1980/optionsAPI
+Keywords: mcp,options,covered calls,iron condor,stocks,finance,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# magiqa-mcp
+
+MCP server for [MagiQa Options](https://options.magiqa.us). Lets Claude, Cursor and other MCP clients screen US stock options with your MagiQa API key.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `get_stock_snapshot` | Price, SMA/RSI/MACD, signal, trend, valuation, earnings estimates |
+| `find_covered_calls` | Covered calls, one symbol or market-wide |
+| `find_cash_secured_puts` | Cash-secured puts |
+| `find_credit_spreads` | Bull put (bullish) or bear call (bearish) spreads |
+| `find_debit_spreads` | Bull call (bullish) or bear put (bearish) spreads |
+| `find_iron_condors` | Short or long iron condors |
+| `find_straddles_strangles` | Long or short straddles and strangles |
+| `find_high_probability_options` | Highest probability-of-profit trades |
+| `get_unusual_options_activity` | Volume far above open interest |
+| `get_most_active_options` | Highest options volume |
+| `get_highest_open_interest` | Largest open interest |
+| `get_earnings_calendar` | Upcoming earnings |
+
+Each tool returns at most 50 rows (default 10). Option premiums are from the previous session close. Results are analytics, not investment advice.
+
+## Setup
+
+Get an API key at [options.magiqa.us](https://options.magiqa.us), then add the server to your MCP client.
+
+**Claude Desktop** (`claude_desktop_config.json`) or **Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "magiqa": {
+      "command": "uvx",
+      "args": ["magiqa-mcp"],
+      "env": { "MAGIQA_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+Without `uv`: `pip install magiqa-mcp` and use `"command": "magiqa-mcp"` with no `args`.
+
+Your plan's rate limits and symbol access apply.

magiqa_mcp-0.1.0/README.md

@@ -0,0 +1,44 @@
+# magiqa-mcp
+
+MCP server for [MagiQa Options](https://options.magiqa.us). Lets Claude, Cursor and other MCP clients screen US stock options with your MagiQa API key.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `get_stock_snapshot` | Price, SMA/RSI/MACD, signal, trend, valuation, earnings estimates |
+| `find_covered_calls` | Covered calls, one symbol or market-wide |
+| `find_cash_secured_puts` | Cash-secured puts |
+| `find_credit_spreads` | Bull put (bullish) or bear call (bearish) spreads |
+| `find_debit_spreads` | Bull call (bullish) or bear put (bearish) spreads |
+| `find_iron_condors` | Short or long iron condors |
+| `find_straddles_strangles` | Long or short straddles and strangles |
+| `find_high_probability_options` | Highest probability-of-profit trades |
+| `get_unusual_options_activity` | Volume far above open interest |
+| `get_most_active_options` | Highest options volume |
+| `get_highest_open_interest` | Largest open interest |
+| `get_earnings_calendar` | Upcoming earnings |
+
+Each tool returns at most 50 rows (default 10). Option premiums are from the previous session close. Results are analytics, not investment advice.
+
+## Setup
+
+Get an API key at [options.magiqa.us](https://options.magiqa.us), then add the server to your MCP client.
+
+**Claude Desktop** (`claude_desktop_config.json`) or **Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "magiqa": {
+      "command": "uvx",
+      "args": ["magiqa-mcp"],
+      "env": { "MAGIQA_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+Without `uv`: `pip install magiqa-mcp` and use `"command": "magiqa-mcp"` with no `args`.
+
+Your plan's rate limits and symbol access apply.

magiqa_mcp-0.1.0/magiqa_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MagiQa Options MCP server: options strategy screeners for AI assistants."""
+
+__version__ = "0.1.0"

magiqa_mcp-0.1.0/magiqa_mcp/server.py

@@ -0,0 +1,331 @@
+"""
+MagiQa Options MCP server (stdio).
+
+Thin wrapper over the MagiQa REST API using the caller's own API key
+(MAGIQA_API_KEY). Plan limits and symbol access are enforced by the API.
+
+Scanner fields that are estimated rather than measured (IV rank/percentile,
+historical volatility, OI change) are stripped from every response until
+they are backed by stored history.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Literal, Optional
+
+import httpx
+from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+
+from magiqa_mcp import __version__
+
+DEFAULT_BASE_URL = "https://options.magiqa.us"
+DEFAULT_LIMIT = 10
+MAX_LIMIT = 50
+TIMEOUT_SECONDS = 30.0
+
+ESTIMATED_FIELDS = frozenset({
+    "iv_rank", "iv_percentile", "iv_high_52w", "iv_low_52w", "iv_signal", "strategy_hint",
+    "iv_hv", "iv_hv_ratio", "historical_volatility", "his_vol_30d",
+    "previous_oi", "oi_change", "oi_change_pct",
+})
+
+STOCK_SNAPSHOT_FIELDS = (
+    "symbol", "name", "sector", "price", "change", "change_percent", "open", "high", "low",
+    "volume_raw", "avg_volume_raw", "market_cap", "pe_ratio", "dividend_yield", "one_year_return",
+    "sma_5", "sma_8", "sma_13", "sma_50", "sma_200", "rsi", "macd", "macd_signal", "volatility",
+    "signal", "sma_decision", "trend", "altman_z_score", "piotroski_score",
+    "eps_actual", "eps_estimated", "revenue_actual", "revenue_estimated",
+    "quote_year_high", "quote_year_low", "last_updated", "quote_refreshed_at",
+)
+
+INSTRUCTIONS = (
+    "MagiQa screens US stock options (S&P 500 + popular ETFs) and returns strategy-ready trades "
+    "with probability of profit, breakevens and returns. Option premiums come from the previous "
+    "session close. Results are analytics, not investment advice."
+)
+
+
+class MagiqaAPIError(ToolError):
+    """Anticipated API failure; the SDK shows this message to the model."""
+
+
+class MagiqaClient:
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None,
+                 transport: Optional[httpx.BaseTransport] = None):
+        self.api_key = api_key or os.getenv("MAGIQA_API_KEY", "")
+        self.base_url = (base_url or os.getenv("MAGIQA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"X-API-Key": self.api_key, "User-Agent": f"magiqa-mcp/{__version__}"},
+            timeout=TIMEOUT_SECONDS,
+            transport=transport,
+        )
+
+    def get(self, path: str, params: Optional[dict] = None) -> Any:
+        if not self.api_key:
+            raise MagiqaAPIError(
+                "MAGIQA_API_KEY is not set. Get a key at https://options.magiqa.us and add it to "
+                "the MCP server's environment."
+            )
+        clean = {k: v for k, v in (params or {}).items() if v is not None}
+        try:
+            resp = self._http.get(path, params=clean)
+        except httpx.HTTPError as e:
+            raise MagiqaAPIError(f"Could not reach MagiQa API: {e}") from e
+        if resp.status_code == 401:
+            raise MagiqaAPIError(_unauthorized_message(resp))
+        if resp.status_code == 403:
+            raise MagiqaAPIError(f"Not available on your MagiQa plan (403): {_detail(resp)}")
+        if resp.status_code == 429:
+            raise MagiqaAPIError("MagiQa rate limit reached (429). Try again later or upgrade the plan.")
+        if resp.status_code >= 400:
+            raise MagiqaAPIError(f"MagiQa API error {resp.status_code}: {_detail(resp)}")
+        return resp.json()
+
+
+def _unauthorized_message(resp: httpx.Response) -> str:
+    """A 401 is either a bad key or an endpoint that still accepts RapidAPI only."""
+    detail = _detail(resp)
+    lowered = detail.lower()
+    if "rapidapi" in lowered or "x-rapidapi" in lowered:
+        return (
+            "This MagiQa endpoint is not available with an API key (401). "
+            "It only accepts RapidAPI traffic."
+        )
+    if detail and detail not in ("nope", "{}"):
+        return f"MagiQa rejected the API key (401): {detail}"
+    return "MagiQa rejected the API key (401). Check MAGIQA_API_KEY."
+
+
+def _detail(resp: httpx.Response) -> str:
+    try:
+        body = resp.json()
+        return str(body.get("detail", body))[:300] if isinstance(body, dict) else str(body)[:300]
+    except ValueError:
+        return resp.text[:300]
+
+
+def _clamp(limit: int) -> int:
+    return max(1, min(int(limit), MAX_LIMIT))
+
+
+def shape(payload: Any, limit: int) -> Any:
+    """Drop estimated fields at any depth and cap every list at `limit` rows."""
+    if isinstance(payload, dict):
+        out = {}
+        for k, v in payload.items():
+            if k in ESTIMATED_FIELDS:
+                continue
+            if isinstance(v, list) and len(v) > limit:
+                out[k] = [shape(x, limit) for x in v[:limit]]
+                out[f"{k}_total"] = len(v)
+            else:
+                out[k] = shape(v, limit)
+        return out
+    if isinstance(payload, list):
+        return [shape(x, limit) for x in payload[:limit]]
+    return payload
+
+
+def build_server(client: Optional[MagiqaClient] = None) -> MCPServer:
+    api = client or MagiqaClient()
+    mcp = MCPServer(
+        "MagiQa Options",
+        instructions=INSTRUCTIONS,
+        version=__version__,
+        website_url="https://options.magiqa.us",
+    )
+
+    def fetch(path: str, limit: int, params: Optional[dict] = None) -> Any:
+        n = _clamp(limit)
+        return shape(api.get(path, {**(params or {}), "limit": n}), n)
+
+    @mcp.tool()
+    def get_stock_snapshot(symbol: str) -> dict:
+        """Price, technical indicators (SMA, RSI, MACD, volatility, signal, trend), valuation and
+        upcoming earnings estimates for one US stock or ETF."""
+        data = api.get(f"/api/stocks/{symbol.upper().strip()}")
+        if not isinstance(data, dict):
+            return {"symbol": symbol.upper(), "data": data}
+        return {k: data.get(k) for k in STOCK_SNAPSHOT_FIELDS if k in data}
+
+    @mcp.tool()
+    def find_covered_calls(
+        symbol: Optional[str] = None,
+        min_days_to_expiration: int = 0,
+        max_days_to_expiration: int = 60,
+        min_probability: float = 0,
+        min_return: float = 0,
+        limit: int = DEFAULT_LIMIT,
+    ) -> Any:
+        """Covered call opportunities (own 100 shares, sell a call). With `symbol`, returns that
+        symbol's covered calls; without it, the best across the market using the filters."""
+        if symbol:
+            return fetch(f"/api/basic-options/covered-calls/{symbol.upper().strip()}", limit)
+        return fetch("/api/basic-options/covered-calls", limit, {
+            "minDaysToExpiration": min_days_to_expiration,
+            "maxDaysToExpiration": max_days_to_expiration,
+            "minProbability": min_probability,
+            "minReturn": min_return,
+        })
+
+    @mcp.tool()
+    def find_cash_secured_puts(
+        symbol: Optional[str] = None,
+        min_days_to_expiration: Optional[int] = None,
+        max_days_to_expiration: Optional[int] = None,
+        min_profit_probability: Optional[float] = None,
+        min_annualized_return: Optional[float] = None,
+        max_investment: Optional[float] = None,
+        limit: int = DEFAULT_LIMIT,
+    ) -> Any:
+        """Cash-secured (naked) put opportunities: sell a put, collect premium, possibly buy the
+        stock at the strike. Optional symbol and filters."""
+        return fetch("/api/basic-options/naked-puts", limit, {
+            "symbol": symbol.upper().strip() if symbol else None,
+            "minDaysToExpiration": min_days_to_expiration,
+            "maxDaysToExpiration": max_days_to_expiration,
+            "minProfitProbability": min_profit_probability,
+            "minAnnualizedReturn": min_annualized_return,
+            "maxInvestment": max_investment,
+        })
+
+    @mcp.tool()
+    def find_credit_spreads(
+        direction: Literal["bullish", "bearish"],
+        min_days_to_expiration: Optional[int] = None,
+        max_days_to_expiration: Optional[int] = None,
+        min_profit_probability: Optional[float] = None,
+        min_roi: Optional[float] = None,
+        max_investment: Optional[float] = None,
+        limit: int = DEFAULT_LIMIT,
+    ) -> Any:
+        """Credit spreads: bullish = bull put spread, bearish = bear call spread. Defined risk,
+        collect premium up front."""
+        path = "/api/spreads/bull-put" if direction == "bullish" else "/api/spreads/bear-call"
+        return fetch(path, limit, {
+            "minDaysToExpiration": min_days_to_expiration,
+            "maxDaysToExpiration": max_days_to_expiration,
+            "minProfitProbability": min_profit_probability,
+            "minROI": min_roi,
+            "maxInvestment": max_investment,
+        })
+
+    @mcp.tool()
+    def find_debit_spreads(
+        direction: Literal["bullish", "bearish"],
+        min_days_to_expiration: Optional[int] = None,
+        max_days_to_expiration: Optional[int] = None,
+        min_profit_probability: Optional[float] = None,
+        min_roi: Optional[float] = None,
+        max_investment: Optional[float] = None,
+        limit: int = DEFAULT_LIMIT,
+    ) -> Any:
+        """Debit spreads: bullish = bull call spread, bearish = bear put spread. Defined risk,
+        pay premium up front."""
+        path = "/api/spreads/bull-call" if direction == "bullish" else "/api/spreads/bear-put"
+        return fetch(path, limit, {
+            "minDaysToExpiration": min_days_to_expiration,
+            "maxDaysToExpiration": max_days_to_expiration,
+            "minProfitProbability": min_profit_probability,
+            "minROI": min_roi,
+            "maxInvestment": max_investment,
+        })
+
+    @mcp.tool()
+    def find_iron_condors(
+        side: Literal["short", "long"] = "short",
+        min_days_to_expiration: int = 0,
+        max_days_to_expiration: int = 180,
+        min_profit_probability: float = 0,
+        limit: int = DEFAULT_LIMIT,
+    ) -> Any:
+        """Iron condors. short = sell the condor for a credit (profits if the stock stays in a
+        range); long = buy it (profits on a big move)."""
+        return fetch("/api/scanners/iron-condor-screener", limit, {
+            "strategy_type": f"{side}_iron_condor",
+            "minDaysToExpiration": min_days_to_expiration,
+            "maxDaysToExpiration": max_days_to_expiration,
+            "minProbProfit": min_profit_probability,
+        })
+
+    @mcp.tool()
+    def find_straddles_strangles(
+        kind: Literal["straddle", "strangle"] = "straddle",
+        side: Literal["long", "short"] = "long",
+        min_days_to_expiration: int = 0,
+        max_days_to_expiration: int = 90,
+        min_profit_probability: float = 0,
+        min_volume: int = 0,
+        limit: int = DEFAULT_LIMIT,
+    ) -> Any:
+        """Straddles (same strike) or strangles (different strikes). long = bet on a big move;
+        short = bet on a quiet market."""
+        return fetch(f"/api/scanners/{kind}-screener", limit, {
+            "strategy_type": side,
+            "minDaysToExpiration": min_days_to_expiration,
+            "maxDaysToExpiration": max_days_to_expiration,
+            "minProbProfit": min_profit_probability,
+            "minVolume": min_volume,
+        })
+
+    @mcp.tool()
+    def find_high_probability_options(
+        min_profit_probability: float = 60,
+        max_days_to_expiration: int = 45,
+        min_volume: int = 100,
+        limit: int = DEFAULT_LIMIT,
+    ) -> Any:
+        """Option trades with the highest probability of profit across the market."""
+        return fetch("/api/scanners/options-screener/high-probability", limit, {
+            "minProfitProb": min_profit_probability,
+            "maxDaysToExpiration": max_days_to_expiration,
+            "minVolume": min_volume,
+        })
+
+    @mcp.tool()
+    def get_unusual_options_activity(
+        symbol: Optional[str] = None,
+        option_type: Literal["all", "call", "put"] = "all",
+        min_volume: int = 1000,
+        max_days_to_expiration: int = 45,
+        limit: int = DEFAULT_LIMIT,
+    ) -> Any:
+        """Contracts trading far above their open interest (possible new positioning)."""
+        if symbol:
+            return fetch(f"/api/scanners/unusual-activity/{symbol.upper().strip()}", limit)
+        return fetch("/api/scanners/unusual-activity", limit, {
+            "optionType": option_type,
+            "minVolume": min_volume,
+            "maxDaysToExpiration": max_days_to_expiration,
+        })
+
+    @mcp.tool()
+    def get_most_active_options(symbol: Optional[str] = None, limit: int = DEFAULT_LIMIT) -> Any:
+        """Underlyings (or one symbol's contracts) with the highest options volume."""
+        if symbol:
+            return fetch(f"/api/scanners/most-active-options/{symbol.upper().strip()}", limit)
+        return fetch("/api/scanners/most-active-options", limit)
+
+    @mcp.tool()
+    def get_highest_open_interest(symbol: Optional[str] = None, limit: int = DEFAULT_LIMIT) -> Any:
+        """Underlyings (or one symbol's contracts) with the largest open interest."""
+        if symbol:
+            return fetch(f"/api/scanners/highest-open-interest/{symbol.upper().strip()}", limit)
+        return fetch("/api/scanners/highest-open-interest", limit)
+
+    @mcp.tool()
+    def get_earnings_calendar(days: int = 7) -> Any:
+        """Upcoming earnings reports for the next `days` days (max 30)."""
+        return shape(api.get("/api/stocks/earnings-calendar", {"days": max(1, min(days, 30))}), 200)
+
+    return mcp
+
+
+def main() -> None:
+    build_server().run("stdio")
+
+
+if __name__ == "__main__":
+    main()

magiqa_mcp-0.1.0/magiqa_mcp.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: magiqa-mcp
+Version: 0.1.0
+Summary: MCP server for MagiQa Options: covered calls, cash-secured puts, spreads, iron condors and options scanners for AI assistants
+Author-email: Magiqa <info@magiqa.us>
+License: MIT
+Project-URL: Homepage, https://options.magiqa.us
+Project-URL: Documentation, https://options.magiqa.us/documentation
+Project-URL: Source, https://github.com/Avetik1980/optionsAPI
+Keywords: mcp,options,covered calls,iron condor,stocks,finance,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# magiqa-mcp
+
+MCP server for [MagiQa Options](https://options.magiqa.us). Lets Claude, Cursor and other MCP clients screen US stock options with your MagiQa API key.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `get_stock_snapshot` | Price, SMA/RSI/MACD, signal, trend, valuation, earnings estimates |
+| `find_covered_calls` | Covered calls, one symbol or market-wide |
+| `find_cash_secured_puts` | Cash-secured puts |
+| `find_credit_spreads` | Bull put (bullish) or bear call (bearish) spreads |
+| `find_debit_spreads` | Bull call (bullish) or bear put (bearish) spreads |
+| `find_iron_condors` | Short or long iron condors |
+| `find_straddles_strangles` | Long or short straddles and strangles |
+| `find_high_probability_options` | Highest probability-of-profit trades |
+| `get_unusual_options_activity` | Volume far above open interest |
+| `get_most_active_options` | Highest options volume |
+| `get_highest_open_interest` | Largest open interest |
+| `get_earnings_calendar` | Upcoming earnings |
+
+Each tool returns at most 50 rows (default 10). Option premiums are from the previous session close. Results are analytics, not investment advice.
+
+## Setup
+
+Get an API key at [options.magiqa.us](https://options.magiqa.us), then add the server to your MCP client.
+
+**Claude Desktop** (`claude_desktop_config.json`) or **Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "magiqa": {
+      "command": "uvx",
+      "args": ["magiqa-mcp"],
+      "env": { "MAGIQA_API_KEY": "your-api-key" }
+    }
+  }
+}
+```
+
+Without `uv`: `pip install magiqa-mcp` and use `"command": "magiqa-mcp"` with no `args`.
+
+Your plan's rate limits and symbol access apply.

magiqa_mcp-0.1.0/magiqa_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+magiqa_mcp/__init__.py
+magiqa_mcp/server.py
+magiqa_mcp.egg-info/PKG-INFO
+magiqa_mcp.egg-info/SOURCES.txt
+magiqa_mcp.egg-info/dependency_links.txt
+magiqa_mcp.egg-info/entry_points.txt
+magiqa_mcp.egg-info/requires.txt
+magiqa_mcp.egg-info/top_level.txt
+tests/test_server.py

magiqa_mcp-0.1.0/magiqa_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

magiqa_mcp-0.1.0/magiqa_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+magiqa-mcp = magiqa_mcp.server:main

magiqa_mcp-0.1.0/magiqa_mcp.egg-info/requires.txt

@@ -0,0 +1,5 @@
+mcp<3,>=2.3
+httpx>=0.27
+
+[dev]
+pytest>=7

magiqa_mcp-0.1.0/magiqa_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+magiqa_mcp

magiqa_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "magiqa-mcp"
+dynamic = ["version"]
+description = "MCP server for MagiQa Options: covered calls, cash-secured puts, spreads, iron condors and options scanners for AI assistants"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Magiqa", email = "info@magiqa.us" }]
+keywords = ["mcp", "options", "covered calls", "iron condor", "stocks", "finance", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "mcp>=2.3,<3",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+magiqa-mcp = "magiqa_mcp.server:main"
+
+[project.urls]
+Homepage = "https://options.magiqa.us"
+Documentation = "https://options.magiqa.us/documentation"
+Source = "https://github.com/Avetik1980/optionsAPI"
+
+[tool.setuptools]
+packages = ["magiqa_mcp"]
+
+[tool.setuptools.dynamic]
+version = { attr = "magiqa_mcp.__version__" }

magiqa_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

magiqa_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,127 @@
+"""In-memory tests for magiqa-mcp against a mocked MagiQa API (no network)."""
+from __future__ import annotations
+
+import asyncio
+import json
+
+import httpx
+import pytest
+from mcp import Client
+
+from magiqa_mcp.server import MAX_LIMIT, MagiqaClient, build_server, shape
+
+EXPECTED_TOOLS = {
+    "get_stock_snapshot", "find_covered_calls", "find_cash_secured_puts", "find_credit_spreads",
+    "find_debit_spreads", "find_iron_condors", "find_straddles_strangles",
+    "find_high_probability_options", "get_unusual_options_activity", "get_most_active_options",
+    "get_highest_open_interest", "get_earnings_calendar",
+}
+
+
+def make_server(handler, api_key="test-key"):
+    seen = []
+
+    def wrapped(request: httpx.Request) -> httpx.Response:
+        seen.append(request)
+        return handler(request)
+
+    client = MagiqaClient(api_key=api_key, base_url="https://api.test",
+                          transport=httpx.MockTransport(wrapped))
+    return build_server(client), seen
+
+
+def call(server, name, args):
+    async def run():
+        async with Client(server) as c:
+            return await c.call_tool(name, args)
+    return asyncio.run(run())
+
+
+def payload(result):
+    if result.structured_content is not None:
+        sc = result.structured_content
+        return sc.get("result", sc) if isinstance(sc, dict) and set(sc) == {"result"} else sc
+    return json.loads(result.content[0].text)
+
+
+def test_lists_exactly_the_v1_tools():
+    server, _ = make_server(lambda r: httpx.Response(200, json={}))
+
+    async def run():
+        async with Client(server) as c:
+            return await c.list_tools()
+    tools = {t.name for t in asyncio.run(run()).tools}
+    assert tools == EXPECTED_TOOLS
+
+
+def test_shape_strips_estimated_fields_and_caps_lists():
+    data = {"count": 3, "data": [{"symbol": "A", "iv_rank": 50, "pop": 70}] * 3}
+    out = shape(data, 2)
+    assert len(out["data"]) == 2 and out["data_total"] == 3
+    assert "iv_rank" not in out["data"][0] and out["data"][0]["pop"] == 70
+
+
+def test_covered_calls_sends_key_filters_and_clamped_limit():
+    server, seen = make_server(lambda r: httpx.Response(200, json={"data": [{"symbol": "AAPL"}]}))
+    res = call(server, "find_covered_calls", {"max_days_to_expiration": 45, "limit": 500})
+    assert not res.is_error
+    req = seen[-1]
+    assert req.url.path == "/api/basic-options/covered-calls"
+    assert req.headers["X-API-Key"] == "test-key"
+    assert req.url.params["maxDaysToExpiration"] == "45"
+    assert req.url.params["limit"] == str(MAX_LIMIT)
+
+
+def test_covered_calls_with_symbol_uses_symbol_route():
+    server, seen = make_server(lambda r: httpx.Response(200, json={"data": []}))
+    call(server, "find_covered_calls", {"symbol": "aapl"})
+    assert seen[-1].url.path == "/api/basic-options/covered-calls/AAPL"
+
+
+def test_credit_spread_direction_routes():
+    server, seen = make_server(lambda r: httpx.Response(200, json={"data": []}))
+    call(server, "find_credit_spreads", {"direction": "bearish"})
+    assert seen[-1].url.path == "/api/spreads/bear-call"
+    call(server, "find_credit_spreads", {"direction": "bullish", "min_roi": 10})
+    assert seen[-1].url.path == "/api/spreads/bull-put"
+    assert seen[-1].url.params["minROI"] == "10.0"
+    assert "maxInvestment" not in seen[-1].url.params
+
+
+def test_iron_condor_side_maps_to_strategy_type():
+    server, seen = make_server(lambda r: httpx.Response(200, json={"data": []}))
+    call(server, "find_iron_condors", {"side": "short"})
+    assert seen[-1].url.params["strategy_type"] == "short_iron_condor"
+
+
+def test_stock_snapshot_returns_curated_fields_only():
+    row = {"symbol": "NVDA", "price": 239.24, "sma_50": 219.77, "balance_total_assets": 1, "iv_rank": 9}
+    server, _ = make_server(lambda r: httpx.Response(200, json=row))
+    out = payload(call(server, "get_stock_snapshot", {"symbol": "nvda"}))
+    assert out == {"symbol": "NVDA", "price": 239.24, "sma_50": 219.77}
+
+
+@pytest.mark.parametrize("status,needle", [(401, "API key"), (403, "plan"), (429, "rate limit")])
+def test_api_errors_become_readable_tool_errors(status, needle):
+    server, _ = make_server(lambda r: httpx.Response(status, json={"detail": "nope"}))
+    res = call(server, "get_most_active_options", {})
+    assert res.is_error
+    assert needle in res.content[0].text
+
+
+def test_rapidapi_only_endpoint_is_not_blamed_on_the_key():
+    server, _ = make_server(lambda r: httpx.Response(
+        401, json={"detail": "Missing RapidAPI header. X-RapidAPI-Host is required."}
+    ))
+    res = call(server, "get_most_active_options", {})
+    assert res.is_error
+    text = res.content[0].text
+    assert "not available with an API key" in text
+    assert "Check MAGIQA_API_KEY" not in text
+
+
+def test_missing_api_key_is_explained_without_calling_api():
+    server, seen = make_server(lambda r: httpx.Response(200, json={}), api_key="")
+    res = call(server, "get_earnings_calendar", {})
+    assert res.is_error and "MAGIQA_API_KEY" in res.content[0].text
+    assert seen == []