SEC EDGAR LM Studio Plugin (sec-edgar-lmstudio)

This MCP server is porting from https://github.com/stefanoamorelli/sec-edgar-mcp

---

TL;DR

這是一個將 Python 專案 sec-edgar-mcp 移植為 LM Studio 相容的 MCP Server Plugin。它讓 AI 助手能夠透過 LM Studio 存取 SEC EDGAR 的公司申報文件、財務報表及內部人交易資料，且維持了原始 sec-edgar-mcp 專案的完整性，未來升級只需替換原始碼目錄即可。

🌟 功能特色

1. 無縫整合 LM Studio：完全相容 LM Studio Plugin SDK，包含自訂設定 UI。
2. 自動化 Python 環境建置：安裝時自動從 GitHub clone sec-edgar-mcp，建立 Python 虛擬環境 (venv) 並安裝相依套件。
3. User Agent 動態設定：首次啟動使用 Pseudo User Agent，進入 LM Studio 後可透過 Plugin 設定介面輸入真實的 SEC EDGAR User Agent。
4. 工具自動同步：所有 sec-edgar-mcp 提供的工具都會自動註冊並顯示在 LM Studio 的工具面板上。
5. 原始碼解耦：不更動 sec-edgar-mcp 原始碼，日後版本升級只需替換 sec-edgar-mcp 資料夾。

📋 系統需求

LM Studio: 0.3.0 或以上版本
Node.js: 18+ (用於執行 Plugin 及 Setup Script)
Python: 3.11+ (用於建立 venv 及執行 MCP Server)
Git: 用於自動 clone 專案

🚀 安裝說明

方法一：透過 LM Studio Hub

在 LM Studio 中開啟 Developer 模式。
進入 Plugins 分頁，搜尋 sec-edgar-lmstudio 並點擊 Install。
安裝完成後，Plugin 會自動在背景執行 setup script 下載並建置 Python 環境。

方法二：手動安裝 (本地開發)

1.下載或 Clone 此專案：

git clone <此專案網址> sec-edgar-lmstudio
cd sec-edgar-lmstudio

2. 安裝 Node.js 相依套件並觸發自動建置：

npm install

(這會自動執行 scripts/setup.js，建立 venv 並 clone sec-edgar-mcp)

3. 編譯 TypeScript：

npm run build

將整個 sec-edgar-lmstudio 資料夾複製到 LM Studio 的 Plugins 目錄中：
    macOS: ~/.lmstudio/plugins/
    Windows: %USERPROFILE%\.lmstudio\plugins\
    Linux: ~/.lmstudio/plugins/
重新啟動 LM Studio，並確保在設定中啟用了 sec-edgar-lmstudio。

⚙️ 使用說明

1. 設定 SEC EDGAR User Agent 基於 SEC EDGAR 的法規與 Fair Access 原則，存取其 API 必須設定 User Agent。

   打開 LM Studio，進入左側選單的 Developer -> Plugins。 找到 sec-edgar-lmstudio，點擊進入設定 UI。 在 SEC EDGAR User Agent 欄位中，輸入您的真實身份，格式建議為：您的名字 (您的Email)，例如：John Doe (john.doe@example.com)。 儲存設定後，Plugin 會自動重啟 Python MCP Server 以套用新的 User Agent。

2. 與 AI 助手對話

   建立一個新的 Chat。 確保在 Chat 右側的 Tools 面板中，已勾選啟用 sec-edgar-lmstudio 提供的相關工具 (如 get_company_facts, search_filings 等)。 開始向 AI 提問，例如： "幫我查詢 Apple Inc. (AAPL) 最近的 10-K 財報重點" "列出 Tesla 最近的內部人交易 (Form 4)" AI 會自動呼叫 sec-edgar-mcp 的工具抓取 SEC EDGAR 的即時資料並回答。

🔄 版本升級 (針對 sec-edgar-mcp)

由於此 Plugin 採用解耦設計，並未複製 sec-edgar-mcp 的原始碼。若 sec-edgar-mcp 發布了新版本：

進入 Plugin 目錄下的 sec-edgar-mcp 資料夾。
執行 git pull 更新原始碼。
執行 ../venv/bin/pip install -e . (macOS/Linux) 或 ..\venv\Scripts\pip.exe install -e . (Windows) 來更新套件。
在 LM Studio 中重啟 Plugin 即可生效。