joplin-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jordan Burke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,384 @@
+# Joplin MCP Server
+
+This is a Node.js implementation of an MCP (Model Context Protocol) server for Joplin.
+
+## Installation
+
+```bash
+npm install
+```
+
+## Configuration
+
+Create a `.env` file with the following variables:
+
+```
+JOPLIN_PORT=41184
+JOPLIN_TOKEN=your_joplin_token
+```
+
+You can find your Joplin token in the Joplin desktop app under:
+Tools > Options > Web Clipper
+
+## Usage
+
+### Local Development
+
+Start the server:
+
+```bash
+npm start
+```
+
+You can also specify a custom environment file:
+
+```bash
+npm start -- --env-file .env.custom
+```
+
+### Using npx (Recommended)
+
+After publishing to npm, you can use npx to run the server without installation:
+
+```bash
+# Using command line arguments
+npx joplin-mcp-server --port 41184 --token your_joplin_token
+
+# Using environment file
+npx joplin-mcp-server --env-file /path/to/your/.env
+
+# Mixed approach (args override env file)
+npx joplin-mcp-server --env-file .env --port 41185
+```
+
+### Command Line Options
+
+```
+OPTIONS:
+  --env-file <file>    Load environment variables from file
+  --port <port>        Joplin port (default: 41184)
+  --token <token>      Joplin API token
+  --help, -h           Show help message
+```
+
+### MCP Client Configuration
+
+Usage in Augment Code:
+
+```
+name: joplin
+command: npx joplin-mcp-server --port 41184 --token your_token
+```
+
+Usage in mcp.json (Cursor and other tools):
+
+```json
+{
+  "joplin": {
+    "command": "npx",
+    "args": ["joplin-mcp-server", "--port", "41184", "--token", "your_joplin_token"]
+  }
+}
+```
+
+Or using environment file:
+
+```json
+{
+  "joplin": {
+    "command": "npx",
+    "args": ["joplin-mcp-server", "--env-file", "/path/to/your/.env"]
+  }
+}
+```
+
+### Legacy Usage (if installed locally)
+
+Usage in Augment Code:
+name: `joplin`
+command: `node /path/to/your/mcp-joplin/index.js --env-file /path/to/your/mcp-joplin/.env`
+
+Usage in mcp.json (cursor other tools)
+
+```json
+  "joplin":{
+      "command":"node",
+      "args":[
+        "/path/to/your/mcp-joplin/index.js",
+        "--env-file",
+        "/path/to/your/mcp-joplin/.env"
+      ]
+  }
+```
+
+### Logging
+
+The server logs all incoming commands and outgoing responses. Logs are stored in two places:
+
+1. **Console output**: Basic information is displayed in the console
+2. **Log files**: Detailed logs are saved in the `logs` directory with timestamps
+
+You can adjust the log level by setting the `LOG_LEVEL` environment variable:
+
+```bash
+LOG_LEVEL=debug npm start
+```
+
+Available log levels (from most to least verbose):
+
+- `debug`: All messages including detailed command and response data
+- `info`: Standard operational messages (default)
+- `warn`: Warnings and errors only
+- `error`: Only error messages
+
+## Available Tools
+
+### list_notebooks
+
+Retrieves the complete notebook hierarchy from Joplin.
+
+```
+# Example output:
+Notebook 1 (id: "abc123")
+  Subnotebook 1.1 (id: "def456")
+  Subnotebook 1.2 (id: "ghi789")
+Notebook 2 (id: "jkl012")
+```
+
+### search_notes
+
+Searches for notes in Joplin and returns matching notebooks.
+
+**Parameters:**
+
+- `query`: The search query string
+
+```
+# Example usage:
+search_notes query="project meeting"
+
+# Example output:
+Found 2 notes matching query: "project meeting"
+NOTE: To read a notebook, use the notebook ID (not the note title)
+
+- Note: "Weekly Project Meeting" (note_id: "abc123")
+  Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
+  Updated: 3/15/2025, 10:30:45 AM
+  Snippet: Notes from our weekly project meeting. Topics discussed: timeline, resources, next steps...
+  To read this notebook: read_notebook notebook_id="58a0a29f68bc4141b49c99f5d367638a"
+
+- Note: "Project Kickoff Meeting" (note_id: "def456")
+  Notebook: "Projects" (notebook_id: "72b1c45d89ef3212a67b98f4e5d23a1b")
+  Updated: 3/10/2025, 2:15:30 PM
+  Snippet: Initial project meeting with stakeholders. Key decisions: project scope, team members...
+  To read this notebook: read_notebook notebook_id="72b1c45d89ef3212a67b98f4e5d23a1b"
+```
+
+> **Important**: Note the difference between note titles and IDs. When using the `read_notebook` command, you must use the notebook ID (a long alphanumeric string), not the notebook title.
+
+### read_notebook
+
+Reads the contents of a specific notebook.
+
+**Parameters:**
+
+- `notebook_id`: The ID of the notebook to read
+
+```
+# Example usage:
+read_notebook notebook_id="58a0a29f68bc4141b49c99f5d367638a"
+
+# Example output:
+# Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
+Contains 3 notes:
+NOTE: This is showing the contents of notebook "Work", not a specific note.
+
+- Note: "Weekly Project Meeting" (note_id: "def456")
+  Updated: 3/15/2025, 10:30:45 AM
+
+- ✅ Note: "Call client" (note_id: "ghi789")
+  Updated: 3/14/2025, 3:45:12 PM
+
+- ☐ Note: "Prepare presentation" (note_id: "jkl012")
+  Updated: 3/13/2025, 9:20:33 AM
+```
+
+> **Common Error**: If you try to use a note title (like "todo") instead of a notebook ID, you'll get an error. Always use the notebook ID (the long alphanumeric string) shown in the search results or notebook list.
+
+### read_note
+
+Reads the full content of a specific note.
+
+**Parameters:**
+
+- `note_id`: The ID of the note to read
+
+```
+# Example usage:
+read_note note_id="def456"
+
+# Example output:
+# Note: "Weekly Project Meeting"
+Note ID: def456
+Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
+Created: 3/15/2025, 10:00:12 AM
+Updated: 3/15/2025, 10:30:45 AM
+
+---
+
+# Weekly Project Meeting
+
+## Agenda
+1. Project status update
+2. Timeline review
+3. Resource allocation
+4. Next steps
+
+## Notes
+- Project is on track for Q2 delivery
+- Need to allocate additional resources to the UI team
+- Next meeting scheduled for next Friday
+
+---
+
+Related commands:
+- To view the notebook containing this note: read_notebook notebook_id="58a0a29f68bc4141b49c99f5d367638a"
+- To search for more notes: search_notes query="your search term"
+```
+
+> **Note**: The `read_note` command shows the full content of a specific note, while the `read_notebook` command shows a list of notes in a notebook. Use `search_notes` to find notes and get their IDs.
+
+### read_multinote
+
+Reads the full content of multiple notes at once.
+
+**Parameters:**
+
+- `note_ids`: An array of note IDs to read
+
+```
+# Example usage:
+read_multinote note_ids=["def456", "ghi789", "jkl012"]
+
+# Example output:
+# Reading 3 notes
+
+## Note 1 of 3 (ID: def456)
+
+### Note: "Weekly Project Meeting"
+Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
+Created: 3/15/2025, 10:00:12 AM
+Updated: 3/15/2025, 10:30:45 AM
+
+---
+
+# Weekly Project Meeting
+
+## Agenda
+1. Project status update
+2. Timeline review
+
+---
+
+## Note 2 of 3 (ID: ghi789)
+
+### Note: "Call client"
+Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
+Status: Completed
+Created: 3/14/2025, 3:00:00 PM
+Updated: 3/14/2025, 3:45:12 PM
+
+---
+
+Discussed project timeline and next steps.
+Client is happy with progress.
+
+---
+
+## Note 3 of 3 (ID: jkl012)
+
+### Note: "Prepare presentation"
+Notebook: "Work" (notebook_id: "58a0a29f68bc4141b49c99f5d367638a")
+Status: Not completed
+Due: 3/20/2025, 9:00:00 AM
+Created: 3/13/2025, 9:00:00 AM
+Updated: 3/13/2025, 9:20:33 AM
+
+---
+
+# Presentation Outline
+- Introduction
+- Project overview
+- Timeline
+- Budget
+- Next steps
+
+---
+
+# Summary
+Total notes requested: 3
+Successfully retrieved: 3
+```
+
+> **Tip**: When you search for notes or view a notebook, you'll see a suggestion for using `read_multinote` with the exact IDs of the notes found. This makes it easy to read multiple related notes at once.
+
+## Development
+
+### Local Development Setup
+
+To test the npx command locally during development:
+
+```bash
+# In the project root directory
+cd /path/to/mcp-joplin
+npm install
+npm link
+```
+
+After linking, you can test your local changes immediately:
+
+```bash
+# Test the CLI
+npx joplin-mcp-server --help
+npx joplin-mcp-server --port 41184 --token your_token
+
+# Make code changes, then test again (no rebuild needed)
+npx joplin-mcp-server --help
+```
+
+### Making Changes
+
+1. Edit any `.js` files in the project
+2. Run tests: `npm test`
+3. Test the CLI: `npx joplin-mcp-server --help`
+
+No build step is required - changes are immediately available through the npm link.
+
+### Running Tests
+
+Create a `.env.test.local` file with your test configuration, then run:
+
+```bash
+npm test
+```
+
+### Publishing to npm
+
+To make this package available via npx:
+
+1. Update the version in `package.json`
+2. Run `npm publish`
+
+Users can then run it with `npx joplin-mcp-server`
+
+### Unlinking (if needed)
+
+To remove the local link:
+
+```bash
+npm unlink -g joplin-mcp-server
+```
+
+## License
+
+MIT

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Import and run the compiled index.js
+const { default: main } = await import(resolve(__dirname, "../index.js"));

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,204 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import parseArgs from "./lib/parse-args.js";
+import JoplinAPIClient from "./lib/joplin-api-client.js";
+import { ListNotebooks, SearchNotes, ReadNotebook, ReadNote, ReadMultiNote, CreateNote, CreateFolder, EditNote, EditFolder, DeleteNote, DeleteFolder, } from "./lib/tools/index.js";
+// Parse command line arguments
+parseArgs();
+// Set default port if not specified
+if (!process.env.JOPLIN_PORT) {
+    process.env.JOPLIN_PORT = "41184";
+}
+// Check for required environment variables
+if (!process.env.JOPLIN_TOKEN) {
+    process.stderr.write("Error: JOPLIN_TOKEN is required. Use --token <token> or set JOPLIN_TOKEN environment variable.\n");
+    process.stderr.write("Find your token in Joplin: Tools > Options > Web Clipper\n");
+    process.exit(1);
+}
+// Create the Joplin API client
+const apiClient = new JoplinAPIClient({
+    port: parseInt(process.env.JOPLIN_PORT || "41184"),
+    token: process.env.JOPLIN_TOKEN,
+});
+// Create the MCP server
+const server = new McpServer({
+    name: "joplin-mcp-server",
+    version: "1.0.0",
+});
+// Register the list_notebooks tool
+server.tool("list_notebooks", "Retrieve the complete notebook hierarchy from Joplin", {}, async () => {
+    const result = await new ListNotebooks(apiClient).call();
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the search_notes tool
+server.tool("search_notes", "Search for notes in Joplin and return matching notebooks", { query: z.string() }, async ({ query }) => {
+    const result = await new SearchNotes(apiClient).call(query);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the read_notebook tool
+server.tool("read_notebook", "Read the contents of a specific notebook", { notebook_id: z.string() }, async ({ notebook_id }) => {
+    const result = await new ReadNotebook(apiClient).call(notebook_id);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the read_note tool
+server.tool("read_note", "Read the full content of a specific note", { note_id: z.string() }, async ({ note_id }) => {
+    const result = await new ReadNote(apiClient).call(note_id);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the read_multinote tool
+server.tool("read_multinote", "Read the full content of multiple notes at once", { note_ids: z.array(z.string()) }, async ({ note_ids }) => {
+    const result = await new ReadMultiNote(apiClient).call(note_ids);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the create_note tool
+server.tool("create_note", "Create a new note in Joplin", {
+    title: z.string().optional(),
+    body: z.string().optional(),
+    body_html: z.string().optional(),
+    parent_id: z.string().optional(),
+    is_todo: z.boolean().optional(),
+    image_data_url: z.string().optional(),
+}, async (params) => {
+    const result = await new CreateNote(apiClient).call(params);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the create_folder tool
+server.tool("create_folder", "Create a new folder/notebook in Joplin", {
+    title: z.string(),
+    parent_id: z.string().optional(),
+}, async (params) => {
+    const result = await new CreateFolder(apiClient).call(params);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the edit_note tool
+server.tool("edit_note", "Edit/update an existing note in Joplin", {
+    note_id: z.string(),
+    title: z.string().optional(),
+    body: z.string().optional(),
+    body_html: z.string().optional(),
+    parent_id: z.string().optional(),
+    is_todo: z.boolean().optional(),
+    todo_completed: z.boolean().optional(),
+    todo_due: z.number().optional(),
+}, async (params) => {
+    const result = await new EditNote(apiClient).call(params);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the edit_folder tool
+server.tool("edit_folder", "Edit/update an existing folder/notebook in Joplin", {
+    folder_id: z.string(),
+    title: z.string().optional(),
+    parent_id: z.string().optional(),
+}, async (params) => {
+    const result = await new EditFolder(apiClient).call(params);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the delete_note tool
+server.tool("delete_note", "Delete a note from Joplin (requires confirmation)", {
+    note_id: z.string(),
+    confirm: z.boolean().optional(),
+}, async (params) => {
+    const result = await new DeleteNote(apiClient).call(params);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Register the delete_folder tool
+server.tool("delete_folder", "Delete a folder/notebook from Joplin (requires confirmation)", {
+    folder_id: z.string(),
+    confirm: z.boolean().optional(),
+    force: z.boolean().optional(),
+}, async (params) => {
+    const result = await new DeleteFolder(apiClient).call(params);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Create logs directory if it doesn't exist
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const logsDir = path.join(__dirname, "logs");
+if (!fs.existsSync(logsDir)) {
+    fs.mkdirSync(logsDir, { recursive: true });
+}
+// Create a log file for this session
+const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+const logFile = path.join(logsDir, `mcp-server-${timestamp}.log`);
+// Log server startup (commented out for debugging)
+// logger.info(`Starting MCP server (version 1.0.0)`);
+// logger.info(`Log file: ${logFile}`);
+// Create a custom transport wrapper to log commands and responses
+class LoggingTransport extends StdioServerTransport {
+    commandCounter;
+    constructor() {
+        super();
+        this.commandCounter = 0;
+    }
+    async sendMessage(message) {
+        // Log outgoing message (response)
+        const logEntry = {
+            timestamp: new Date().toISOString(),
+            direction: "RESPONSE",
+            message,
+        };
+        // Log to console (commented out for debugging)
+        // logger.debug(`Sending response: ${JSON.stringify(message)}`);
+        // Log to file
+        fs.appendFileSync(logFile, JSON.stringify(logEntry) + "\n");
+        // Call the original method
+        const parent = Object.getPrototypeOf(Object.getPrototypeOf(this));
+        return parent.sendMessage.call(this, message);
+    }
+    async handleMessage(message) {
+        // Log incoming message (command)
+        this.commandCounter++;
+        const logEntry = {
+            timestamp: new Date().toISOString(),
+            direction: "COMMAND",
+            commandNumber: this.commandCounter,
+            message,
+        };
+        // Log to console (commented out for debugging)
+        // logger.info(`Received command #${this.commandCounter}: ${message.method || 'unknown method'}`);
+        // logger.debug(`Command details: ${JSON.stringify(message)}`);
+        // Log to file
+        fs.appendFileSync(logFile, JSON.stringify(logEntry) + "\n");
+        // Call the original method
+        const parent = Object.getPrototypeOf(Object.getPrototypeOf(this));
+        return parent.handleMessage.call(this, message);
+    }
+}
+// Start the server with logging transport
+const transport = new LoggingTransport();
+// Log connection status (commented out for debugging)
+// logger.info('Connecting to transport...');
+try {
+    await server.connect(transport);
+    // logger.info('MCP server started and ready to receive commands');
+}
+catch (error) {
+    process.stderr.write(`Failed to start MCP server: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+}

package/dist/lib/joplin-api-client.d.ts

@@ -0,0 +1,23 @@
+interface JoplinAPIClientConfig {
+    port?: number;
+    token: string;
+}
+interface RequestOptions {
+    query?: Record<string, any>;
+    [key: string]: any;
+}
+declare class JoplinAPIClient {
+    private readonly baseURL;
+    private readonly token;
+    constructor({ port, token }: JoplinAPIClientConfig);
+    serviceAvailable(): Promise<boolean>;
+    getAllItems<T = any>(path: string, options?: RequestOptions): Promise<T[]>;
+    get<T = any>(path: string, options?: RequestOptions): Promise<T>;
+    post<T = any>(path: string, body: any, options?: RequestOptions): Promise<T>;
+    delete<T = any>(path: string, options?: RequestOptions): Promise<T>;
+    put<T = any>(path: string, body: any, options?: RequestOptions): Promise<T>;
+    private requestOptions;
+    private mergeRequestOptions;
+    private except;
+}
+export default JoplinAPIClient;