MCP NodeServer — 程式設計師的私人 AI 助理員工

Node.js MCP Server，為 Claude Code 打造私人 AI 工具鏈，讓 AI 直接讀寫檔案、操作 DB、執行 PHP、部署 SFTP。詳見 技能儀表板。

📊 查看技能儀表板 →

---

前置條件

工具	版本	說明
Node.js	18+	執行 MCP Server 必需
Docker Desktop	最新版	Python 容器（run_python_script，選用）
Git	任意版	Clone 專案

---

快速開始（首次安裝）

git clone https://github.com/Bing-Xuan-Lu/MCP_NodeServer.git
cd MCP_NodeServer
.\setup.ps1        # 一鍵初始化（npm install + Python 容器 + 部署 Skills）

安裝完成後，依下方「新專案掛載」將 MCP Server 接上你的專案，重啟 Claude Code 即可使用。

---

新專案掛載

MCP Server 安裝一次即可，每個需要使用的專案只要掛上連線設定。有兩種方式：

方式 A：全域設定（推薦）

設定一次，所有專案自動共用，不需逐個專案設定。

編輯 ~/.claude/mcp_settings.json（不存在則新建）：

{
  "mcpServers": {
    "project-migration-assistant-pro": {
      "type": "stdio",
      "command": "node",
      "args": ["{MCP_NodeServer安裝路徑}\\index.js"]
    }
  }
}

將 {MCP_NodeServer安裝路徑} 替換為 index.js 的實際絕對路徑，例如 D:\\MCP_NodeServer\\index.js。

方式 B：單專案設定

只在特定專案啟用 MCP Server。在該專案的根目錄建立 .mcp.json：

{
  "mcpServers": {
    "project-migration-assistant-pro": {
      "type": "stdio",
      "command": "node",
      "args": ["{MCP_NodeServer安裝路徑}\\index.js"]
    }
  }
}

掛載後注意事項

項目	說明
重啟	設定完成後需重啟 Claude Code 才會生效
路徑存取	MCP 檔案工具預設只能存取 D:\Project\ 下的檔案；專案不在此路徑的話，每次對話需先呼叫 grant_path_access 授權
DB 連線	set_database 只在當次對話有效，每次新對話需重新設定
Skills	全域已部署的 /skill-name 指令自動可用，不需額外設定
驗證	重啟後在對話中輸入任意 /skill-name，能觸發即代表掛載成功

Session Hooks（全域自動生效）

已在 ~/.claude/settings.json 全域設定，所有專案對話自動觸發：

Hook	事件	功能
session-start.js	SessionStart	對話開場載入 MEMORY.md 摘要、上次 session 快照、24h 內更新的記憶檔、近期踩坑紀錄、CLAUDE.md 老化偵測
pre-compact.js	PreCompact	Context 壓縮前自動存快照到 ~/.claude/sessions/，偵測重試/失敗/大量修改模式並存踩坑紀錄，GC 清舊紀錄
write-guard.js	PreToolUse (Write|Edit)	依 risk-tiers.json 分級警告（🔴 高風險 / 🟡 中風險）、敏感檔案保護、Prompt Injection 偵測（非阻擋式）
llm-judge.js	PostToolUse (Write|Edit)	Write/Edit 後依風險層級注入自我審查清單，PHP 非測試檔自動提醒「事故→測試」習慣；PHP 版本感知 lint：漸進式回退（動態發現本機 PHP 容器由新到舊逐版 php -l，任一版過即放行並標明舊版，全版皆語法錯才 BLOCK），避免 legacy 5.x 檔被最新版誤判
php-containers.js	（llm-judge 共用模組）	動態發現本機在跑的 PHP 容器（docker ps + 逐一問 PHP_VERSION，不寫死容器名），結果快取 30 分鐘；env MCP_PHP_LINT_CONTAINERS 可覆寫
memory-auto-recall.js	PreToolUse	依 memory frontmatter triggers 比對 tool / file_path / 最近 prompt，命中且距上次注入 ≥ N 次 tool call 即注入提醒，解 memory attention 衰減

Hook 腳本存放於 hooks/ 目錄，設定在全域 ~/.claude/settings.json 的 hooks 欄位。

全域 vs 專案 Hooks：

設定位置	檔案	適用範圍
全域	~/.claude/settings.json → hooks	所有專案對話自動觸發
專案	{project}/.claude/settings.json → hooks	僅該專案對話觸發
專案本地	{project}/.claude/settings.local.json → hooks	同上，不進版控

本專案的 3 個 hooks 設定在全域，因為 session 記憶載入與敏感檔案防護不限於特定專案。 若需要專案專屬 hook（如特定專案的 lint 檢查），可在該專案的 .claude/settings.json 另行設定。

