note-mcp 1.1.0 → 1.1.2

package/README.md

@@ -5,16 +5,62 @@ Unofficial stdio MCP server for note.com. It uses cookie-based access to note.co
 > [!WARNING]
 > This project is unofficial and not affiliated with note.com. Internal APIs can change without notice. Keep cookies local and never commit them to GitHub, npm, logs, or issue reports.
 
-## Install / run
+## Quick start
+
+### Local/desktop agents
+
+Use browser login first:
 
 ```bash
-npx note-mcp
+npx note-mcp auth
+```
+
+After you log in to note.com in the opened browser, `note-mcp` saves the cookie locally and prints the saved file path:
+
+```json
+{
+  "authenticated": true,
+  "saved": true,
+  "configPath": "/Users/you/.config/note-mcp/config.json",
+  "cookiePreview": "fp=b…5948",
+  "message": "note.com authentication configured from browser login. Cookie saved to /Users/you/.config/note-mcp/config.json."
+}
+```
+
+Then configure your MCP client without putting cookies in the config:
+
+```json
+{
+  "mcpServers": {
+    "note": {
+      "command": "npx",
+      "args": ["-y", "note-mcp"]
+    }
+  }
+}
+```
+
+### Servers, containers, and CI
+
+Do not rely on browser login in headless/container environments. Provide a cookie through env or a mounted config file instead:
+
+```bash
+NOTE_COOKIE='your note.com Cookie header' npx note-mcp
 ```
 
-For advanced/server setups, you can still provide a Cookie header through the environment:
+Or mount a config file and point `NOTE_MCP_CONFIG` at it:
 
 ```bash
-NOTE_COOKIE='your note.com cookie string' npx note-mcp
+docker run \
+  -v ~/.config/note-mcp/config.json:/run/secrets/note-mcp-config.json:ro \
+  -e NOTE_MCP_CONFIG=/run/secrets/note-mcp-config.json \
+  your-agent-image
+```
+
+## Install / run
+
+```bash
+npx note-mcp
 ```
 
 For local development:
@@ -27,7 +73,7 @@ node dist/index.js
 
 ## MCP client configuration
 
-Desktop/local browser-login friendly setup:
+Recommended desktop setup after `npx note-mcp auth`:
 
 ```json
 {
@@ -49,7 +95,7 @@ Advanced env-based setup:
       "command": "npx",
       "args": ["-y", "note-mcp"],
       "env": {
-        "NOTE_COOKIE": "your note.com cookie string"
+        "NOTE_COOKIE": "your note.com Cookie header"
       }
     }
   }
@@ -78,7 +124,21 @@ This opens a browser, lets you log in to note.com normally, then stores note.com
 ~/.config/note-mcp/config.json
 ```
 
-The config file is written with `0600` permissions where supported.
+The CLI and MCP tool response include the actual `configPath` used.
+
+If the browser executable is not installed yet, install Playwright's Chromium once on the same machine/user account, then retry:
+
+```bash
+npx playwright install chromium
+```
+
+When using `note-mcp` only through `npx` and Playwright is not otherwise installed globally/in the project, this form is often more reliable:
+
+```bash
+npx -p playwright playwright install chromium
+```
+
+For remote servers, containers, or CI, prefer the secret/env/config-file path below instead of browser login.
 
 Useful CLI commands:
 
@@ -91,7 +151,7 @@ npx note-mcp auth --headed
 
 ### 2. Advanced/server/CI: secret, env, or config file
 
-For remote agents, servers, CI, and secret managers, provide a Cookie header via:
+For remote agents, servers, containers, CI, and secret managers, provide a Cookie header via:
 
 - `NOTE_COOKIE`
 - `NOTE_SESSION_COOKIE`
@@ -113,12 +173,24 @@ Cookie lookup priority:
 2. `NOTE_SESSION_COOKIE`
 3. config file cookie
 
+Default config path:
+
+```text
+~/.config/note-mcp/config.json
+```
+
+Override config path:
+
+```bash
+NOTE_MCP_CONFIG=/path/to/config.json npx note-mcp
+```
+
 ## Tools
 
 Authentication/setup tools:
 
-- `note_auth_status` — inspect whether auth is configured
-- `note_auth_login` — open a browser login flow and save cookies locally
+- `note_auth_status` — inspect whether auth is configured and which config path is used
+- `note_auth_login` — open a browser login flow and save cookies locally; response includes `configPath`
 - `note_set_cookie` — save a Cookie header to the local config file, optionally verifying it first
 - `note_clear_cookie` — delete the stored config-file cookie
 - `note_login_help` — explain supported setup paths

package/dist/index.js

@@ -203,7 +203,12 @@ async function runBrowserLogin(options = {}) {
   const timeoutMs = options.timeoutMs ?? 18e4;
   const headless = options.headless ?? process.env.NOTE_MCP_HEADLESS === "true";
   const { chromium } = await importPlaywright();
-  const browser = await chromium.launch({ headless });
+  let browser;
+  try {
+    browser = await chromium.launch({ headless });
+  } catch (error) {
+    throw toBrowserLoginError(error);
+  }
   try {
     const context = await browser.newContext();
     const page = await context.newPage();
@@ -217,15 +222,9 @@ async function runBrowserLogin(options = {}) {
       const client = new NoteClient({ cookie });
       try {
         await client.authCheck();
-        if (options.save ?? true) {
-          await saveCookie(cookie);
-        }
-        return {
-          authenticated: true,
-          saved: options.save ?? true,
-          cookiePreview: previewCookie2(cookie),
-          message: "note.com authentication configured from browser login."
-        };
+        const shouldSave = options.save ?? true;
+        const saveStatus = shouldSave ? await saveCookie(cookie) : void 0;
+        return buildBrowserLoginResult(cookie, shouldSave, saveStatus);
       } catch {
       }
     }
@@ -245,6 +244,32 @@ async function importPlaywright() {
     );
   }
 }
+function buildBrowserLoginResult(cookie, saved, saveStatus) {
+  const configPath = saveStatus?.configPath;
+  return {
+    authenticated: true,
+    saved,
+    ...configPath ? { configPath } : {},
+    cookiePreview: saveStatus?.cookiePreview ?? previewCookie2(cookie),
+    message: configPath ? `note.com authentication configured from browser login. Cookie saved to ${configPath}.` : "note.com authentication configured from browser login."
+  };
+}
+function toBrowserLoginError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.includes("Executable doesn't exist") || message.includes("Please run the following command to download new browsers") || message.includes("playwright install")) {
+    return new Error(
+      [
+        "Playwright browser is not installed, so note-mcp cannot open the note.com browser login flow.",
+        "Run this once on the same machine/user account, then retry:",
+        "  npx playwright install chromium",
+        "If you are running note-mcp through npx and Playwright is not otherwise installed, use:",
+        "  npx -p playwright playwright install chromium",
+        "For remote servers, containers, or CI, prefer NOTE_COOKIE / NOTE_SESSION_COOKIE or NOTE_MCP_CONFIG instead of browser login."
+      ].join("\n")
+    );
+  }
+  return error instanceof Error ? error : new Error(message);
+}
 function isNoteDomain(domain) {
   const normalized = domain.replace(/^\./, "").toLowerCase();
   return normalized === "note.com" || normalized.endsWith(".note.com");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "note-mcp",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Unofficial stdio MCP server for note.com using cookie-based internal APIs.",
   "type": "module",
   "bin": {