note-mcp 1.0.0 → 1.1.0

package/README.md

@@ -7,6 +7,12 @@ Unofficial stdio MCP server for note.com. It uses cookie-based access to note.co
 
 ## Install / run
 
+```bash
+npx note-mcp
+```
+
+For advanced/server setups, you can still provide a Cookie header through the environment:
+
 ```bash
 NOTE_COOKIE='your note.com cookie string' npx note-mcp
 ```
@@ -16,12 +22,25 @@ For local development:
 ```bash
 npm install
 npm run build
-NOTE_COOKIE='your note.com cookie string' node dist/index.js
+node dist/index.js
 ```
 
 ## MCP client configuration
 
-Example:
+Desktop/local browser-login friendly setup:
+
+```json
+{
+  "mcpServers": {
+    "note": {
+      "command": "npx",
+      "args": ["-y", "note-mcp"]
+    }
+  }
+}
+```
+
+Advanced env-based setup:
 
 ```json
 {
@@ -37,15 +56,84 @@ Example:
 }
 ```
 
+## Authentication
+
+`note-mcp` supports two authentication paths.
+
+### 1. Local/desktop: browser login
+
+For local desktop agents, ask the agent to call:
+
+- `note_auth_login`
+
+Or run it directly:
+
+```bash
+npx note-mcp auth
+```
+
+This opens a browser, lets you log in to note.com normally, then stores note.com cookies in:
+
+```text
+~/.config/note-mcp/config.json
+```
+
+The config file is written with `0600` permissions where supported.
+
+Useful CLI commands:
+
+```bash
+npx note-mcp auth --status
+npx note-mcp auth --clear
+npx note-mcp auth --headless
+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:
+
+- `NOTE_COOKIE`
+- `NOTE_SESSION_COOKIE`
+- `NOTE_MCP_CONFIG` pointing to a config JSON file
+- MCP tool `note_set_cookie`
+
+Example config file:
+
+```json
+{
+  "cookie": "your note.com Cookie header",
+  "updatedAt": "2026-06-21T00:00:00.000Z"
+}
+```
+
+Cookie lookup priority:
+
+1. `NOTE_COOKIE`
+2. `NOTE_SESSION_COOKIE`
+3. config file cookie
+
 ## Tools
 
-- `note_auth_check` — verify cookie-based access to note.com internal APIs
+Authentication/setup tools:
+
+- `note_auth_status` — inspect whether auth is configured
+- `note_auth_login` — open a browser login flow and save cookies locally
+- `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
+
+note.com tools:
+
+- `note_auth_check` — verify configured cookie-based access to note.com internal APIs
 - `note_list_my_notes` — list notes for the authenticated account
 - `note_list_drafts` — list drafts for the authenticated account
 - `note_get_note` — fetch a note by note key, e.g. `n1a0b26f944f4`
 - `note_create_draft` — create a draft
 - `note_update_draft` — update a draft by draft id
 
+If authentication is missing, note tools return an `auth_required` error suggesting `note_auth_login` or `note_set_cookie`.
+
 ## API basis
 
 The initial endpoints are based on public, unofficial note API references, including:
@@ -60,15 +148,6 @@ Known endpoint basis:
 - Draft save: `POST /v1/text_notes/draft_save?id={draftId}`
 - Auth smoke test: `GET /v3/notice_counts`
 
-## Authentication
-
-Set one of these environment variables before launching the server:
-
-- `NOTE_COOKIE`
-- `NOTE_SESSION_COOKIE`
-
-Use the full Cookie header value from an authenticated browser session.
-
 ## Release
 
 Releases are handled by GitHub Actions + semantic-release.

package/dist/index.js

@@ -6,15 +6,98 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 
 // src/note/auth.ts
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import { homedir } from "os";
 var COOKIE_ENV_KEYS = ["NOTE_COOKIE", "NOTE_SESSION_COOKIE"];
