optioncontext-mcp 0.1.0__tar.gz

optioncontext_mcp-0.1.0/.gitignore

@@ -0,0 +1,84 @@
+# mac
+.DS_Store
+**/.DS_Store
+
+# backups
+*.bak
+*.backup
+
+# data
+*.csv
+*.db
+backend/data/
+angelone_core/data/
+backend/invoices/
+
+# env
+.env
+.groww_env
+
+# Ignore virtual environment
+venv/
+
+# Ignore logs and temporary files
+*.log
+logs/
+temp/
+
+# Ignore text files (but allow website/robots.txt which must be deployed)
+*.txt
+!website/robots.txt
+
+# SECURITY: Never upload actual environment variables
+.env
+.groww_env
+
+# Ignore Python cache files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+
+# Date-stamped backup files
+*.08042026
+*.07042026
+licenses.db
+backend/licenses.db*
+
+
+# Large video/AE project assets (112MB+)
+working_files/SetupVideo/
+
+# Working files and build artifacts (root-level local only)
+/working_files/
+/templates/
+/package.json
+/package-lock.json
+
+# Excel temp lock files
+~$*.xlsx
+~$*.xls
+
+# One-off scripts not for deployment
+backend/send_optchain_announcement.py
+
+# Virtual environments
+pdf-env/
+
+backend/licenses.db
+node_modules/
+.claude/
+
+# Credentials
+keys/ga-credentials.json
+
+# Video Automation generated files & models
+video-automation/output/
+video-automation/models/
+video-automation/*.mp4
+video-automation/*.mp3
+video-automation/*.aiff
+video-automation/*.json
+!video-automation/*.py
+!video-automation/*.md
+

optioncontext_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: optioncontext_mcp
+Version: 0.1.0
+Summary: Official Model Context Protocol (MCP) Server for OptionContext Stock and Options Data APIs
+Author-email: OptionContext Team <support@optioncontext.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# OptionContext MCP Server
+
+Official Model Context Protocol (MCP) Server for the OptionContext Stock and Options Data APIs. This premium integration delivers rich analytical and structural data for Indian Stock Markets directly into LLM agents and clients supporting the Model Context Protocol.
+
+## Installation
+
+You can install the OptionContext MCP package using `pip`, or run it on-demand with Node and LLM-centric workflows.
+
+### Installation via pip
+```bash
+pip install optioncontext_mcp
+```
+
+### Direct Run with npx (Node environment)
+```bash
+npx -y optioncontext-mcp
+```
+
+## Configuration
+
+To use the OptionContext MCP Server, you must specify your API key and base endpoint URL. You can configure these options via environment variables:
+
+- `OPTIONCONTEXT_API_KEY`: Your Agent-as-a-Service API key.
+- `OPTIONCONTEXT_BASE_URL`: The OptionContext endpoint gateway URL (defaults to `https://optioncontext.com` if omitted).
+
+For local or custom API gateway environments, `OPTIONCONTEXT_BASE_URL` will fallback automatically to `FASTAPI_BASE_URL` if defined.
+
+## Available Tools
+
+The MCP Server exposes the following powerful market analytical tools to any connected client:
+
+1. **`suggest_symbols`**
+   - **Description**: Search and resolve correct ticker symbols (e.g., searching 'Reliance' to get 'RELIANCE').
+   - **Arguments**:
+     - `query` (string): The search text or company name.
+
+2. **`get_market_context`**
+   - **Description**: Fetch live quote details, last traded price (LTP), volume, and context for Stocks, Indices, and Futures.
+   - **Arguments**:
+     - `symbol` (string): Ticker symbol (e.g. 'NIFTY', 'BANKNIFTY', 'RELIANCE').
+     - `expiry` (string, optional): Expiry cycle ('SPOT', 'NEAR', 'FAR', 'NEXT'). Default is 'SPOT'.
+     - `asset_type` (string, optional): Asset category ('stock', 'index', 'future', 'auto'). Default is 'auto'.
+     - `api_key` (string, optional): Override API Key. If omitted, uses environment key.
+
+3. **`get_option_chain`**
+   - **Description**: Fetch complete option chain matrix including PCR, ATM strike, CE/PE quotes, volume, and Greeks.
+   - **Arguments**:
+     - `symbol` (string): Underlying index or stock ticker (e.g. 'NIFTY', 'BANKNIFTY').
+     - `api_key` (string, optional): Override API Key. If omitted, uses environment key.
+
+4. **`get_historical_data`**
+   - **Description**: Fetch historical daily/intraday OHLCV candles (Requires Plan B subscription).
+   - **Arguments**:
+     - `symbol` (string): Ticker symbol.
+     - `from_date` (string): YYYY-MM-DD.
+     - `to_date` (string): YYYY-MM-DD.
+     - `interval` (string, optional): Candle interval ('ONE_MINUTE', 'FIVE_MINUTE', 'FIFTEEN_MINUTE', 'ONE_DAY'). Default is 'ONE_DAY'.
+     - `api_key` (string, optional): Override API Key.
+
+---
+
+Disclaimer & Risk Warning:
+- Data Delay: All market prices, quotes, and option chains provided represent the last completed minute (minimum 1-minute delayed feed) and are not real-time tick feeds.
+- Accuracy: Data is provided on an 'as-is' basis without warranties of absolute accuracy or timeliness.
+- No Liability: The service is strictly for analytical/educational purposes. We assume no liability for any trading losses or investment decisions.
+- Regulatory Risk Disclosure: Trading in derivatives (options and futures) involves high risk. Past performance is not indicative of future results.

optioncontext_mcp-0.1.0/README.md

@@ -0,0 +1,66 @@
+# OptionContext MCP Server
+
+Official Model Context Protocol (MCP) Server for the OptionContext Stock and Options Data APIs. This premium integration delivers rich analytical and structural data for Indian Stock Markets directly into LLM agents and clients supporting the Model Context Protocol.
+
+## Installation
+
+You can install the OptionContext MCP package using `pip`, or run it on-demand with Node and LLM-centric workflows.
+
+### Installation via pip
+```bash
+pip install optioncontext_mcp
+```
+
+### Direct Run with npx (Node environment)
+```bash
+npx -y optioncontext-mcp
+```
+
+## Configuration
+
+To use the OptionContext MCP Server, you must specify your API key and base endpoint URL. You can configure these options via environment variables:
+
+- `OPTIONCONTEXT_API_KEY`: Your Agent-as-a-Service API key.
+- `OPTIONCONTEXT_BASE_URL`: The OptionContext endpoint gateway URL (defaults to `https://optioncontext.com` if omitted).
+
+For local or custom API gateway environments, `OPTIONCONTEXT_BASE_URL` will fallback automatically to `FASTAPI_BASE_URL` if defined.
+
+## Available Tools
+
+The MCP Server exposes the following powerful market analytical tools to any connected client:
+
+1. **`suggest_symbols`**
+   - **Description**: Search and resolve correct ticker symbols (e.g., searching 'Reliance' to get 'RELIANCE').
+   - **Arguments**:
+     - `query` (string): The search text or company name.
+
+2. **`get_market_context`**
+   - **Description**: Fetch live quote details, last traded price (LTP), volume, and context for Stocks, Indices, and Futures.
+   - **Arguments**:
+     - `symbol` (string): Ticker symbol (e.g. 'NIFTY', 'BANKNIFTY', 'RELIANCE').
+     - `expiry` (string, optional): Expiry cycle ('SPOT', 'NEAR', 'FAR', 'NEXT'). Default is 'SPOT'.
+     - `asset_type` (string, optional): Asset category ('stock', 'index', 'future', 'auto'). Default is 'auto'.
+     - `api_key` (string, optional): Override API Key. If omitted, uses environment key.
+
+3. **`get_option_chain`**
+   - **Description**: Fetch complete option chain matrix including PCR, ATM strike, CE/PE quotes, volume, and Greeks.
+   - **Arguments**:
+     - `symbol` (string): Underlying index or stock ticker (e.g. 'NIFTY', 'BANKNIFTY').
+     - `api_key` (string, optional): Override API Key. If omitted, uses environment key.
+
+4. **`get_historical_data`**
+   - **Description**: Fetch historical daily/intraday OHLCV candles (Requires Plan B subscription).
+   - **Arguments**:
+     - `symbol` (string): Ticker symbol.
+     - `from_date` (string): YYYY-MM-DD.
+     - `to_date` (string): YYYY-MM-DD.
+     - `interval` (string, optional): Candle interval ('ONE_MINUTE', 'FIVE_MINUTE', 'FIFTEEN_MINUTE', 'ONE_DAY'). Default is 'ONE_DAY'.
+     - `api_key` (string, optional): Override API Key.
+
+---
+
+Disclaimer & Risk Warning:
+- Data Delay: All market prices, quotes, and option chains provided represent the last completed minute (minimum 1-minute delayed feed) and are not real-time tick feeds.
+- Accuracy: Data is provided on an 'as-is' basis without warranties of absolute accuracy or timeliness.
+- No Liability: The service is strictly for analytical/educational purposes. We assume no liability for any trading losses or investment decisions.
+- Regulatory Risk Disclosure: Trading in derivatives (options and futures) involves high risk. Past performance is not indicative of future results.

optioncontext_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "optioncontext_mcp"
+version = "0.1.0"
+description = "Official Model Context Protocol (MCP) Server for OptionContext Stock and Options Data APIs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "OptionContext Team", email = "support@optioncontext.com" }
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0"
+]
+
+[project.scripts]
+optioncontext-mcp = "optioncontext_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/optioncontext_mcp"]

optioncontext_mcp-0.1.0/src/optioncontext_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

optioncontext_mcp-0.1.0/src/optioncontext_mcp/__main__.py

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

optioncontext_mcp-0.1.0/src/optioncontext_mcp/client.py

@@ -0,0 +1,71 @@
+import os
+import uuid
+import asyncio
+import httpx
+from typing import Dict, Any, Optional
+
+class OptionContextClient:
+    def __init__(self, base_url: Optional[str] = None, api_key: Optional[str] = None):
+        self.base_url = (base_url or os.getenv("OPTIONCONTEXT_BASE_URL") or os.getenv("FASTAPI_BASE_URL") or "https://optioncontext.com").rstrip("/")
+        self.default_api_key = api_key or os.getenv("OPTIONCONTEXT_API_KEY")
+
+    def _resolve_api_key(self, provided_key: Optional[str]) -> str:
+        key = provided_key or self.default_api_key
+        if not key:
+            raise ValueError("API Key is missing. Pass 'api_key' to the tool or set OPTIONCONTEXT_API_KEY in your environment variables.")
+        return key
+
+    async def _request_with_retry(self, endpoint: str, params: Dict[str, Any], api_key: Optional[str], requires_auth: bool = True, max_attempts: int = 3) -> str:
+        url = f"{self.base_url}{endpoint}"
+        headers = {"X-Idempotency-Key": str(uuid.uuid4())}
+
+        if requires_auth:
+            headers["X-Agent-API-Key"] = self._resolve_api_key(api_key)
+
+        for attempt in range(max_attempts):
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(url, headers=headers, params=params, timeout=15.0)
+                    if response.status_code == 200:
+                        try:
+                            data = response.json()
+                            if data.get("status") in ("PENDING", "loading") and attempt < max_attempts - 1:
+                                await asyncio.sleep(4.0)
+                                continue
+                        except ValueError:
+                            pass
+                        return response.text
+                    elif response.status_code == 403:
+                        return f"Forbidden (403): Access Denied. Historical data requires a Plan B subscription."
+                    elif response.status_code == 401:
+                        return f"Unauthorized (401): Invalid or expired API credentials."
+                    else:
+                        return f"Error {response.status_code}: {response.text}"
+            except Exception as e:
+                if attempt < max_attempts - 1:
+                    await asyncio.sleep(4.0)
+                    continue
+                return f"Error connecting to OptionContext gateway: {str(e)}"
+        return "Error: Request timed out after multiple retries."
+
+    async def suggest_symbols(self, query: str) -> str:
+        return await self._request_with_retry("/api/suggest-symbols", {"query": query}, api_key=None, requires_auth=False)
+
+    async def get_market_context(self, symbol: str, expiry: str = "SPOT", asset_type: str = "auto", api_key: Optional[str] = None) -> str:
+        params = {"symbol": symbol.upper().strip(), "expiry": expiry.upper().strip()}
+        if asset_type and asset_type != "auto":
+            params["asset_type"] = asset_type
+        return await self._request_with_retry("/api/agent/market-data", params, api_key)
+
+    async def get_option_chain(self, symbol: str, api_key: Optional[str] = None) -> str:
+        params = {"symbol": symbol.upper().strip()}
+        return await self._request_with_retry("/api/agent/option-chain", params, api_key)
+
+    async def get_historical_data(self, symbol: str, from_date: str, to_date: str, interval: str = "ONE_DAY", api_key: Optional[str] = None) -> str:
+        params = {
+            "symbol": symbol.upper().strip(),
+            "from": from_date,
+            "to": to_date,
+            "interval": interval
+        }
+        return await self._request_with_retry("/api/agent/historical-data", params, api_key)

optioncontext_mcp-0.1.0/src/optioncontext_mcp/server.py

@@ -0,0 +1,56 @@
+from mcp.server.fastmcp import FastMCP
+from typing import Optional
+from optioncontext_mcp.client import OptionContextClient
+
+mcp = FastMCP("OptionContext MCP Server")
+client = OptionContextClient()
+
+@mcp.tool()
+async def suggest_symbols(query: str) -> str:
+    """
+    Search and resolve correct ticker symbols (e.g. searching 'Reliance' to get 'RELIANCE').
+    Args:
+        query (str): The search text or company name.
+    """
+    return await client.suggest_symbols(query)
+
+@mcp.tool()
+async def get_market_context(symbol: str, expiry: str = "SPOT", asset_type: str = "auto", api_key: Optional[str] = None) -> str:
+    """
+    Fetch live quote details, last traded price (LTP), volume, and context for Stocks, Indices, and Futures.
+    Args:
+        symbol (str): Ticker symbol (e.g. 'NIFTY', 'BANKNIFTY', 'RELIANCE').
+        expiry (str): Expiry cycle ('SPOT', 'NEAR', 'FAR', 'NEXT'). Default is 'SPOT'.
+        asset_type (str): Asset category ('stock', 'index', 'future', 'auto'). Default is 'auto'.
+        api_key (str, optional): API Key. If omitted, uses OPTIONCONTEXT_API_KEY from environment.
+    """
+    return await client.get_market_context(symbol, expiry, asset_type, api_key)
+
+@mcp.tool()
+async def get_option_chain(symbol: str, api_key: Optional[str] = None) -> str:
+    """
+    Fetch complete option chain matrix including PCR, ATM strike, CE/PE quotes, volume, and Greeks.
+    Args:
+        symbol (str): Underlying index or stock ticker (e.g. 'NIFTY', 'BANKNIFTY').
+        api_key (str, optional): API Key. If omitted, uses OPTIONCONTEXT_API_KEY from environment.
+    """
+    return await client.get_option_chain(symbol, api_key)
+
+@mcp.tool()
+async def get_historical_data(symbol: str, from_date: str, to_date: str, interval: str = "ONE_DAY", api_key: Optional[str] = None) -> str:
+    """
+    Fetch historical daily/intraday OHLCV candles (Requires Plan B subscription).
+    Args:
+        symbol (str): Ticker symbol.
+        from_date (str): YYYY-MM-DD.
+        to_date (str): YYYY-MM-DD.
+        interval (str): Candle interval ('ONE_MINUTE', 'FIVE_MINUTE', 'FIFTEEN_MINUTE', 'ONE_DAY'). Default is 'ONE_DAY'.
+        api_key (str, optional): API Key.
+    """
+    return await client.get_historical_data(symbol, from_date, to_date, interval, api_key)
+
+def main():
+    mcp.run()
+
+if __name__ == "__main__":
+    main()