給 AI agent 的 MCP 伺服器

找個股、13F 機構、公司內部人（Form 4 申報人）與政治人物（美國國會議員）。代號完全相符或開頭相符，CIK 或 9 碼的 CUSIP 要完全相符，名稱至少 2 個字。大師也可以用基金或人物的中英文名字找，大型資產管理公司還可以用中英文通稱找，例如用 Fidelity 或「富達」找到 FMR LLC。政治人物用英文姓名、暱稱、姓氏或 Bioguide ID 找，現任的排前面。

個股的公司名稱在 name，代號已不在 SEC 清單上的（已下市或換了代號）active 是 false。機構的 detail 是大師的代表人物，一般機構是「13F filer」；內部人的 detail 是職稱與公司。內部人以 SEC 上的英文姓名列出，姓在前，例如「Cook Timothy D」。政治人物在 politicians 這一組，附黨籍（D、R、I）、院別、州、選區與是否在任（in_office）。

一檔美國上市股票的總覽：SEC 名稱、CIK、交易所、SIC 產業與其他股別；近 90 天的公開市場內部人買賣（Form 4 代碼 P、S，非衍生），以申報份數與美元合計表示；最新完整季的 13F 機構持有概況，附上一季比較；以及持有這檔股票的大師。

「完整季」指已過 45 天申報期限、資料也已載入的季。不同股別（GOOG 與 GOOGL、BRK.A 與 BRK.B）是不同代號。代號已不在 SEC 清單上的照樣查得到：delisted 表示公司已經沒有掛牌的普通股，delisted_on 是 Form 25 上的下市日（沒有下市或找不到 Form 25 時是 null），13F 的數字是它最後一個有完整 13F 持有人的季，f13.note 會說明。

financials 是最新一個年度與最新一季的摘要（營收、淨利、自由現金流與年增率，申報幣別），short_interest 是 FINRA 最新一期的空單餘額（空單股數、變化、回補天數）；沒有資料時是 null。

market_cap 是公司的市值（美元）：主要代號（market_cap.ticker）最新的每日收盤價乘以最新一份 10-K 或 10-Q 封面的流通股數（shares、shares_as_of），之後有拆股的話依比例換算（split_factor，1 是沒有拆股），附用的是哪一天的收盤（close_date）。不回傳股價。market_cap 是 null 時，market_cap_unavailable 寫原因：no_price 或 stale_price（近 7 天沒有收盤價）、no_shares 或 stale_shares（約 400 天內沒有封面流通股數，封面把各股別分開列的公司多半如此）、foreign_filer（申報 20-F 的外國公司，在美國掛牌的多半是 ADS）、shares_mismatch（封面股數對不上掛牌的股票：13F 持股超過封面股數的 1.5 倍，或同一家有好幾條在交易的普通股、收盤價相差超過 1.25 倍，例如好幾檔 ETP 共用一個封面股數的信託）或 out_of_range（數字不合理，包括市值不到 100 萬美元）。Livermore 沒有這家公司的市值資料時兩個都是 null。

一份申報裡同一種交易合計成一列：同一天的多筆成交合併（lots 是筆數），avg_price_usd 依金額加權，shares_owned_after 是最後一筆成交後的持股。ownership_change_pct 是內部人持股的變化，新建立的部位是 null。

4/A 只重述原件的一部分時，原件其他的交易仍然有效：這些列放在 4/A 的 accession 底下，carried_from 是原件的 accession，filed_at 與 sec_url 是原件的；其他列的 carried_from 是 null。

給了 ticker 或 insider_cik 可以查 2021 年 7 月以來的全部紀錄。兩個都沒給就是全市場查詢，申報日期最多 30 天；沒給日期就查近 7 天，區間被縮短時 note 會說明。交易代碼的意思請看術語白話。

跟網站上的內部人清單相同。時間窗依 SEC 申報時間從現在往前算，只看非衍生交易，排除價格異常與沒有代號的發行人。群聚買進回在 companies，其他清單回在 trades（欄位同 get_insider_trades）。

