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

This MCP server is porting from [https://github.com/stefanoamorelli/sec-edgar-mcp](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 即可生效。