# FRED MCP → LM Studio Plugin (Port)

> 原專案: https://github.com/stefanoamorelli/fred-mcp-server  
> 本移植版將 3 大工具完整帶入 LM Studio Plugin 系統，程式碼精簡高效 (< 300 LOC 核心)。

## 功能對應
| 原 MCP Tool | LM Studio Plugin Tool | 說明 |
|---|---|---|
| `fred_browse` | `fred_browse` | 瀏覽 categories/releases/sources/category_series/release_series |
| `fred_search` | `fred_search` | 關鍵字 / tag 搜尋 80 萬+ 指標，找 GDP, UNRATE 等 ID |
| `fred_get_series` | `fred_get_series` | 取回時間序列觀測值，支援 units/frequency 轉換 |

## 架構
```
fred-mcp-lmstudio/
├── manifest.json      # LM Studio 插件描述 (owner=local)
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts         # main() 註冊 config + toolsProvider
│   ├── config.ts        # globalConfig: fredApiKey, perChat: limit/sort
│   ├── fredClient.ts    # 極簡 FRED API fetch wrapper (共用)
│   └── toolsProvider.ts # 3 tools 實作，<250 行
```

核心設計：
- **fredClient.ts** 單一 fetch 函式處理所有 FRED endpoint，自動加上 `api_key` & `file_type=json`，錯誤精簡拋出
- **config** 分離：API Key 放 Global (跨對話共用)，limit/sort 放 Per-Chat
- **toolsProvider** 共用 `getKey()` + `clean()` 去除空參數，避免冗長程式碼
- 觀測值只回傳最後 200 筆 + metadata，避免 LLM token 爆炸，仍保留 count/range

## 安裝 (LM Studio Plugin 模式 - 推薦)

### 前置
- LM Studio >= 0.3.17
- `lms` CLI 已在 PATH (LM Studio 附帶)
- FRED API Key: https://fred.stlouisfed.org/docs/api/api_key.html

### 自動安裝
```bash
git clone https://github.com/stefanoamorelli/fred-mcp-server fred-mcp-lmstudio
cd fred-mcp-lmstudio
# 複製本移植的檔案覆蓋 (或直接用本資料夾)
npm install
npx tsc
# 複製到 LM Studio plugins 目錄
# Windows:
# mkdir "%USERPROFILE%\.lmstudio\extensions\plugins\lmstudio\fred-mcp-lmstudio"
# Linux/macOS:
mkdir -p ~/.lmstudio/extensions/plugins/lmstudio/fred-mcp-lmstudio
cp -r manifest.json package.json dist src ~/.lmstudio/extensions/plugins/lmstudio/fred-mcp-lmstudio/

# 啟動 dev 模式
cd ~/.lmstudio/extensions/plugins/lmstudio/fred-mcp-lmstudio
lms dev
```

### 在 LM Studio 設定 API Key
1. 開 LM Studio → 右側 Program → Plugins → fred-mcp → Settings
2. Global Config → FRED API Key 貼上
3. 存檔，plugin 自動重載

### 使用
載入任意支援 tool calling 的模型 (Qwen2.5, Llama 3.1, GPT-OSS 等)
> "幫我搜尋失業率相關指標，然後取 UNRATE 最近 2 年數據"

模型會自動呼叫 `fred_search` → `fred_get_series`。

## 安裝 (MCP Server 相容模式 - 給 LM Studio mcp.json)

如果你不想用 Plugin，也可當成純 MCP Server 給 LM Studio 使用 (LM Studio 原生支援 MCP)。

### 1. 編譯獨立 MCP Server
本移植已內含 `src/mcpServer.ts` 精簡版 MCP Server (std io + http 可選)。

```bash
npm install @modelcontextprotocol/sdk
# 已在 src/mcpServer.ts
npx tsc
```

### 2. 編輯 LM Studio mcp.json
Program → Install → Edit mcp.json

```json
{
  "mcpServers": {
    "fred-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/fred-mcp-lmstudio/dist/mcpServer.js"],
      "env": {
        "FRED_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}
```

或使用 http 傳輸:
```json
{
  "mcpServers": {
    "fred-mcp": {
      "url": "http://localhost:3000/mcp",
      "headers": {}
    }
  }
}
# 啟動: PORT=3000 TRANSPORT=http node dist/mcpServer.js
```

儲存後 LM Studio 會自動載入 3 tools。


## 範例 Prompt
- "瀏覽 FRED 的 GDP 相關分類"
- "搜尋 CPI 相關 series，選最熱門的 5 個"
- "取 GDP (series_id=GDP) 2020-01-01 到現在，轉成年增率 pc1"
- "比較 UNRATE 和 CPIAUCSL 最近一年走勢"

## 授權
AGPL-3.0 (跟隨原專案)。商業授權請聯絡 stefano@amorelli.tech

## 免責
非聯準會官方，FRED 為 St. Louis Fed 註冊商標。