superkit-mcp-server 1.0.2 → 1.1.0

package/skills/tech/alpha-vantage/references/fundamentals.md

@@ -0,0 +1,223 @@
+# Fundamental Data APIs
+
+## OVERVIEW — Company Overview
+
+Returns key company information, valuation metrics, and financial ratios.
+
+**Required:** `symbol`
+
+```python
+data = av_get("OVERVIEW", symbol="AAPL")
+
+# Key fields returned:
+# "Symbol", "AssetType", "Name", "Description", "Exchange", "Currency"
+# "Country", "Sector", "Industry", "Address"
+# "MarketCapitalization", "EBITDA", "PERatio", "PEGRatio"
+# "BookValue", "DividendPerShare", "DividendYield", "EPS"
+# "RevenuePerShareTTM", "ProfitMargin", "OperatingMarginTTM"
+# "ReturnOnAssetsTTM", "ReturnOnEquityTTM"
+# "RevenueTTM", "GrossProfitTTM", "DilutedEPSTTM"
+# "QuarterlyEarningsGrowthYOY", "QuarterlyRevenueGrowthYOY"
+# "AnalystTargetPrice", "AnalystRatingStrongBuy", "AnalystRatingBuy",
+# "AnalystRatingHold", "AnalystRatingSell", "AnalystRatingStrongSell"
+# "TrailingPE", "ForwardPE", "PriceToSalesRatioTTM"
+# "PriceToBookRatio", "EVToRevenue", "EVToEBITDA"
+# "Beta", "52WeekHigh", "52WeekLow", "50DayMovingAverage", "200DayMovingAverage"
+# "SharesOutstanding", "DividendDate", "ExDividendDate", "FiscalYearEnd"
+
+print(data["MarketCapitalization"])  # "2850000000000"
+print(data["PERatio"])               # "29.50"
+print(data["Sector"])                # "TECHNOLOGY"
+```
+
+## ETF_PROFILE — ETF Profile & Holdings
+
+**Required:** `symbol`
+
+```python
+data = av_get("ETF_PROFILE", symbol="QQQ")
+# Fields: "net_assets", "nav", "inception_date", "description",
+#         "asset_allocation" (stocks/bonds/cash/etc.)
+#         "sectors" (list of sector weights)
+#         "holdings" (top holdings list)
+for h in data["holdings"][:5]:
+    print(h["symbol"], h["description"], h["weight"])
+```
+
+## DIVIDENDS — Corporate Dividend History
+
+**Required:** `symbol`
+
+```python
+data = av_get("DIVIDENDS", symbol="IBM")
+divs = data["data"]
+for d in divs:
+    print(d["ex_dividend_date"], d["amount"])
+# Fields per record: "ex_dividend_date", "declaration_date",
+#                    "record_date", "payment_date", "amount"
+```
+
+## SPLITS — Stock Split History
+
+**Required:** `symbol`
+
+```python
+data = av_get("SPLITS", symbol="AAPL")
+splits = data["data"]
+for s in splits:
+    print(s["effective_date"], s["split_factor"])
+# Fields: "effective_date", "split_factor" (e.g., "4/1" for 4-for-1 split)
+```
+
+## INCOME_STATEMENT — Income Statement
+
+Returns annual and quarterly income statements.
+
+**Required:** `symbol`
+
+```python
+data = av_get("INCOME_STATEMENT", symbol="IBM")
+annual = data["annualReports"]    # list, most recent first
+quarterly = data["quarterlyReports"]  # list, most recent first
+
+yr = annual[0]  # Most recent fiscal year
+print(yr["fiscalDateEnding"])       # "2023-12-31"
+print(yr["totalRevenue"])           # "61860000000"
+print(yr["grossProfit"])            # "32688000000"
+print(yr["operatingIncome"])        # "..."
+print(yr["netIncome"])              # "..."
+print(yr["ebitda"])                 # "..."
+# Other keys: "reportedCurrency", "costOfRevenue", "costofGoodsAndServicesSold",
+#   "sellingGeneralAndAdministrative", "researchAndDevelopment",
+#   "operatingExpenses", "investmentIncomeNet", "netInterestIncome",
+#   "interestIncome", "interestExpense", "nonInterestIncome",
+#   "otherNonOperatingIncome", "depreciation",
+#   "depreciationAndAmortization", "incomeBeforeTax",
+#   "incomeTaxExpense", "interestAndDebtExpense",
+#   "netIncomeFromContinuingOperations", "comprehensiveIncomeNetOfTax",
+#   "ebit", "dilutedEPS", "basicEPS"
+```
+
+## BALANCE_SHEET — Balance Sheet
+
+**Required:** `symbol`
+
+```python
+data = av_get("BALANCE_SHEET", symbol="IBM")
+annual = data["annualReports"]
+
+yr = annual[0]
+print(yr["totalAssets"])           # "..."
+print(yr["totalLiabilities"])      # "..."
+print(yr["totalShareholderEquity"]) # "..."
+# Other keys: "reportedCurrency", "fiscalDateEnding",
+#   "cashAndCashEquivalentsAtCarryingValue", "cashAndShortTermInvestments",
+#   "inventory", "currentNetReceivables", "totalCurrentAssets",
+#   "propertyPlantEquipmentNet", "intangibleAssets",
+#   "intangibleAssetsExcludingGoodwill", "goodwill", "investments",
+#   "longTermInvestments", "shortTermInvestments", "otherCurrentAssets",
+#   "otherNonCurrrentAssets", "currentAccountsPayable", "deferredRevenue",
+#   "currentDebt", "shortTermDebt", "totalCurrentLiabilities",
+#   "capitalLeaseObligations", "longTermDebt", "currentLongTermDebt",
+#   "longTermDebtNoncurrent", "shortLongTermDebtTotal",
+#   "otherCurrentLiabilities", "otherNonCurrentLiabilities",
+#   "totalNonCurrentLiabilities", "retainedEarnings",
+#   "additionalPaidInCapital", "commonStockSharesOutstanding"
+```
+
+## CASH_FLOW — Cash Flow Statement
+
+**Required:** `symbol`
+
+```python
+data = av_get("CASH_FLOW", symbol="IBM")
+annual = data["annualReports"]
+
+yr = annual[0]
+print(yr["operatingCashflow"])              # "..."
+print(yr["capitalExpenditures"])            # "..."
+print(yr["cashflowFromInvestment"])         # "..."
+print(yr["cashflowFromFinancing"])          # "..."
+# Other keys: "reportedCurrency", "fiscalDateEnding",
+#   "paymentsForRepurchaseOfCommonStock", "dividendPayout",
+#   "dividendPayoutCommonStock", "dividendPayoutPreferredStock",
+#   "proceedsFromIssuanceOfCommonStock", "changeInOperatingLiabilities",
+#   "changeInOperatingAssets", "depreciationDepletionAndAmortization",
+#   "capitalExpenditures", "changeInReceivables", "changeInInventory",
+#   "profitLoss", "netIncomeFromContinuingOperations"
+```
+
+## SHARES_OUTSTANDING — Shares Outstanding History
+
+**Required:** `symbol`
+
+```python
+data = av_get("SHARES_OUTSTANDING", symbol="AAPL")
+shares = data["data"]
+for s in shares[:5]:
+    print(s["date"], s["reportedShares"])
+```
+
+## EARNINGS — Earnings History (EPS)
+
+Returns annual and quarterly EPS + surprise data.
+
+**Required:** `symbol`
+
+```python
+data = av_get("EARNINGS", symbol="IBM")
+annual = data["annualEarnings"]
+quarterly = data["quarterlyEarnings"]
+
+# Annual: "fiscalDateEnding", "reportedEPS"
+# Quarterly: "fiscalDateEnding", "reportedDate", "reportedEPS",
+#            "estimatedEPS", "surprise", "surprisePercentage"
+q = quarterly[0]
+print(q["reportedEPS"], q["estimatedEPS"], q["surprisePercentage"])
+```
+
+## EARNINGS_CALENDAR — Upcoming Earnings Dates
+
+Returns earnings release schedule for the next 3-12 months.
+
+**Optional:** `symbol` (if omitted, returns all companies), `horizon` (`3month`, `6month`, `12month`)
+
+```python
+# Returns CSV format - use requests directly
+import requests, csv, io, os
+resp = requests.get(
+    "https://www.alphavantage.co/query",
+    params={"function": "EARNINGS_CALENDAR", "symbol": "IBM", "apikey": os.environ["ALPHAVANTAGE_API_KEY"]}
+)
+reader = csv.DictReader(io.StringIO(resp.text))
+for row in reader:
+    print(row["symbol"], row["name"], row["reportDate"], row["estimate"])
+```
+
+## LISTING_STATUS — Listed/Delisted Tickers
+
+**Optional:** `date` (format `YYYY-MM-DD`), `state` (`active` or `delisted`)
+
+```python
+# Returns CSV
+resp = requests.get(
+    "https://www.alphavantage.co/query",
+    params={"function": "LISTING_STATUS", "state": "active", "apikey": API_KEY}
+)
+reader = csv.DictReader(io.StringIO(resp.text))
+# Fields: "symbol", "name", "exchange", "assetType", "ipoDate",
+#         "delistingDate", "status"
+```
+
+## IPO_CALENDAR — Upcoming IPOs
+
+```python
+# Returns CSV
+resp = requests.get(
+    "https://www.alphavantage.co/query",
+    params={"function": "IPO_CALENDAR", "apikey": API_KEY}
+)
+reader = csv.DictReader(io.StringIO(resp.text))
+for row in reader:
+    print(row["symbol"], row["name"], row["ipoDate"], row["priceRangeLow"], row["priceRangeHigh"])
+```