-function readCookieFromEnv(env = process.env) {
+var CONFIG_ENV_KEY = "NOTE_MCP_CONFIG";
+var AuthRequiredError = class extends Error {
+  constructor(message = "note.com authentication is not configured.") {
+    super(message);
+    this.name = "AuthRequiredError";
+  }
+};
+async function readCookie(options = {}) {
+  const envCookie = readCookieFromEnvValue(options.env ?? process.env);
+  if (envCookie) return envCookie;
+  const storedCookie = await readCookieFromConfig(options);
+  if (storedCookie) return storedCookie;
+  throw new AuthRequiredError();
+}
+async function authStatus(options = {}) {
+  const env = options.env ?? process.env;
+  const envCookie = readCookieFromEnvValue(env);
+  const configPath = resolveConfigPath(options);
+  if (envCookie) {
+    return {
+      configured: true,
+      source: "env",
+      configPath,
+      cookiePreview: previewCookie(envCookie),
+      message: "note.com cookie is configured from environment variables."
+    };
+  }
+  const configCookie = await readCookieFromConfig(options);
+  if (configCookie) {
+    return {
+      configured: true,
+      source: "config",
+      configPath,
+      cookiePreview: previewCookie(configCookie),
+      message: "note.com cookie is configured from note-mcp config file."
+    };
+  }
+  return {
+    configured: false,
+    source: "none",
+    configPath,
+    message: "note.com cookie is not configured. Use note_auth_login for browser login or note_set_cookie / NOTE_COOKIE for advanced setups.",
+    suggestedTools: ["note_auth_login", "note_set_cookie"]
+  };
+}
+async function saveCookie(cookie, options = {}) {
+  const trimmed = cookie.trim();
+  if (!trimmed) throw new Error("Cookie must not be empty.");
+  const configPath = resolveConfigPath(options);
+  await mkdir(dirname(configPath), { recursive: true });
+  const config = {
+    cookie: trimmed,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+  return authStatus({ ...options, env: {} });
+}
+async function clearStoredCookie(options = {}) {
+  await rm(resolveConfigPath(options), { force: true });
+  return authStatus({ ...options, env: {} });
+}
+function resolveConfigPath(options = {}) {
+  const env = options.env ?? process.env;
+  return options.configPath ?? env[CONFIG_ENV_KEY] ?? join(homedir(), ".config", "note-mcp", "config.json");
+}
+function readCookieFromEnvValue(env) {
   for (const key of COOKIE_ENV_KEYS) {
     const value = env[key];
     if (value?.trim()) return value.trim();
   }
-  throw new Error(
-    `Missing note.com cookie. Set ${COOKIE_ENV_KEYS.join(" or ")} before starting note-mcp.`
-  );
+  return null;
+}
+async function readCookieFromConfig(options) {
+  try {
+    const raw = await readFile(resolveConfigPath(options), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed.cookie?.trim() || null;
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+function previewCookie(cookie) {
+  if (cookie.length <= 8) return "********";
+  return `${cookie.slice(0, 4)}\u2026${cookie.slice(-4)}`;
 }
 
 // src/note/errors.ts
@@ -108,13 +191,266 @@ async function parseBody(response) {
   }
 }
 
+// src/note/browser-login.ts
+function cookiesToHeader(cookies) {
+  const noteCookies = cookies.filter((cookie) => isNoteDomain(cookie.domain));
+  if (noteCookies.length === 0) {
+    throw new Error("No note.com cookies were found in the browser session.");
+  }
+  return noteCookies.map((cookie) => `${cookie.name}=${cookie.value}`).join("; ");
+}
+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 });
+  try {
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    await page.goto("https://note.com/login", { waitUntil: "domcontentloaded" });
+    const deadline = Date.now() + timeoutMs;
+    let lastCookie = "";
+    while (Date.now() < deadline) {
+      await page.waitForTimeout(2e3);
+      const cookie = cookiesToHeader(await context.cookies("https://note.com"));
+      lastCookie = cookie;
+      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."
+        };
+      } catch {
+      }
+    }
+    throw new Error(
+      lastCookie ? "Timed out waiting for note.com authentication to become valid." : "Timed out waiting for note.com login cookies."
+    );
+  } finally {
+    await browser.close();
+  }
+}
+async function importPlaywright() {
+  try {
+    return await import("playwright");
+  } catch (error) {
+    throw new Error(
+      `Browser login requires the optional "playwright" package and a usable desktop browser environment. Original error: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+function isNoteDomain(domain) {
+  const normalized = domain.replace(/^\./, "").toLowerCase();
+  return normalized === "note.com" || normalized.endsWith(".note.com");
+}
+function previewCookie2(cookie) {
+  if (cookie.length <= 8) return "********";
+  return `${cookie.slice(0, 4)}\u2026${cookie.slice(-4)}`;
+}
+
 // src/index.ts
-var server = new McpServer({
-  name: "note-mcp",
-  version: "0.0.0-development"
-});
-function createClient() {
-  return new NoteClient({ cookie: readCookieFromEnv() });
+if (process.argv[2] === "auth") {
+  await runAuthCli(process.argv.slice(3));
+} else {
+  await runMcpServer();
+}
+async function runAuthCli(args) {
+  try {
+    if (args.includes("--status")) {
+      console.log(jsonText(await authStatus()));
+      return;
+    }
+    if (args.includes("--clear")) {
+      console.log(jsonText(await clearStoredCookie()));
+      return;
+    }
+    const headless = args.includes("--headless") ? true : args.includes("--headed") ? false : void 0;
+    console.error("Opening note.com login in a browser. Complete login there; note-mcp will save cookies locally.");
+    console.log(jsonText(await runBrowserLogin(headless === void 0 ? {} : { headless })));
+  } catch (error) {
+    console.error(jsonText(errorDetail(error)));
+    process.exitCode = 1;
+  }
+}
+async function runMcpServer() {
+  const server = new McpServer({
+    name: "note-mcp",
+    version: "1.1.0-development"
+  });
+  server.registerTool(
+    "note_auth_status",
+    {
+      title: "Get note.com authentication status",
+      description: "Checks whether note-mcp has a note.com cookie from env or config file.",
+      inputSchema: {}
+    },
+    async () => result(await authStatus())
+  );
+  server.registerTool(
+    "note_auth_login",
+    {
+      title: "Log in to note.com with a browser",
+      description: "Opens a local Playwright browser login flow and saves note.com cookies to the note-mcp config file. Intended for desktop/local agents; remote/headless servers should use env or note_set_cookie.",
+      inputSchema: {
+        headless: z.boolean().optional()
+      }
+    },
+    async ({ headless }) => {
+      try {
+        return result(await runBrowserLogin({ ...headless === void 0 ? {} : { headless } }));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "note_set_cookie",
+    {
+      title: "Set note.com cookie",
+      description: "Stores a note.com Cookie header in the local note-mcp config file. By default, verifies the cookie before saving.",
+      inputSchema: {
+        cookie: z.string().min(1),
+        verify: z.boolean().default(true)
+      }
+    },
+    async ({ cookie, verify }) => {
+      try {
+        if (verify) {
+          await new NoteClient({ cookie }).authCheck();
+        }
+        return result(await saveCookie(cookie));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "note_clear_cookie",
+    {
+      title: "Clear stored note.com cookie",
+      description: "Deletes the note-mcp config file cookie. Environment cookies are not modified.",
+      inputSchema: {}
+    },
+    async () => {
+      try {
+        return result(await clearStoredCookie());
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "note_login_help",
+    {
+      title: "Get note-mcp login help",
+      description: "Explains the supported note-mcp authentication setup paths.",
+      inputSchema: {}
+    },
+    async () => result({
+      recommended: "For local/desktop agents, call note_auth_login to open a browser login flow.",
+      advanced: "For servers/CI, provide NOTE_COOKIE / NOTE_SESSION_COOKIE or call note_set_cookie with a Cookie header obtained by a trusted operator.",
+      configFile: (await authStatus()).configPath,
+      cli: ["npx note-mcp auth", "npx note-mcp auth --status", "npx note-mcp auth --clear"]
+    })
+  );
+  server.registerTool(
+    "note_auth_check",
+    {
+      title: "Check note.com authentication",
+      description: "Checks whether configured note.com cookies can access note.com internal APIs.",
+      inputSchema: {}
+    },
+    async () => withClient((client) => client.authCheck())
+  );
+  server.registerTool(
+    "note_list_my_notes",
+    {
+      title: "List my note.com notes",
+      description: "Lists notes for the authenticated note.com account.",
+      inputSchema: {
+        page: z.number().int().positive().default(1)
+      }
+    },
+    async ({ page }) => withClient((client) => client.listMyNotes(page))
+  );
+  server.registerTool(
+    "note_list_drafts",
+    {
+      title: "List note.com drafts",
+      description: "Lists drafts for the authenticated note.com account. This uses an unofficial internal API and may need adjustment if note.com changes endpoints.",
+      inputSchema: {
+        page: z.number().int().positive().default(1)
+      }
+    },
+    async ({ page }) => withClient((client) => client.listDrafts(page))
+  );
+  server.registerTool(
+    "note_get_note",
+    {
+      title: "Get note.com note",
+      description: "Fetches a note by note key, e.g. n1a0b26f944f4.",
+      inputSchema: {
+        noteKey: z.string().min(1)
+      }
+    },
+    async ({ noteKey }) => withClient((client) => client.getNote(noteKey))
+  );
+  server.registerTool(
+    "note_create_draft",
+    {
+      title: "Create note.com draft",
+      description: "Creates a note.com draft with title/body/hashtags using an unofficial internal API.",
+      inputSchema: {
+        title: z.string().min(1),
+        body: z.string().min(1),
+        hashtags: z.array(z.string().min(1)).optional()
+      }
+    },
+    async ({ title, body, hashtags }) => withClient(
+      (client) => client.createDraft({
+        title,
+        body,
+        ...hashtags ? { hashtags } : {}
+      })
+    )
+  );
+  server.registerTool(
+    "note_update_draft",
+    {
+      title: "Update note.com draft",
+      description: "Updates a note.com draft by draft id using an unofficial internal API.",
+      inputSchema: {
+        draftId: z.string().min(1),
+        title: z.string().min(1),
+        body: z.string().min(1),
+        hashtags: z.array(z.string().min(1)).optional()
+      }
+    },
+    async ({ draftId, title, body, hashtags }) => withClient(
+      (client) => client.updateDraft({
+        draftId,
+        title,
+        body,
+        ...hashtags ? { hashtags } : {}
+      })
+    )
+  );
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+async function withClient(fn) {
+  try {
+    const client = new NoteClient({ cookie: await readCookie() });
+    return result(await fn(client));
+  } catch (error) {
+    return errorResult(error);
+  }
 }
 function jsonText(value) {
   return JSON.stringify(value, null, 2);
@@ -130,134 +466,31 @@ function result(value) {
   };
 }
 function errorResult(error) {
-  const detail = error instanceof NoteApiError ? { message: error.message, status: error.status, body: error.body } : { message: toErrorMessage(error) };
   return {
     isError: true,
     content: [
       {
         type: "text",
-        text: jsonText(detail)
+        text: jsonText(errorDetail(error))
       }
     ]
   };
 }
-server.registerTool(
-  "note_auth_check",
-  {
-    title: "Check note.com authentication",
-    description: "Checks whether NOTE_COOKIE / NOTE_SESSION_COOKIE can access note.com internal APIs.",
-    inputSchema: {}
-  },
-  async () => {
-    try {
-      return result(await createClient().authCheck());
-    } catch (error) {
-      return errorResult(error);
-    }
+function errorDetail(error) {
+  if (error instanceof AuthRequiredError) {
+    return {
+      error: "auth_required",
+      message: error.message,
+      suggestedTools: ["note_auth_login", "note_set_cookie"]
+    };
   }
-);
-server.registerTool(
-  "note_list_my_notes",
-  {
-    title: "List my note.com notes",
-    description: "Lists notes for the authenticated note.com account.",
-    inputSchema: {
-      page: z.number().int().positive().default(1)
-    }
-  },
-  async ({ page }) => {
-    try {
-      return result(await createClient().listMyNotes(page));
-    } catch (error) {
-      return errorResult(error);
-    }
+  if (error instanceof NoteApiError) {
+    return {
+      error: "note_api_error",
+      message: error.message,
+      status: error.status,
+      body: error.body
+    };
   }
-);
-server.registerTool(
-  "note_list_drafts",
-  {
-    title: "List note.com drafts",
-    description: "Lists drafts for the authenticated note.com account. This uses an unofficial internal API and may need adjustment if note.com changes endpoints.",
-    inputSchema: {
-      page: z.number().int().positive().default(1)
-    }
-  },
-  async ({ page }) => {
-    try {
-      return result(await createClient().listDrafts(page));
-    } catch (error) {
-      return errorResult(error);
-    }
-  }
-);
-server.registerTool(
-  "note_get_note",
-  {
-    title: "Get note.com note",
-    description: "Fetches a note by note key, e.g. n1a0b26f944f4.",
-    inputSchema: {
-      noteKey: z.string().min(1)
-    }
-  },
-  async ({ noteKey }) => {
-    try {
-      return result(await createClient().getNote(noteKey));
-    } catch (error) {
-      return errorResult(error);
-    }
-  }
-);
-server.registerTool(
-  "note_create_draft",
-  {
-    title: "Create note.com draft",
-    description: "Creates a note.com draft with title/body/hashtags using an unofficial internal API.",
-    inputSchema: {
-      title: z.string().min(1),
-      body: z.string().min(1),
-      hashtags: z.array(z.string().min(1)).optional()
-    }
-  },
-  async ({ title, body, hashtags }) => {
-    try {
-      return result(
-        await createClient().createDraft({
-          title,
-          body,
-          ...hashtags ? { hashtags } : {}
-        })
-      );
-    } catch (error) {
-      return errorResult(error);
-    }
-  }
-);
-server.registerTool(
-  "note_update_draft",
-  {
-    title: "Update note.com draft",
-    description: "Updates a note.com draft by draft id using an unofficial internal API.",
-    inputSchema: {
-      draftId: z.string().min(1),
-      title: z.string().min(1),
-      body: z.string().min(1),
-      hashtags: z.array(z.string().min(1)).optional()
-    }
-  },
-  async ({ draftId, title, body, hashtags }) => {
-    try {
-      return result(
-        await createClient().updateDraft({
-          draftId,
-          title,
-          body,
-          ...hashtags ? { hashtags } : {}
-        })
-      );
-    } catch (error) {
-      return errorResult(error);
-    }
-  }
-);
-var transport = new StdioServerTransport();
-await server.connect(transport);
+  return { error: "error", message: toErrorMessage(error) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "note-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Unofficial stdio MCP server for note.com using cookie-based internal APIs.",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsup src/index.ts --format esm --dts --clean --external playwright",
     "dev": "tsx src/index.ts",
     "lint": "eslint .",
     "format": "prettier --check .",
@@ -61,5 +61,8 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.61.1",
     "vitest": "^4.1.9"
+  },
+  "optionalDependencies": {
+    "playwright": "^1.61.0"
   }
 }