joplin-mcp-server

Instructions

Implementation Reference

• src/lib/tools/create-note.ts:14-103 (handler)

  Core implementation of the create_note tool: CreateNote class extending BaseTool with the async call(options) method that handles note creation via Joplin API, validation, error handling, and formatted response.

  class CreateNote extends BaseTool {
    async call(options: CreateNoteOptions): Promise<string> {
      if (!options || typeof options !== "object") {
        return 'Please provide note creation options. Example: create_note {"title": "My Note", "body": "Note content"}'
      }
  
      // Validate that we have at least a title or body
      if (!options.title && !options.body && !options.body_html) {
        return "Please provide at least a title, body, or body_html for the note."
      }
  
      // Validate parent_id if provided
      if (options.parent_id && (options.parent_id.length < 10 || !options.parent_id.match(/[a-f0-9]/i))) {
        return `Error: "${options.parent_id}" does not appear to be a valid notebook ID.\n\nNotebook IDs are long alphanumeric strings like "58a0a29f68bc4141b49c99f5d367638a".\n\nUse list_notebooks to see available notebooks and their IDs.`
      }
  
      try {
        // Prepare the request body
        const requestBody: CreateNoteOptions = {}
  
        if (options.title) requestBody.title = options.title
        if (options.body) requestBody.body = options.body
        if (options.body_html) requestBody.body_html = options.body_html
        if (options.parent_id) requestBody.parent_id = options.parent_id
        if (options.is_todo !== undefined) requestBody.is_todo = options.is_todo
        if (options.image_data_url) requestBody.image_data_url = options.image_data_url
  
        // Create the note
        const createdNote = await this.apiClient.post<CreateNoteResponse>("/notes", requestBody)
  
        // Validate response
        if (!createdNote || typeof createdNote !== "object" || !createdNote.id) {
          return "Error: Unexpected response format from Joplin API when creating note"
        }
  
        // Get notebook info if available
        let notebookInfo = "Root level"
        if (createdNote.parent_id) {
          try {
            const notebook = await this.apiClient.get(`/folders/${createdNote.parent_id}`, {
              query: { fields: "id,title" },
            })
            if (notebook && notebook.title) {
              notebookInfo = `"${notebook.title}" (notebook_id: "${createdNote.parent_id}")`
            }
          } catch {
            // Continue even if we can't get notebook info
            notebookInfo = `Notebook ID: ${createdNote.parent_id}`
          }
        }
  
        // Format success response
        const resultLines: string[] = []
        resultLines.push(`✅ Successfully created note!`)
        resultLines.push("")
        resultLines.push(`📝 Note Details:`)
        resultLines.push(`   Title: "${createdNote.title || "Untitled"}"`)
        resultLines.push(`   Note ID: ${createdNote.id}`)
        resultLines.push(`   Location: ${notebookInfo}`)
  
        if (createdNote.is_todo) {
          resultLines.push(`   Type: Todo item`)
        }
  
        const createdDate = this.formatDate(createdNote.created_time)
        resultLines.push(`   Created: ${createdDate}`)
  
        resultLines.push("")
        resultLines.push(`🔗 Next steps:`)
        resultLines.push(`   - Read the note: read_note note_id="${createdNote.id}"`)
        if (createdNote.parent_id) {
          resultLines.push(`   - View notebook: read_notebook notebook_id="${createdNote.parent_id}"`)
        }
        resultLines.push(`   - Search for it: search_notes query="${createdNote.title}"`)
  
        return resultLines.join("\n")
      } catch (error: any) {
        if (error.response) {
          // Handle specific API errors
          if (error.response.status === 400) {
            return `Error creating note: Invalid request data.\n\nPlease check your input parameters. ${error.response.data?.error || ""}`
          }
          if (error.response.status === 404 && options.parent_id) {
            return `Error: Notebook with ID "${options.parent_id}" not found.\n\nUse list_notebooks to see available notebooks and their IDs.`
          }
        }
        return this.formatError(error, "creating note")
      }
    }
  }

• src/lib/tools/create-note.ts:3-10 (schema)

  TypeScript interface defining the input parameters for the create_note tool.

  interface CreateNoteOptions {
    title?: string | undefined
    body?: string | undefined
    body_html?: string | undefined
    parent_id?: string | undefined
    is_todo?: boolean | undefined
    image_data_url?: string | undefined
  }

• src/server-fastmcp.ts:104-118 (registration)

  Registration of create_note tool in FastMCP server, including Zod input schema and execution delegating to JoplinServerManager.createNote.

  server.addTool({
    name: "create_note",
    description: "Create a new note in Joplin",
    parameters: z.object({
      title: z.string().optional().describe("Note title"),
      body: z.string().optional().describe("Note content in Markdown"),
      body_html: z.string().optional().describe("Note content in HTML"),
      parent_id: z.string().optional().describe("ID of parent notebook"),
      is_todo: z.boolean().optional().describe("Whether this is a todo note"),
      image_data_url: z.string().optional().describe("Base64 encoded image data URL"),
    }),
    execute: async (args) => {
      return await manager.createNote(args)
    },
  })

• src/index.ts:132-145 (registration)

  Tool schema registration for create_note in the stdio MCP server's ListTools response.

    name: "create_note",
    description: "Create a new note in Joplin",
    inputSchema: {
      type: "object",
      properties: {
        title: { type: "string", description: "Note title" },
        body: { type: "string", description: "Note content in Markdown" },
        body_html: { type: "string", description: "Note content in HTML" },
        parent_id: { type: "string", description: "ID of parent notebook" },
        is_todo: { type: "boolean", description: "Whether this is a todo note" },
        image_data_url: { type: "string", description: "Base64 encoded image data URL" },
      },
    },
  },

• src/server-core.ts:86-95 (helper)

  JoplinServerManager wrapper method for createNote that delegates to the instantiated CreateNote tool instance.

  async createNote(params: {
    title?: string | undefined
    body?: string | undefined
    body_html?: string | undefined
    parent_id?: string | undefined
    is_todo?: boolean | undefined
    image_data_url?: string | undefined
  }): Promise<string> {
    return await this.tools.createNote.call(params)
  }