joplin-mcp-server 1.0.0

package/dist/lib/joplin-api-client.js

@@ -0,0 +1,110 @@
+import axios from "axios";
+class JoplinAPIClient {
+    baseURL;
+    token;
+    constructor({ port = 41184, token }) {
+        this.baseURL = `http://127.0.0.1:${port}`;
+        this.token = token;
+    }
+    async serviceAvailable() {
+        try {
+            const response = await axios.get(`${this.baseURL}/ping`);
+            return response.status === 200 && response.data === "JoplinClipperServer";
+        }
+        catch (error) {
+            process.stderr.write(`Error checking Joplin service availability: ${error}\n`);
+            return false;
+        }
+    }
+    async getAllItems(path, options = {}) {
+        let page = 1;
+        const items = [];
+        try {
+            while (true) {
+                const response = await this.get(path, this.mergeRequestOptions(options, { query: { page } }));
+                // Validate response format
+                if (!response || typeof response !== "object" || !Array.isArray(response.items)) {
+                    throw new Error(`Unexpected response format from Joplin API for path: ${path}`);
+                }
+                items.push(...response.items);
+                page += 1;
+                if (!response.has_more)
+                    break;
+            }
+            return items;
+        }
+        catch (error) {
+            process.stderr.write(`Error in getAllItems for path ${path}: ${error}\n`);
+            throw error;
+        }
+    }
+    async get(path, options = {}) {
+        try {
+            const { data } = await axios.get(`${this.baseURL}${path}`, {
+                params: this.requestOptions(options).query,
+            });
+            return data;
+        }
+        catch (error) {
+            process.stderr.write(`Error in GET request for path ${path}: ${error}\n`);
+            throw error;
+        }
+    }
+    async post(path, body, options = {}) {
+        try {
+            const { data } = await axios.post(`${this.baseURL}${path}`, body, {
+                params: this.requestOptions(options).query,
+            });
+            return data;
+        }
+        catch (error) {
+            process.stderr.write(`Error in POST request for path ${path}: ${error}\n`);
+            throw error;
+        }
+    }
+    async delete(path, options = {}) {
+        try {
+            const { data } = await axios.delete(`${this.baseURL}${path}`, {
+                params: this.requestOptions(options).query,
+            });
+            return data;
+        }
+        catch (error) {
+            process.stderr.write(`Error in DELETE request for path ${path}: ${error}\n`);
+            throw error;
+        }
+    }
+    async put(path, body, options = {}) {
+        try {
+            const { data } = await axios.put(`${this.baseURL}${path}`, body, {
+                params: this.requestOptions(options).query,
+            });
+            return data;
+        }
+        catch (error) {
+            process.stderr.write(`Error in PUT request for path ${path}: ${error}\n`);
+            throw error;
+        }
+    }
+    requestOptions(options = {}) {
+        return this.mergeRequestOptions({
+            query: { token: this.token },
+        }, options);
+    }
+    mergeRequestOptions(options1, options2) {
+        return {
+            query: {
+                ...(options1.query || {}),
+                ...(options2.query || {}),
+            },
+            ...this.except(options1, "query"),
+            ...this.except(options2, "query"),
+        };
+    }
+    except(obj, key) {
+        const result = { ...obj };
+        delete result[key];
+        return result;
+    }
+}
+export default JoplinAPIClient;

package/dist/lib/logger.d.ts

@@ -0,0 +1,21 @@
+type LogLevel = "error" | "warn" | "info" | "debug";
+interface LoggerOptions {
+    logLevel?: LogLevel;
+    enableTimestamp?: boolean;
+}
+declare class Logger {
+    private readonly logLevel;
+    private readonly logLevels;
+    private readonly enableTimestamp;
+    constructor(options?: LoggerOptions);
+    getTimestamp(): string;
+    formatMessage(level: LogLevel, message: string): string;
+    shouldLog(level: LogLevel): boolean;
+    error(message: string): void;
+    warn(message: string): void;
+    info(message: string): void;
+    debug(message: string): void;
+    logObject(level: LogLevel, label: string, obj: any): void;
+}
+declare const logger: Logger;
+export default logger;