每一列有股數、市值、pct_of_portfolio（這檔股票佔該機構 13F 組合的比重），以及跟上一個日曆季比的變化：action 是 new 新進、added 加碼、reduced 減碼、unchanged 不變或 sold_out 清倉，另有 share_change 與 share_change_pct。兩季之間拆股的，上一季的股數先依拆股比例（split_factor）換算再比。合計數字涵蓋全部持有人，不只這一頁。

上一季持有、這一季有申報但沒有部位的機構列在最後，算清倉；這一季還沒申報的機構不算清倉。

用 SEC CIK 查一家機構或精選大師：名稱（大師另附經理人與投資風格）、最近 12 季的申報、某一季的持倉與跟上一個日曆季比的變化，以及最大的 10 筆清倉與 10 筆選擇權部位。

組合總值只算多頭部位、不含選擇權。這家機構上一季沒申報時，不給變化與清倉。變化依拆股比例換算（每一列的 split_factor），拆股時換了 CUSIP 的合併成一列、列在新的 CUSIP。沒有代號的證券 url 是 null。

每位大師的組合總值（多頭部位、不含選擇權）、持股檔數、申報日與前三大持股，依組合總值排序，中文名稱在 name_zh 與 manager_zh。最新一季是用前身 CIK 申報時，source_cik 會有值。

拿一季跟上一個日曆季比較，只比兩季都有申報的大師。加碼、減碼看股數，不看市值，拆股的股票先依拆股比例（split_factor）換算上一季的股數；證券依代號合併（沒有代號的依 CUSIP）。

沒給 superinvestor_cik 時，回最多大師買進（most_bought）、最多大師賣出（most_sold）的股票與每位大師的動作次數（by_superinvestor）；給了就回那位大師依動作分組的變動。

每位大股東有最新一份 Schedule 13D 或 13G 上的 pct_of_class（占該類股份的百分比）與股數、跟同一個部位上一份申報比的變化（previous_pct_of_class 與以百分點計的 pct_of_class_change；第一份申報的 new_position 是 true）、表單、申報日與事件日、這個部位最早的申報日與申報份數，並附持有人頁面與 SEC 原文的連結。

群組申報的每位成員各報自己算得到的股份，所以數字是最大的單一持股，不是加總。GOOG 與 GOOGL 這類不同股別依申報上的 CUSIP 分開。公司被收購或下市之後持有人通常不再申報；最新一份是舊格式 SC 13D 或 SC 13G 的持有人沒有持股比例，不算在內。

13D 是可能想影響公司的持有人（例如積極型投資人）申報的，13G 是被動持有人；/A 是修正申報。每一列有公司、申報人（是大師時附大師名稱，群組申報附申報人數）、pct_of_class 與股數、跟同一個部位上一份申報比的變化、below_5_pct（出清或降到 5% 以下），以及事件日與 livermore.club、SEC 的連結。

給了 ticker 或 filer_cik 可以查全部歷史；兩個都沒給就是全市場查詢，申報日期最多 365 天，沒給日期就是近 30 天，區間被縮短時 note 會說明。2024 年 12 月 18 日以前的舊格式 SC 13D、SC 13G 標 legacy，沒有持股比例、股數與事件日。

Form 144 是預計賣出受限股票或控制股的通知，不是已經成交的賣出。每一列有公司、賣方與他跟公司的關係、預計賣出的股數、市值、流通在外股數、預計賣出日、有申報時附 Rule 10b5-1 計畫的採用日與券商，並附 livermore.club 與 SEC 的連結。已經被 Form 144/A 取代的通知不列。

給了 ticker 或 seller_cik 可以查全部歷史，市值明顯填錯的通知照樣列出並標 value_outlier；兩個都沒給就是全市場查詢，申報日期最多 365 天（預設近 30 天），市值明顯填錯的不列，同網站。

