joplin-mcp-server 1.0.0

package/dist/tests/unit/edit-tools.test.js

@@ -0,0 +1,261 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import JoplinAPIClient from "../../lib/joplin-api-client.js";
+import EditNote from "../../lib/tools/edit-note.js";
+import EditFolder from "../../lib/tools/edit-folder.js";
+// Mock JoplinAPIClient
+vi.mock("../../lib/joplin-api-client.js", () => {
+    const mockClient = {
+        get: vi.fn(),
+        put: vi.fn(),
+    };
+    return { default: vi.fn(() => mockClient) };
+});
+describe("Edit Tools", () => {
+    let mockApiClient;
+    let editNote;
+    let editFolder;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockApiClient = new JoplinAPIClient({ token: "test-token" });
+        editNote = new EditNote(mockApiClient);
+        editFolder = new EditFolder(mockApiClient);
+    });
+    describe("EditNote", () => {
+        const mockCurrentNote = {
+            id: "note-123",
+            title: "Original Title",
+            body: "Original content",
+            parent_id: null,
+            is_todo: false,
+            todo_completed: false,
+            updated_time: 1234567890000,
+        };
+        const mockUpdatedNote = {
+            id: "note-123",
+            title: "Updated Title",
+            body: "Updated content",
+            parent_id: null,
+            is_todo: false,
+            todo_completed: false,
+            updated_time: 1234567891000,
+        };
+        it("should update note title", async () => {
+            mockApiClient.get.mockResolvedValue(mockCurrentNote);
+            mockApiClient.put.mockResolvedValue(mockUpdatedNote);
+            const result = await editNote.call({
+                note_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                title: "Updated Title",
+            });
+            expect(mockApiClient.get).toHaveBeenCalledWith("/notes/a1b2c3d4e5f6789012345678901234567890abcd", {
+                query: { fields: "id,title,body,parent_id,is_todo,todo_completed,todo_due,updated_time" },
+            });
+            expect(mockApiClient.put).toHaveBeenCalledWith("/notes/a1b2c3d4e5f6789012345678901234567890abcd", {
+                title: "Updated Title",
+            });
+            expect(result).toContain("✅ Successfully updated note!");
+            expect(result).toContain('Title: "Original Title" → "Updated Title"');
+        });
+        it("should update note body", async () => {
+            const updatedNote = { ...mockCurrentNote, body: "New content", updated_time: 1234567891000 };
+            mockApiClient.get.mockResolvedValue(mockCurrentNote);
+            mockApiClient.put.mockResolvedValue(updatedNote);
+            const result = await editNote.call({
+                note_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                body: "New content",
+            });
+            expect(mockApiClient.put).toHaveBeenCalledWith("/notes/a1b2c3d4e5f6789012345678901234567890abcd", {
+                body: "New content",
+            });
+            expect(result).toContain("Content: Updated");
+        });
+        it("should convert note to todo", async () => {
+            const updatedNote = { ...mockCurrentNote, is_todo: true, updated_time: 1234567891000 };
+            mockApiClient.get.mockResolvedValue(mockCurrentNote);
+            mockApiClient.put.mockResolvedValue(updatedNote);
+            const result = await editNote.call({
+                note_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                is_todo: true,
+            });
+            expect(mockApiClient.put).toHaveBeenCalledWith("/notes/a1b2c3d4e5f6789012345678901234567890abcd", {
+                is_todo: true,
+            });
+            expect(result).toContain("Type: Regular note → Todo");
+        });
+        it("should mark todo as completed", async () => {
+            const currentTodo = { ...mockCurrentNote, is_todo: true, todo_completed: false };
+            const updatedTodo = { ...currentTodo, todo_completed: true, updated_time: 1234567891000 };
+            mockApiClient.get.mockResolvedValue(currentTodo);
+            mockApiClient.put.mockResolvedValue(updatedTodo);
+            const result = await editNote.call({
+                note_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                todo_completed: true,
+            });
+            expect(mockApiClient.put).toHaveBeenCalledWith("/notes/a1b2c3d4e5f6789012345678901234567890abcd", {
+                todo_completed: true,
+            });
+            expect(result).toContain("Todo Status: Not completed → Completed");
+        });
+        it("should move note to different notebook", async () => {
+            const updatedNote = {
+                ...mockCurrentNote,
+                parent_id: "a1b2c3d4e5f6789012345678901234567890abce",
+                updated_time: 1234567891000,
+            };
+            const mockNotebook = { title: "New Notebook" };
+            mockApiClient.get.mockResolvedValueOnce(mockCurrentNote).mockResolvedValueOnce(mockNotebook);
+            mockApiClient.put.mockResolvedValue(updatedNote);
+            const result = await editNote.call({
+                note_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                parent_id: "a1b2c3d4e5f6789012345678901234567890abce",
+            });
+            expect(mockApiClient.put).toHaveBeenCalledWith("/notes/a1b2c3d4e5f6789012345678901234567890abcd", {
+                parent_id: "a1b2c3d4e5f6789012345678901234567890abce",
+            });
+            expect(result).toContain('Location: Root level → "New Notebook"');
+        });
+        it("should validate required note_id", async () => {
+            const result = await editNote.call({});
+            expect(result).toContain("Please provide note edit options");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+        it("should validate note_id format", async () => {
+            const result = await editNote.call({
+                note_id: "short",
+                title: "New Title",
+            });
+            expect(result).toContain("does not appear to be a valid note ID");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+        it("should require at least one update field", async () => {
+            const result = await editNote.call({
+                note_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+            });
+            expect(result).toContain("Please provide at least one field to update");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+        it("should handle note not found", async () => {
+            mockApiClient.get.mockResolvedValue(null);
+            const result = await editNote.call({
+                note_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                title: "New Title",
+            });
+            expect(result).toContain("Note with ID");
+            expect(result).toContain("not found");
+        });
+        it("should validate parent_id format", async () => {
+            const result = await editNote.call({
+                note_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                parent_id: "short",
+            });
+            expect(result).toContain("does not appear to be a valid notebook ID");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+    });
+    describe("EditFolder", () => {
+        const mockCurrentFolder = {
+            id: "folder-123",
+            title: "Original Folder",
+            parent_id: null,
+        };
+        const mockUpdatedFolder = {
+            id: "folder-123",
+            title: "Updated Folder",
+            parent_id: null,
+            updated_time: 1234567891000,
+        };
+        it("should update folder title", async () => {
+            mockApiClient.get.mockResolvedValue(mockCurrentFolder);
+            mockApiClient.put.mockResolvedValue(mockUpdatedFolder);
+            const result = await editFolder.call({
+                folder_id: "folder-123",
+                title: "Updated Folder",
+            });
+            expect(mockApiClient.get).toHaveBeenCalledWith("/folders/folder-123", {
+                query: { fields: "id,title,parent_id" },
+            });
+            expect(mockApiClient.put).toHaveBeenCalledWith("/folders/folder-123", {
+                title: "Updated Folder",
+            });
+            expect(result).toContain("✅ Successfully updated notebook!");
+            expect(result).toContain('Title: "Original Folder" → "Updated Folder"');
+        });
+        it("should move folder to different parent", async () => {
+            const updatedFolder = { ...mockCurrentFolder, parent_id: "parent-456", updated_time: 1234567891000 };
+            const mockParent = { title: "Parent Folder" };
+            mockApiClient.get.mockResolvedValueOnce(mockCurrentFolder).mockResolvedValueOnce(mockParent);
+            mockApiClient.put.mockResolvedValue(updatedFolder);
+            const result = await editFolder.call({
+                folder_id: "folder-123",
+                parent_id: "parent-456",
+            });
+            expect(mockApiClient.put).toHaveBeenCalledWith("/folders/folder-123", {
+                parent_id: "parent-456",
+            });
+            expect(result).toContain('Location: Top level → Inside "Parent Folder"');
+        });
+        it("should validate required folder_id", async () => {
+            const result = await editFolder.call({});
+            expect(result).toContain("Please provide folder edit options");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+        it("should validate folder_id format", async () => {
+            const result = await editFolder.call({
+                folder_id: "short",
+                title: "New Title",
+            });
+            expect(result).toContain("does not appear to be a valid folder ID");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+        it("should require at least one update field", async () => {
+            const result = await editFolder.call({
+                folder_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+            });
+            expect(result).toContain("Please provide at least one field to update");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+        it("should validate empty title", async () => {
+            const result = await editFolder.call({
+                folder_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                title: "   ",
+            });
+            expect(result).toContain("Title must be a non-empty string");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+        it("should prevent self-parenting", async () => {
+            const result = await editFolder.call({
+                folder_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                parent_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+            });
+            expect(result).toContain("A folder cannot be its own parent");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+        it("should handle folder not found", async () => {
+            mockApiClient.get.mockResolvedValue(null);
+            const result = await editFolder.call({
+                folder_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                title: "New Title",
+            });
+            expect(result).toContain("Folder with ID");
+            expect(result).toContain("not found");
+        });
+        it("should validate parent_id format", async () => {
+            const result = await editFolder.call({
+                folder_id: "a1b2c3d4e5f6789012345678901234567890abcd",
+                parent_id: "short",
+            });
+            expect(result).toContain("does not appear to be a valid parent notebook ID");
+            expect(mockApiClient.get).not.toHaveBeenCalled();
+        });
+        it("should handle 409 conflict errors", async () => {
+            const error = new Error("Conflict");
+            error.response = { status: 409 };
+            mockApiClient.get.mockResolvedValue(mockCurrentFolder);
+            mockApiClient.put.mockRejectedValue(error);
+            const result = await editFolder.call({
+                folder_id: "folder-123",
+                title: "Existing Name",
+            });
+            expect(result).toContain('folder with the title "Existing Name" might already exist');
+        });
+    });
+});

package/dist/tests/unit/joplin-api-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/unit/joplin-api-client.test.js

@@ -0,0 +1,154 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import JoplinAPIClient from "../../lib/joplin-api-client.js";
+// Mock axios
+vi.mock("axios", () => {
+    const mockAxios = {
+        get: vi.fn(),
+        post: vi.fn(),
+        put: vi.fn(),
+        delete: vi.fn(),
+    };
+    return { default: mockAxios };
+});
+import axios from "axios";
+describe("JoplinAPIClient", () => {
+    let client;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        client = new JoplinAPIClient({
+            port: 41184,
+            token: "test-token",
+        });
+    });
+    describe("constructor", () => {
+        it("should create client with default port", () => {
+            const defaultClient = new JoplinAPIClient({ token: "test-token" });
+            expect(defaultClient.baseURL).toBe("http://127.0.0.1:41184");
+            expect(defaultClient.token).toBe("test-token");
+        });
+        it("should create client with custom port", () => {
+            expect(client.baseURL).toBe("http://127.0.0.1:41184");
+            expect(client.token).toBe("test-token");
+        });
+    });
+    describe("serviceAvailable", () => {
+        it("should return true when service is available", async () => {
+            ;
+            axios.get.mockResolvedValue({
+                status: 200,
+                data: "JoplinClipperServer",
+            });
+            const result = await client.serviceAvailable();
+            expect(result).toBe(true);
+            expect(axios.get).toHaveBeenCalledWith("http://127.0.0.1:41184/ping");
+        });
+        it("should return false when service is not available", async () => {
+            ;
+            axios.get.mockRejectedValue(new Error("Connection failed"));
+            const result = await client.serviceAvailable();
+            expect(result).toBe(false);
+        });
+        it("should return false when response is incorrect", async () => {
+            ;
+            axios.get.mockResolvedValue({
+                status: 200,
+                data: "Wrong response",
+            });
+            const result = await client.serviceAvailable();
+            expect(result).toBe(false);
+        });
+    });
+    describe("get", () => {
+        it("should make GET request with token", async () => {
+            const mockData = { items: [], has_more: false };
+            axios.get.mockResolvedValue({ data: mockData });
+            const result = await client.get("/folders");
+            expect(result).toEqual(mockData);
+            expect(axios.get).toHaveBeenCalledWith("http://127.0.0.1:41184/folders", { params: { token: "test-token" } });
+        });
+        it("should make GET request with additional query params", async () => {
+            const mockData = { items: [], has_more: false };
+            axios.get.mockResolvedValue({ data: mockData });
+            const result = await client.get("/folders", {
+                query: { limit: 10, fields: "id,title" },
+            });
+            expect(result).toEqual(mockData);
+            expect(axios.get).toHaveBeenCalledWith("http://127.0.0.1:41184/folders", {
+                params: {
+                    token: "test-token",
+                    limit: 10,
+                    fields: "id,title",
+                },
+            });
+        });
+    });
+    describe("post", () => {
+        it("should make POST request with token", async () => {
+            const mockData = { id: "123", title: "Test Note" };
+            const requestBody = { title: "Test Note", body: "Test content" };
+            axios.post.mockResolvedValue({ data: mockData });
+            const result = await client.post("/notes", requestBody);
+            expect(result).toEqual(mockData);
+            expect(axios.post).toHaveBeenCalledWith("http://127.0.0.1:41184/notes", requestBody, {
+                params: { token: "test-token" },
+            });
+        });
+    });
+    describe("getAllItems", () => {
+        it("should fetch all paginated items", async () => {
+            const page1 = {
+                items: [{ id: "1", title: "Item 1" }],
+                has_more: true,
+            };
+            const page2 = {
+                items: [{ id: "2", title: "Item 2" }],
+                has_more: false,
+            };
+            axios.get.mockResolvedValueOnce({ data: page1 }).mockResolvedValueOnce({ data: page2 });
+            const result = await client.getAllItems("/folders");
+            expect(result).toEqual([
+                { id: "1", title: "Item 1" },
+                { id: "2", title: "Item 2" },
+            ]);
+            expect(axios.get).toHaveBeenCalledTimes(2);
+        });
+        it("should throw error on invalid response format", async () => {
+            ;
+            axios.get.mockResolvedValue({ data: "invalid response" });
+            await expect(client.getAllItems("/folders")).rejects.toThrow("Unexpected response format from Joplin API for path: /folders");
+        });
+    });
+    describe("requestOptions", () => {
+        it("should merge options correctly", () => {
+            const options = client.requestOptions({
+                query: { limit: 10 },
+            });
+            expect(options).toEqual({
+                query: {
+                    token: "test-token",
+                    limit: 10,
+                },
+            });
+        });
+        it("should handle empty options", () => {
+            const options = client.requestOptions();
+            expect(options).toEqual({
+                query: {
+                    token: "test-token",
+                },
+            });
+        });
+    });
+    describe("error handling", () => {
+        it("should handle GET errors", async () => {
+            const error = new Error("Network error");
+            axios.get.mockRejectedValue(error);
+            await expect(client.get("/folders")).rejects.toThrow("Network error");
+        });
+        it("should handle POST errors", async () => {
+            const error = new Error("Server error");
+            axios.post.mockRejectedValue(error);
+            await expect(client.post("/notes", {})).rejects.toThrow("Server error");
+        });
+    });
+});

package/dist/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/vitest.config.js

@@ -0,0 +1,22 @@
+import { defineConfig } from "vitest/config";
+export default defineConfig({
+    test: {
+        // Test files pattern
+        include: ["tests/**/*.{test,spec}.{ts,tsx}"],
+        exclude: ["node_modules", "dist", ".idea", ".git", ".cache", "tests/manual/**/*"],
+        // Test environment
+        environment: "node",
+        // Globals
+        globals: true,
+        // Test timeout
+        testTimeout: 10000,
+        // Coverage settings
+        coverage: {
+            provider: "v8",
+            reporter: ["text", "json", "html"],
+            exclude: ["node_modules/", "bin/", "logs/", "**/*.config.{js,ts}", "**/*.test.{js,ts}", "**/*.spec.{js,ts}"],
+        },
+        // Setup files
+        setupFiles: ["./vitest.setup.ts"],
+    },
+});

package/dist/vitest.setup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/vitest.setup.js

@@ -0,0 +1,24 @@
+import { beforeAll, afterAll } from "vitest";
+import dotenv from "dotenv";
+import { resolve } from "path";
+// Load test environment variables
+beforeAll(() => {
+    // Try to load .env.test.local, fallback to .env.test, then .env
+    const envFiles = [".env.test.local", ".env.test", ".env"];
+    for (const envFile of envFiles) {
+        try {
+            dotenv.config({ path: resolve(process.cwd(), envFile) });
+            break;
+        }
+        catch (error) {
+            // Continue to next file if current one doesn't exist
+        }
+    }
+    // Set test defaults if not provided
+    if (!process.env.JOPLIN_PORT) {
+        process.env.JOPLIN_PORT = "41184";
+    }
+});
+afterAll(() => {
+    // Cleanup if needed
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "joplin-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Joplin",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "joplin-mcp-server": "./dist/bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "start": "tsx index.ts",
+    "start:js": "node dist/index.js",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "test:coverage": "vitest --coverage",
+    "test:manual:search": "tsx tests/manual/search-notes.test.ts",
+    "test:manual:read-note": "tsx tests/manual/read-note.test.ts",
+    "test:manual:create-note": "tsx tests/manual/create-note.test.ts",
+    "test:manual:create-folder": "tsx tests/manual/create-folder.test.ts",
+    "test:manual:edit-note": "tsx tests/manual/edit-note.test.ts",
+    "test:manual:edit-folder": "tsx tests/manual/edit-folder.test.ts",
+    "test:manual:delete-note": "tsx tests/manual/delete-note.test.ts",
+    "test:manual:delete-folder": "tsx tests/manual/delete-folder.test.ts",
+    "test:manual:list-notebooks": "tsx tests/manual/list-notebooks.test.ts",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "mcp",
+    "joplin"
+  ],
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Jordan Burke <jordan.burke@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "axios": "^1.6.7",
+    "dotenv": "^16.4.5",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.21",
+    "@vitest/ui": "^3.1.4",
+    "prettier": "^3.5.3",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4"
+  }
+}