---

目錄結構

MCP_NodeServer/
├── index.js             ← MCP Server 主程式
├── config.js            ← resolveSecurePath (預設 basePath 為 D:\Project\)
├── tools/               ← MCP 工具模組
│   ├── filesystem.js    ← list_files, read_file, create_file, apply_diff, apply_diff_batch, *_batch (read_files/list_files/create_file)（PROTECTED_PATTERNS 防寫入測試檔 + audit log）
│   ├── php.js           ← run_php_script, run_php_code, run_php_test, send_http_request（含 body_filter regex tool 端 grep）, tail_log, *_batch (http_requests/php_script)（PHP 執行 + tail_log 支援 container 參數走 Docker；stderr 自動濾 Xdebug Step Debug 雜訊）
│   ├── php_modernize.js ← php_modernize（PHP 舊語法確定性升級：token_get_all 詞法做 6 條等價轉換 — 結尾 ?>／$str{0}→[0]／PHP4 建構子→__construct／var→public／define 裸常數加引號／__autoload 改名+註冊；每檔 php -l 過才寫，預設 apply:false 預覽；mysql_*/ereg 等只列殘留交 LLM）
│   ├── database.js      ← set_database, load_db_connection, get_db_schema, execute_sql（危險語句攔截 + confirm + audit log + ER_* 錯誤摘要）, *_batch, schema_diff, mysql_log_tail
│   ├── gsheet.js        ← gsheet_fetch_with_state（含 auto_recalc_check polling + preserve_validation 跳過空字串寫入保留 dropdown）, gsheet_xlookup_trace, trace_gsheet_formula, gsheet_get_metadata, gsheet_fetch_formatted, gsheet_get_values（輕量 batch get）, gsheet_set_values（輕量 batch update）（gspread 一條龍 + 查表鏈遞迴展開 + markdown 公式追蹤報告 + worksheet metadata 列舉 + FORMATTED_VALUE 顯示字串抓取 + 輕量讀寫取代 PHP 手刻 JWT+curl，python_runner 容器）
│   ├── excel.js         ← get_excel_values_batch, trace_excel_logic, simulate_excel_change
│   ├── export_fetch.js  ← fetch_export_file（帶 cookie / 先登入下載受保護的 .xlsx/.xls/.csv 匯出檔 → SheetJS 解析回傳儲存格；偵測登入頁 + csv UTF-8 防亂碼）
│   ├── bookmarks.js     ← Chrome 書籤管理 (12 工具)
│   ├── sftp.js          ← sftp_connect/upload/download/list/delete, sftp_*_batch (list/upload/download/delete), sftp_preset, sftp_diff_hash (MD5 比對不下載全文)
│   ├── docker_ops.js    ← docker_cp（本機 container ↔ 主機檔案拷貝；basePath 白名單 + container 名 + path regex 防注入；遠端機器仍走 ssh_exec）
│   ├── python.js        ← run_python_script (via Docker python_runner)
│   ├── word.js          ← read_word_file, read_word_files_batch (.docx → Markdown/HTML/Text)
│   ├── pptx.js          ← read_pptx_file, read_pptx_files_batch (.pptx → Markdown/Text + 圖片)
│   ├── pdf.js           ← read_pdf_file, read_pdf_files_batch (.pdf → Markdown/Text)
│   ├── images.js        ← read_image, read_images_batch（圖片讀取 + 縮放，支援 PNG/JPG/WebP/GIF/SVG）
│   ├── video.js         ← read_video（影片 → faster-whisper 字幕 + ffmpeg 關鍵幀，支援 MP4/MOV/MKV/WebM/AVI/M4V，python_runner 容器）
│   ├── git.js           ← git_status, git_diff, git_log, git_stash_ops（container 模式以 -w workdir 指定容器內 repo 路徑，預設 /var/www/html；本機模式可加 cwd 指定專案目錄）
│   ├── dom_compare.js   ← dom_compare（批次比對兩個 URL 的 CSS/HTML/JS 差異，需 Playwright）
│   ├── playwright_tools.js ← browser_interact, page_audit, css_inspect, element_measure, style_snapshot, css_coverage（含 detectOverridden 死宣告偵測）, browser_save_session, browser_restore_session（自帶 headless 瀏覽器，需 Playwright）
│   ├── print_layout.js  ← print_layout_test（列印版面測試：產真實分頁 PDF → poppler render 每頁 PNG → 頁圖 + 頁數 + 字體嵌入 + selector 落點，需 Playwright + python_runner）
│   ├── image_diff.js    ← image_diff（設計稿 vs 截圖像素級比對，產生 diff 圖）
│   ├── image_transform.js ← image_transform（圖片 resize / 背景色 / 圓形裁切 / 合成）
│   ├── file_diff.js     ← file_diff（純 Node 雙檔 unified diff，零依賴；支援 project 參數）
│   ├── analyze_csv.js   ← analyze_csv（CSV pivot/group/aggregate；取代 batch test 後手寫解析腳本）
│   ├── csv_recompute_audit.js ← csv_recompute_audit（baseline CSV vs PHP 重算 diff 報告；情境：報價/計算類 service 對齊 Sheet baseline 避免 GSheet quota）
│   ├── agent_coord.js   ← agent_coord（多 Agent 協調：post/poll/status/delete/archive，JSON 檔案持久化）
│   ├── file_to_prompt.js ← file_to_prompt, file_to_prompt_preview
│   ├── css_tools.js     ← css_specificity_check, css_computed_winner（CSS specificity 分析與活頁面規則勝出查詢）
│   ├── php_class.js     ← class_method_lookup（PHP class/method 原始碼直接定位，自動解析 use Trait）
│   ├── php_symbol.js    ← symbol_index, find_usages, find_hierarchy, find_dependencies, trace_logic, find_dead_symbols（PHP AST 符號索引、交叉引用、邏輯追蹤、零引用死碼掃描）
│   ├── js_symbol.js     ← js_symbol_index, js_symbol_lookup, js_find_usages, js_trace_logic（JS/TS/Vue AST 符號索引：function/class/object methods/`obj.method=fn` 賦值/`return {fn}` 工廠）
│   ├── css_class.js     ← css_class_lookup, css_find_usages（CSS class 定義位置 + 跨檔引用：HTML/PHP/JS/Vue 內 class attribute / addClass / classList / 選擇器）
│   ├── session_search.js ← session_search, session_recall（跨 session 搜尋/回顧歷史對話，解換場重踩同個坑）
│   └── skill_factory.js ← save/list/delete_claude_skill, grant/list/revoke_path_access
├── skills/index.js      ← MCP Prompts 路由
├── Skills/commands/     ← Skill MD 檔（12 個部門子資料夾）
├── python/              ← Python Docker 環境（python_runner 容器）
├── hooks/               ← Claude Code Session Hooks（全域生效）
│   ├── session-start.js ← SessionStart：對話開場自動載入記憶與上次摘要
│   ├── pre-compact.js   ← PreCompact：context 壓縮前存快照 + 踩坑偵測 + GC
│   ├── write-guard.js   ← PreToolUse(Write|Edit)：risk-tiers 分級警告 + Prompt Injection 偵測
│   ├── llm-judge.js     ← PostToolUse(Write|Edit)：自我審查清單觸發器
│   └── memory-auto-recall.js ← PreToolUse：memory frontmatter triggers 比對 → 動態 recall 注入
├── docs/                ← 舊版技能儀表板 (備份)
├── dashboard/           ← 新版動態技能儀表板 (index.html / js / style.css)
├── setup.ps1            ← 一鍵環境初始化
└── deploy-commands.bat  ← 部署所有 Skills 到 ~/.claude/commands/