package/dist/lib/logger.js

@@ -0,0 +1,68 @@
+class Logger {
+    logLevel;
+    logLevels;
+    enableTimestamp;
+    constructor(options = {}) {
+        this.logLevel = options.logLevel || "info";
+        this.logLevels = {
+            error: 0,
+            warn: 1,
+            info: 2,
+            debug: 3,
+        };
+        this.enableTimestamp = options.enableTimestamp !== false;
+    }
+    getTimestamp() {
+        return new Date().toISOString();
+    }
+    formatMessage(level, message) {
+        const timestamp = this.enableTimestamp ? `[${this.getTimestamp()}] ` : "";
+        return `${timestamp}[${level.toUpperCase()}] ${message}`;
+    }
+    shouldLog(level) {
+        return this.logLevels[level] <= this.logLevels[this.logLevel];
+    }
+    error(message) {
+        if (this.shouldLog("error")) {
+            console.error(this.formatMessage("error", message));
+        }
+    }
+    warn(message) {
+        if (this.shouldLog("warn")) {
+            console.warn(this.formatMessage("warn", message));
+        }
+    }
+    info(message) {
+        if (this.shouldLog("info")) {
+            console.info(this.formatMessage("info", message));
+        }
+    }
+    debug(message) {
+        if (this.shouldLog("debug")) {
+            console.debug(this.formatMessage("debug", message));
+        }
+    }
+    logObject(level, label, obj) {
+        if (this.shouldLog(level)) {
+            const message = `${label}: ${JSON.stringify(obj, null, 2)}`;
+            switch (level) {
+                case "error":
+                    this.error(message);
+                    break;
+                case "warn":
+                    this.warn(message);
+                    break;
+                case "info":
+                    this.info(message);
+                    break;
+                case "debug":
+                    this.debug(message);
+                    break;
+                default:
+                    this.info(message);
+            }
+        }
+    }
+}
+const logger = new Logger({ logLevel: process.env.LOG_LEVEL || "info" });
+export default logger;

package/dist/lib/parse-args.d.ts

@@ -0,0 +1,2 @@
+declare function parseArgs(): string[];
+export default parseArgs;

package/dist/lib/parse-args.js

@@ -0,0 +1,81 @@
+import dotenv from "dotenv";
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function parseArgs() {
+    const args = process.argv.slice(2);
+    // Handle --env-file
+    if (args.includes("--env-file")) {
+        const envFileIndex = args.indexOf("--env-file");
+        const envFile = args[envFileIndex + 1];
+        if (!envFile || envFile.startsWith("--")) {
+            process.stderr.write("Error: --env-file requires a file path\n");
+            process.exit(1);
+        }
+        // Remove the --env-file and its value from args
+        args.splice(envFileIndex, 2);
+        // Load the environment variables from the specified file
+        dotenv.config({ path: resolve(process.cwd(), envFile) });
+    }
+    else {
+        // Load from default .env file
+        dotenv.config();
+    }
+    // Handle --port
+    if (args.includes("--port")) {
+        const portIndex = args.indexOf("--port");
+        const port = args[portIndex + 1];
+        if (!port || port.startsWith("--")) {
+            process.stderr.write("Error: --port requires a port number\n");
+            process.exit(1);
+        }
+        // Remove the --port and its value from args
+        args.splice(portIndex, 2);
+        // Set environment variable
+        process.env.JOPLIN_PORT = port;
+    }
+    // Handle --token
+    if (args.includes("--token")) {
+        const tokenIndex = args.indexOf("--token");
+        const token = args[tokenIndex + 1];
+        if (!token || token.startsWith("--")) {
+            process.stderr.write("Error: --token requires a token value\n");
+            process.exit(1);
+        }
+        // Remove the --token and its value from args
+        args.splice(tokenIndex, 2);
+        // Set environment variable
+        process.env.JOPLIN_TOKEN = token;
+    }
+    // Handle --help
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stderr.write(`
+Joplin MCP Server
+
+USAGE:
+  joplin-mcp-server [OPTIONS]
+
+OPTIONS:
+  --env-file <file>    Load environment variables from file
+  --port <port>        Joplin port (default: 41184)
+  --token <token>      Joplin API token
+  --help, -h           Show this help message
+
+ENVIRONMENT VARIABLES:
+  JOPLIN_PORT          Joplin port (default: 41184)
+  JOPLIN_TOKEN         Joplin API token (required)
+  LOG_LEVEL           Log level: debug, info, warn, error (default: info)
+
+EXAMPLES:
+  joplin-mcp-server --port 41184 --token your_token
+  joplin-mcp-server --env-file /path/to/.env
+  joplin-mcp-server --env-file .env.local --port 41185
+
+Find your Joplin token in: Tools > Options > Web Clipper
+`);
+        process.exit(0);
+    }
+    return args;
+}
+export default parseArgs;

