superkit-mcp-server 1.1.4 → 1.2.0

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

@@ -1,223 +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"])
-```
+# 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"])
+```