finstack-mcp 0.3.0__tar.gz

finstack_mcp-0.3.0/.env.example

@@ -0,0 +1,33 @@
+# FinStack MCP Server Configuration
+# Copy this to .env and fill in your values
+
+# ===== FREE DATA SOURCES (no key needed for basic usage) =====
+# yfinance: No API key required
+# SEC EDGAR: No API key required (but set a user agent)
+SEC_EDGAR_USER_AGENT="FinStack/0.1.0 your-email@example.com"
+
+# ===== OPTIONAL: Enhanced Data Sources =====
+# Alpha Vantage (free tier: 25 requests/day)
+# Get yours at: https://www.alphavantage.co/support/#api-key
+ALPHA_VANTAGE_API_KEY=""
+
+# CoinGecko (free tier: 30 calls/min)
+# Get yours at: https://www.coingecko.com/en/api
+COINGECKO_API_KEY=""
+
+# ===== HOSTED MODE (Phase 2+) =====
+# Only needed if you're running the hosted/paid version
+FINSTACK_MODE="free"  # free | pro | enterprise
+FINSTACK_API_KEY=""    # For hosted mode authentication
+STRIPE_SECRET_KEY=""   # For payment processing
+STRIPE_WEBHOOK_SECRET=""
+RAZORPAY_KEY_ID=""
+RAZORPAY_KEY_SECRET=""
+
+# ===== SERVER CONFIG =====
+FINSTACK_HOST="127.0.0.1"
+FINSTACK_PORT=8000
+FINSTACK_LOG_LEVEL="INFO"
+FINSTACK_CACHE_TTL_QUOTES=300      # 5 minutes for live quotes
+FINSTACK_CACHE_TTL_FUNDAMENTALS=3600  # 1 hour for fundamentals
+FINSTACK_CACHE_TTL_HISTORICAL=86400   # 24 hours for historical data

finstack_mcp-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-check:
+    name: Lint & Import Check
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Check syntax (all Python files compile)
+        run: |
+          find src -name "*.py" -exec python -m py_compile {} +
+          echo "All files compiled successfully"
+
+      - name: Ruff lint
+        run: ruff check src/
+
+      - name: Run tests
+        env:
+          PYTHONPATH: src
+        run: pytest tests -q -p no:cacheprovider
+
+      - name: Verify server imports
+        run: |
+          python -c "from finstack.server import mcp; print('Server OK')"
+
+      - name: Verify all tool modules load
+        run: |
+          python -c "
+          from finstack.tools.indian import register_indian_tools
+          from finstack.tools.global_ import register_global_tools
+          from finstack.tools.fundamentals import register_fundamental_tools
+          from finstack.tools.analytics import register_analytics_tools
+          print('All tool modules OK')
+          "

finstack_mcp-0.3.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Environment
+.env
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+pytest-cache-files-*/
+
+# Logs
+*.log
+
+# Local DB (payments)
+*.db
+*.sqlite
+
+# Secrets
+*.pem
+*.key

finstack_mcp-0.3.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to FinStack MCP are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [0.3.0] — 2025-03-25
+
+### Added
+- **37 total MCP tools** across Indian markets, global markets, fundamentals, and analytics
+- `mutual_fund_nav` — live NAV for any Indian mutual fund via AMFI (free, no key)
+- `nse_circuit_breakers` — scan stocks hitting upper/lower circuit limits today
+- `sensex_components` — full constituent list of Nifty 50 or Sensex with live prices, top gainers/losers within the index
+- `nse_52week_scanner` — scan Nifty 50 for stocks near 52-week high or low with configurable threshold
+- `stock_screener` (Pro) — filter stocks by P/E, ROE, market cap, sector, momentum
+- `nse_options_chain` (Pro) — full options chain with PCR, max pain, IV skew
+- `backtest_strategy` (Pro) — SMA crossover backtesting with CAGR, win rate, trade log
+- `portfolio_analysis` (Pro) — P&L, weights, correlation, risk for a basket of stocks
+- `support_resistance` (Pro) — pivot points and key price levels
+- `nse_fii_dii_data` — FII/DII institutional activity
+- `nse_bulk_deals` — bulk and block deals
+- `nse_corporate_actions` — dividends, splits, bonuses
+- `nse_quarterly_results` — latest quarterly financials with QoQ growth
+- `earnings_calendar` — upcoming earnings dates
+- `ipo_calendar` — upcoming and recent IPOs
+- `sector_performance` — Nifty sectoral index performance
+- Landing page (`landing-page/index.html`) with interactive mesh background
+- Dockerfile and Railway deployment config
+- Health check function for hosted deployments
+- GitHub Actions CI (Python 3.10 / 3.11 / 3.12)
+
+### Changed
+- SEC filing fetcher now uses context manager — eliminates resource leak on error paths
+- Removed unused `pandas-ta` and `cachetools` dependencies
+- Added `numpy` as explicit dependency
+- Version classifier upgraded Alpha → Beta
+
+---
+
+## [0.2.0] — 2025-03-18
+
+### Added
+- **20 total MCP tools**
+- `stock_quote`, `stock_historical` — global equities (US, EU, Asia)
+- `crypto_price`, `crypto_historical` — Bitcoin, Ethereum, any coin
+- `forex_rate` — any currency pair live
+- `market_news` — news by ticker or general market
+- `sec_filing`, `sec_filing_search` — SEC EDGAR 10-K / 10-Q / 8-K
+- `income_statement`, `balance_sheet`, `cash_flow` — annual & quarterly
+- `key_ratios`, `company_profile`, `dividend_history`
+- TTL cache system (5 min quotes / 1 hr fundamentals / 24 hr history)
+- Per-tier rate limiter
+
+---
+
+## [0.1.0] — 2025-03-11
+
+### Added
+- Initial release — 6 Indian market tools
+- `nse_quote` — real-time NSE price, P/E, market cap
+- `bse_quote` — real-time BSE price
+- `nse_market_status` — open / closed / pre-open check
+- `nifty_index` — Nifty 50, Sensex, Bank Nifty, IT index
+- `nse_historical` — OHLCV for any period and interval
+- `nse_top_movers` — top gainers, losers, most active
+- FastMCP-based server with stdio and HTTP transport
+- MIT license