package/dist/lib/tools/base-tool.d.ts

@@ -0,0 +1,27 @@
+import JoplinAPIClient from "../joplin-api-client.js";
+interface JoplinFolder {
+    id: string;
+    title: string;
+    parent_id?: string;
+}
+interface JoplinNote {
+    id: string;
+    title: string;
+    body?: string;
+    parent_id?: string;
+    created_time: number;
+    updated_time: number;
+    is_todo: boolean;
+    todo_completed?: boolean;
+    todo_due?: number;
+}
+declare abstract class BaseTool {
+    protected apiClient: JoplinAPIClient;
+    constructor(apiClient: JoplinAPIClient);
+    abstract call(...args: any[]): Promise<string>;
+    protected formatError(error: any, context: string): string;
+    protected validateId(id: string, type: "note" | "notebook"): string | null;
+    protected formatDate(timestamp: number): string;
+}
+export default BaseTool;
+export type { JoplinFolder, JoplinNote };

package/dist/lib/tools/base-tool.js

@@ -0,0 +1,24 @@
+class BaseTool {
+    apiClient;
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    formatError(error, context) {
+        process.stderr.write(`${context} error: ${error}\n`);
+        return `Error ${context.toLowerCase()}: ${error.message || "Unknown error"}`;
+    }
+    validateId(id, type) {
+        if (!id) {
+            return `Please provide a ${type} ID. Example: ${type === "note" ? "read_note" : "read_notebook"} ${type}_id="your-${type}-id"`;
+        }
+        if (id.length < 10 || !id.match(/[a-f0-9]/i)) {
+            const searchHint = type === "note" ? "search_notes" : "list_notebooks";
+            return `Error: "${id}" does not appear to be a valid ${type} ID. \n\n${type.charAt(0).toUpperCase() + type.slice(1)} IDs are long alphanumeric strings like "58a0a29f68bc4141b49c99f5d367638a".\n\nUse ${searchHint} to ${type === "note" ? "find notes" : "see all available notebooks"} and their IDs.`;
+        }
+        return null;
+    }
+    formatDate(timestamp) {
+        return new Date(timestamp).toLocaleString();
+    }
+}
+export default BaseTool;

package/dist/lib/tools/create-folder.d.ts

@@ -0,0 +1,9 @@
+import BaseTool from "./base-tool.js";
+interface CreateFolderOptions {
+    title: string;
+    parent_id?: string | undefined;
+}
+declare class CreateFolder extends BaseTool {
+    call(options: CreateFolderOptions): Promise<string>;
+}
+export default CreateFolder;

package/dist/lib/tools/create-folder.js

