bharatstock-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `bharatstock-mcp` are documented here (newest first).
+
+## 0.1.0 (2026-09-22)
+
+- Initial release.
+- Local **stdio** server (`bharatstock-mcp`) and remote **Streamable HTTP**
+  server (`bharatstock-mcp-http`) wrapping the official `bharatstock` JS SDK.
+- Remote server is multi-tenant (per-request key) and accepts the key on
+  `Authorization: Bearer` or `X-API-Key`.
+- MCP is a Developer/Pro feature, gated server-side via `/v1/mcp/authorize`
+  (checked at stdio startup and on every remote request).
+- Tools: `get_stock_quote`, `get_company_profile`, `get_stock_quotes_batch`,
+  `get_stock_prices`, `get_financials`, `get_stock_fundamentals`,
+  `get_technical_indicators`, `get_shareholding`, `get_corporate_actions`,
+  `get_stock_bulk_deals`, `get_stock_block_deals`, `get_stock_insider_trades`,
+  `compare_sector_peers`, `search_stocks`, `get_stock_rank`,
+  `get_price_shockers`, `run_screener`, `list_indices`, `get_index_prices`,
+  `get_fii_dii_activity`, `get_bulk_deals`, `get_block_deals`,
+  `get_insider_trades`, `search_mutual_fund_schemes`,
+  `get_mutual_fund_scheme`, `get_mutual_fund_nav`, `get_mutual_fund_returns`,
+  `get_mutual_fund_holdings`, `get_data_status`.
+- Reads `BHARATSTOCK_API_KEY` and optional `BHARATSTOCK_BASE_URL` from env.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BharatStock
+
+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.

package/README.md

