note-mcp-server 2.3.2 → 2.4.1

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

@@ -14,8 +14,10 @@ import FormData from "form-data";
 
 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」。
  *
@@ -76,7 +78,7 @@ const APP_NAME = firstEnv("app_name", "APP_NAME", "notes_app_name", "NOTES_APP_N
 const server = new Server(
   {
     name: `note-mcp-server (${APP_NAME})`,
-    version: "2.3.0",
+    version: "2.4.1",
   },
   {
     capabilities: {
@@ -124,10 +126,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 "";
@@ -171,8 +197,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",
@@ -190,8 +218,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.2",
+  "version": "2.4.1",
   "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": {