note-mcp 1.1.1 → 1.2.0

package/README.md

@@ -5,16 +5,72 @@ 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
 ```
 
-For advanced/server setups, you can still provide a Cookie header through the environment:
+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"]
+    }
+  }
+}
+```
+
+Some MCP clients only load newly added tools when a process or conversation starts. After authentication or config changes, restart the client or open a new thread/session if `note_*` tools do not appear immediately.
+
+Quick setup check:
+
+1. `npx note-mcp auth`
+2. `npx note-mcp auth --status`
+3. Add `npx -y note-mcp` to your MCP client config
+4. Restart the client or open a new thread/session
+5. Run `note_auth_status` from the MCP client
+
+### 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 string' npx note-mcp
+NOTE_COOKIE='your note.com Cookie header' npx note-mcp
+```
+
+Or mount a config file and point `NOTE_MCP_CONFIG` at it:
+
+```bash
+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 +83,7 @@ node dist/index.js
 
 ## MCP client configuration
 
-Desktop/local browser-login friendly setup:
+Recommended desktop setup after `npx note-mcp auth`:
 
 ```json
 {
@@ -49,13 +105,33 @@ 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"
       }
     }
   }
 }
 ```
 
+### Codex CLI
+
+For Codex, add `note-mcp` as a stdio MCP server with `npx`:
+
+```bash
+codex mcp add note -- npx -y note-mcp
+codex mcp list
+npx -y note-mcp auth --status
+```
+
+Recommended verification flow:
+
+1. `npx note-mcp auth`
+2. `npx note-mcp auth --status`
+3. `codex mcp add note -- npx -y note-mcp`
+4. Restart Codex or create a new thread
+5. Run `note_auth_status`
+
+If the server is listed but `note_*` tools are not available in the current thread, restart Codex or start a new thread so the MCP tools are loaded from the new configuration.
+
 ## Authentication
 
 `note-mcp` supports two authentication paths.
@@ -78,6 +154,8 @@ This opens a browser, lets you log in to note.com normally, then stores note.com
 ~/.config/note-mcp/config.json
 ```
 
+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
@@ -92,8 +170,6 @@ npx -p playwright playwright install chromium
 
 For remote servers, containers, or CI, prefer the secret/env/config-file path below instead of browser login.
 
-The config file is written with `0600` permissions where supported.
-
 Useful CLI commands:
 
 ```bash
@@ -105,7 +181,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`
@@ -127,12 +203,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
@@ -140,7 +228,7 @@ Authentication/setup tools:
 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_my_notes` — list creator contents for the authenticated account via `GET /v2/creators/info/contents?kind=note&page={page}`. By default returns the full internal API payload. For LLM-friendly list views, pass `fields: "summary"` or `includeBody: false` to return summary fields such as `title`, `key`, `url`, `publishAt`, `status`, and `likeCount`.
 - `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
@@ -158,10 +246,12 @@ Known endpoint basis:
 
 - Base URL: `https://note.com/api`
 - Note detail: `GET /v3/notes/{noteKey}`
-- Own contents: `GET /v2/creators/info/contents?kind=note&page=1`
+- Authenticated creator contents: `GET /v2/creators/info/contents?kind=note&page=1`
 - Draft save: `POST /v1/text_notes/draft_save?id={draftId}`
 - Auth smoke test: `GET /v3/notice_counts`
 
+`note_list_my_notes` intentionally exposes the authenticated creator contents endpoint above. The exact visibility and shape are determined by note.com's internal API response for the configured cookie; use the default full response when debugging endpoint behavior, and use summary mode when a compact list is enough.
+
 ## Release
 
 Releases are handled by GitHub Actions + semantic-release.

package/dist/index.js

@@ -131,8 +131,12 @@ var NoteClient = class {
   async authCheck() {
     return this.request("/v3/notice_counts");
   }
-  async listMyNotes(page = 1) {
-    return this.request(`/v2/creators/info/contents?kind=note&page=${page}`);
+  async listMyNotes(page = 1, options = {}) {
+    const payload = await this.request(`/v2/creators/info/contents?kind=note&page=${page}`);
+    if (options.fields === "summary" || options.includeBody === false) {
+      return summarizeListPayload(payload);
+    }
+    return payload;
   }
   async listDrafts(page = 1) {
     return this.request(`/v2/creators/info/contents?kind=draft&page=${page}`);
@@ -181,6 +185,54 @@ var NoteClient = class {
     return body;
   }
 };
+function summarizeListPayload(payload) {
+  if (!isJsonObject(payload)) return payload;
+  if (isJsonObject(payload.data) && Array.isArray(payload.data.contents)) {
+    return {
+      ...payload,
+      data: {
+        ...payload.data,
+        contents: payload.data.contents.map(summarizeNoteItem)
+      }
+    };
+  }
+  if (Array.isArray(payload.contents)) {
+    return {
+      ...payload,
+      contents: payload.contents.map(summarizeNoteItem)
+    };
+  }
+  return payload;
+}
+function summarizeNoteItem(item) {
+  if (!isJsonObject(item)) return item;
+  const key = firstString(item.key, item.noteKey, item.id);
+  return omitUndefined({
+    key,
+    title: firstString(item.title, item.name),
+    url: firstString(item.url, item.noteUrl, item.note_url, item.path) ?? noteUrl(key),
+    publishAt: firstDefined(item.publishAt, item.publish_at, item.publishedAt, item.published_at),
+    status: item.status,
+    likeCount: firstDefined(item.likeCount, item.like_count)
+  });
+}
+function firstDefined(...values) {
+  return values.find((value) => value !== void 0);
+}
+function firstString(...values) {
+  return values.find((value) => typeof value === "string" && value.length > 0);
+}
+function noteUrl(key) {
+  return key ? `https://note.com/notes/${key}` : void 0;
+}
+function omitUndefined(record) {
+  return Object.fromEntries(
+    Object.entries(record).filter((entry) => entry[1] !== void 0)
+  );
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 async function parseBody(response) {
   const text = await response.text();
   if (!text) return null;
@@ -222,15 +274,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 {
       }
     }
@@ -250,6 +296,16 @@ 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")) {
@@ -393,12 +449,14 @@ async function runMcpServer() {
     "note_list_my_notes",
     {
       title: "List my note.com notes",
-      description: "Lists notes for the authenticated note.com account.",
+      description: 'Lists creator contents for the authenticated note.com account via GET /v2/creators/info/contents?kind=note. By default returns the full internal API payload; pass fields: "summary" or includeBody: false for a lightweight list with title/key/url/publishAt/status/likeCount.',
       inputSchema: {
-        page: z.number().int().positive().default(1)
+        page: z.number().int().positive().default(1),
+        fields: z.enum(["full", "summary"]).default("full"),
+        includeBody: z.boolean().optional()
       }
     },
-    async ({ page }) => withClient((client) => client.listMyNotes(page))
+    async ({ page, fields, includeBody }) => withClient((client) => client.listMyNotes(page, { fields, includeBody }))
   );
   server.registerTool(
     "note_list_drafts",

package/package.json

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