@pan-sec/notebooklm-mcp 2026.2.11 → 2026.3.1

package/dist/index.js

@@ -32,6 +32,8 @@ 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 { createRequire } from "module";
+import crypto from "node:crypto";
+import { pathToFileURL } from "node:url";
 import { AuthManager } from "./auth/auth-manager.js";
 import { SessionManager } from "./session/session-manager.js";
 // Read version from package.json
@@ -43,15 +45,126 @@ import { ToolHandlers, buildToolDefinitions } from "./tools/index.js";
 import { ResourceHandlers } from "./resources/resource-handlers.js";
 import { SettingsManager } from "./utils/settings-manager.js";
 import { CliHandler } from "./utils/cli-handler.js";
-import { CONFIG } from "./config.js";
+import { CONFIG, ensureDirectories } from "./config.js";
 import { log } from "./utils/logger.js";
 import { audit, getAuditLogger } from "./utils/audit-logger.js";
 import { checkSecurityContext } from "./utils/security.js";
 import { getMCPAuthenticator, authenticateMCPRequest } from "./auth/mcp-auth.js";
+import { getComplianceTools, handleComplianceToolCall, } from "./compliance/compliance-tools.js";
+import { getPrivacyNoticeManager, getPrivacyNoticeCLIText } from "./compliance/privacy-notice.js";
+import { runRetentionPolicies } from "./compliance/retention-engine.js";
+import { getBreachDetector } from "./compliance/breach-detection.js";
+import { exportToSIEM } from "./compliance/siem-exporter.js";
+const LIST_TOOLS_PAGE_SIZE = 25;
+const TOOL_NAMES = [
+    "ask_question", "add_notebook", "list_notebooks", "get_notebook", "select_notebook",
+    "update_notebook", "remove_notebook", "search_notebooks", "get_library_stats",
+    "export_library", "get_quota", "set_quota_tier", "get_project_info", "create_notebook",
+    "batch_create_notebooks", "sync_library", "list_sessions", "close_session", "reset_session",
+    "get_health", "setup_auth", "re_auth", "cleanup_data", "list_sources", "add_source",
+    "add_folder", "remove_source", "generate_audio_overview", "get_audio_status", "download_audio",
+    "generate_video_overview", "get_video_status", "generate_data_table", "get_data_table",
+    "configure_webhook", "list_webhooks", "test_webhook", "remove_webhook", "deep_research",
+    "gemini_query", "get_research_status", "upload_document", "query_document", "list_documents",
+    "delete_document", "query_chunked_document", "get_query_history", "get_notebook_chat_history",
+    "submit_dsar", "export_user_data", "request_data_erasure",
+    "grant_consent", "revoke_consent", "report_security_incident", "collect_audit_evidence",
+    "generate_compliance_report",
+];
+function isToolName(name) {
+    return TOOL_NAMES.includes(name);
+}
+function toToolArgs(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return Object.fromEntries(Object.entries(value));
+    }
+    return {};
+}
+function asToolInput(args) {
+    return args;
+}
+function parseListToolsCursor(cursor, totalTools) {
+    if (!cursor)
+        return 0;
+    const offset = Number.parseInt(cursor, 10);
+    if (!Number.isInteger(offset) || offset < 0 || offset >= totalTools)
+        return 0;
+    return offset;
+}
+function classifyToolError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /\b(transport|protocol|json-?rpc|connection|stdio|notification)\b/i.test(message)
+        ? "transport"
+        : "domain";
+}
+const TOOLS_EXEMPT_FROM_AUTH = new Set([
+    "ask_question", "add_notebook", "list_notebooks", "get_notebook", "select_notebook",
+    "update_notebook", "remove_notebook", "search_notebooks", "get_library_stats",
+    "get_quota", "set_quota_tier", "get_project_info", "create_notebook",
+    "batch_create_notebooks", "sync_library", "list_sessions", "close_session", "reset_session",
+    "get_health", "list_sources", "add_source", "remove_source",
+    "generate_audio_overview", "get_audio_status", "generate_video_overview", "get_video_status",
+    "generate_data_table", "get_data_table", "list_webhooks",
+    "deep_research", "gemini_query", "get_research_status",
+    "query_document", "list_documents", "query_chunked_document",
+    "get_query_history", "get_notebook_chat_history",
+]);
+const TOOLS_REQUIRING_AUTH = new Set([
+    "add_folder",
+    "cleanup_data",
+    "export_library",
+    "setup_auth",
+    "re_auth",
+    "configure_webhook",
+    "remove_webhook",
+    "test_webhook",
+    "delete_document",
+    "upload_document",
+    "download_audio",
+    // Compliance — destructive or privileged operations.
+    "submit_dsar",
+    "export_user_data",
+    "request_data_erasure",
+    "grant_consent",
+    "revoke_consent",
+    "report_security_incident",
+    "collect_audit_evidence",
+    "generate_compliance_report",
+]);
+const ADVANCED_TOOLS = new Set([
+    "export_library",
+    "list_sessions",
+    "close_session",
+    "reset_session",
+    "cleanup_data",
+    "configure_webhook",
+    "list_webhooks",
+    "test_webhook",
+    "remove_webhook",
+    "deep_research",
+    "gemini_query",
+    "get_research_status",
+    "upload_document",
+    "query_document",
+    "list_documents",
+    "delete_document",
+    "query_chunked_document",
+    "get_query_history",
+    "get_notebook_chat_history",
+    "submit_dsar",
+    "export_user_data",
+    "request_data_erasure",
+    "grant_consent",
+    "revoke_consent",
+    "report_security_incident",
+    "collect_audit_evidence",
+    "generate_compliance_report",
+]);
 /**
  * Main MCP Server Class
  */