詳細開發規範見 CLAUDE.md。

---

第三方依賴與授權

npm 套件

套件	授權	用途
@modelcontextprotocol/sdk	MIT	MCP 協議 SDK
mysql2	MIT	MySQL/MariaDB 連線
turndown	MIT	HTML → Markdown 轉換
mammoth	BSD-2-Clause	.docx 讀取
dotenv	BSD-2-Clause	環境變數載入
glob	BlueOak-1.0.0	檔案 pattern 匹配
pdfjs-dist	Apache-2.0	PDF 讀取
ssh2-sftp-client	Apache-2.0	SFTP 連線
xlsx	Apache-2.0	Excel 讀取
jszip	MIT / GPL-3.0	ZIP 解壓（.pptx 讀取用）
hyperformula	GPL-3.0	Excel 公式計算引擎
php-parser	BSD-3-Clause	PHP AST 解析（符號索引）
@babel/parser	MIT	JS/TS/JSX/Vue AST 解析（js_symbol_*）
postcss	MIT	CSS AST 解析（css_class_lookup）
postcss-selector-parser	MIT	CSS selector 拆解

Docker 映像檔

映像檔	授權	用途
python:3.12-slim	PSF License	Python 執行環境

Embedding 模型

模型	授權	用途
paraphrase-multilingual-MiniLM-L12-v2	Apache-2.0	RAG 多語言向量化（免費、本地執行）

---

License

MIT License © 2024 Bing-Xuan Lu

詳見 LICENSE。