眾議院與參議院 2020 年起的定期交易申報，一筆交易一列：政治人物（politician_bioguide、politician_name、黨籍、院別、州）、資產與代號、資產類別、交易類型、持有人（本人、配偶、共同或子女）、交易日與申報日、申報延遲天數、金額級距、官方原檔，以及政治人物與個股頁面的連結。totals 是符合篩選條件的全部交易的彙總，包括幾位政治人物。

預設只列上市證券：股票（含 ADR）、ETF 與選擇權。asset=other 回國庫券與公債、市政債與公司債、未上市公司、私募基金、加密貨幣等其他資產，asset=all 回全部。

金額是議員申報的法定級距：amount_min_usd 到 amount_max_usd，「Over $X」這一級的 amount_max_usd 是 null；估計金額把每個級距的中間值加總。申報上的交易日晚於申報日（打錯日期，trade_date_error 是 true）時 delay_days 是 null；交易後超過 45 天才申報的 late 是 true。被修正取代的交易與重複申報不列。

用 Bioguide ID 或英文姓名查：黨籍、院別、州與選區、是否在任、歷任任期，基本資料（官方照片、職位、席位代碼、生日與年齡、官網、社群帳號與維基百科、黨團領導職，現任的另有本屆的委員會與小組委員會席位和職稱），以及 2020 年起的統計：交易筆數、買進與賣出、估計金額、申報延遲中位數、遲報的交易與它們所在的申報、申報份數（其中幾份是紙本或掃描檔）與最近的申報日，另附最常交易的 5 個代號。

交易統計與代號預設只算上市證券，也就是股票（含 ADR）、ETF 與選擇權，可以用 asset 換。unlisted_trades 一律是這位政治人物債券、私人持股等其他資產的交易筆數；所選的資產沒有交易時，note 會說明怎麼拿到其他資產的交易。

交易明細用 get_politician_trades 帶 Bioguide ID 查。紙本與掃描檔申報列在政治人物頁上，但不讀取裡面的交易，所以不算進統計。

取自公司 10-K、10-Q、20-F、40-F 申報的 XBRL 資料，新的期間在前：損益表、資產負債表、現金流量表，另外可以要申報封面的流通股數。每一期有來源申報（form、filed_date、sec_url）、reported_date（期末之後第一份 Item 2.02 的 8-K）、利潤率、年增率（yoy_pct），以及推算的數字（derived）與沒通過會計恆等式的檢查（check_failed）。

金額是公司的申報幣別（currency），不一定是美元：台積電是新台幣（TWD）。外幣公司另外給 usd_rate（1 單位外幣等於幾美元，FRED H.10 匯率）：損益表與現金流量表乘 usd_rate.average，資產負債表乘 usd_rate.period_end。

已知的缺口：申報 20-F、40-F 的外國公司只有年度；EPS 與股數照申報時的數字，不依之後的拆股調整（期間內的拆股列在 stock_splits）；ADR 的 EPS 是每股普通股，不是每股 ADS；Q4 與單季現金流多半是相減推算的；銀行的營收可能只有利息收入；有好幾個股別的公司可能沒有 EPS 與封面股數。note 會說明這家公司適用的缺口，以及沒有財報的原因（ETF、基金沒有財報）。

一家公司或全市場的 SEC 申報，新的在前：10-K（含 10-KT）、10-Q、8-K、20-F、40-F，各含修正版。每一列有表單、8-K 的 Item 代碼與說明（2.02 財報結果、4.02 先前的財報不可再信賴、5.02 董事或高階主管異動）、申報日、SEC 受理時間、期間、公司，以及 url（這家公司的申報分頁）、sec_url（SEC 上的主文件）、index_url（申報目錄，所有附件都在這裡）。

Livermore 不存申報的內文。要知道 8-K 發生了什麼、10-K 或 10-Q 的業務說明、風險因素、管理層討論，請抓 sec_url；財報新聞稿（8-K Item 2.02）通常是 index_url 裡的附件 EX-99.1。

給了 ticker 或 cik 可以查這家公司的全部歷史，包括用舊 CIK 申報的。兩個都沒給就是全市場查詢（只列有代號的公司），申報日期最多 30 天；沒給日期就查近 7 天，區間被縮短時 note 會說明。