-class NotebookLMMCPServer {
+export class NotebookLMMCPServer {
+    options;
     server;
     authManager;
     sessionManager;
@@ -61,8 +174,12 @@ class NotebookLMMCPServer {
     settingsManager;
     toolDefinitions;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    toolRegistry;
-    constructor() {
+    toolRegistry = new Map();
+    complianceToolNames;
+    retentionTimer;
+    advancedToolsEnabled;
+    constructor(options = {}) {
+        this.options = options;
         // Initialize MCP Server
         this.server = new Server({
             name: "notebooklm-mcp",
@@ -72,8 +189,7 @@ class NotebookLMMCPServer {
                 tools: {},
                 resources: {},
                 prompts: {},
-                completions: {}, // Required for completion/complete handler
-                logging: {},
+                completions: {},
             },
         });
         // Initialize managers
@@ -81,21 +197,37 @@ class NotebookLMMCPServer {
         this.sessionManager = new SessionManager(this.authManager);
         this.library = new NotebookLibrary();
         this.settingsManager = new SettingsManager();
+        this.advancedToolsEnabled = process.env.NLMCP_ADVANCED_TOOLS === "1";
         // Initialize handlers
         this.toolHandlers = new ToolHandlers(this.sessionManager, this.authManager, this.library);
         this.resourceHandlers = new ResourceHandlers(this.library);
         // Build and Filter tool definitions
         const allTools = buildToolDefinitions(this.library);
-        this.toolDefinitions = this.settingsManager.filterTools(allTools);
+        this.toolDefinitions = this.filterAdvancedTools(this.settingsManager.filterTools(allTools));
+        // Track compliance tool names for the short-circuit dispatch path.
+        this.complianceToolNames = new Set(this.filterAdvancedTools(getComplianceTools()).map((t) => t.name));
         // Setup handlers
         this.setupHandlers();
-        this.setupShutdownHandlers();
+        if (this.options.registerShutdownHandlers !== false) {
+            this.setupShutdownHandlers();
+        }
         const activeSettings = this.settingsManager.getEffectiveSettings();
         log.info("🚀 NotebookLM MCP Server initialized");
         log.info(`  Version: ${VERSION}`);
         log.info(`  Node: ${process.version}`);
         log.info(`  Platform: ${process.platform}`);
         log.info(`  Profile: ${activeSettings.profile} (${this.toolDefinitions.length} tools active)`);
+        log.info(`  Advanced tools: ${this.advancedToolsEnabled ? "enabled" : "disabled"}`);
+    }
+    filterAdvancedTools(tools) {
+        if (this.advancedToolsEnabled)
+            return tools;
+        return tools.filter((tool) => !isToolName(tool.name) || !ADVANCED_TOOLS.has(tool.name));
+    }
+    filterAdvancedToolRegistry(registry) {
+        if (this.advancedToolsEnabled)
+            return registry;
+        return new Map(Array.from(registry.entries()).filter(([name]) => !isToolName(name) || !ADVANCED_TOOLS.has(name)));
     }
     /**
      * Setup MCP request handlers
@@ -104,99 +236,124 @@ class NotebookLMMCPServer {
         // Register Resource Handlers (Resources, Templates, Completions)
         this.resourceHandlers.registerHandlers(this.server);
         // Build tool registry once (not per-request)
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        this.toolRegistry = new Map([
+        this.toolRegistry = this.filterAdvancedToolRegistry(new Map([
             // Ask Question
-            ["ask_question", (a, p) => this.toolHandlers.handleAskQuestion(a, p)],
+            ["ask_question", (args, progress) => this.toolHandlers.handleAskQuestion(asToolInput(args), progress)],
             // Notebook Management
-            ["add_notebook", (a) => this.toolHandlers.handleAddNotebook(a)],
+            ["add_notebook", (args) => this.toolHandlers.handleAddNotebook(asToolInput(args))],
             ["list_notebooks", () => this.toolHandlers.handleListNotebooks()],
-            ["get_notebook", (a) => this.toolHandlers.handleGetNotebook(a)],
-            ["select_notebook", (a) => this.toolHandlers.handleSelectNotebook(a)],
-            ["update_notebook", (a) => this.toolHandlers.handleUpdateNotebook(a)],
-            ["remove_notebook", (a) => this.toolHandlers.handleRemoveNotebook(a)],
-            ["search_notebooks", (a) => this.toolHandlers.handleSearchNotebooks(a)],
+            ["get_notebook", (args) => this.toolHandlers.handleGetNotebook(asToolInput(args))],
+            ["select_notebook", (args) => this.toolHandlers.handleSelectNotebook(asToolInput(args))],
+            ["update_notebook", (args) => this.toolHandlers.handleUpdateNotebook(asToolInput(args))],
+            ["remove_notebook", (args) => this.toolHandlers.handleRemoveNotebook(asToolInput(args))],
+            ["search_notebooks", (args) => this.toolHandlers.handleSearchNotebooks(asToolInput(args))],
             ["get_library_stats", () => this.toolHandlers.handleGetLibraryStats()],
-            ["export_library", (a) => this.toolHandlers.handleExportLibrary(a)],
+            ["export_library", (args) => this.toolHandlers.handleExportLibrary(asToolInput(args))],
             // Quota & System
-            ["get_quota", (a) => this.toolHandlers.handleGetQuota(a)],
-            ["set_quota_tier", (a) => this.toolHandlers.handleSetQuotaTier(a)],
+            ["get_quota", (args) => this.toolHandlers.handleGetQuota(asToolInput(args))],
+            ["set_quota_tier", (args) => this.toolHandlers.handleSetQuotaTier(asToolInput(args))],
             ["get_project_info", () => this.toolHandlers.handleGetProjectInfo()],
             // Notebook Creation
-            ["create_notebook", (a, p) => this.toolHandlers.handleCreateNotebook(a, p)],
-            ["batch_create_notebooks", (a, p) => this.toolHandlers.handleBatchCreateNotebooks(a, p)],
-            ["sync_library", (a) => this.toolHandlers.handleSyncLibrary(a)],
+            ["create_notebook", (args, progress) => this.toolHandlers.handleCreateNotebook(asToolInput(args), progress)],
+            ["batch_create_notebooks", (args, progress) => this.toolHandlers.handleBatchCreateNotebooks(asToolInput(args), progress)],
+            ["sync_library", (args) => this.toolHandlers.handleSyncLibrary(asToolInput(args))],
             // Session Management
             ["list_sessions", () => this.toolHandlers.handleListSessions()],
-            ["close_session", (a) => this.toolHandlers.handleCloseSession(a)],
-            ["reset_session", (a) => this.toolHandlers.handleResetSession(a)],
-            ["get_health", (a) => this.toolHandlers.handleGetHealth(a)],
+            ["close_session", (args) => this.toolHandlers.handleCloseSession(asToolInput(args))],
+            ["reset_session", (args) => this.toolHandlers.handleResetSession(asToolInput(args))],
+            ["get_health", (args) => this.toolHandlers.handleGetHealth(asToolInput(args))],
             // Auth
-            ["setup_auth", (a, p) => this.toolHandlers.handleSetupAuth(a, p)],
-            ["re_auth", (a, p) => this.toolHandlers.handleReAuth(a, p)],
-            ["cleanup_data", (a) => this.toolHandlers.handleCleanupData(a)],
+            ["setup_auth", (args, progress) => this.toolHandlers.handleSetupAuth(asToolInput(args), progress)],
+            ["re_auth", (args, progress) => this.toolHandlers.handleReAuth(asToolInput(args), progress)],
+            ["cleanup_data", (args) => this.toolHandlers.handleCleanupData(asToolInput(args))],
             // Sources
-            ["list_sources", (a) => this.toolHandlers.handleListSources(a)],
-            ["add_source", (a) => this.toolHandlers.handleAddSource(a)],
-            ["add_folder", (a, p) => this.toolHandlers.handleAddFolder(a, p)],
-            ["remove_source", (a) => this.toolHandlers.handleRemoveSource(a)],
+            ["list_sources", (args) => this.toolHandlers.handleListSources(asToolInput(args))],
+            ["add_source", (args) => this.toolHandlers.handleAddSource(asToolInput(args))],
+            ["add_folder", (args, progress) => this.toolHandlers.handleAddFolder(asToolInput(args), progress)],
+            ["remove_source", (args) => this.toolHandlers.handleRemoveSource(asToolInput(args))],
             // Audio / Video / Data Table
-            ["generate_audio_overview", (a) => this.toolHandlers.handleGenerateAudioOverview(a)],
-            ["get_audio_status", (a) => this.toolHandlers.handleGetAudioStatus(a)],
-            ["download_audio", (a) => this.toolHandlers.handleDownloadAudio(a)],
-            ["generate_video_overview", (a) => this.toolHandlers.handleGenerateVideoOverview(a)],
-            ["get_video_status", (a) => this.toolHandlers.handleGetVideoStatus(a)],
-            ["generate_data_table", (a) => this.toolHandlers.handleGenerateDataTable(a)],
-            ["get_data_table", (a) => this.toolHandlers.handleGetDataTable(a)],
+            ["generate_audio_overview", (args) => this.toolHandlers.handleGenerateAudioOverview(asToolInput(args))],
+            ["get_audio_status", (args) => this.toolHandlers.handleGetAudioStatus(asToolInput(args))],
+            ["download_audio", (args) => this.toolHandlers.handleDownloadAudio(asToolInput(args))],
+            ["generate_video_overview", (args) => this.toolHandlers.handleGenerateVideoOverview(asToolInput(args))],
+            ["get_video_status", (args) => this.toolHandlers.handleGetVideoStatus(asToolInput(args))],
+            ["generate_data_table", (args) => this.toolHandlers.handleGenerateDataTable(asToolInput(args))],
+            ["get_data_table", (args) => this.toolHandlers.handleGetDataTable(asToolInput(args))],
             // Webhooks
-            ["configure_webhook", (a) => this.toolHandlers.handleConfigureWebhook(a)],
+            ["configure_webhook", (args) => this.toolHandlers.handleConfigureWebhook(asToolInput(args))],
             ["list_webhooks", () => this.toolHandlers.handleListWebhooks()],
-            ["test_webhook", (a) => this.toolHandlers.handleTestWebhook(a)],
-            ["remove_webhook", (a) => this.toolHandlers.handleRemoveWebhook(a)],
+            ["test_webhook", (args) => this.toolHandlers.handleTestWebhook(asToolInput(args))],
+            ["remove_webhook", (args) => this.toolHandlers.handleRemoveWebhook(asToolInput(args))],
             // Gemini API
-            ["deep_research", (a, p) => this.toolHandlers.handleDeepResearch(a, p)],
-            ["gemini_query", (a) => this.toolHandlers.handleGeminiQuery(a)],
-            ["get_research_status", (a) => this.toolHandlers.handleGetResearchStatus(a)],
-            ["upload_document", (a) => this.toolHandlers.handleUploadDocument(a)],
-            ["query_document", (a) => this.toolHandlers.handleQueryDocument(a)],
-            ["list_documents", (a) => this.toolHandlers.handleListDocuments(a)],
-            ["delete_document", (a) => this.toolHandlers.handleDeleteDocument(a)],
-            ["query_chunked_document", (a) => this.toolHandlers.handleQueryChunkedDocument(a)],
-            ["get_query_history", (a) => this.toolHandlers.handleGetQueryHistory(a)],
-            ["get_notebook_chat_history", (a) => this.toolHandlers.handleGetNotebookChatHistory(a)],
-        ]);
-        // List available tools
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            ["deep_research", (args, progress) => this.toolHandlers.handleDeepResearch(asToolInput(args), progress)],
+            ["gemini_query", (args) => this.toolHandlers.handleGeminiQuery(asToolInput(args))],
+            ["get_research_status", (args) => this.toolHandlers.handleGetResearchStatus(asToolInput(args))],
+            ["upload_document", (args) => this.toolHandlers.handleUploadDocument(asToolInput(args))],
+            ["query_document", (args) => this.toolHandlers.handleQueryDocument(asToolInput(args))],
+            ["list_documents", (args) => this.toolHandlers.handleListDocuments(asToolInput(args))],
+            ["delete_document", (args) => this.toolHandlers.handleDeleteDocument(asToolInput(args))],
+            ["query_chunked_document", (args) => this.toolHandlers.handleQueryChunkedDocument(asToolInput(args))],
+            ["get_query_history", (args) => this.toolHandlers.handleGetQueryHistory(asToolInput(args))],
+            ["get_notebook_chat_history", (args) => this.toolHandlers.handleGetNotebookChatHistory(asToolInput(args))],
+        ]));
+        // Startup assertion: every dispatched tool must be explicitly auth-classified (I313)
+        for (const toolName of this.toolRegistry.keys()) {
+            if (isToolName(toolName) && !TOOLS_REQUIRING_AUTH.has(toolName) && !TOOLS_EXEMPT_FROM_AUTH.has(toolName)) {
+                log.warning(`⚠️ Tool '${toolName}' not in auth lists — defaulting to unauthenticated`);
+            }
+        }
+        for (const toolName of this.complianceToolNames) {
+            if (!isToolName(toolName)) {
+                // Compliance tools not in TOOL_NAMES use read-auth by default; log for audit visibility
+                log.info(`  [auth] compliance:'${toolName}' → read-auth (not in TOOLS_REQUIRING_AUTH)`);
+            }
+        }
+        // List available tools — rebuild each call so ask_question description reflects current notebook (I022)
+        this.server.setRequestHandler(ListToolsRequestSchema, async (request) => {
             log.info("📋 [MCP] list_tools request received");
+            const allTools = buildToolDefinitions(this.library);
+            const tools = this.filterAdvancedTools(this.settingsManager.filterTools(allTools));
+            const offset = parseListToolsCursor(request.params?.cursor, tools.length);
+            const page = tools.slice(offset, offset + LIST_TOOLS_PAGE_SIZE);
+            const nextOffset = offset + page.length;
             return {
-                tools: this.toolDefinitions,
+                tools: page,
+                ...(nextOffset < tools.length && { nextCursor: String(nextOffset) }),
             };
         });
         // Handle tool calls
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => log.withContext({
+            correlation_id: crypto.randomUUID(),
+            tool: request.params.name,
+        }, async () => {
             const { name, arguments: args } = request.params;
-            const progressToken = args?._meta?.progressToken;
-            const authToken = args?._meta?.authToken || process.env.NLMCP_AUTH_TOKEN;
+            // Per MCP spec, _meta lives on request.params, not inside arguments
+            const meta = request.params._meta;
+            const progressToken = meta?.progressToken;
+            const authToken = meta?.authToken || process.env.NLMCP_AUTH_TOKEN;
             log.info(`🔧 [MCP] Tool call: ${name}`);
             if (progressToken) {
                 log.info(`  📊 Progress token: ${progressToken}`);
             }
             // === SECURITY: MCP Authentication ===
-            // Tools that access the filesystem always require auth, even if globally disabled
-            const TOOLS_REQUIRING_AUTH = ["add_folder", "cleanup_data", "export_library"];
-            const requiresAuth = TOOLS_REQUIRING_AUTH.includes(name);
+            // Tools that touch the filesystem, wipe credentials, dispatch outbound
+            // HTTP, delete remote resources, or exercise GDPR data-subject rights
+            // always require auth, even if globally disabled via NLMCP_AUTH_DISABLED.
+            const requiresAuth = isToolName(name) && TOOLS_REQUIRING_AUTH.has(name);
             const authResult = requiresAuth
-                ? await authenticateMCPRequest(authToken, name, true)
-                : await authenticateMCPRequest(authToken, name);
+                ? await authenticateMCPRequest(authToken, name, true, "admin")
+                : await authenticateMCPRequest(authToken, name, false, "read");
             if (!authResult.authenticated) {
                 log.warning(`🔒 [MCP] Authentication failed for tool: ${name}`);
                 return {
+                    isError: true,
                     content: [
                         {
                             type: "text",
                             text: JSON.stringify({
                                 success: false,
                                 error: authResult.error || "Authentication required",
+                                _errorType: "domain",
                             }),
                         },
                     ],
@@ -218,19 +375,33 @@ class NotebookLMMCPServer {
                 }
             };
             try {
+                // Compliance tools have their own dispatcher that returns MCP-shaped
+                // TextContent[] directly. Short-circuit before the generic wrapper
+                // so dashboard/report text isn't double-encoded as JSON.
+                if (this.complianceToolNames.has(name)) {
+                    const content = await handleComplianceToolCall(name, toToolArgs(args));
+                    return { content };
+                }
                 const handler = this.toolRegistry.get(name);
                 if (!handler) {
                     log.error(`❌ [MCP] Unknown tool: ${name}`);
+                    const errorBody = {
+                        success: false,
+                        error: `Unknown tool: ${name}`,
+                        _errorType: "domain",
+                    };
                     return {
+                        isError: true,
                         content: [
                             {
                                 type: "text",
-                                text: JSON.stringify({ success: false, error: `Unknown tool: ${name}` }, null, 2),
+                                text: JSON.stringify(errorBody, null, 2),
                             },
                         ],
+                        structuredContent: errorBody,
                     };
                 }
-                const result = await handler(args, sendProgress);
+                const result = await handler(toToolArgs(args), sendProgress);
                 // Return result
                 return {
                     content: [
@@ -239,37 +410,77 @@ class NotebookLMMCPServer {
                             text: JSON.stringify(result, null, 2),
                         },
                     ],
+                    structuredContent: result,
                 };
             }
             catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                log.error(`❌ [MCP] Tool execution error: ${errorMessage}`);
+                const rawMessage = error instanceof Error ? error.message : String(error);
+                const errorType = classifyToolError(error);
+                log.error(`❌ [MCP] Tool execution error for '${name}': ${rawMessage}`);
+                // Sanitize before returning to client: strip absolute paths and stack fragments (I328)
+                const sanitized = rawMessage
+                    .replace(/(?:\/[^\s/:,'"]+)+/g, "[path]")
+                    .replace(/\bat\s+\S+\s+\(\S+:\d+:\d+\)/g, "")
+                    .trim();
+                const errorBody = {
+                    success: false,
+                    data: null,
+                    error: sanitized,
+                    _errorType: errorType,
+                };
                 return {
+                    isError: true,
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify({
-                                success: false,
-                                error: errorMessage,
-                            }, null, 2),
+                            text: JSON.stringify(errorBody, null, 2),
                         },
                     ],
+                    structuredContent: errorBody,
                 };
             }
-        });
+        }));
     }
     /**
      * Setup graceful shutdown handlers
      */
     setupShutdownHandlers() {
         let shuttingDown = false;
-        const shutdown = async (signal) => {
+        const flushFatalError = async (signal, error) => {
+            if (signal !== "uncaughtException" && signal !== "unhandledRejection")
+                return;
+            const message = error instanceof Error ? error.message : String(error ?? signal);
+            try {
+                await this.server.notification({
+                    method: "notifications/message",
+                    params: {
+                        level: "error",
+                        logger: "notebooklm-mcp",
+                        data: {
+                            success: false,
+                            error: message,
+                            _errorType: "transport",
+                            signal,
+                        },
+                    },
+                });
+            }
+            catch (notifyError) {
+                log.warning(`⚠️ Failed to flush fatal MCP error notification: ${notifyError instanceof Error ? notifyError.message : String(notifyError)}`);
+            }
+        };
+        const shutdown = async (signal, error) => {
             if (shuttingDown) {
                 return;
             }
             shuttingDown = true;
             log.info(`\n🛑 Received ${signal}, shutting down gracefully...`);
             try {
+                await flushFatalError(signal, error);
+                if (this.retentionTimer) {
+                    clearInterval(this.retentionTimer);
+                    this.retentionTimer = undefined;
+                }
                 // Cleanup tool handlers (closes all sessions)
                 await this.toolHandlers.cleanup();
                 // Close server
@@ -282,28 +493,108 @@ class NotebookLMMCPServer {
                 process.exit(1);
             }
         };
-        const requestShutdown = (signal) => {
-            void shutdown(signal);
+        const requestShutdown = (signal, error) => {
+            void shutdown(signal, error);
         };
         process.on("SIGINT", () => requestShutdown("SIGINT"));
         process.on("SIGTERM", () => requestShutdown("SIGTERM"));
         process.on("uncaughtException", (error) => {
             log.error(`💥 Uncaught exception: ${error}`);
             log.error(error.stack || "");
-            requestShutdown("uncaughtException");
+            requestShutdown("uncaughtException", error);
         });
         process.on("unhandledRejection", (reason, promise) => {
             log.error(`💥 Unhandled rejection at: ${promise}`);
             log.error(`Reason: ${reason}`);
-            requestShutdown("unhandledRejection");
+            requestShutdown("unhandledRejection", reason);
         });
     }
+    /**
+     * Bootstrap the compliance module at startup:
+     *   1. Display the privacy notice to stderr on first run and auto-record
+     *      acknowledgment (stdio MCP cannot prompt interactively, so the
+     *      notice is informational — operators wishing for explicit consent
+     *      should call the `grant_consent` MCP tool).
+     *   2. Run the retention engine immediately and schedule it every 6 hours
+     *      so archive/delete policies actually fire. Timer is unref()'d so it
+     *      does not keep the process alive on shutdown.
+     */
+    async bootstrapCompliance() {
+        try {
+            const privacy = getPrivacyNoticeManager();
+            if (await privacy.needsDisplay()) {
+                log.info("");
+                log.info("━━━ Privacy notice (first run) ━━━");
+                // Multi-line notice — write via stderr directly so formatting survives.
+                process.stderr.write(getPrivacyNoticeCLIText() + "\n");
+                log.info("━━━ End privacy notice ━━━");
+                log.info("");
+                await privacy.acknowledge("auto");
+                log.info("📜 Privacy notice recorded (method=auto). Use grant_consent to record explicit consent.");
+            }
+        }
+        catch (err) {
+            log.warning(`⚠️ Privacy notice bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        try {
+            const runOnce = async () => {
+                const results = await runRetentionPolicies();
+                if (results.length > 0) {
+                    log.info(`🗂️  Retention engine ran ${results.length} policy(ies)`);
+                }
+            };
+            await runOnce();
+            const SIX_HOURS_MS = 6 * 60 * 60 * 1000;
+            this.retentionTimer = setInterval(() => {
+                void runOnce().catch((err) => log.warning(`⚠️ retention policy run failed: ${err instanceof Error ? err.message : String(err)}`));
+            }, SIX_HOURS_MS);
+            this.retentionTimer.unref();
+        }
+        catch (err) {
+            log.warning(`⚠️ Retention engine bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Subscribe breach detector to audit event stream (I244)
+        try {
+            const breachDetector = getBreachDetector();
+            getAuditLogger().onEvent(async (event) => {
+                if (event.eventType !== "auth" && event.eventType !== "security")
+                    return;
+                try {
+                    await breachDetector.checkEvent(event.eventName, event.details);
+                }
+                catch (err) {
+                    log.warning(`breach detector checkEvent failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            });
+            log.info("🛡️  Breach detector subscribed to audit events");
+        }
+        catch (err) {
+            log.warning(`⚠️ Breach detector bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Pipe audit events to SIEM when enabled (I247). exportToSIEM is a no-op
+        // when NLMCP_SIEM_ENABLED is not true.
+        try {
+            getAuditLogger().onEvent(async (event) => {
+                const severity = event.eventType === "security" && typeof event.details.severity === "string"
+                    ? event.details.severity
+                    : event.success ? "info" : "error";
+                await exportToSIEM(event.eventType, event.eventName, severity, `${event.eventType}:${event.eventName}`, "audit-logger", event.details);
+            });
+            log.info("📡 SIEM audit export bridge registered");
+        }
+        catch (err) {
+            log.warning(`⚠️ SIEM bootstrap failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     /**
      * Start the MCP server
      */
-    async start() {
+    async start(transport = new StdioServerTransport()) {
         log.info("🎯 Starting NotebookLM MCP Server (Security Hardened)...");
         log.info("");
+        if (process.env.NODE_ENV !== "test") {
+            ensureDirectories();
+        }
         // Security: Check security context and warn about issues
         const securityCheck = checkSecurityContext();
         if (!securityCheck.secure) {
@@ -317,6 +608,21 @@ class NotebookLMMCPServer {
         const mcpAuth = getMCPAuthenticator();
         await mcpAuth.initialize();
         const authStatus = mcpAuth.getStatus();
+        // Audit: verify hash-chain integrity from previous run (I218)
+        try {
+            const integrity = await getAuditLogger().verifyIntegrity();
+            if (!integrity.valid) {
+                log.warning(`⚠️ Audit log integrity check failed: ${integrity.errors.join(", ")}`);
+            }
+            else {
+                log.info("🔒 Audit log integrity verified");
+            }
+        }
+        catch (err) {
+            log.warning(`⚠️ Audit integrity check error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Compliance: surface privacy notice on first run and schedule retention.
+        await this.bootstrapCompliance();
         // Audit: Log server startup
         await audit.system("server_start", {
             version: VERSION,
@@ -337,10 +643,15 @@ class NotebookLMMCPServer {
         log.info(`  Session Timeout: ${CONFIG.sessionTimeout}s`);
         log.info(`  Stealth: ${CONFIG.stealthEnabled}`);
         log.info(`  Audit Logging: ${getAuditLogger().getStats().totalEvents >= 0 ? 'enabled' : 'disabled'}`);
-        log.info(`  MCP Authentication: ${authStatus.enabled ? 'enabled' : 'disabled'}`);
+        // I314: verbose effective auth state
+        log.info(`  MCP Authentication: ${authStatus.enabled ? 'ENABLED' : 'DISABLED'}`);
+        if (authStatus.enabled) {
+            const tokenSrc = process.env.NLMCP_AUTH_TOKEN ? "env var" : "hash file";
+            log.info(`    Admin token: ${authStatus.hasToken ? `configured (${tokenSrc})` : 'NOT SET — all admin tools will reject'}`);
+            log.info(`    Read-only token: ${authStatus.hasReadOnlyToken ? 'configured' : 'not set (admin token used for read)'}`);
+            log.info(`    Admin tools (${TOOLS_REQUIRING_AUTH.size}): require auth even if globally disabled`);
+        }
         log.info("");
-        // Create stdio transport
-        const transport = new StdioServerTransport();
         // Connect server to transport
         await this.server.connect(transport);
         log.success("✅ MCP Server connected via stdio");
@@ -348,19 +659,27 @@ class NotebookLMMCPServer {
         log.info("");
         log.info("💡 Available tools:");
         for (const tool of this.toolDefinitions) {
-            const desc = tool.description ? tool.description.split('\n')[0] : 'No description'; // First line only
-            log.info(`  - ${tool.name}: ${desc.substring(0, 80)}...`);
+            const raw = tool.description ? tool.description.split('\n')[0] : 'No description';
+            const desc = raw.replace(/\p{Extended_Pictographic}/gu, '').trim();
+            log.info(`  - ${tool.name}: ${desc.substring(0, 80)}${desc.length > 80 ? '...' : ''}`);
         }
         log.info("");
         log.info("📖 For documentation, see: README.md");
-        log.info("📖 For MCP details, see: MCP_INFOS.md");
         log.info("");
     }
+    async stop() {
+        if (this.retentionTimer) {
+            clearInterval(this.retentionTimer);
+            this.retentionTimer = undefined;
+        }
+        await this.toolHandlers.cleanup();
+        await this.server.close();
+    }
 }
 /**
  * Main entry point
  */
-async function main() {
+export async function main() {
     // Handle CLI commands
     const args = process.argv.slice(2);
     if (args.length > 0 && args[0] === "config") {
@@ -394,6 +713,10 @@ async function main() {
         process.exit(1);
     }
 }
-// Run the server
-main();
+const isDirectRun = process.argv[1]
+    ? import.meta.url === pathToFileURL(process.argv[1]).href
+    : false;
+if (isDirectRun) {
+    void main();
+}
 //# sourceMappingURL=index.js.map