joplin-mcp-server

Instructions

Implementation Reference

• src/lib/tools/read-note.ts:4-90 (handler)

  Core handler logic in ReadNote.call(): validates note ID, fetches note and parent notebook details via Joplin API, formats metadata, todo status, timestamps, body content, and helpful commands.

  async call(noteId: string): Promise<string> {
    const validationError = this.validateId(noteId, "note")
    if (validationError) {
      return validationError
    }
  
    try {
      // Get the note details with all relevant fields
      const note = await this.apiClient.get<JoplinNote>(`/notes/${noteId}`, {
        query: {
          fields: "id,title,body,parent_id,created_time,updated_time,is_todo,todo_completed,todo_due",
        },
      })
  
      // Validate note response
      if (!note || typeof note !== "object" || !note.id) {
        return `Error: Unexpected response format from Joplin API when fetching note`
      }
  
      // Get the notebook info to show where this note is located
      let notebookInfo = "Unknown notebook"
      if (note.parent_id) {
        try {
          const notebook = await this.apiClient.get<JoplinFolder>(`/folders/${note.parent_id}`, {
            query: { fields: "id,title" },
          })
          if (notebook && notebook.title) {
            notebookInfo = `"${notebook.title}" (notebook_id: "${note.parent_id}")`
          }
        } catch (err: unknown) {
          process.stderr.write(`Error fetching notebook info: ${err}\n`)
          // Continue even if we can't get the notebook info
        }
      }
  
      // Format the note content
      const resultLines: string[] = []
  
      // Add note header with metadata
      resultLines.push(`# Note: "${note.title}"`)
      resultLines.push(`Note ID: ${note.id}`)
      resultLines.push(`Notebook: ${notebookInfo}`)
  
      // Add todo status if applicable
      if (note.is_todo) {
        const status = note.todo_completed ? "Completed" : "Not completed"
        resultLines.push(`Status: ${status}`)
  
        if (note.todo_due) {
          const dueDate = this.formatDate(note.todo_due)
          resultLines.push(`Due: ${dueDate}`)
        }
      }
  
      // Add timestamps
      const createdDate = this.formatDate(note.created_time)
      const updatedDate = this.formatDate(note.updated_time)
      resultLines.push(`Created: ${createdDate}`)
      resultLines.push(`Updated: ${updatedDate}`)
  
      // Add a separator before the note content
      resultLines.push("\n---\n")
  
      // Add the note body
      if (note.body) {
        resultLines.push(note.body)
      } else {
        resultLines.push("(This note has no content)")
      }
  
      // Add a footer with helpful commands
      resultLines.push("\n---\n")
      resultLines.push("Related commands:")
      resultLines.push(`- To view the notebook containing this note: read_notebook notebook_id="${note.parent_id}"`)
      resultLines.push('- To search for more notes: search_notes query="your search term"')
  
      return resultLines.join("\n")
    } catch (error: any) {
      if (error.response && error.response.status === 404) {
        return `Note with ID "${noteId}" not found.\n\nThis might happen if:\n1. The ID is incorrect\n2. You're using a notebook ID instead of a note ID\n3. The note has been deleted\n\nUse search_notes to find notes and their IDs.`
      }
      return (
        this.formatError(error, "reading note") +
        `\n\nMake sure you're using a valid note ID.\nUse search_notes to find notes and their IDs.`
      )
    }
  }

• src/server-fastmcp.ts:79-89 (registration)

  Registers the read_note tool with FastMCP server, defining name, description, input schema (note_id), and execution delegating to manager.readNote.

  // Add read_note tool
  server.addTool({
    name: "read_note",
    description: "Read the full content of a specific note",
    parameters: z.object({
      note_id: z.string().describe("ID of the note to read"),
    }),
    execute: async (args) => {
      return await manager.readNote(args.note_id)
    },
  })

• src/server-fastmcp.ts:83-85 (schema)

  Zod schema for tool input: requires note_id as string.

  parameters: z.object({
    note_id: z.string().describe("ID of the note to read"),
  }),

• src/server-core.ts:78-80 (helper)

  JoplinServerManager.readNote(): delegates execution to the ReadNote tool instance.

  async readNote(noteId: string): Promise<string> {
    return await this.tools.readNote.call(noteId)
  }

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

  Instantiates ReadNote tool with API client in JoplinServerManager constructor.

  readNote: new ReadNote(this.apiClient),