finstack_mcp-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing to FinStack MCP
+
+Thanks for your interest! Here's how to contribute.
+
+## Setup
+
+```bash
+git clone https://github.com/SpawnAgent/finstack-mcp.git
+cd finstack-mcp
+pip install -e ".[dev]"
+```
+
+## Adding a New Tool
+
+1. Add data fetcher function in `src/finstack/data/`
+2. Add MCP tool wrapper in `src/finstack/tools/`
+3. Register in `src/finstack/server.py`
+4. Test with Claude Desktop locally
+5. Submit PR
+
+## Code Style
+
+- Python 3.10+, type hints everywhere
+- Docstrings on all public functions (Claude reads these)
+- Use `clean_nan()` on all return dicts
+- Use `@cached()` decorator for API calls
+- Return `{"error": True, "message": "..."}` on failures
+
+## Tool Naming
+
+- Indian tools: `nse_*` or `bse_*` prefix
+- Global tools: `stock_*`, `crypto_*`, `forex_*`
+- Analytics: descriptive name (`technical_indicators`, `stock_screener`)
+
+## Questions?
+
+Open an issue or reach out on [Twitter/X @SpawnAgent](https://x.com/SpawnAgent).

finstack_mcp-0.3.0/Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY pyproject.toml .
+COPY src/ src/
+COPY README.md .
+COPY LICENSE .
+
+RUN pip install --no-cache-dir -e ".[hosted]"
+
+# Environment
+ENV FINSTACK_HOST=0.0.0.0
+ENV FINSTACK_PORT=8000
+ENV FINSTACK_TRANSPORT=streamable-http
+ENV FINSTACK_LOG_LEVEL=INFO
+
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
+  CMD python -c "import httpx; httpx.get('http://localhost:8000/health')" || exit 1
+
+CMD ["python", "-m", "finstack.server", "--transport", "streamable-http"]

finstack_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpawnAgent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

finstack_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: finstack-mcp
+Version: 0.3.0
+Summary: Open-source MCP server for Indian (NSE/BSE) + Global financial data with built-in AI analytics
+Project-URL: Homepage, https://github.com/SpawnAgent/finstack-mcp
+Project-URL: Repository, https://github.com/SpawnAgent/finstack-mcp
+Project-URL: Issues, https://github.com/SpawnAgent/finstack-mcp/issues
+Author-email: SpawnAgent <spawnagent@proton.me>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,bse,claude,cursor,finance,mcp,nse,stocks,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: yfinance>=0.2.40
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Provides-Extra: hosted
+Requires-Dist: stripe>=8.0.0; extra == 'hosted'
+Requires-Dist: uvicorn>=0.30.0; extra == 'hosted'
+Description-Content-Type: text/markdown
+
+# FinStack MCP
+
+[![PyPI version](https://badge.fury.io/py/finstack-mcp.svg)](https://pypi.org/project/finstack-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
+
+India-first MCP server for market data, fundamentals, and research workflows.
+
+39 tools. Zero API keys. Works with Claude, Cursor, ChatGPT, and MCP clients.
+
+## Install
+
+```bash
+pip install finstack-mcp
+```
+
+Add to Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "finstack": {
+      "command": "python",
+      "args": ["-m", "finstack.server"]
+    }
+  }
+}
+```
+
+Restart Claude and ask:
+
+- "What's Reliance's stock price?"
+- "Compare TCS, Infosys, and Wipro."
+- "Show me technical indicators for HDFCBANK."
+
+## Coverage
+
+- Indian markets: NSE/BSE quotes, indices, historical data, corporate actions, quarterly results, FII/DII, bulk deals, IPOs
+- Global markets: stocks, crypto, forex, market news, SEC filings
+- Fundamentals: income statement, balance sheet, cash flow, key ratios, company profile, dividend history
+- Analytics: indicators, stock comparison, sector performance, screeners, options chain, backtesting
+
+## Product Role
+
+This repo is the open-source engine and public distribution layer for FinStack.
+
+The paid wedge we are building on top of this is the hosted **Indian market daily brief** product.
+
+- Strategy: [docs/PARTNER_PLAN.md](docs/PARTNER_PLAN.md)
+- Running updates: [docs/WORKLOG.md](docs/WORKLOG.md)
+
+## Data Sources
+
+| Source | Covers | API Key |
+|---|---|---|
+| yfinance | NSE, BSE, US, Crypto, Forex | Not needed |
+| SEC EDGAR | US company filings | Not needed |
+| NSE Direct | FII/DII, bulk deals, IPOs | Not needed |
+
+## Contributing
+
+PRs are welcome. Keep changes focused, test what you touch, and document any new tool clearly.
+
+## License
+
+MIT

finstack_mcp-0.3.0/README.md

@@ -0,0 +1,67 @@
+# FinStack MCP
+
+[![PyPI version](https://badge.fury.io/py/finstack-mcp.svg)](https://pypi.org/project/finstack-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)
+
+India-first MCP server for market data, fundamentals, and research workflows.
+
+39 tools. Zero API keys. Works with Claude, Cursor, ChatGPT, and MCP clients.
+
+## Install
+
+```bash
+pip install finstack-mcp
+```
+
+Add to Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "finstack": {
+      "command": "python",
+      "args": ["-m", "finstack.server"]
+    }
+  }
+}
+```
+
+Restart Claude and ask:
+
+- "What's Reliance's stock price?"
+- "Compare TCS, Infosys, and Wipro."
+- "Show me technical indicators for HDFCBANK."
+
+## Coverage
+
+- Indian markets: NSE/BSE quotes, indices, historical data, corporate actions, quarterly results, FII/DII, bulk deals, IPOs
+- Global markets: stocks, crypto, forex, market news, SEC filings
+- Fundamentals: income statement, balance sheet, cash flow, key ratios, company profile, dividend history
+- Analytics: indicators, stock comparison, sector performance, screeners, options chain, backtesting
+
+## Product Role
+
+This repo is the open-source engine and public distribution layer for FinStack.
+
+The paid wedge we are building on top of this is the hosted **Indian market daily brief** product.
+
+- Strategy: [docs/PARTNER_PLAN.md](docs/PARTNER_PLAN.md)
+- Running updates: [docs/WORKLOG.md](docs/WORKLOG.md)
+
+## Data Sources
+
+| Source | Covers | API Key |
+|---|---|---|
+| yfinance | NSE, BSE, US, Crypto, Forex | Not needed |
+| SEC EDGAR | US company filings | Not needed |
+| NSE Direct | FII/DII, bulk deals, IPOs | Not needed |
+
+## Contributing
+
+PRs are welcome. Keep changes focused, test what you touch, and document any new tool clearly.
+
+## License
+
+MIT

finstack_mcp-0.3.0/claude_desktop_config.json.example

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "finstack": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/ABSOLUTE/PATH/TO/finstack-mcp",
+        "run",
+        "python",
+        "-m",
+        "finstack.server"
+      ]
+    }
+  }
+}