package/skills/tech/alpha-vantage/references/intelligence.md

@@ -0,0 +1,138 @@
+# Alpha Intelligence™ APIs
+
+## NEWS_SENTIMENT — Market News & Sentiment
+
+Returns live/historical news articles with sentiment scores for tickers, sectors, and topics.
+
+**Optional:**
+- `tickers` — comma-separated ticker symbols (e.g., `IBM,AAPL`)
+- `topics` — comma-separated topics: `blockchain`, `earnings`, `ipo`, `mergers_and_acquisitions`, `financial_markets`, `economy_fiscal`, `economy_monetary`, `economy_macro`, `energy_transportation`, `finance`, `life_sciences`, `manufacturing`, `real_estate`, `retail_wholesale`, `technology`
+- `time_from` / `time_to` — format `YYYYMMDDTHHMM`
+- `sort` — `LATEST`, `EARLIEST`, or `RELEVANCE`
+- `limit` — max articles returned (default 50, max 1000)
+
+```python
+# Get news for specific ticker
+data = av_get("NEWS_SENTIMENT", tickers="AAPL", sort="LATEST", limit=10)
+articles = data["feed"]
+
+for a in articles[:3]:
+    print(a["title"])
+    print(a["url"])
+    print(a["time_published"])
+    print(a["overall_sentiment_label"])   # "Bullish", "Bearish", "Neutral", etc.
+    print(a["overall_sentiment_score"])   # -1.0 to 1.0
+    for ts in a["ticker_sentiment"]:
+        if ts["ticker"] == "AAPL":
+            print(f"  AAPL sentiment: {ts['ticker_sentiment_label']} ({ts['ticker_sentiment_score']})")
+            print(f"  Relevance: {ts['relevance_score']}")
+
+# Article fields: "title", "url", "time_published", "authors", "summary",
+#                 "source", "source_domain", "topics", "overall_sentiment_score",
+#                 "overall_sentiment_label", "ticker_sentiment"
+# Sentiment labels: "Bearish", "Somewhat-Bearish", "Neutral", "Somewhat-Bullish", "Bullish"
+
+# Get news by topic
+data = av_get("NEWS_SENTIMENT", topics="earnings,technology", time_from="20240101T0000", limit=50)
+```
+
+## EARNINGS_CALL_TRANSCRIPT — Earnings Call Transcript
+
+Returns full earnings call transcripts (requires premium).
+
+**Required:** `symbol`, `quarter` (format `YYYYQN`, e.g., `2023Q4`)
+
+```python
+data = av_get("EARNINGS_CALL_TRANSCRIPT", symbol="AAPL", quarter="2023Q4")
+transcript = data["transcript"]
+
+for segment in transcript[:5]:
+    print(f"[{segment['speaker']}]: {segment['content'][:200]}")
+# Fields: "symbol", "quarter", "transcript" (list of {speaker, title, content})
+```
+
+## TOP_GAINERS_LOSERS — Top Market Movers
+
+Returns top 20 gainers, losers, and most actively traded US stocks for the current/most recent trading day.
+
+```python
+data = av_get("TOP_GAINERS_LOSERS")
+
+for g in data["top_gainers"][:5]:
+    print(g["ticker"], g["price"], g["change_amount"], g["change_percentage"], g["volume"])
+
+for l in data["top_losers"][:5]:
+    print(l["ticker"], l["price"], l["change_amount"], l["change_percentage"])
+
+# Fields: "ticker", "price", "change_amount", "change_percentage", "volume"
+# Also: data["most_actively_traded"]
+```
+
+## INSIDER_TRANSACTIONS — Insider Trading Data
+
+Returns insider transactions (Form 4) for a given company (requires premium).
+
+**Required:** `symbol`
+
+```python
+data = av_get("INSIDER_TRANSACTIONS", symbol="AAPL")
+transactions = data["data"]
+
+for t in transactions[:5]:
+    print(
+        t["transaction_date"],
+        t["executive"],         # insider name
+        t["executive_title"],   # e.g., "CEO"
+        t["action"],            # "Buy" or "Sell"
+        t["shares"],
+        t["share_price"],
+        t["total_value"]
+    )
+```
+
+## ANALYTICS_FIXED_WINDOW — Portfolio Analytics (Fixed Window)
+
+Returns mean return, variance, covariance, correlation, and alpha/beta for a set of tickers over a fixed historical window.
+
+**Required:**
+- `SYMBOLS` — comma-separated tickers (e.g., `AAPL,MSFT,IBM`)
+- `RANGE` — date range format: `2year`, `6month`, `30day`, or `YYYY-MM-DD&YYYY-MM-DD`
+- `INTERVAL` — `DAILY`, `WEEKLY`, or `MONTHLY`
+- `OHLC` — `close`, `open`, `high`, or `low`
+- `CALCULATIONS` — comma-separated: `MEAN`, `STDDEV`, `MAX_DRAWDOWN`, `CORRELATION`, `COVARIANCE`, `VARIANCE`, `CUMULATIVE_RETURN`, `MIN`, `MAX`, `MEDIAN`, `HISTOGRAM`
+
+```python
+data = av_get(
+    "ANALYTICS_FIXED_WINDOW",
+    SYMBOLS="AAPL,MSFT,IBM",
+    RANGE="1year",
+    INTERVAL="DAILY",
+    OHLC="close",
+    CALCULATIONS="MEAN,STDDEV,CORRELATION,MAX_DRAWDOWN"
+)
+payload = data["payload"]
+print(payload["MEAN"])        # {"AAPL": 0.0012, "MSFT": 0.0009, ...}
+print(payload["STDDEV"])
+print(payload["CORRELATION"])  # correlation matrix
+print(payload["MAX_DRAWDOWN"])
+```
+
+## ANALYTICS_SLIDING_WINDOW — Portfolio Analytics (Sliding Window)
+
+Same as fixed window but with rolling calculations over time.
+
+**Required:** Same as fixed window, plus:
+- `WINDOW_SIZE` — number of periods (e.g., `20` for 20-day rolling window)
+
+```python
+data = av_get(
+    "ANALYTICS_SLIDING_WINDOW",
+    SYMBOLS="AAPL,MSFT",
+    RANGE="1year",
+    INTERVAL="DAILY",
+    OHLC="close",
+    CALCULATIONS="MEAN,STDDEV",
+    WINDOW_SIZE=20
+)
+# Returns time series of rolling calculations
+```