@@ -0,0 +1,129 @@
+# bharatstock-mcp
+
+Official **Model Context Protocol (MCP)** server for the [BharatStock API](https://bharatstockapi.com) — reliable Indian stock market data (NSE/BSE) exposed as tools your AI assistant can call directly.
+
+Point any MCP host (Claude Desktop, Cursor, Kiro, VS Code, etc.) at this server and your model can ask for live quotes, financials, mutual-fund NAVs, screener results and more — no code required.
+
+📋 **[Jump to Changelog](#changelog)**
+
+## What you need
+
+- Node.js 20+
+- A BharatStock API key (`bsk_live_...`) on the **Developer or Pro plan** — MCP access is a paid feature. The server verifies your plan on startup and refuses to run for Free/Starter keys. Your plan's rate limit and history depth apply exactly as they do over REST. Sign up / upgrade at [bharatstockapi.com](https://bharatstockapi.com/#pricing).
+
+## Setup
+
+Add the server to your MCP host's config. Most hosts use a `mcpServers` block:
+
+```json
+{
+  "mcpServers": {
+    "bharatstock": {
+      "command": "npx",
+      "args": ["-y", "bharatstock-mcp"],
+      "env": { "BHARATSTOCK_API_KEY": "bsk_live_your_key_here" }
+    }
+  }
+}
+```
+
+`npx -y bharatstock-mcp` downloads and runs the server on demand — no global install needed. Restart your host and the BharatStock tools appear.
+
+### Environment variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `BHARATSTOCK_API_KEY` | yes | Your `bsk_live_...` key. |
+| `BHARATSTOCK_BASE_URL` | no | Override the API host (self-hosted/staging). Defaults to the public API. |
+
+## Tools
+
+Each tool wraps a consumer-facing BharatStock endpoint. Your model picks the right one from its description.
+
+**Stocks**
+- `get_stock_quote` — latest price + market cap + headline metrics for a ticker
+- `get_company_profile` — company identity/classification for a ticker
+- `get_stock_quotes_batch` — latest snapshot for up to 50 tickers at once
+- `get_stock_prices` — historical daily OHLCV (split/bonus-adjusted)
+- `get_financials` — quarterly/annual P&L, balance sheet, cash flow
+- `get_stock_fundamentals` — current ratios (P/E, P/B, ROE, ROCE, EPS, yield…)
+- `get_technical_indicators` — daily indicators over a date range
+- `get_shareholding` — quarterly promoter/FII/DII/public holding
+- `get_corporate_actions` — dividends, bonuses, splits, rights, buybacks
+- `get_stock_bulk_deals` / `get_stock_block_deals` — deals for one stock
+- `get_stock_insider_trades` — SEBI PIT disclosures for one stock
+- `compare_sector_peers` — relative valuation across a sector
+
+**Discovery & rankings**
+- `search_stocks` — resolve a name to a ticker
+- `get_stock_rank` — top gainers / losers / most-active
+- `get_price_shockers` — stocks moving beyond a % threshold
+- `run_screener` — fundamental screen (`pe_ratio.lt.15`, `roe.gt.18`, …)
+
+**Indices & market**
+- `list_indices` — indices with latest values
+- `get_index_prices` — historical index values
+- `get_fii_dii_activity` — institutional net buy/sell by day
+- `get_bulk_deals` / `get_block_deals` / `get_insider_trades` — market-wide
+
+**Mutual funds**
+- `search_mutual_fund_schemes` — find a scheme_code across all AMCs
+- `get_mutual_fund_scheme` — scheme identity + latest NAV
+- `get_mutual_fund_nav` — daily NAV history
+- `get_mutual_fund_returns` — trailing returns (1m…5y, CAGR)
+- `get_mutual_fund_holdings` — which funds hold a given stock
+
+**Platform**
+- `get_data_status` — public data-integrity/freshness report
+
+## Remote (hosted HTTP) mode
+
+If your AI host connects to a **URL** instead of spawning a local process, use our hosted remote MCP endpoint — no install:
+
+```
+https://bharatstockapi.com/v1/mcp
+```
+
+Config for a URL-based host:
+
+```json
+{
+  "mcpServers": {
+    "bharatstock": {
+      "url": "https://bharatstockapi.com/v1/mcp",
+      "headers": { "Authorization": "Bearer bsk_live_..." }
+    }
+  }
+}
+```
+
+Pass your key on **either** header (Bearer preferred): `Authorization: Bearer bsk_live_...` or `X-API-Key: bsk_live_...`. Same Developer/Pro gate and rate/limit rules as everywhere else. No OAuth — the API key is the credential.
+
+### Self-hosting the remote server (optional)
+
+This package also ships a standalone remote server (`bharatstock-mcp-http`) if you'd rather run your own:
+
+```bash
+BHARATSTOCK_BASE_URL=https://bharatstockapi.com PORT=8080 npx -y bharatstock-mcp-http
+# POST /mcp (the MCP endpoint)  |  GET /healthz (liveness)
+```
+
+It's stateless (a fresh server per request), multi-tenant (each request carries its own key), and validates/plan-gates every request before any tool runs.
+
+## How it works
+
+This server is a thin layer over the official [`bharatstock`](https://www.npmjs.com/package/bharatstock) JS SDK. Auth, retries, base URL and typed decoding all come from the SDK, so the tool set tracks the API surface. Tool results are returned as JSON text.
+
+## Notes
+
+- **MCP is a Developer/Pro feature.** On startup the server calls the API to check your plan; a Free/Starter key gets a clear "upgrade" message and the server exits without connecting.
+- Free-tier keys are limited to a recent history window on deep-history tools (prices, financials, NAV, etc.); paid keys get the full archive — identical to the REST behaviour.
+- Errors from the API (invalid key, rate limit, not found) are returned as a tool error message the model can read, not a crash.
+
+## License
+
+MIT
+
+## Changelog
+
+- **0.1.0** (2026-09-22): initial release. Local stdio server (`bharatstock-mcp`) + remote Streamable HTTP server (`bharatstock-mcp-http`, multi-tenant, Bearer/X-API-Key auth). MCP is a Developer/Pro feature, gated via `/v1/mcp/authorize`. Tools for stocks (quote, profile, prices, financials, fundamentals, technicals, shareholding, corporate actions, deals, insider trades, peer compare), discovery (search, movers, price shockers, screener), indices, market-wide (FII/DII, deals, insider), and mutual funds (schemes, scheme, NAV, returns, holdings), plus data status.

package/dist/chunk-RPAWW7CN.js

@@ -0,0 +1,456 @@
+#!/usr/bin/env node
+
+// src/auth.ts
+var DEFAULT_UPGRADE_URL = "https://bharatstockapi.com/#pricing";
+async function checkAuthorization(baseUrl, apiKey, fetchImpl = fetch) {
+  let res;
+  try {
+    res = await fetchImpl(`${baseUrl}/v1/mcp/authorize`, {
+      method: "GET",
+      headers: { "X-API-Key": apiKey, Accept: "application/json" }
+    });
+  } catch (err) {
+    return { ok: true };
+  }
+  if (res.ok) {
+    let plan;
+    try {
+      const body = await res.json();
+      plan = body?.plan;
+    } catch {
+    }
+    return { ok: true, plan };
+  }
+  if (res.status === 401) {
+    return { ok: false, status: 401, message: "Invalid or missing API key." };
+  }
+  if (res.status === 403) {
+    let message = "MCP access requires the Developer or Pro plan.";
+    let upgradeUrl = DEFAULT_UPGRADE_URL;
+    try {
+      const body = await res.json();
+      if (body?.detail?.message) message = body.detail.message;
+      if (body?.detail?.upgrade_url) upgradeUrl = body.detail.upgrade_url;
+    } catch {
+    }
+    return { ok: false, status: 403, message, upgradeUrl };
+  }
+  return { ok: true };
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BharatStock } from "bharatstock";
+import { z } from "zod";
+var SERVER_NAME = "bharatstock";
+var SERVER_VERSION = "0.1.0";
+async function run(fn) {
+  try {
+    const data = await fn();
+    return {
+      content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      isError: true,
+      content: [{ type: "text", text: `BharatStock API error: ${message}` }]
+    };
+  }
+}
+function buildServer(options = {}) {
+  const client = new BharatStock(options);
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  const ticker = z.string().describe("NSE/BSE ticker symbol (e.g. RELIANCE, TCS) or ISIN.");
+  const exchange = z.enum(["NSE", "BSE"]).optional().describe("Optional exchange to disambiguate a cross-listed stock.");
+  const fromDate = z.string().optional().describe("Start date, YYYY-MM-DD (inclusive).");
+  const toDate = z.string().optional().describe("End date, YYYY-MM-DD (inclusive).");
+  server.registerTool(
+    "get_stock_quote",
+    {
+      title: "Get stock quote",
+      description: "Latest snapshot for a stock: company name, latest price, day change, 52-week high/low, market cap, and headline valuation metrics (P/E, P/B, EPS). Use this for a single 'what is X trading at' question.",
+      inputSchema: { ticker, exchange }
+    },
+    async ({ ticker: ticker2, exchange: exchange2 }) => run(() => client.stocks.get(ticker2, { exchange: exchange2 }))
+  );
+  server.registerTool(
+    "get_company_profile",
+    {
+      title: "Get company profile",
+      description: "Company identity and classification for a stock: full company name, sector, exchange listing(s), and identifiers. This is the same detail record as get_stock_quote (which also carries price/metrics); use this when you only need who the company is, not the live price.",
+      inputSchema: { ticker, exchange }
+    },
+    async ({ ticker: ticker2, exchange: exchange2 }) => run(() => client.stocks.get(ticker2, { exchange: exchange2 }))
+  );
+  server.registerTool(
+    "get_stock_quotes_batch",
+    {
+      title: "Get quotes for multiple stocks",
+      description: "Latest price snapshot for up to 50 tickers in one call. Prefer this over many get_stock_quote calls when comparing several stocks.",
+      inputSchema: {
+        symbols: z.array(z.string()).min(1).max(50).describe("List of ticker symbols (max 50).")
+      }
+    },
+    async ({ symbols }) => run(() => client.stocks.quotes(symbols))
+  );
+  server.registerTool(
+    "get_stock_prices",
+    {
+      title: "Get historical daily prices",
+      description: "Historical end-of-day OHLCV for a stock, including bonus/split adjusted close. Paginated. Free-tier keys get a recent window; paid keys get the full multi-year archive.",
+      inputSchema: {
+        ticker,
+        fromDate,
+        toDate,
+        exchange,
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(500).optional()
+      }
+    },
+    async ({ ticker: ticker2, fromDate: fromDate2, toDate: toDate2, exchange: exchange2, page, pageSize }) => run(() => client.stocks.prices(ticker2, { fromDate: fromDate2, toDate: toDate2, exchange: exchange2, page, pageSize }))
+  );
+  server.registerTool(
+    "get_financials",
+    {
+      title: "Get financial statements",
+      description: "Quarterly or annual financial statements (P&L, balance sheet, cash flow) for a stock, as filed with the exchange. Set periodType to 'annual' for yearly figures or 'quarterly' for quarterly results.",
+      inputSchema: {
+        ticker,
+        periodType: z.enum(["quarterly", "annual"]).optional().describe("Reporting cadence. Defaults to quarterly."),
+        exchange,
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(50).optional()
+      }
+    },
+    async ({ ticker: ticker2, periodType, exchange: exchange2, page, pageSize }) => run(() => client.stocks.financials(ticker2, { periodType, exchange: exchange2, page, pageSize }))
+  );
+  server.registerTool(
+    "get_stock_fundamentals",
+    {
+      title: "Get stock fundamentals / ratios",
+      description: "Current computed valuation and profitability ratios for a stock: P/E, P/B, ROE, ROCE, EPS, dividend yield, margins, and more. Use this for 'is X expensive / how profitable is X' questions.",
+      inputSchema: { ticker, exchange }
+    },
+    async ({ ticker: ticker2, exchange: exchange2 }) => run(() => client.stocks.ratios(ticker2, { exchange: exchange2 }))
+  );
+  server.registerTool(
+    "get_technical_indicators",
+    {
+      title: "Get technical indicators",
+      description: "Daily technical indicators for a stock (moving averages, RSI, etc.) over a date range. Free-tier keys get a recent window.",
+      inputSchema: {
+        ticker,
+        fromDate,
+        toDate,
+        exchange,
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(500).optional()
+      }
+    },
+    async ({ ticker: ticker2, fromDate: fromDate2, toDate: toDate2, exchange: exchange2, page, pageSize }) => run(
+      () => client.stocks.technicalIndicators(ticker2, { fromDate: fromDate2, toDate: toDate2, exchange: exchange2, page, pageSize })
+    )
+  );
+  server.registerTool(
+    "get_shareholding",
+    {
+      title: "Get shareholding pattern",
+      description: "Quarterly shareholding pattern for a stock: promoter / FII / DII / public holding percentages over time.",
+      inputSchema: {
+        ticker,
+        exchange,
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(50).optional()
+      }
+    },
+    async ({ ticker: ticker2, exchange: exchange2, page, pageSize }) => run(() => client.stocks.shareholding(ticker2, { exchange: exchange2, page, pageSize }))
+  );
+  server.registerTool(
+    "get_corporate_actions",
+    {
+      title: "Get corporate actions",
+      description: "Corporate actions for a stock: dividends, bonuses, stock splits, rights issues, and buybacks, with ex-dates.",
+      inputSchema: {
+        ticker,
+        actionType: z.string().optional().describe("Filter by type, e.g. dividend, bonus, split."),
+        exchange,
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(50).optional()
+      }
+    },
+    async ({ ticker: ticker2, actionType, exchange: exchange2, page, pageSize }) => run(() => client.stocks.corporateActions(ticker2, { actionType, exchange: exchange2, page, pageSize }))
+  );
+  server.registerTool(
+    "get_stock_bulk_deals",
+    {
+      title: "Get bulk deals for a stock",
+      description: "Bulk deals reported for a specific stock.",
+      inputSchema: {
+        ticker,
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ ticker: ticker2, page, pageSize }) => run(() => client.stocks.bulkDeals(ticker2, { page, pageSize }))
+  );
+  server.registerTool(
+    "get_stock_block_deals",
+    {
+      title: "Get block deals for a stock",
+      description: "Block deals reported for a specific stock.",
+      inputSchema: {
+        ticker,
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ ticker: ticker2, page, pageSize }) => run(() => client.stocks.blockDeals(ticker2, { page, pageSize }))
+  );
+  server.registerTool(
+    "get_stock_insider_trades",
+    {
+      title: "Get insider trades for a stock",
+      description: "SEBI PIT insider-trading disclosures for a specific stock.",
+      inputSchema: {
+        ticker,
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ ticker: ticker2, page, pageSize }) => run(() => client.stocks.insiderTrades(ticker2, { page, pageSize }))
+  );
+  server.registerTool(
+    "compare_sector_peers",
+    {
+      title: "Compare peers in a sector",
+      description: "Compare valuation/profitability ratios across the peers in a sector, for a quick relative-value view.",
+      inputSchema: {
+        sector: z.string().describe("Sector name, e.g. 'Information Technology'."),
+        sort: z.string().optional().describe("Sort key, e.g. market_cap, pe_ratio."),
+        limit: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ sector, sort, limit }) => run(() => client.stocks.compare(sector, { sort, limit }))
+  );
+  server.registerTool(
+    "search_stocks",
+    {
+      title: "Search stocks",
+      description: "Fuzzy-search listed stocks by ticker symbol or company name. Use this to resolve a company name to a ticker before calling other tools.",
+      inputSchema: {
+        q: z.string().describe("Search text (symbol fragment or company name)."),
+        limit: z.number().int().positive().max(50).optional()
+      }
+    },
+    async ({ q, limit }) => run(() => client.search(q, { limit }))
+  );
+  server.registerTool(
+    "get_stock_rank",
+    {
+      title: "Get top market movers",
+      description: "Ranked market movers: top gainers, top losers, or most-active stocks for the latest trading session. Use category to pick which.",
+      inputSchema: {
+        category: z.enum(["gainers", "losers", "active"]).optional().describe("Which ranking. Defaults to gainers."),
+        limit: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ category, limit }) => run(() => client.movers({ category, limit }))
+  );
+  server.registerTool(
+    "get_price_shockers",
+    {
+      title: "Get price shockers",
+      description: "Stocks that moved at least a threshold percentage vs the previous close, in either direction.",
+      inputSchema: {
+        minChangePct: z.number().positive().optional().describe("Minimum abs % move. Default 5."),
+        direction: z.enum(["up", "down", "both"]).optional(),
+        limit: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ minChangePct, direction, limit }) => run(() => client.priceShockers({ minChangePct, direction, limit }))
+  );
+  server.registerTool(
+    "run_screener",
+    {
+      title: "Run stock screener",
+      description: "Screen stocks by fundamental filters. `filters` is a list of 'metric.operator.value' strings, e.g. ['pe_ratio.lt.15', 'roe.gt.18']. marketCap filter values are in Crores. Optionally scope by sector.",
+      inputSchema: {
+        filters: z.array(z.string()).optional().describe("Filter expressions like 'pe_ratio.lt.15'."),
+        sector: z.string().optional(),
+        exchange,
+        sortBy: z.string().optional().describe("Sort key, default market_cap."),
+        sortOrder: z.enum(["asc", "desc"]).optional(),
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ filters, sector, exchange: exchange2, sortBy, sortOrder, page, pageSize }) => run(
+      () => client.screener.run({ filters, sector, exchange: exchange2, sortBy, sortOrder, page, pageSize })
+    )
+  );
+  server.registerTool(
+    "list_indices",
+    {
+      title: "List indices",
+      description: "List market indices (NIFTY 50, SENSEX, sectoral indices, etc.) with their latest values.",
+      inputSchema: {
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(200).optional()
+      }
+    },
+    async ({ page, pageSize }) => run(() => client.indices.list({ page, pageSize }))
+  );
+  server.registerTool(
+    "get_index_prices",
+    {
+      title: "Get historical index prices",
+      description: "Historical daily values for an index over a date range. Free-tier keys get a recent window; paid keys get the full archive.",
+      inputSchema: {
+        name: z.string().describe("Index name, e.g. 'NIFTY 50'."),
+        fromDate,
+        toDate,
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(500).optional()
+      }
+    },
+    async ({ name, fromDate: fromDate2, toDate: toDate2, page, pageSize }) => run(() => client.indices.prices(name, { fromDate: fromDate2, toDate: toDate2, page, pageSize }))
+  );
+  server.registerTool(
+    "get_fii_dii_activity",
+    {
+      title: "Get FII/DII activity",
+      description: "Foreign (FII) and domestic (DII) institutional investor net buy/sell activity (Rs Crores) by trading day. Pass latest=true for only the most recent day.",
+      inputSchema: {
+        fromDate,
+        toDate,
+        limit: z.number().int().positive().max(500).optional(),
+        latest: z.boolean().optional().describe("Return only the most recent day.")
+      }
+    },
+    async ({ fromDate: fromDate2, toDate: toDate2, limit, latest }) => run(() => client.market.fiiDii({ fromDate: fromDate2, toDate: toDate2, limit, latest }))
+  );
+  server.registerTool(
+    "get_bulk_deals",
+    {
+      title: "Get market-wide bulk deals",
+      description: "Bulk deals across the whole market for the latest sessions.",
+      inputSchema: {
+        buySell: z.enum(["BUY", "SELL"]).optional(),
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ buySell, page, pageSize }) => run(() => client.deals.bulk({ buySell, page, pageSize }))
+  );
+  server.registerTool(
+    "get_block_deals",
+    {
+      title: "Get market-wide block deals",
+      description: "Block deals across the whole market for the latest sessions.",
+      inputSchema: {
+        buySell: z.enum(["BUY", "SELL"]).optional(),
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ buySell, page, pageSize }) => run(() => client.deals.block({ buySell, page, pageSize }))
+  );
+  server.registerTool(
+    "get_insider_trades",
+    {
+      title: "Get market-wide insider trades",
+      description: "SEBI PIT insider-trading disclosures across the whole market.",
+      inputSchema: {
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(100).optional()
+      }
+    },
+    async ({ page, pageSize }) => run(() => client.deals.insiderTrades({ page, pageSize }))
+  );
+  server.registerTool(
+    "search_mutual_fund_schemes",
+    {
+      title: "Search mutual-fund schemes",
+      description: "List/search mutual-fund schemes across all AMCs (industry-wide AMFI dataset). Filter by name (q), AMC, category, plan (Direct/Regular), option (Growth/IDCW), or exact ISIN. Use this to find a scheme_code.",
+      inputSchema: {
+        q: z.string().optional(),
+        amc: z.string().optional(),
+        category: z.string().optional(),
+        plan: z.string().optional(),
+        option: z.string().optional(),
+        isin: z.string().optional(),
+        limit: z.number().int().positive().max(200).optional(),
+        offset: z.number().int().nonnegative().optional()
+      }
+    },
+    async (args) => run(() => client.mutualFunds.listSchemes(args))
+  );
+  server.registerTool(
+    "get_mutual_fund_scheme",
+    {
+      title: "Get mutual-fund scheme detail",
+      description: "One scheme's identity plus its latest NAV (with as-of date).",
+      inputSchema: {
+        schemeCode: z.string().describe("AMFI scheme code.")
+      }
+    },
+    async ({ schemeCode }) => run(() => client.mutualFunds.getScheme(schemeCode))
+  );
+  server.registerTool(
+    "get_mutual_fund_nav",
+    {
+      title: "Get mutual-fund NAV history",
+      description: "Daily NAV history for a scheme, most recent first. Free-tier keys are limited to a recent window; paid keys get the full archive.",
+      inputSchema: {
+        schemeCode: z.string().describe("AMFI scheme code."),
+        fromDate,
+        toDate,
+        limit: z.number().int().positive().max(2e3).optional()
+      }
+    },
+    async ({ schemeCode, fromDate: fromDate2, toDate: toDate2, limit }) => run(() => client.mutualFunds.nav(schemeCode, { fromDate: fromDate2, toDate: toDate2, limit }))
+  );
+  server.registerTool(
+    "get_mutual_fund_returns",
+    {
+      title: "Get mutual-fund trailing returns",
+      description: "Trailing returns (1m/3m/6m/1y/3y/5y + since-inception) computed from the scheme's NAV series (CAGR for >=1y horizons).",
+      inputSchema: {
+        schemeCode: z.string().describe("AMFI scheme code.")
+      }
+    },
+    async ({ schemeCode }) => run(() => client.mutualFunds.returns(schemeCode))
+  );
+  server.registerTool(
+    "get_mutual_fund_holdings",
+    {
+      title: "Get mutual-fund holdings for a stock",
+      description: "Which mutual-fund schemes hold a given stock (portfolio positions aggregated per stock), optionally for a specific portfolio month. Answers 'which funds own X'.",
+      inputSchema: {
+        ticker,
+        month: z.string().optional().describe("Portfolio month YYYY-MM-DD (month-end). Latest if omitted."),
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(200).optional()
+      }
+    },
+    async ({ ticker: ticker2, month, page, pageSize }) => run(() => client.stocks.mfHoldings(ticker2, { month, page, pageSize }))
+  );
+  server.registerTool(
+    "get_data_status",
+    {
+      title: "Get data-integrity status",
+      description: "Public data-trust report: freshness and correctness status of the BharatStock pipelines. No sensitive detail.",
+      inputSchema: {}
+    },
+    async () => run(() => client.status())
+  );
+  return server;
+}
+
+export {
+  checkAuthorization,
+  SERVER_NAME,
+  SERVER_VERSION,
+  buildServer
+};

package/dist/http.d.ts

@@ -0,0 +1,8 @@
+import * as http from 'http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/** Extract the API key from Authorization: Bearer or X-API-Key. */
+declare function extractApiKey(headers: IncomingMessage["headers"]): string | undefined;
+declare function createHttpServer(): http.Server<typeof IncomingMessage, typeof ServerResponse>;
+
+export { createHttpServer, extractApiKey };

package/dist/http.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import {
+  buildServer,
+  checkAuthorization
+} from "./chunk-RPAWW7CN.js";
+
+// src/http.ts
+import { randomUUID } from "crypto";
+import { createServer } from "http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { DEFAULT_BASE_URL } from "bharatstock";
+var PORT = Number(process.env.PORT || 8080);
+var BASE_URL = (process.env.BHARATSTOCK_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
+function extractApiKey(headers) {
+  const auth = headers["authorization"];
+  if (typeof auth === "string") {
+    const m = auth.match(/^Bearer\s+(.+)$/i);
+    if (m) return m[1].trim();
+  }
+  const xApiKey = headers["x-api-key"];
+  if (typeof xApiKey === "string" && xApiKey.trim()) return xApiKey.trim();
+  if (Array.isArray(xApiKey) && xApiKey[0]) return xApiKey[0].trim();
+  return void 0;
+}
+function sendJson(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(payload);
+}
+function jsonRpcError(res, status, message) {
+  sendJson(res, status, {
+    jsonrpc: "2.0",
+    error: { code: status === 401 || status === 403 ? -32001 : -32e3, message },
+    id: null
+  });
+}
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  if (chunks.length === 0) return void 0;
+  const raw = Buffer.concat(chunks).toString("utf8");
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+async function handleMcp(req, res) {
+  const apiKey = extractApiKey(req.headers);
+  if (!apiKey) {
+    jsonRpcError(res, 401, "Missing API key. Pass Authorization: Bearer <key> or X-API-Key.");
+    return;
+  }
+  const gate = await checkAuthorization(BASE_URL, apiKey);
+  if (!gate.ok) {
+    const suffix = gate.upgradeUrl ? ` Upgrade at ${gate.upgradeUrl}` : "";
+    jsonRpcError(res, gate.status, `${gate.message}${suffix}`);
+    return;
+  }
+  const body = await readBody(req);
+  const server = buildServer({ apiKey, baseUrl: BASE_URL });
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+  res.on("close", () => {
+    void transport.close();
+    void server.close();
+  });
+  try {
+    await server.connect(transport);
+    await transport.handleRequest(req, res, body);
+  } catch (err) {
+    if (!res.headersSent) {
+      jsonRpcError(res, 500, `Internal server error: ${String(err)}`);
+    }
+  }
+}
+function createHttpServer() {
+  return createServer((req, res) => {
+    const url = req.url || "/";
+    const path = url.split("?")[0];
+    if (req.method === "GET" && path === "/healthz") {
+      sendJson(res, 200, { status: "ok", service: "bharatstock-mcp-http" });
+      return;
+    }
+    if (path === "/mcp") {
+      if (req.method === "POST") {
+        void handleMcp(req, res);
+        return;
+      }
+      res.writeHead(405, { "Content-Type": "application/json", Allow: "POST" }).end(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          error: { code: -32e3, message: "Method not allowed. This endpoint is POST-only (stateless)." },
+          id: null
+        })
+      );
+      return;
+    }
+    jsonRpcError(res, 404, "Not found. The MCP endpoint is POST /mcp.");
+  });
+}
+function main() {
+  const server = createHttpServer();
+  server.listen(PORT, () => {
+    console.log(`bharatstock-mcp-http listening on :${PORT} (POST /mcp), API ${BASE_URL} [${randomUUID().slice(0, 8)}]`);
+  });
+}
+if (process.env.NODE_ENV !== "test") {
+  main();
+}
+export {
+  createHttpServer,
+  extractApiKey
+};

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { BharatStockOptions } from 'bharatstock';
+
+/**
+ * Builds the BharatStock MCP server: a thin layer that exposes the
+ * BharatStock REST API's consumer-facing (X-API-Key gated) endpoints as
+ * Model Context Protocol tools.
+ *
+ * Every tool is a thin wrapper over the official `bharatstock` JS SDK, so
+ * this server inherits the SDK's auth, base URL, retry/backoff and typed
+ * decoding, and stays in sync with the API surface. When the SDK adds a
+ * response field, it flows through automatically (results are serialized as
+ * JSON); a genuinely NEW endpoint is the only case that needs a new tool.
+ */
+
+declare const SERVER_NAME = "bharatstock";
+declare const SERVER_VERSION = "0.1.0";
+/**
+ * Construct the MCP server and register all tools against a BharatStock
+ * client. Exposed separately from the stdio wiring so tests can build a
+ * server with an injected `fetchImpl` and drive it over an in-memory
+ * transport (no network, no real key).
+ */
+declare function buildServer(options?: BharatStockOptions): McpServer;
+
+/**
+ * Shared plan-gate check for both the stdio and HTTP transports.
+ *
+ * MCP access is a Developer/Pro feature. The authoritative gate is
+ * server-side: `GET /v1/mcp/authorize` on the BharatStock API returns 200
+ * for an eligible key, 401 for an invalid key, and 403 for a valid key on an
+ * ineligible plan. Every MCP tool call is also a real X-API-Key request, so
+ * this check is about failing fast with a clear message, not the last line
+ * of defence.
+ */
+type AuthResult = {
+    ok: true;
+    plan?: string;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+    upgradeUrl?: string;
+};
+/** Call GET /v1/mcp/authorize with the given key. `baseUrl` must not have a
+ * trailing slash. `fetchImpl` is injectable for tests. */
+declare function checkAuthorization(baseUrl: string, apiKey: string, fetchImpl?: typeof fetch): Promise<AuthResult>;
+
+export { SERVER_NAME, SERVER_VERSION, buildServer, checkAuthorization };

package/dist/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import {
+  SERVER_NAME,
+  SERVER_VERSION,
+  buildServer,
+  checkAuthorization
+} from "./chunk-RPAWW7CN.js";
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { DEFAULT_BASE_URL } from "bharatstock";
+async function main() {
+  const apiKey = process.env.BHARATSTOCK_API_KEY;
+  if (!apiKey) {
+    process.stderr.write(
+      "bharatstock-mcp: BHARATSTOCK_API_KEY is not set. Set it in your MCP host config's `env` block. Get a key at https://bharatstockapi.com\n"
+    );
+    process.exit(1);
+  }
+  const baseUrl = (process.env.BHARATSTOCK_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
+  const gate = await checkAuthorization(baseUrl, apiKey);
+  if (!gate.ok) {
+    const suffix = gate.upgradeUrl ? ` Upgrade at ${gate.upgradeUrl}` : "";
+    process.stderr.write(`bharatstock-mcp: ${gate.message}${suffix}
+`);
+    process.exit(1);
+  }
+  const server = buildServer({ apiKey, baseUrl });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  process.stderr.write(`bharatstock-mcp failed to start: ${String(err)}
+`);
+  process.exit(1);
+});
+export {
+  SERVER_NAME,
+  SERVER_VERSION,
+  buildServer,
+  checkAuthorization
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "bharatstock-mcp",
+  "version": "0.1.0",
+  "description": "Official Model Context Protocol (MCP) server for the BharatStock API - reliable Indian stock market data (NSE/BSE) as AI-agent tools.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "bharatstock-mcp": "./dist/index.js",
+    "bharatstock-mcp-http": "./dist/http.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "nse",
+    "bse",
+    "india",
+    "stocks",
+    "market-data",
+    "finance",
+    "ai-tools"
+  ],
+  "homepage": "https://bharatstockapi.com",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "bharatstock": "^0.1.8",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.5.4",
+    "vitest": "^5.0.0"
+  }
+}