finstack_mcp-0.3.0/docs/DAILY_BRIEF.md

@@ -0,0 +1,55 @@
+# Daily Brief
+
+## Purpose
+
+`finstack-mcp` remains the public open-source engine.
+
+The first commercial bridge built on top of it is the **Indian market daily brief** workflow.
+
+This repo now includes a first generator module for that workflow.
+
+## CLI Usage
+
+```bash
+python -m finstack.briefs --watchlist RELIANCE,TCS,HDFCBANK
+```
+
+Or after install:
+
+```bash
+finstack-brief --watchlist RELIANCE,TCS,HDFCBANK
+```
+
+## Output
+
+The generator returns structured JSON with:
+
+- market status
+- Nifty, Sensex, Bank Nifty snapshot
+- gainers, losers, most active
+- sector performance
+- FII/DII summary
+- bulk deals
+- watchlist earnings, results, and corporate actions
+- short narrative summary
+
+## Intended Product Path
+
+This generator should be reused later in:
+
+- email briefs
+- Telegram or WhatsApp formatted briefs
+- premium watchlist products
+- the future hosted `finstack-brief` product
+
+## Current Status
+
+This is version 1 of the brief engine.
+
+It is suitable for:
+
+- demos
+- early user feedback
+- launch positioning
+
+It is not yet a full hosted product.

