Project Notebook Binding

Project Notebook Binding (ADR-017)

To prevent confusion across multiple client projects and eliminate manual notebook selection in every session while maintaining user control, the MCP gateway supports Project-Level Notebook Binding via .notebook_mcp.json.

---

How It Works

1. Config File Location: Stored in your workspace root as .notebook_mcp.json:

   {
     "notebook_id": "00000000-0000-0000-0000-000000000001",
     "title": "My Project Knowledge Base",
     "updated_at": 1728800000.0
   }

2. Automatic Guidance on Startup (SESSION_UNLOCKED): When an AI agent attempts to run a notebook operation before selecting a notebook, the gateway inspects .notebook_mcp.json and returns:
   • If .notebook_mcp.json exists:

     {
       "ok": false,
       "error": {
         "code": "SESSION_UNLOCKED",
         "message": "Gateway locked. This project is configured to use notebook 'My Project Knowledge Base'. Please ask the user to confirm, then call select_notebook.",
         "retryable": false
       }
     }

3. Conversational Confirmation Handshake: At the start of a chat, the AI assistant calls list_notebooks, discovers your project setting, and performs a conversational handshake:

   "This project is configured to use notebook 'My Project Knowledge Base'. Would you like to use this notebook, or select another from your allowlist?"

4. Persistent Project Selection: When calling select_notebook:
   • save_for_project: true (default): Persists the choice into .notebook_mcp.json in the current project root, ensuring future sessions recall this choice.
   • save_for_project: false: Locks the current session only without updating .notebook_mcp.json.

---

Recommended AI Client Prompt Rule

Add this instruction to your project's AGENTS.md, .cursorrules, or system prompt:

### NotebookLM MCP Session Initialization Rule
When starting any task that interacts with Google NotebookLM via the `gemini-notebook` MCP:
1. Call `list_notebooks` to check available notebooks and the project default in `.notebook_mcp.json`.
2. Always ask the user to confirm the active notebook before proceeding:
   > "This project is set to use notebook **[Title]**. Would you like to use this notebook, or select another from your allowlist?"
3. Upon confirmation or selection, invoke `select_notebook(notebook_id=..., save_for_project=true)`.
4. Proceed with `query_notebook`, `create_note`, `add_source`, etc.