Idle stdio server accumulates CPU time (second half of the --help report)

[asg9991]

Description

The notebooklm-mcp binary does not parse CLI arguments. Passing --help (or any flag) is silently ignored and the full MCP server starts in stdio mode. When launched by an MCP client that doesn't actively need it, the process stays alive indefinitely consuming significant CPU.

Steps to reproduce

# This should show help text but instead starts the full server:
notebooklm-mcp --help

# The process runs indefinitely until killed:
# PID   CPU%  MEM%  TIME
# 749651 37.2% 2.0% 360:29 (after ~6 hours idle)
Expected behavior
notebooklm-mcp --help should print usage information and exit (like npm run help does via dist/cli/help.js), or at minimum recognize --help/-h flags.
Actual behavior
- --help flag is ignored
- Full MCP server starts in stdio mode
- Process stays alive consuming CPU indefinitely when no MCP client is actively communicating
- Requires kill -9 to terminate
Environment
- Package: @roomi-fields/notebooklm-mcp v3.0.1
- Node: v22.23.2
- OS: Linux x86_64 (Ubuntu 24.04)
- Install: local (npm install in project directory)
Additional context
The package.json defines a help script (node dist/cli/help.js) but the binary entry point (dist/index.js) has no argument parsing — it unconditionally starts the MCP server regardless of CLI arguments.
This is particularly problematic when MCP clients (e.g., OpenCode) spawn the process speculatively but don't actively use it — the zombie process accumulates CPU time with no useful work.

[roomi-fields]

Thanks — the --help half is exactly right, and the cause is precisely what you inferred from package.json.

3.0.1 added subcommand dispatch to the binary (setup-auth, de-auth, accounts, help) so global-install users could run the interactive login outside the client's tool-call timeout. The guard was written as:

if (subcommand && !subcommand.startsWith('-')) { ... }

which deliberately skipped anything beginning with - — so --help fell straight past the dispatch table and into the server boot. A bare help worked; --help could not.

Fixed in 563679d on main. --help/-h and --version/-v are now handled before the subcommand table and exit:

$ notebooklm-mcp --help      # usage, exit 0
$ notebooklm-mcp --version   # 3.0.1, exit 0
$ notebooklm-mcp bogus       # error, exit 1
$ notebooklm-mcp             # MCP server on stdio (unchanged)

An unrecognised flag still starts the server rather than aborting — some MCP clients append flags of their own and exiting would break them — but it now says so on stderr instead of staying silent. Warnings go to stderr only, since stdout is the JSON-RPC channel. I also added the installed-binary commands to the help text, which previously only documented the npm run forms of a cloned repo.

On the CPU half I need your help — I can't reproduce it. On Linux/x86_64 with the published build, an idle server's cumulative CPU time stays flat at ~1s no matter how long it sits, and every shutdown path works:

stdin	result
pipe held open, silent	idle, CPU time flat
/dev/null (immediate EOF)	exits cleanly
pipe whose writer exited	exits cleanly
fd 0 closed	exits cleanly
pseudo-terminal	idle, 0% CPU

My working hypothesis is that the process you measured was the --help invocation itself — it would have booted a full server attached to your terminal, where stdin never reaches EOF, so nothing would ever shut it down. That path is now impossible. But 360 minutes of CPU is not what an idle server does here, so if you still see it after the fix, could you grab:

• top -H -p <pid> — which thread is burning it (V8 GC, libuv, or JS)
• whether a chrome/chromium process is alive alongside it (the browser is only meant to start on demand)
• the process's stderr — the startup banner logs which subsystems initialised
• whether that install is authenticated (notebooklm-mcp accounts)

Happy to cut a patch release once you've confirmed the flag fix resolves what you were seeing.

[roomi-fields]

Shipped in v3.0.2, now on npm as @roomi-fields/notebooklm-mcp@3.0.2.

notebooklm-mcp --help      # usage, exit 0
notebooklm-mcp --version   # 3.0.2, exit 0

The stray-server path you hit is gone: --help can no longer reach the server boot at all. If the CPU burn still shows up on a plain notebooklm-mcp launch, the four diagnostics above would help me chase it — I could not reproduce it here across piped, EOF, closed-fd and pseudo-terminal stdin.

Thanks for the clear report; the package.json observation pointed straight at the cause.

[roomi-fields]

Reopening — this was auto-closed by the Fixes #30 keyword on the commit that shipped the flag handling, which only covered the first half of your report. The CPU behaviour is unresolved and shouldn't disappear with it. Retitled so the remaining scope is clear.

Settled and released (v3.0.2, and v3.0.3 today): --help/-h and --version/-v exit instead of booting a server, so the specific process you caught can no longer be created that way.

Still open: whether a plain notebooklm-mcp launch can accumulate CPU while idle. I could not reproduce it — cumulative CPU time stays flat here across piped-and-silent, /dev/null, dead-writer, closed-fd and pseudo-terminal stdin, and all the EOF paths shut the server down cleanly.

If it still happens on a bare launch, these four would let me chase it:

1. top -H -p <pid> — which thread is burning it (V8 GC, libuv, or JS)
2. whether a chrome/chromium process is alive alongside (the browser is only meant to start on demand)
3. the process's stderr — the startup banner names which subsystems initialised
4. whether that install is authenticated (notebooklm-mcp accounts)

No rush, and no obligation — if the flag fix turned out to be the whole story for you, say so and I'll close it for good.

[asg9991]

Fixed in v3.0.4 — --help now works correctly and exits without starting the server. Thanks for the quick turnaround!

[roomi-fields]

Closing — the --help half is fixed and you confirmed it, and I have now measured the CPU half on the current release rather than leaving it open on an unfalsifiable hypothesis.

Measured on 3.1.2, a bare notebooklm-mcp launch on Linux/x86_64, stdin held open by a live writer and completely silent — the configuration most likely to keep a server alive with nothing to do:

elapsed	cumulative CPU
130 s	1 s
265 s	1 s
592 s	1 s
671 s	1 s

That single second is process startup. It does not grow. Every libuv worker thread sits at 0.0%, no chrome/chromium process is spawned alongside (the browser only starts when a tool actually needs it), and the process exits cleanly on SIGTERM.

Extrapolated to your six hours, that is about 1 second of CPU where you measured 360 minutes — so whatever you caught was not an idle server doing its normal thing.

Which leaves the hypothesis from my first reply as the only one still standing: the process you measured was the --help invocation itself. It booted a full server attached to your terminal, where stdin never reaches EOF, so nothing could ever shut it down — and it would sit there for as long as the terminal lived. That path no longer exists: --help and --version print and exit before any server code runs.

If a bare launch ever does burn CPU on your machine, reopen this with top -H -p <pid> and I will chase it — the four diagnostics from earlier still stand. But I would rather close it on a measurement than leave it hanging on a question you have no reason to keep answering.

Thanks again — the package.json observation in your report pointed straight at the actual bug.