@roomi-fields/notebooklm-mcp 1.5.9 → 1.6.0

package/deployment/docs/openapi.yaml

@@ -0,0 +1,492 @@
+openapi: 3.1.0
+info:
+  title: NotebookLM REST API
+  version: 1.5.9
+  description: |
+    Local HTTP REST API for Google NotebookLM. Citation-backed Q&A, Studio
+    content generation (audio, video, infographic, report, presentation,
+    data table), notebook library management, multi-account auto-reauth.
+
+    Companion to the MCP server in the same package
+    (`@roomi-fields/notebooklm-mcp`). See
+    https://roomi-fields.github.io/notebooklm-mcp/ for the full guide.
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+  contact:
+    name: Romain Peyrichou
+    url: https://github.com/roomi-fields/notebooklm-mcp
+
+servers:
+  - url: http://localhost:3000
+    description: Local server (default)
+  - url: http://{host}:{port}
+    description: Custom host
+    variables:
+      host:
+        default: localhost
+      port:
+        default: '3000'
+
+tags:
+  - name: Health
+  - name: Auth
+  - name: Q&A
+  - name: Notebooks
+  - name: Sources
+  - name: Content
+  - name: Sessions
+
+paths:
+  /health:
+    get:
+      tags: [Health]
+      summary: Server health check
+      responses:
+        '200':
+          description: Server status, uptime, active sessions
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Health' }
+
+  /setup-auth:
+    post:
+      tags: [Auth]
+      summary: First-time Google authentication (opens visible browser)
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                show_browser: { type: boolean, default: true }
+                account: { type: string }
+      responses:
+        '200':
+          description: Auth completed
+          content: { application/json: { schema: { $ref: '#/components/schemas/Result' } } }
+
+  /de-auth:
+    post:
+      tags: [Auth]
+      summary: Logout, clear all credentials
+      responses:
+        '200':
+          description: Logged out
+          content: { application/json: { schema: { $ref: '#/components/schemas/Result' } } }
+
+  /re-auth:
+    post:
+      tags: [Auth]
+      summary: Re-authenticate or switch account
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                account: { type: string }
+      responses:
+        '200':
+          description: Re-authenticated
+          content: { application/json: { schema: { $ref: '#/components/schemas/Result' } } }
+
+  /ask:
+    post:
+      tags: [Q&A]
+      summary: Ask a question with citation-backed response
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/AskRequest' }
+      responses:
+        '200':
+          description: Answer with citations
+          content: { application/json: { schema: { $ref: '#/components/schemas/AskResponse' } } }
+        '400':
+          description: Missing question
+        '500':
+          description: Server error
+
+  /notebooks:
+    get:
+      tags: [Notebooks]
+      summary: List all notebooks in the local library
+      responses:
+        '200': { description: Notebook list }
+    post:
+      tags: [Notebooks]
+      summary: Manually add a notebook to the library
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [id, name, url]
+              properties:
+                id: { type: string }
+                name: { type: string }
+                url: { type: string }
+                description: { type: string }
+                topics: { type: array, items: { type: string } }
+      responses:
+        '200': { description: Notebook added }
+
+  /notebooks/scrape:
+    get:
+      tags: [Notebooks]
+      summary: Scrape all notebooks from NotebookLM UI
+      responses:
+        '200': { description: Live notebook list with ids and names }
+
+  /notebooks/import-from-scrape:
+    post:
+      tags: [Notebooks]
+      summary: Bulk import scraped notebooks into local library
+      responses:
+        '200': { description: Import summary }
+
+  /notebooks/auto-discover:
+    post:
+      tags: [Notebooks]
+      summary: Generate notebook metadata autonomously via NotebookLM queries
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                notebook_id: { type: string }
+                notebook_url: { type: string }
+      responses:
+        '200': { description: Generated metadata }
+
+  /notebooks/search:
+    get:
+      tags: [Notebooks]
+      summary: Search the local library by keyword
+      parameters:
+        - in: query
+          name: q
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Matching notebooks }
+
+  /notebooks/stats:
+    get:
+      tags: [Notebooks]
+      summary: Library statistics
+      responses:
+        '200': { description: Counts and aggregates }
+
+  /notebooks/bulk-delete:
+    delete:
+      tags: [Notebooks]
+      summary: Delete multiple notebooks at once
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                ids: { type: array, items: { type: string } }
+      responses:
+        '200': { description: Deletion summary }
+
+  /notebooks/{id}:
+    get:
+      tags: [Notebooks]
+      summary: Get notebook details
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Notebook details }
+    put:
+      tags: [Notebooks]
+      summary: Update notebook metadata
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Updated }
+    delete:
+      tags: [Notebooks]
+      summary: Delete a notebook from the library
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Deleted }
+
+  /notebooks/{id}/activate:
+    put:
+      tags: [Notebooks]
+      summary: Set notebook as the default active notebook
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Activated }
+
+  /notebooks/create:
+    post:
+      tags: [Notebooks]
+      summary: Create a new notebook in NotebookLM
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name: { type: string }
+                description: { type: string }
+      responses:
+        '200': { description: Created notebook }
+
+  /sessions:
+    get:
+      tags: [Sessions]
+      summary: List active sessions
+      responses:
+        '200': { description: Active sessions }
+
+  /sessions/{id}:
+    delete:
+      tags: [Sessions]
+      summary: Close a session
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Closed }
+
+  /sessions/{id}/reset:
+    post:
+      tags: [Sessions]
+      summary: Reset a session's history
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Reset }
+
+  /content/sources:
+    post:
+      tags: [Sources]
+      summary: Add a source (file, url, text, youtube, drive) to the active notebook
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/AddSourceRequest' }
+      responses:
+        '200': { description: Source added }
+    delete:
+      tags: [Sources]
+      summary: Delete source by name (query parameter)
+      parameters:
+        - in: query
+          name: name
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Deleted }
+
+  /content/sources/{id}:
+    delete:
+      tags: [Sources]
+      summary: Delete source by id
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Deleted }
+
+  /content/generate:
+    post:
+      tags: [Content]
+      summary: Generate Studio content (audio, video, infographic, report, presentation, data table)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/GenerateRequest' }
+      responses:
+        '200': { description: Generated artifact metadata }
+
+  /content/download:
+    get:
+      tags: [Content]
+      summary: Download a generated artifact (WAV, MP4, PNG)
+      parameters:
+        - in: query
+          name: content_id
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Binary file }
+
+  /content:
+    get:
+      tags: [Content]
+      summary: List sources and generated content for the active notebook
+      responses:
+        '200': { description: Content list }
+
+  /content/notes:
+    post:
+      tags: [Content]
+      summary: Create a note in the active notebook
+      responses:
+        '200': { description: Note created }
+
+  /content/chat-to-note:
+    post:
+      tags: [Content]
+      summary: Save the current chat discussion as a note
+      responses:
+        '200': { description: Note saved }
+
+  /content/notes/{noteTitle}/to-source:
+    post:
+      tags: [Content]
+      summary: Convert a note into a NotebookLM source
+      parameters:
+        - in: path
+          name: noteTitle
+          required: true
+          schema: { type: string }
+      responses:
+        '200': { description: Note converted to source }
+
+  /cleanup-data:
+    post:
+      tags: [Auth]
+      summary: Wipe all local data (requires confirmation)
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                confirm: { type: boolean }
+      responses:
+        '200': { description: Cleaned }
+
+components:
+  schemas:
+    Health:
+      type: object
+      properties:
+        status: { type: string, example: ok }
+        uptime_s: { type: number }
+        active_sessions: { type: integer }
+        version: { type: string, example: 1.5.9 }
+
+    Result:
+      type: object
+      properties:
+        success: { type: boolean }
+        message: { type: string }
+        error: { type: string }
+
+    AskRequest:
+      type: object
+      required: [question]
+      properties:
+        question:
+          type: string
+          example: 'Summarize chapter 3'
+        notebook_id:
+          type: string
+        notebook_url:
+          type: string
+        session_id:
+          type: string
+        source_format:
+          type: string
+          enum: [none, inline, footnotes, json, expanded]
+          default: json
+        show_browser:
+          type: boolean
+          default: false
+
+    AskResponse:
+      type: object
+      properties:
+        success: { type: boolean }
+        answer: { type: string }
+        citations:
+          type: array
+          items:
+            type: object
+            properties:
+              id: { type: integer }
+              source: { type: string }
+              excerpt: { type: string }
+        session_id: { type: string }
+
+    AddSourceRequest:
+      type: object
+      required: [source_type]
+      properties:
+        source_type:
+          type: string
+          enum: [file, url, text, youtube, drive]
+        file_path: { type: string }
+        url: { type: string }
+        text: { type: string }
+        title: { type: string }
+        notebook_url: { type: string }
+        session_id: { type: string }
+
+    GenerateRequest:
+      type: object
+      required: [content_type]
+      properties:
+        content_type:
+          type: string
+          enum:
+            - audio_overview
+            - video
+            - infographic
+            - report
+            - presentation
+            - data_table
+        language: { type: string, example: en }
+        custom_instructions: { type: string }
+        video_style:
+          type: string
+          enum: [classroom, documentary, animated, corporate, cinematic, minimalist]
+        video_format:
+          type: string
+          enum: [brief, explainer]
+        infographic_format:
+          type: string
+          enum: [horizontal, vertical]
+        report_format:
+          type: string
+          enum: [summary, detailed]
+        presentation_style:
+          type: string
+          enum: [overview, detailed]
+        presentation_length:
+          type: string
+          enum: [short, medium, long]

