add_notebook

Instructions

Implementation Reference

• src/tools/handlers.ts:575-594 (handler)

  Main MCP tool handler for 'add_notebook'. Logs the call, delegates to NotebookLibrary.addNotebook, handles errors, and returns ToolResult.

  async handleAddNotebook(args: AddNotebookInput): Promise<ToolResult<{ notebook: any }>> {
    log.info(`🔧 [TOOL] add_notebook called`);
    log.info(`  Name: ${args.name}`);
  
    try {
      const notebook = this.library.addNotebook(args);
      log.success(`✅ [TOOL] add_notebook completed: ${notebook.id}`);
      return {
        success: true,
        data: { notebook },
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      log.error(`❌ [TOOL] add_notebook failed: ${errorMessage}`);
      return {
        success: false,
        error: errorMessage,
      };
    }
  }

• src/library/notebook-library.ts:138-175 (helper)

  Core implementation of adding a notebook: generates unique ID, creates NotebookEntry with defaults, appends to library, persists to JSON file.

  addNotebook(input: AddNotebookInput): NotebookEntry {
    log.info(`📝 Adding notebook: ${input.name}`);
  
    // Generate ID
    const id = this.generateId(input.name);
  
    // Create entry
    const notebook: NotebookEntry = {
      id,
      url: input.url,
      name: input.name,
      description: input.description,
      topics: input.topics,
      content_types: input.content_types || ["documentation", "examples"],
      use_cases: input.use_cases || [
        `Learning about ${input.name}`,
        `Implementing features with ${input.name}`,
      ],
      added_at: new Date().toISOString(),
      last_used: new Date().toISOString(),
      use_count: 0,
      tags: input.tags || [],
    };
  
    // Add to library
    const updated = { ...this.library };
    updated.notebooks.push(notebook);
  
    // Set as active if it's the first notebook
    if (updated.notebooks.length === 1) {
      updated.active_notebook_id = id;
    }
  
    this.saveLibrary(updated);
    log.success(`✅ Notebook added: ${id}`);
  
    return notebook;
  }

• src/library/types.ts:45-53 (schema)

  TypeScript interface defining the input parameters for add_notebook, used by handler and library method.

  export interface AddNotebookInput {
    url: string; // Required: NotebookLM URL
    name: string; // Required: Display name
    description: string; // Required: What's in it
    topics: string[]; // Required: Topics covered
    content_types?: string[]; // Optional: defaults to ["documentation", "examples"]
    use_cases?: string[]; // Optional: defaults based on description
    tags?: string[]; // Optional: custom tags
  }

• src/tools/definitions/notebook-management.ts:5-82 (registration)

  MCP Tool definition object for 'add_notebook' including detailed description, input schema, and usage instructions. Part of notebookManagementTools array.

      name: "add_notebook",
      description:
        `PERMISSION REQUIRED — Only when user explicitly asks to add a notebook.
  
  ## Conversation Workflow (Mandatory)
  When the user says: "I have a NotebookLM with X"
  
  1) Ask URL: "What is the NotebookLM URL?"
  2) Ask content: "What knowledge is inside?" (1–2 sentences)
  3) Ask topics: "Which topics does it cover?" (3–5)
  4) Ask use cases: "When should we consult it?"
  5) Propose metadata and confirm:
     - Name: [suggested]
     - Description: [from user]
     - Topics: [list]
     - Use cases: [list]
     "Add it to your library now?"
  6) Only after explicit "Yes" → call this tool
  
  ## Rules
  - Do not add without user permission
  - Do not guess metadata — ask concisely
  - Confirm summary before calling the tool
  
  ## Example
  User: "I have a notebook with n8n docs"
  You: Ask URL → content → topics → use cases; propose summary
  User: "Yes"
  You: Call add_notebook
  
  ## How to Get a NotebookLM Share Link
  
  Visit https://notebooklm.google/ → Login (free: 100 notebooks, 50 sources each, 500k words, 50 daily queries)
  1) Click "+ New" (top right) → Upload sources (docs, knowledge)
  2) Click "Share" (top right) → Select "Anyone with the link"
  3) Click "Copy link" (bottom left) → Give this link to Claude
  
  (Upgraded: Google AI Pro/Ultra gives 5x higher limits)`,
      inputSchema: {
        type: "object",
        properties: {
          url: {
            type: "string",
            description: "The NotebookLM notebook URL",
          },
          name: {
            type: "string",
            description: "Display name for the notebook (e.g., 'n8n Documentation')",
          },
          description: {
            type: "string",
            description: "What knowledge/content is in this notebook",
          },
          topics: {
            type: "array",
            items: { type: "string" },
            description: "Topics covered in this notebook",
          },
          content_types: {
            type: "array",
            items: { type: "string" },
            description:
              "Types of content (e.g., ['documentation', 'examples', 'best practices'])",
          },
          use_cases: {
            type: "array",
            items: { type: "string" },
            description: "When should Claude use this notebook (e.g., ['Implementing n8n workflows'])",
          },
          tags: {
            type: "array",
            items: { type: "string" },
            description: "Optional tags for organization",
          },
        },
        required: ["url", "name", "description", "topics"],
      },
    },

• src/index.ts:171-182 (registration)

  Dispatch logic in main MCP server that routes 'add_notebook' tool calls to the appropriate handler method.

  case "add_notebook":
    result = await this.toolHandlers.handleAddNotebook(
      args as {
        url: string;
        name: string;
        description: string;
        topics: string[];
        content_types?: string[];
        use_cases?: string[];
        tags?: string[];
      }
    );