四個區塊，新的在前：short_interest（FINRA，每月兩次，2021 年起：空單股數、變化、平均日成交量、回補天數）、short_volume（FINRA Reg SHO 的每日場外放空量，近兩年）、fails_to_deliver（SEC，近兩年：股數、SEC 公布的價格與金額）、ats_weekly（FINRA 每週的暗池與其他場外成交量，依層級，2021 年 12 月起）。沒給日期時是約一年的空單餘額（24 個結算日）、30 個交易日的放空量與交割失敗、12 週的暗池成交量；給了 from 或 to，每個區塊都照那個區間，最多 200 列。

空單餘額與每日放空量是兩種東西：放空量是某一天場外成交裡放空的股數，short_volume_pct 也不是情緒指標，因為造市商避險的放空本來就佔場外成交量的一半上下。FINRA 回報上限 999.99 天時，days_to_cover 是 null、dtc_capped 是 true。沒有空單佔流通股的比例。

跟 livermore.club/zh/shorts 同一份排行：某一個結算日（預設最新一期）每檔股票的空單餘額，以及跟前一個結算日比的變化。平均日成交量低於 min_avg_volume（預設 10 萬股）的不列，避免成交冷清、變化 % 爆表的股票擠上排行。缺值與回補天數卡在 FINRA 上限（dtc_capped）的列，不論排序方向都排在最後。

不是結算日的日期會回錯誤並列出最近幾期；每次回傳的 recent_settlement_dates 都有最近 12 期。FINRA 的代號對不到上市公司的列，ticker 與 url 是 null。

有市值的美國上市公司，市值大的在前（dir 給 asc 是小的在前），可以用 min_market_cap_usd、max_market_cap_usd 限定區間（美元，兩端都含）。市值是公司主要代號最新的每日收盤價乘以最新一份 10-K 或 10-Q 封面的流通股數，之後有拆股的話依比例換算，每個美股交易日收盤後重算。不回傳股價。

沒有市值的公司不列：近 7 天沒有收盤價（櫃買或停止交易）、沒有近期的封面流通股數（封面把各股別分開列的公司多半如此，例如 Alphabet、波克夏、Meta）、在美國掛牌的是 ADS 的 20-F 外國公司、封面股數對不上掛牌股票的公司（13F 持股遠超過封面股數，或好幾檔 ETP 共用一個封面股數的信託），以及算出的數字不合理的（包括市值不到 100 萬美元）。

每一列有拿來算的代號、名稱、交易所、SIC 產業、market_cap_usd、close_date、shares、shares_as_of、split_factor 與 url。total 是符合條件的公司家數，as_of 是最新的收盤日。要研究某一家公司，接著用 get_stock、get_financials、get_insider_trades。

找證交所上市、櫃買中心上櫃還在交易的股票與 ETF，可以用代號、中文簡稱或全名、英文名稱（例如 TSMC）找。分級比對：代號完全相符、代號開頭相符、簡稱完全相符、簡稱開頭相符、簡稱包含，最後是全名或英文名稱包含；同一級公司排在 ETF 前面，再依市值。2330.TW、2330.TWO 當代號找。

每一筆有代號、繁體中文的簡稱與全名、name_en、市場（TWSE 或 TPEx）、種類（stock、etf、other）與台股站的網址（台股站只有繁體中文）。美股的工具不含台股，查台股從這裡開始。

一檔台股或 ETF 的總覽：證交所、櫃買中心與公開資訊觀測站的基本資料；最新行情與交易所公布的本益比、淨值比、殖利率，以及 Livermore 算的漲跌幅與市值；最新一個月的營收；最新一季的營收、獲利、EPS、利潤率、年增率、ROE 與負債比率；近 5 年的股利與最近一次除權息。

intro 是 AI 依公司最新一份股東會年報整理的介紹：產品與營收比重、銷售地區、客戶、供應商、競爭者、產業地位、去年成果、展望、沿革，繁體中文；可能有錯，數字以年報為準。production_sites 是 AI 依公開資料整理的工廠與座標，OpenStreetMap 查到的座標附上要標的聲明。industry_chains 是這家公司在櫃買中心產業價值鏈的環節，每個環節附最多 5 家同業。