package/dist/http-wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-wrapper.d.ts","sourceRoot":"","sources":["../src/http-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAeH,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,SAAS,EAAE,MAAM,CAAC;SACnB;KACF;CACF"}
+{"version":3,"file":"http-wrapper.d.ts","sourceRoot":"","sources":["../src/http-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,SAAS,EAAE,MAAM,CAAC;SACnB;KACF;CACF"}

package/dist/http-wrapper.js

@@ -8,6 +8,8 @@ import express from 'express';
 import { randomUUID } from 'crypto';
 import net from 'net';
 import { execSync } from 'child_process';
+import { promises as fs } from 'fs';
+import path from 'path';
 import { AuthManager } from './auth/auth-manager.js';
 import { SessionManager } from './session/session-manager.js';
 import { NotebookLibrary } from './library/notebook-library.js';
@@ -15,6 +17,7 @@ import { ToolHandlers } from './tools/index.js';
 import { AutoDiscovery } from './auto-discovery/auto-discovery.js';
 import { StartupManager } from './startup/startup-manager.js';
 import { log } from './utils/logger.js';
+import { formatAnswerJson, formatAnswerMarkdown, makeSlug, } from './utils/vault-writer.js';
 const app = express();
 app.use(express.json({ limit: '10mb' }));
 // Request ID middleware for debugging and log correlation
@@ -48,6 +51,7 @@ app.get('/', (_req, res) => {
         endpoints: {
             health: 'GET /health',
             ask: 'POST /ask',
+            batch_to_vault: 'POST /batch-to-vault',
             setup_auth: 'POST /setup-auth',
             notebooks: 'GET /notebooks',
             sessions: 'GET /sessions',
@@ -94,6 +98,117 @@ app.post('/ask', async (req, res) => {
         });
     }
 });
+// Batch-to-vault — run a list of questions and persist each answer as
+// markdown + JSON sidecar files, ready for ingestion by RTFM or any
+// markdown vault indexer. Conforms to the nblm-answer-v1 schema.
+app.post('/batch-to-vault', async (req, res) => {
+    const reqId = req.requestId.substring(0, 8);
+    try {
+        const { questions, notebook_id, notebook_url, vault_dir, slug_prefix = '', source_format = 'json', sleep_between_ms = 0, session_id, } = req.body;
+        if (!Array.isArray(questions) || questions.length === 0) {
+            return res.status(400).json({
+                success: false,
+                error: 'Missing or empty required field: questions (non-empty string array)',
+            });
+        }
+        if (!vault_dir || typeof vault_dir !== 'string') {
+            return res.status(400).json({
+                success: false,
+                error: 'Missing required field: vault_dir (absolute or relative directory path)',
+            });
+        }
+        const absVaultDir = path.resolve(vault_dir);
+        await fs.mkdir(absVaultDir, { recursive: true });
+        log.info(`[${reqId}] /batch-to-vault — ${questions.length} questions → ${absVaultDir}`);
+        const results = [];
+        let currentSession = session_id;
+        const notebookMeta = {};
+        for (let i = 0; i < questions.length; i++) {
+            const q = questions[i];
+            log.info(`[${reqId}] [${i + 1}/${questions.length}] ${String(q).substring(0, 80)}`);
+            try {
+                const askResult = await toolHandlers.handleAskQuestion({
+                    question: q,
+                    session_id: currentSession,
+                    notebook_id,
+                    notebook_url,
+                    source_format,
+                }, async () => { });
+                if (!askResult?.success || !askResult.data || askResult.data.status !== 'success') {
+                    const errMsg = askResult?.error ||
+                        (askResult?.data && 'error' in askResult.data ? askResult.data.error : 'Unknown error');
+                    results.push({
+                        question: q,
+                        md_path: '',
+                        json_path: '',
+                        success: false,
+                        citations_count: 0,
+                        error: errMsg,
+                    });
+                    continue;
+                }
+                const data = askResult.data;
+                if (data.session_id)
+                    currentSession = data.session_id;
+                if (!notebookMeta.url && data.notebook_url)
+                    notebookMeta.url = data.notebook_url;
+                if (!notebookMeta.id && notebook_id)
+                    notebookMeta.id = notebook_id;
+                const askedAt = new Date().toISOString();
+                const slug = makeSlug(q, slug_prefix, i);
+                const mdPath = path.join(absVaultDir, `${slug}.md`);
+                const jsonPath = path.join(absVaultDir, `${slug}.json`);
+                const markdown = formatAnswerMarkdown(data, notebookMeta, askedAt);
+                const jsonPayload = formatAnswerJson(data, notebookMeta, askedAt);
+                await fs.writeFile(mdPath, markdown, 'utf-8');
+                await fs.writeFile(jsonPath, JSON.stringify(jsonPayload, null, 2), 'utf-8');
+                results.push({
+                    question: q,
+                    md_path: mdPath,
+                    json_path: jsonPath,
+                    success: true,
+                    citations_count: data.sources?.citations.length ?? 0,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log.error(`[${reqId}] [${i + 1}] failed: ${msg}`);
+                results.push({
+                    question: q,
+                    md_path: '',
+                    json_path: '',
+                    success: false,
+                    citations_count: 0,
+                    error: msg,
+                });
+            }
+            if (sleep_between_ms > 0 && i < questions.length - 1) {
+                await new Promise((r) => setTimeout(r, sleep_between_ms));
+            }
+        }
+        const succeeded = results.filter((r) => r.success).length;
+        log.success(`[${reqId}] /batch-to-vault — ${succeeded}/${questions.length} written to ${absVaultDir}`);
+        res.json({
+            success: true,
+            data: {
+                vault_dir: absVaultDir,
+                total: questions.length,
+                succeeded,
+                failed: questions.length - succeeded,
+                session_id: currentSession,
+                notebook: notebookMeta,
+                files: results,
+            },
+        });
+    }
+    catch (error) {
+        log.error(`[${reqId}] /batch-to-vault - Error: ${error instanceof Error ? error.message : String(error)}`);
+        res.status(500).json({
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+});
 // Setup auth
 app.post('/setup-auth', async (req, res) => {
     try {