package/skills/tech/alpha-vantage/references/options.md

@@ -0,0 +1,93 @@
+# Options Data APIs (Premium)
+
+Both options endpoints require a premium Alpha Vantage subscription.
+
+## REALTIME_OPTIONS — Real-time Options Chain
+
+Returns real-time options contracts for a given symbol.
+
+**Required:** `symbol`
+
+**Optional:**
+- `contract` — specific contract ID (e.g., `AAPL240119C00150000`) to get a single contract
+- `datatype` — `json` or `csv`
+
+```python
+data = av_get("REALTIME_OPTIONS", symbol="AAPL")
+options = data["data"]
+
+for contract in options[:5]:
+    print(
+        contract["contractID"],    # e.g., "AAPL240119C00150000"
+        contract["strike"],        # "150.00"
+        contract["expiration"],    # "2024-01-19"
+        contract["type"],          # "call" or "put"
+        contract["last"],          # last price
+        contract["bid"],
+        contract["ask"],
+        contract["volume"],
+        contract["open_interest"],
+        contract["implied_volatility"],
+        contract["delta"],
+        contract["gamma"],
+        contract["theta"],
+        contract["vega"],
+        contract["rho"]
+    )
+
+# Get a specific contract
+data = av_get("REALTIME_OPTIONS", symbol="AAPL", contract="AAPL240119C00150000")
+```
+
+## HISTORICAL_OPTIONS — Historical Options Chain
+
+Returns historical end-of-day options data for a specific date.
+
+**Required:** `symbol`
+
+**Optional:**
+- `date` — format `YYYY-MM-DD` (up to 2 years of history)
+- `datatype` — `json` or `csv`
+
+```python
+# Get options chain for a specific historical date
+data = av_get("HISTORICAL_OPTIONS", symbol="AAPL", date="2023-12-15")
+options = data["data"]
+
+for contract in options[:5]:
+    print(
+        contract["contractID"],
+        contract["strike"],
+        contract["expiration"],
+        contract["type"],           # "call" or "put"
+        contract["last"],
+        contract["mark"],           # mark price
+        contract["bid"],
+        contract["ask"],
+        contract["volume"],
+        contract["open_interest"],
+        contract["date"],           # the date of this snapshot
+        contract["implied_volatility"],
+        contract["delta"],
+        contract["gamma"],
+        contract["theta"],
+        contract["vega"],
+        contract["rho"]
+    )
+```
+
+## Filter Options by Expiration/Type
+
+```python
+import pandas as pd
+
+data = av_get("HISTORICAL_OPTIONS", symbol="AAPL", date="2023-12-15")
+df = pd.DataFrame(data["data"])
+df["strike"] = pd.to_numeric(df["strike"])
+df["expiration"] = pd.to_datetime(df["expiration"])
+
+# Filter calls expiring in January 2024
+calls_jan = df[(df["type"] == "call") & (df["expiration"].dt.month == 1) & (df["expiration"].dt.year == 2024)]
+calls_jan = calls_jan.sort_values("strike")
+print(calls_jan[["contractID", "strike", "bid", "ask", "implied_volatility", "delta"]].head(10))
+```