沒有資料的那一塊是 null，ETF 與其他證券通常只有基本資料、行情與股利。每個台股的回傳都有 currency TWD 與 attribution（提供機關、政府資料開放授權條款、Livermore 算的欄位），呈現資料時要保留。

每個月的營收，新的在前，附上月與去年同月營收、月增、年增、累計年增，與公司寫的增減原因（繁體中文）。台灣的公司每月 10 日前公布上個月的營收；百分比是公司經公開資訊觀測站申報的，不是 Livermore 算的。ETF 與其他證券沒有月營收。

2013 年第 1 季起的財報，新的在前：近 8 季的單季或近 5 年。每一期有新台幣的損益表、資產負債表、現金流量表，與 Livermore 算的利潤率、年增率、ROE、負債比率。

公司第 4 季只申報全年，所以單季的第 4 季是相減推算的，第 4 季 EPS 是全年減前三季，兩者都有標記。template 是行業格式（一般業、銀行、證券、金控、保險、異業），各格式的營收定義不同，不能拿來比；保險業 2026 年起的營收是 IFRS 17 的保險收入，不能跟以前比。季度的 ROE 不年化。

2021 年起每天一列，新的在前：開高低收（原始價格，除權息不還原）、漲跌、成交量、成交金額；外資、投信、自營商的買賣；融資融券與餘額；借券賣出；外資持股與投資上限。股數一律是股。

台股的每日行情是政府開放資料，所以會回傳。融資融券、借券賣出、外資持股台灣時間 22:30 左右才補，最新一天這幾塊可能是 null。

上市、上櫃各一列：成交金額合計與上漲、下跌、平盤的公司家數，由 Livermore 依官方行情加總、計數。三個只列公司（不含 ETF）的排行：成交金額最大、漲幅最大、跌幅最大。沒有行情的日子（週末、休市）回錯誤並寫出最新的交易日。

一種法人在一段期間（最後一天是最近的交易日之一）的買賣超排行，只列公司。每一列有期間買賣超股數、估計金額（每天的買賣超 × 那天的收盤，加總）、最後一天的收盤與漲跌、期間漲跌幅；估計金額、期間漲跌幅與多天的合計是 Livermore 算的。期間的最後一天可以選近 30 個有三大法人資料的交易日。

上市、上櫃還在交易的公司，一頁 100 家，附最新的收盤與漲跌、交易所公布的本益比，與 Livermore 算的市值（最新收盤 × 發行股數）。回傳列出全部的產業別代碼、中文名稱與家數，先不帶產業呼叫一次就知道有哪些代碼：24 是半導體業，etf 改列 ETF。列裡只有中文名稱，英文名稱用 tw_get_stock。

櫃買中心「產業價值鏈資訊平台」的 47 條產業鏈（例如半導體 D000），依「做什麼」找公司。沒給 chain 列全部產業鏈與公司家數；給了 chain 回那條鏈上中下游的環節與每個環節的公司，上市櫃公司依市值排在前面；再給 segment 只回那個環節與它的子環節。名稱是繁體中文。產業鏈資料不是政府開放資料，在 attribution 裡另外列出處。

Form 4 的申報日期範圍、全市場都有資料的 13F 季度與最新完整季、大師人數、Schedule 13D、13G、Form 144 與政治人物向國會提出的申報（congress）的日期範圍、公司申報、FINRA 空單餘額、每日放空量、暗池週報與 SEC 交割失敗的日期範圍、有財報的公司家數、有市值的公司家數與用到的最新收盤日（market_caps）、tw_ 工具的台股資料（taiwan：每張每日表的最新日期、月營收最新的月份與財報最新的一季、各資料的起點）、最近成功更新的時間、更新排程，以及伺服器的使用限制。新加的幾項在資料載入前是 null，各有自己的 last_updated。要確認某個日期或季度有沒有資料時先呼叫它。