note-mcp-server 1.0.0

package/.env.example

@@ -0,0 +1,11 @@
+# 筆記 API 基底（擇一方式設定）
+
+# 方式 A：拆開（推薦，與 Laravel Socialite 路徑一致）
+notes_url=https://notes.example.com
+socialite=github
+# 路徑上加密 token（與 key 擇一即可）
+key=
+# socialite_id=
+
+# 方式 B：整段 API base（若設定則優先於方式 A，勿結尾斜線）
+# NOTES_API_BASE=https://notes.example.com/api/notes/github/your-encrypted-token

package/README.md

@@ -0,0 +1,144 @@
+# note-mcp-server
+
+以 [Model Context Protocol](https://modelcontextprotocol.io/)（stdio）連接 **Notes API v2**，讓 Cursor 等客戶端透過工具列出／讀寫筆記、上傳圖片、發送 Web Push。
+
+---
+
+## 需求
+
+- Node.js **18+**
+- 已註冊之 Notes API（路徑形如：`{網站}/api/notes/{socialite}/{加密 token}`）
+
+---
+
+## 安裝
+
+```bash
+cd /path/to/note-mcp-server
+npm install
+```
+
+---
+
+## 設定 `.env`
+
+在 **`index.js` 同一目錄**建立 `.env`（本專案已將 `.env` 列入 `.gitignore`，請勿提交私密內容）。
+
+### 方式 A：拆開設定（建議）
+
+與 Laravel 端 **Socialite 提供者代號** 及 **加密後的路徑 token** 對齊，由程式組出完整 API base：
+
+| 變數 | 說明 |
+|------|------|
+| `notes_url` 或 `NOTES_URL` | 站台根網址，例如 `https://notes.example.com`（**不要**結尾斜線） |
+| `socialite` 或 `SOCIALITE` | 路徑中的提供者代號，例如 `github`（依你後端路由為準） |
+| `key` 或 `KEY` | 路徑最後一段的 **加密 token** |
+| `socialite_id` 或 `SOCIALITE_ID` | 與 **`key` 擇一即可**；語意相同，都是該段加密字串 |
+
+實際請求的 base 為：
+
+```text
+{notes_url}/api/notes/{socialite}/{key 或 socialite_id}
+```
+
+**範例：**
+
+```env
+notes_url=https://notes.example.com
+socialite=github
+key=eyJpdiI6I…（你的加密 token，整段貼上）
+```
+
+若你習慣用「加密 socialite id」命名，可改為：
+
+```env
+notes_url=https://notes.example.com
+socialite=github
+socialite_id=eyJpdiI6I…
+```
+
+### 方式 B：整段 API base（選用）
+
+若已持有完整 API URL（到 token 為止、**無結尾斜線**），可只設：
+
+| 變數 | 說明 |
+|------|------|
+| `NOTES_API_BASE` | 例如 `https://notes.example.com/api/notes/github/eyJ…` |
+
+**優先序：** 只要設了 `NOTES_API_BASE`，就會 **忽略** 方式 A 的 `notes_url` / `socialite` / `key`。
+
+---
+
+## 參考檔案
+
+- **`.env.example`**：不含密鑰的範本，可複製為 `.env` 再填入。
+- 啟動時會執行 `dotenv`，從 **`index.js` 所在目錄** 讀取 `.env`，與終端機目前工作目錄無關（方便 Cursor 從任意 cwd 啟動 MCP）。
+
+---
+
+## 在 Cursor 中掛載
+
+於 **使用者** 或 **專案** 的 `.cursor/mcp.json` 加入（路徑請改成你的本機路徑）：
+
+```json
+{
+  "mcpServers": {
+    "note-assistant": {
+      "command": "node",
+      "args": ["/path/to/note-mcp-server/index.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+- **不必**在 `mcp.json` 重複貼 token**：放在 `note-mcp-server` 目錄下的 `.env` 即可。
+- 若仍想由 Cursor 注入環境變數，可在 `env` 內設定 `NOTES_API_BASE` 或 `notes_url` / `socialite` / `key`（會覆寫／補齊系統環境；`.env` 仍會載入，順序依 `dotenv` 與既有 `process.env` 行為）。
+
+儲存後在 **Settings → Tools & MCPs** 確認 `note-assistant` 為啟用狀態；必要時 **Reload Window**。
+
+> **提示：** 在 Agent 對話裡，內部工具伺服器名稱可能顯示為 `user-note-assistant`（`user-` 前綴），與設定裡的顯示名稱不同屬正常現象。
+
+---
+
+## 提供的 MCP 工具
+
+| 工具 | 說明 |
+|------|------|
+| `list_notes` | GET 列表，可選 `limit`（預設 3） |
+| `read_note` | GET 單筆，`c_id` |
+| `create_note` | POST 新增，`content` 必填，`title` 可選 |
+| `update_note` | POST 修改，`c_id`、`content` 必填，`title` 可選 |
+| `delete_note` | POST 刪除，`c_id` + `action=delete` |
+| `upload_image` | multipart，`image_base64`、可選 `filename` |
+| `send_push` | POST 推播，`message` 必填，`title` / `url` 可選 |
+
+完整 REST 行為請對你的 API 網址加上 **`/help`** 查官方說明。
+
+---
+
+## 常見問題
+
+### 啟動失敗、訊息請建立 `.env`
+
+代表未滿足任一組條件：請設 **`NOTES_API_BASE`**，或同時設 **`notes_url` + `socialite` +（`key` 或 `socialite_id`）**。
+
+### 不要用終端機手動當 MCP 用
+
+MCP 須由 **Cursor 子程序** 以 **stdio** 啟動；在終端機長駐執行 `node index.js` **不會**自動掛進 Cursor。
+
+### 手動除錯（可選）
+
+僅供本機檢查流程，**不是**正式掛載 MCP：
+
+```bash
+node /path/to/note-mcp-server/index.js
+```
+
+程序會卡在 stdio 等待，除錯完請 Ctrl+C 結束。
+
+---
+
+## 授權
+
+ISC（見 `package.json`）。

package/index.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { config as loadEnv } from "dotenv";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import axios from "axios";
+import FormData from "form-data";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+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）
+ *
+ * 變數名支援常見大小寫（見 resolveNotesApiBase）。
+ */
+
+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;
+    }
+  }
+  return "";
+}
+
+function resolveNotesApiBase() {
+  const direct = firstEnv("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"
+  );
+
+  if (notesUrl && socialite && encryptedToken) {
+    return `${notesUrl}/api/notes/${socialite}/${encryptedToken}`;
+  }
+
+  throw new Error(
+    "note-mcp-server：請在專案目錄建立 .env，設定 notes_url、socialite、key（或 socialite_id），或設定 NOTES_API_BASE。詳見 .env.example。"
+  );
+}
+
+const BASE_URL = resolveNotesApiBase();
+
+const server = new Server(
+  {
+    name: "note-mcp-server",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+function formatAxiosError(err) {
+  if (axios.isAxiosError(err) && err.response?.data !== undefined) {
+    const body =
+      typeof err.response.data === "string"
+        ? err.response.data
+        : JSON.stringify(err.response.data);
+    return `${err.message} | 回應: ${body}`;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
+
+function normalizeListPayload(data) {
+  if (Array.isArray(data)) {
+    return data;
+  }
+  if (data && Array.isArray(data.notes)) {
+    return data.notes;
+  }
+  if (data && Array.isArray(data.data)) {
+    return data.data;
+  }
+  return [];
+}
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "list_notes",
+        description: "列出筆記（GET 列表），可依 limit 截斷前 N 筆。",
+        inputSchema: {
+          type: "object",
+          properties: {
+            limit: {
+              type: "number",
+              description: "最多回傳幾筆（預設 3）",
+              default: 3,
+            },
+          },
+        },
+      },
+      {
+        name: "read_note",
+        description: "讀取單筆筆記（GET ?c_id=）。",
+        inputSchema: {
+          type: "object",
+          properties: {
+            c_id: {
+              type: "number",
+              description: "筆記 ID（c_id）",
+            },
+          },
+          required: ["c_id"],
+        },
+      },
+      {
+        name: "create_note",
+        description:
+          "新增筆記（POST：title、content；title 可省略由 API 自動產生）。內容建議符合 AdminLTE 4 / PrismJS 約定。",
+        inputSchema: {
+          type: "object",
+          properties: {
+            content: { type: "string", description: "HTML 或純文字內容" },
+            title: { type: "string", description: "標題（可選）" },
+          },
+          required: ["content"],
+        },
+      },
+      {
+        name: "update_note",
+        description: "修改筆記（POST：c_id、title、content）。",
+        inputSchema: {
+          type: "object",
+          properties: {
+            c_id: { type: "number", description: "筆記 ID" },
+            content: { type: "string", description: "新內容" },
+            title: { type: "string", description: "新標題（可選）" },
+          },
+          required: ["c_id", "content"],
+        },
+      },
+      {
+        name: "delete_note",
+        description: "刪除筆記（POST：c_id + action=delete）。",
+        inputSchema: {
+          type: "object",
+          properties: {
+            c_id: { type: "number", description: "要刪除的筆記 ID" },
+          },
+          required: ["c_id"],
+        },
+      },
+      {
+        name: "upload_image",
+        description:
+          "上傳圖片（multipart：action=upload_image、image=檔案）。請傳 image_base64 與可選 filename。",
+        inputSchema: {
+          type: "object",
+          properties: {
+            image_base64: {
+              type: "string",
+              description: "圖檔 Base64（可含 data:image/...;base64, 前綴）",
+            },
+            filename: {
+              type: "string",
+              description: "檔名，例如 note.png（預設 upload.bin）",
+            },
+          },
+          required: ["image_base64"],
+        },
+      },
+      {
+        name: "send_push",
+        description: "發送 Web Push（POST：action=push、message；可選 title、url）。",
+        inputSchema: {
+          type: "object",
+          properties: {
+            message: { type: "string", description: "推播主文" },
+            title: { type: "string", description: "推播標題（可選）" },
+            url: { type: "string", description: "點擊後開啟的網址（可選）" },
+          },
+          required: ["message"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: rawArgs } = request.params;
+  const args = rawArgs ?? {};
+
+  try {
+    switch (name) {
+      case "list_notes": {
+        const limit = Number(args.limit) > 0 ? Number(args.limit) : 3;
+        const response = await axios.get(BASE_URL);
+        const list = normalizeListPayload(response.data).slice(0, limit);
+        return {
+          content: [{ type: "text", text: JSON.stringify(list, null, 2) }],
+        };
+      }
+
+      case "read_note": {
+        const cId = Number(args.c_id);
+        const response = await axios.get(BASE_URL, {
+          params: { c_id: cId },
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(response.data, null, 2) }],
+        };
+      }
+
+      case "create_note": {
+        const payload = { content: args.content };
+        if (args.title !== undefined && args.title !== "") {
+          payload.title = args.title;
+        }
+        const response = await axios.post(BASE_URL, payload, {
+          headers: { "Content-Type": "application/json" },
+        });
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(response.data, null, 2) },
+          ],
+        };
+      }
+
+      case "update_note": {
+        const payload = {
+          c_id: Number(args.c_id),
+          content: args.content,
+        };
+        if (args.title !== undefined) {
+          payload.title = args.title;
+        }
+        const response = await axios.post(BASE_URL, payload, {
+          headers: { "Content-Type": "application/json" },
+        });
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(response.data, null, 2) },
+          ],
+        };
+      }
+
+      case "delete_note": {
+        const response = await axios.post(
+          BASE_URL,
+          { c_id: Number(args.c_id), action: "delete" },
+          { headers: { "Content-Type": "application/json" } }
+        );
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(response.data, null, 2) },
+          ],
+        };
+      }
+
+      case "upload_image": {
+        let b64 = String(args.image_base64).replace(/\s/g, "");
+        const dataUrl = /^data:[^;]+;base64,(.+)$/i.exec(b64);
+        if (dataUrl) {
+          b64 = dataUrl[1];
+        }
+        const buffer = Buffer.from(b64, "base64");
+        const form = new FormData();
+        form.append("action", "upload_image");
+        form.append("image", buffer, {
+          filename: args.filename || "upload.png",
+        });
+        const response = await axios.post(BASE_URL, form, {
+          headers: form.getHeaders(),
+          maxBodyLength: Infinity,
+          maxContentLength: Infinity,
+        });
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(response.data, null, 2) },
+          ],
+        };
+      }
+
+      case "send_push": {
+        const body = { action: "push", message: args.message };
+        if (args.title !== undefined) {
+          body.title = args.title;
+        }
+        if (args.url !== undefined) {
+          body.url = args.url;
+        }
+        const response = await axios.post(BASE_URL, body, {
+          headers: { "Content-Type": "application/json" },
+        });
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(response.data, null, 2) },
+          ],
+        };
+      }
+
+      default:
+        throw new Error(`未知工具: ${name}`);
+    }
+  } catch (error) {
+    return {
+      isError: true,
+      content: [{ type: "text", text: `API 錯誤: ${formatAxiosError(error)}` }],
+    };
+  }
+});
+
+async function runServer() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(
+    `Personal Note Assistant MCP on stdio (base: ${BASE_URL.replace(/\/[^/]+$/, "/…")})`
+  );
+}
+
+runServer().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "note-mcp-server",
+  "version": "1.0.0",
+  "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": {
+    "note-mcp-server": "index.js"
+  },
+  "files": [
+    "index.js",
+    ".env.example",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "node --check index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "notes",
+    "cursor",
+    "stdio"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.16.0",
+    "dotenv": "^16.4.5",
+    "form-data": "^4.0.0"
+  }
+}