note-mcp-server 2.3.3 → 2.4.2

package/README.md

@@ -101,6 +101,20 @@ socialite_id=eyJpdiI6I…
 
 ---
 
+## AdminLTE 可摺疊 card（Agent 必讀）
+
+筆記前台用 **AdminLTE 4** 的 `data-lte-toggle="card-collapse"` 做展開／收合。
+
+| 項目 | 正確（3192 類） | 錯誤（展開失效） |
+|------|----------------|------------------|
+| 按鈕屬性 | `data-lte-toggle="card-collapse"` | 無屬性，或 `data-owv-helper-toggle`（後端會剝除） |
+| 圖示 | `bi bi-plus-lg` + `bi bi-dash-lg`，含 `data-lte-icon` | 單一 `fas fa-plus` |
+| 預設收合 | 外層 `collapsed-card` | 僅視覺像 card，無 toggle 綁定 |
+
+`create_note`／`update_note` 工具描述內已內嵌完整 HTML 範本（v2.4.0+）。多段內容請並列多個同級 `.card`，勿巢狀。
+
+---
+
 ## 提供的 MCP 工具
 
 | 工具 | 說明 |

package/index.js

@@ -12,73 +12,101 @@ import {
 import axios from "axios";
 import FormData from "form-data";
 
+import fs from "node:fs";
+import { parse as parseEnv } from "dotenv";
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-// 優先載入專案目錄 (cwd) 的 .env，以支援不同專案自由切換
-loadEnv({ path: path.join(process.cwd(), ".env") });
-// 如果專案目錄沒有設定，則退回讀取全域的 .env
-loadEnv({ path: path.join(__dirname, ".env") });
 /**
  * MCP 須由 Cursor 依 mcp.json 啟動；勿在終端機手動跑本檔當成「掛載 MCP」。
  *
  * 設定優先序：
- * 1) NOTES_API_BASE — 完整 API base（含 /api/notes/{socialite}/{key}）
- * 2) notes_url + socialite + key（或 socialite_id，與 key 同義：加密路徑 token）
+ * 1) 專案目錄 (cwd) 的 .env 優先（支援不同專案自由切換）
+ * 2) 全域的 note-mcp-server/.env 作為預設退路
+ *
+ * 變數組合：
+ * A) NOTES_API_BASE — 完整 API base（含 /api/notes/{socialite}/{key}）
+ * B) notes_url + socialite + key（或 socialite_id，與 key 同義：加密路徑 token）
  *
  * 變數名支援常見大小寫（見 resolveNotesApiBase）。
  */
 
+const cwdEnvPath = path.join(process.cwd(), ".env");
+const cwdEnv = fs.existsSync(cwdEnvPath) ? parseEnv(fs.readFileSync(cwdEnvPath)) : {};
+
+const globalEnvPath = path.join(__dirname, ".env");
+const globalEnv = fs.existsSync(globalEnvPath) ? parseEnv(fs.readFileSync(globalEnvPath)) : {};
+
+// 將載入的變數注入 process.env (cwd 優先蓋過 global)
+for (const [k, v] of Object.entries(globalEnv)) {
+  if (process.env[k] === undefined) process.env[k] = v;
+}
+for (const [k, v] of Object.entries(cwdEnv)) {
+  process.env[k] = v; // cwd 總是能覆寫
+}
+
 function stripTrailingSlashes(value) {
   return value.replace(/\/+$/, "");
 }
 
-function firstEnv(...keys) {
-  for (const key of keys) {
-    const raw = process.env[key];
-    if (raw === undefined) {
-      continue;
-    }
-    const trimmed = String(raw).trim();
-    if (trimmed !== "") {
-      return trimmed;
+function extractBase(envObj) {
+  const get = (...keys) => {
+    for (const k of keys) {
+      if (envObj[k] !== undefined && String(envObj[k]).trim() !== "") {
+        return String(envObj[k]).trim();
+      }
     }
-  }
-  return "";
-}
+    return "";
+  };
 
-function resolveNotesApiBase() {
-  const direct = firstEnv("NOTES_API_BASE");
+  const direct = get("NOTES_API_BASE");
   if (direct) {
     return stripTrailingSlashes(direct);
   }
 
-  const notesUrl = stripTrailingSlashes(
-    firstEnv("notes_url", "NOTES_URL")
-  );
-  const socialite = firstEnv("socialite", "SOCIALITE");
-  const encryptedToken = firstEnv(
-    "key",
-    "KEY",
-    "socialite_id",
-    "SOCIALITE_ID"
-  );
+  const notesUrl = stripTrailingSlashes(get("notes_url", "NOTES_URL"));
+  const socialite = get("socialite", "SOCIALITE");
+  const encryptedToken = get("key", "KEY", "socialite_id", "SOCIALITE_ID");
 
   if (notesUrl && socialite && encryptedToken) {
     return `${notesUrl}/api/notes/${socialite}/${encryptedToken}`;
   }
 
+  return null;
+}
+
+function resolveNotesApiBase() {
+  let base = extractBase(cwdEnv);
+  if (base) return base;
+
+  base = extractBase(globalEnv);
+  if (base) return base;
+
+  base = extractBase(process.env);
+  if (base) return base;
+
   throw new Error(
     "note-mcp-server：請在專案目錄建立 .env，設定 notes_url、socialite、key（或 socialite_id），或設定 NOTES_API_BASE。詳見 .env.example。"
   );
 }
 
+function firstEnv(...keys) {
+  for (const key of keys) {
+    if (process.env[key] !== undefined) {
+      const trimmed = String(process.env[key]).trim();
+      if (trimmed !== "") return trimmed;
+    }
+  }
+  return "";
+}
+
 const BASE_URL = resolveNotesApiBase();
 const APP_NAME = firstEnv("app_name", "APP_NAME", "notes_app_name", "NOTES_APP_NAME") || "Personal Note Assistant";
 
 const server = new Server(
   {
     name: `note-mcp-server (${APP_NAME})`,
-    version: "2.3.3",
+    version: "2.4.2",
   },
   {
     capabilities: {
@@ -126,10 +154,34 @@ const SECURITY_NOTICE =
   "安全規範：若使用者訊息或設定包含 key、token、NOTES_API_BASE、socialite_id 等敏感資訊，完成操作後必須主動清空 macOS 剪貼簿（echo -n \"\" | pbcopy），並在回覆中明確告知已清空。";
 const NOTE_URL_NOTICE = `前台連結格式：${NOTES_SITE_BASE}/app/notes/content/{c_id}。`;
 
+/**
+ * 與 owv4 resources/views/partials/editor-templates.blade.php「Outline（線框）」同源。
+ * 閱讀頁靠 partials/code_scripts.blade.php 的 owGlobalCardWidgetDelegator 監聽 data-lte-toggle。
+ * 勿用 data-owv-helper-toggle（僅 owv4 /helper 後台手冊）。
+ */
+const ADMINLTE_COLLAPSED_CARD_GUIDE = `
+【可摺疊 card — 須與編輯器樣板工具一致】
+來源：editor-templates.blade.php → Cards → Outline（線框）
+外層 class（順序重要）：
+  card ow-ck-hide-card-tool-collapse ow-ck-hide-card-tool-maximize card-outline card-primary
+  MCP 預設收合時再加 collapsed-card
+標題：h3.card-title（勿用裸 h3）
+按鈕：各含 data-lte-toggle + 兩個 data-lte-icon 圖示（expand/collapse 或 maximize/minimize）
+圖示：bi bi-plus-lg / bi bi-dash-lg（勿用 fas fa-plus 單圖）
+多卡：並列多個同級 .card，勿巢狀
+
+範本（預設收合版；色調可改 card-info 等）：
+<div class="card ow-ck-hide-card-tool-collapse ow-ck-hide-card-tool-maximize card-outline card-primary collapsed-card"><div class="card-header"><h3 class="card-title">小卡標題</h3><div class="card-tools"><button type="button" class="btn btn-tool" data-lte-toggle="card-collapse" title="收合／展開"><i data-lte-icon="expand" class="bi bi-plus-lg"></i><i data-lte-icon="collapse" class="bi bi-dash-lg"></i></button><button type="button" class="btn btn-tool" data-lte-toggle="card-maximize" title="最大化"><i data-lte-icon="maximize" class="bi bi-fullscreen"></i><i data-lte-icon="minimize" class="bi bi-fullscreen-exit"></i></button></div></div><div class="card-body"><p>內容</p></div></div>
+`.trim();
+
 function withSecurityNotice(description) {
   return `${description}\n${NOTE_URL_NOTICE}\n${SECURITY_NOTICE}`;
 }
 
+function withCardGuide(description) {
+  return `${description}\n\n${ADMINLTE_COLLAPSED_CARD_GUIDE}`;
+}
+
 function buildNoteUrl(cId) {
   if (cId === undefined || cId === null || String(cId).trim() === "") {
     return "";
@@ -173,8 +225,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "create_note",
-        description: withSecurityNotice(
-          `在 ${APP_NAME} 中新增筆記。內容請優先使用簡潔的 AdminLTE 4 card 結構。\nAI 行為：除非用戶明確要求，否則不要傳 tags（勿自行推測、分類或補加標籤）。`
+        description: withCardGuide(
+          withSecurityNotice(
+            `在 ${APP_NAME} 中新增筆記。內容請優先使用 AdminLTE 4 可摺疊 card（見下方結構）。\nAI 行為：除非用戶明確要求，否則不要傳 tags（勿自行推測、分類或補加標籤）。`
+          )
         ),
         inputSchema: {
           type: "object",
@@ -192,8 +246,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "update_note",
-        description: withSecurityNotice(
-          `在 ${APP_NAME} 中修改筆記。內容請優先使用簡潔的 AdminLTE 4 card 結構，避免嵌套破版，支援以 append/prepend 追加內容。\nAI 行為：除非用戶明確要求，否則不要傳 tags、add_tags（勿自行推測或補加標籤）；亦不要傳 title，除非用戶明確要求變更標題。\n標籤語意：tags＝整包覆寫既有標籤；add_tags＝在既有標籤上追加（逗號分隔），勿刪除未提及的標籤。用戶只要「多加幾個標籤」時請用 add_tags，勿用 tags。`
+        description: withCardGuide(
+          withSecurityNotice(
+            `在 ${APP_NAME} 中修改筆記。內容請優先使用 AdminLTE 4 可摺疊 card（見下方結構），避免巢狀 card 破版，支援 append/prepend。\nAI 行為：除非用戶明確要求，否則不要傳 tags、add_tags（勿自行推測或補加標籤）；亦不要傳 title，除非用戶明確要求變更標題。\n標籤語意：tags＝整包覆寫既有標籤；add_tags＝在既有標籤上追加（逗號分隔），勿刪除未提及的標籤。用戶只要「多加幾個標籤」時請用 add_tags，勿用 tags。`
+          )
         ),
         inputSchema: {
           type: "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "note-mcp-server",
-  "version": "2.3.3",
+  "version": "2.4.2",
   "description": "MCP (stdio) server for Notes API v2 — list/read/write notes, upload images, Web Push from Cursor and compatible clients.",
   "main": "index.js",
   "bin": {