finstack_mcp-0.3.0/docs/LAUNCH_GUIDE.md

@@ -0,0 +1,77 @@
+# Launch Guide
+
+## Goal
+
+Launch `finstack-mcp` today as a clean open-source repo and use it as the public engine for the future paid daily brief product.
+
+## 1. Local Checks
+
+```bash
+cd finstack-mcp
+pip install -e ".[dev]"
+pytest -q -p no:cacheprovider
+python -m finstack.server
+python -m finstack.briefs --watchlist RELIANCE,TCS,HDFCBANK
+```
+
+## 2. GitHub
+
+Create a new public repository named `finstack-mcp`.
+
+Recommended metadata:
+
+- description: `India-first MCP server for NSE/BSE, fundamentals, analytics, and daily research workflows.`
+- topics: `mcp`, `finance`, `nse`, `bse`, `stocks`, `india`, `python`, `claude`
+
+Push commands:
+
+```bash
+git init
+git add .
+git commit -m "Launch finstack-mcp v0.3.0"
+git branch -M main
+git remote add origin https://github.com/<your-username>/finstack-mcp.git
+git push -u origin main
+```
+
+## 3. PyPI
+
+Build locally:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+Publish with Twine or GitHub Trusted Publishing after you create the project on PyPI.
+
+## 4. MCP Registries
+
+Use the current `server.json` after GitHub and PyPI are live.
+
+Submit the project to the registries you plan to target after the package is public.
+
+## 5. Landing Page
+
+Deploy `landing-page/` as a static site.
+
+Current message:
+
+- FinStack MCP = open-source engine
+- FinStack Brief = paid Indian market daily brief
+
+## 6. Demo Story
+
+Use this story consistently in posts and conversations:
+
+1. install `finstack-mcp`
+2. use the MCP tools locally
+3. show the daily brief generator
+4. explain that the paid layer is delivery and workflow, not just access
+
+## 7. After Launch
+
+1. collect first users
+2. collect first daily brief feedback
+3. build delivery formats
+4. validate pricing before adding more features

finstack_mcp-0.3.0/docs/LAUNCH_TODAY.md

@@ -0,0 +1,31 @@
+# Launch Today Checklist
+
+## Public OSS Launch
+
+1. Create the public GitHub repo: `finstack-mcp`
+2. Push the current codebase
+3. Add repo description, topics, and website
+4. Add at least one screenshot or GIF to the README
+5. Build and publish the package to PyPI
+6. Submit `server.json` to MCP registries
+
+## Landing Page
+
+1. Deploy `landing-page/`
+2. Set the main CTA to GitHub for now
+3. Set the waitlist CTA for the paid daily brief
+4. Replace placeholder social/contact links before publishing
+
+## Product Narrative
+
+Use this message consistently:
+
+`FinStack MCP is the open-source engine. FinStack Brief is the paid Indian market daily brief built on top of it.`
+
+## Minimum Launch Assets
+
+- GitHub repo
+- PyPI package
+- landing page
+- one short demo video or GIF
+- one sample daily brief output

finstack_mcp-0.3.0/docs/MASTER_TRACKER.md

@@ -0,0 +1,55 @@
+# FinStack Master Tracker
+
+## Current Position
+
+FinStack now has two clear layers:
+
+- `finstack-mcp`: public open-source engine
+- `finstack-brief`: future paid Indian market daily brief built on top of the engine
+
+## Engine Status
+
+### Core package
+
+- MCP server with `39` tools
+- India-first market coverage
+- global markets and fundamentals support
+- daily brief generator module added
+- local tests passing
+
+### Public repo tasks
+
+- README cleaned
+- landing page repositioned
+- `server.json` updated
+- CI now runs tests
+- partner plan and worklog added
+
+## Product Direction
+
+### What we are building
+
+- Indian market daily brief
+- watchlist-oriented workflow
+- reusable output for email, Telegram, and future hosted delivery
+
+### What we are not building first
+
+- generic finance SaaS
+- broad advisor platform
+- enterprise-heavy product
+
+## Current Priorities
+
+1. Launch the public GitHub repo cleanly
+2. Publish to PyPI
+3. Submit to MCP registries
+4. Use the daily brief generator in demos
+5. Build the first paid delivery layer
+
+## Working Docs
+
+- Strategy: `docs/PARTNER_PLAN.md`
+- Daily brief: `docs/DAILY_BRIEF.md`
+- Launch checklist: `docs/LAUNCH_TODAY.md`
+- Progress log: `docs/WORKLOG.md`