Local LLM MCP

Local LLM MCP Server

Claude Code 與本地 LLM 的高效能橋接 MCP Server

使用 Apple Silicon 優化的 MLX 框架，直接整合 IQuest-Coder-V1-40B-Instruct 模型。

✨ 特點

• ⚡ 極速載入: 模型載入 < 1 秒（vs HTTP Server 10+ 分鐘）
• 🎯 SOTA 程式碼模型: IQuest-40B (SWE-Bench 76.2%)
• 💻 Apple Silicon 優化: 使用 MLX 框架，Metal GPU 加速
• 🔧 Skills 整合: 自動載入 ~/.claude/skills/ 專業知識
• 📦 記憶體高效: 4-bit 量化，僅需 25GB RAM

🛠️ 功能

透過 MCP Protocol 提供三個工具：

📊 效能

完整效能報告：PERFORMANCE_REPORT.md

🚀 快速開始

詳見 → QUICK_START.md

1. 系統需求

• 硬體: Apple Silicon (M1/M2/M3/M4)，建議 ≥32GB RAM
• 軟體: Python 3.11+，MLX 框架
• 模型: IQuest-Coder-V1-40B-Instruct-4bit (~25GB)

2. 安裝

# 1. 下載模型（自動，首次運行時）
cd /Users/sbu/local-llm-mcp
python3 download_model.py

# 2. 安裝依賴
pip install -e .

# 3. 配置 Claude Code（已自動配置於 ~/.claude.json）
# 無需手動操作

3. 使用

啟動 Claude Code 後，MCP 工具會自動可用：

# 在 Claude Code 中
請幫我為這段程式碼生成測試...
請分析這段程式碼的安全性...
請解釋這段程式碼的功能...

⚙️ 架構

當前架構（直接 API - 高效能）

Claude Code → MCP Server → ModelSingleton → mlx_lm.load/generate → IQuest-40B
                ↓                                                      ↓
            Skills 載入                                          0.78s + 0.72s

舊架構（HTTP Server - 已棄用）

Claude Code → MCP Server → HTTP Client → MLX LM Server → IQuest-40B
                                            ↓ BUG: 10+ 分鐘無回應

為什麼改用直接 API？

• IQuest-40B 使用自訂架構，MLX HTTP Server 無法正確處理
• 直接 API 提供 770x 載入速度提升
• 架構更簡單，記憶體使用更穩定

🔧 配置

環境變數

Claude Code 配置

已自動配置於 ~/.claude.json：

{
  "mcpServers": {
    "local-llm-mcp": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "local_llm_mcp.server"],
      "env": {
        "LOCAL_LLM_MAX_TOKENS": "4096",
        "LOCAL_LLM_TEMPERATURE": "0.7"
      }
    }
  }
}

🧪 測試

運行完整測試套件

cd /Users/sbu/local-llm-mcp
pytest -v

端到端測試

# 測試完整流程（載入模型 + 推理 + 工具運作）
python3 test_e2e.py

直接測試模型

# 快速驗證模型可用性
python3 test_model_direct.py

📂 專案結構

local-llm-mcp/
├── src/local_llm_mcp/
│   ├── types.py              # 型別定義（Enum, dataclass）
│   ├── model_singleton.py    # ⭐ 模型 Singleton（執行緒安全）
│   ├── llm_client.py         # ⭐ LLM 客戶端（直接 API）
│   ├── server.py             # MCP Server 主程式
│   ├── skills_loader.py      # Skills 自動載入系統
│   ├── tools/                # MCP 工具實作
│   │   ├── test_generator.py
│   │   ├── code_analyzer.py
│   │   └── code_explainer.py
│   └── prompts/              # Prompt 模板（Skills 整合）
│       ├── test_generation.py
│       └── analysis.py
├── tests/                    # 測試套件（88 tests, 100% pass）
│   ├── test_llm_client.py
│   ├── test_server.py
│   └── test_tools/
├── download_model.py         # 模型下載腳本
├── test_e2e.py              # 端到端測試
├── test_model_direct.py     # 直接 API 測試
├── PERFORMANCE_REPORT.md    # 效能基準測試報告
├── QUICK_START.md           # 快速開始指南
└── TROUBLESHOOTING.md       # 故障排除指南

🔬 技術細節

ModelSingleton

執行緒安全的模型管理：

• Lazy Loading：首次使用時才載入
• Double-check Locking：避免重複載入
• asyncio 安全：使用 asyncio.Lock

關鍵特性：

• 載入時間：< 1 秒
• 記憶體使用：~25 GB（穩定）
• 自動 trust_remote_code（支援自訂模型架構）

LLMClient

高效率推理客戶端：

• 整合 ModelSingleton（單一模型實例）
• 自動重試機制（TimeoutError 可重試）
• 細化錯誤分類（RESOURCE_EXHAUSTED, CONNECTION, TIMEOUT）

型別安全：

• 使用 FinishReason Enum（移除硬編碼）
• 完整 dataclass 型別定義
• 100% 型別提示覆蓋

Skills 整合

自動載入專業知識：

• 從 ~/.claude/skills/*.md 載入
• 動態注入到 prompts
• 完全兼容現有 Skills（dev, review, testing）

📚 文檔

• 快速開始指南 - 5 分鐘上手教學
• 效能報告 - 詳細基準測試數據
• 故障排除 - 常見問題與解決方案

🗺️ 路線圖

✅ 已完成

• Spec 1: Model Download & Optimization (100%)

- ✅ IQuest-40B 模型下載與配置 - ✅ 架構優化（HTTP → 直接 API，770x 提升） - ✅ ModelSingleton 實作（執行緒安全） - ✅ 完整測試套件（88 tests, 100% pass） - ✅ 效能基準測試 - ✅ 文檔完整

🔮 未來 Specs（數據驅動決定）

• Spec 2: TESTER Agent Replacement - 本地化測試生成（Fallback Pattern）
• Spec 3: DEVELOPER Agent Augmentation - 增強程式碼生成能力
• Spec 4: Monitoring & Analytics Dashboard - 成本與品質追蹤
• Spec 5: Tool Expansion - 新增 MCP 工具
• Spec 6: REVIEWER Agent Integration - 本地化程式碼審查

詳見：/Users/sbu/.claude/plans/peppy-tumbling-creek.md

🤝 貢獻

本專案為個人實驗專案，暫不接受外部貢獻。

📝 授權

私人專案，保留所有權利。

🙏 致謝

• IQuest: IQuest-Coder-V1-40B-Instruct 模型
• MLX: Apple 的 Machine Learning 框架
• Claude Code: Anthropic 的 AI 編程助手

狀態: ✅ 生產就緒（Spec 1 完成） 最後更新: 2026-01-16