list_notebooks

Instructions

Implementation Reference

• src/lib/tools/list-notebooks.ts:3-39 (handler)

  Core handler function: fetches all folders/notebooks from Joplin API, builds a hierarchical structure by parent_id, formats as indented list with IDs, handles errors.

  class ListNotebooks extends BaseTool {
    async call(): Promise<string> {
      try {
        const notebooks = await this.apiClient.getAllItems<JoplinFolder>("/folders", {
          query: { fields: "id,title,parent_id" },
        })
  
        const notebooksByParentId: Record<string, JoplinFolder[]> = {}
  
        notebooks.forEach((notebook) => {
          const parentId = notebook.parent_id || ""
          if (!notebooksByParentId[parentId]) {
            notebooksByParentId[parentId] = []
          }
          notebooksByParentId[parentId].push(notebook)
        })
  
        // Add a header with instructions
        const resultLines = [
          "Joplin Notebooks:\n",
          "NOTE: To read a notebook, use the notebook_id with the read_notebook command\n",
          'Example: read_notebook notebook_id="your-notebook-id"\n\n',
        ]
  
        // Add the notebook hierarchy
        resultLines.push(
          ...this.notebooksLines(notebooksByParentId[""] || [], {
            indent: 0,
            notebooksByParentId,
          }),
        )
  
        return resultLines.join("")
      } catch (error: unknown) {
        return this.formatError(error, "listing notebooks")
      }
    }

• src/lib/tools/list-notebooks.ts:41-70 (helper)

  Recursive helper to build indented hierarchical lines of notebooks.

  private notebooksLines(
    notebooks: JoplinFolder[],
    {
      indent = 0,
      notebooksByParentId,
    }: {
      indent: number
      notebooksByParentId: Record<string, JoplinFolder[]>
    },
  ): string[] {
    const result: string[] = []
    const indentSpaces = " ".repeat(indent)
  
    this.sortNotebooks(notebooks).forEach((notebook) => {
      const id = notebook.id
      result.push(`${indentSpaces}Notebook: "${notebook.title}" (notebook_id: "${id}")\n`)
  
      const childNotebooks = notebooksByParentId[id]
      if (childNotebooks) {
        result.push(
          ...this.notebooksLines(childNotebooks, {
            indent: indent + 2,
            notebooksByParentId,
          }),
        )
      }
    })
  
    return result
  }

• src/lib/tools/list-notebooks.ts:72-80 (helper)

  Helper to sort notebooks, special handling for titles starting with '['.

  private sortNotebooks(notebooks: JoplinFolder[]): JoplinFolder[] {
    // Ensure that notebooks starting with '[0]' are sorted first
    const CHARACTER_BEFORE_A = String.fromCharCode("A".charCodeAt(0) - 1)
    return [...notebooks].sort((a, b) => {
      const titleA = a.title.replace("[", CHARACTER_BEFORE_A)
      const titleB = b.title.replace("[", CHARACTER_BEFORE_A)
      return titleA.localeCompare(titleB)
    })
  }

• src/index.ts:80-86 (schema)

  Tool schema definition: no input parameters required.

    name: "list_notebooks",
    description: "Retrieve the complete notebook hierarchy from Joplin",
    inputSchema: {
      type: "object",
      properties: {},
    },
  },

• src/index.ts:225-228 (registration)

  MCP tool call registration: handles 'call_tool' requests for list_notebooks by delegating to manager.

  case "list_notebooks": {
    const listResult = await manager.listNotebooks()
    return { content: [{ type: "text", text: listResult }], isError: false }
  }