@@ -0,0 +1,79 @@
+import BaseTool from "./base-tool.js";
+class CreateFolder extends BaseTool {
+    async call(options) {
+        if (!options || typeof options !== "object") {
+            return 'Please provide folder creation options. Example: create_folder {"title": "My Notebook"}';
+        }
+        // Validate required title
+        if (!options.title || typeof options.title !== "string" || options.title.trim() === "") {
+            return 'Please provide a title for the folder/notebook. Example: create_folder {"title": "My Notebook"}';
+        }
+        // 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 parent notebook ID.\n\nNotebook IDs are long alphanumeric strings like "58a0a29f68bc4141b49c99f5d367638a".\n\nUse list_notebooks to see available notebooks and their IDs, or omit parent_id to create a top-level notebook.`;
+        }
+        try {
+            // Prepare the request body
+            const requestBody = {
+                title: options.title.trim(),
+            };
+            if (options.parent_id) {
+                requestBody.parent_id = options.parent_id;
+            }
+            // Create the folder
+            const createdFolder = await this.apiClient.post("/folders", requestBody);
+            // Validate response
+            if (!createdFolder || typeof createdFolder !== "object" || !createdFolder.id) {
+                return "Error: Unexpected response format from Joplin API when creating folder";
+            }
+            // Get parent notebook info if available
+            let parentInfo = "Top level";
+            if (createdFolder.parent_id) {
+                try {
+                    const parentNotebook = await this.apiClient.get(`/folders/${createdFolder.parent_id}`, {
+                        query: { fields: "id,title" },
+                    });
+                    if (parentNotebook && parentNotebook.title) {
+                        parentInfo = `Inside "${parentNotebook.title}" (notebook_id: "${createdFolder.parent_id}")`;
+                    }
+                }
+                catch (error) {
+                    // Continue even if we can't get parent info
+                    parentInfo = `Parent notebook ID: ${createdFolder.parent_id}`;
+                }
+            }
+            // Format success response
+            const resultLines = [];
+            resultLines.push(`✅ Successfully created notebook!`);
+            resultLines.push("");
+            resultLines.push(`📁 Notebook Details:`);
+            resultLines.push(`   Title: "${createdFolder.title}"`);
+            resultLines.push(`   Notebook ID: ${createdFolder.id}`);
+            resultLines.push(`   Location: ${parentInfo}`);
+            const createdDate = this.formatDate(createdFolder.created_time);
+            resultLines.push(`   Created: ${createdDate}`);
+            resultLines.push("");
+            resultLines.push(`🔗 Next steps:`);
+            resultLines.push(`   - View notebook: read_notebook notebook_id="${createdFolder.id}"`);
+            resultLines.push(`   - Create a note in it: create_note {"title": "My Note", "parent_id": "${createdFolder.id}"}`);
+            resultLines.push(`   - View all notebooks: list_notebooks`);
+            return resultLines.join("\n");
+        }
+        catch (error) {
+            if (error.response) {
+                // Handle specific API errors
+                if (error.response.status === 400) {
+                    return `Error creating notebook: Invalid request data.\n\nPlease check your input parameters. ${error.response.data?.error || ""}`;
+                }
+                if (error.response.status === 404 && options.parent_id) {
+                    return `Error: Parent notebook with ID "${options.parent_id}" not found.\n\nUse list_notebooks to see available notebooks and their IDs, or omit parent_id to create a top-level notebook.`;
+                }
+                if (error.response.status === 409) {
+                    return `Error: A notebook with the title "${options.title}" might already exist in this location.\n\nTry a different title or check existing notebooks with list_notebooks.`;
+                }
+            }
+            return this.formatError(error, "creating notebook");
+        }
+    }
+}
+export default CreateFolder;

package/dist/lib/tools/create-note.d.ts

@@ -0,0 +1,13 @@
+import BaseTool from "./base-tool.js";
+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;
+}
+declare class CreateNote extends BaseTool {
+    call(options: CreateNoteOptions): Promise<string>;
+}
+export default CreateNote;

package/dist/lib/tools/create-note.js

@@ -0,0 +1,88 @@
+import BaseTool from "./base-tool.js";
+class CreateNote extends BaseTool {
+    async call(options) {
+        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 = {};
+            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("/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 (error) {
+                    // Continue even if we can't get notebook info
+                    notebookInfo = `Notebook ID: ${createdNote.parent_id}`;
+                }
+            }
+            // Format success response
+            const resultLines = [];
+            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) {
+            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");
+        }
+    }
+}
+export default CreateNote;

package/dist/lib/tools/delete-folder.d.ts

@@ -0,0 +1,10 @@
+import BaseTool from "./base-tool.js";
+interface DeleteFolderOptions {
+    folder_id: string;
+    confirm?: boolean | undefined;
+    force?: boolean | undefined;
+}
+declare class DeleteFolder extends BaseTool {
+    call(options: DeleteFolderOptions): Promise<string>;
+}
+export default DeleteFolder;