joplin-mcp-server 1.2.0 → 1.3.0

package/README.md

@@ -2,10 +2,12 @@
 
 This is a Node.js implementation of an MCP (Model Context Protocol) server for Joplin.
 
-## Installation
+## Quick Start
+
+Install via npx (no installation required):
 
 ```bash
-npm install
+npx joplin-mcp-server --help
 ```
 
 ## Configuration
@@ -117,54 +119,44 @@ curl http://10.255.255.254:41184/ping
 - **Wrong IP**: Make sure you're using your actual Windows IP address
   - Check with `ipconfig` on Windows (look for IPv4 Address on your active network adapter)
 
-## Usage
-
-### Local Development
+## Command Line Options
 
-Start the server:
-
-```bash
-npm start
 ```
-
-You can also specify a custom environment file:
-
-```bash
-npm start -- --env-file .env.custom
+OPTIONS:
+  --env-file <file>    Load environment variables from file
+  --host <hostname>    Joplin hostname or IP (default: 127.0.0.1)
+  --port <port>        Joplin port (default: 41184)
+  --token <token>      Joplin API token
+  --transport <type>   Transport type: stdio (default) or http
+  --http-port <port>   HTTP server port (default: 3000, only used with --transport http)
+  --help, -h           Show help message
 ```
 
-### Using npx (Recommended)
-
-After publishing to npm, you can use npx to run the server without installation:
+### Command Line Usage Examples
 
 ```bash
 # Using command line arguments
-npx joplin-mcp-server --port 41184 --token your_joplin_token
+npx joplin-mcp-server --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
+# WSL: Connect to Windows host
+npx joplin-mcp-server --host 192.168.0.40 --token your_token
 
-```
-OPTIONS:
-  --env-file <file>    Load environment variables from file
-  --port <port>        Joplin port (default: 41184)
-  --token <token>      Joplin API token
-  --transport <type>   Transport type: stdio (default) or http
-  --http-port <port>   HTTP server port (default: 3000, only used with --transport http)
-  --help, -h           Show help message
+# HTTP mode (for testing with MCP Inspector)
+npx joplin-mcp-server --transport http --token your_token
 ```
 
 ### MCP Client Configuration
 
 #### Claude Desktop Configuration
 
-Add to your `claude_desktop_config.json` file using environment variable expansion (recommended):
+**Important**: Claude Desktop does NOT support environment variable expansion (`${VAR}` syntax). You must provide values directly.
+
+**Option 1: Using env Section (Recommended)**
+
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
@@ -173,85 +165,111 @@ Add to your `claude_desktop_config.json` file using environment variable expansi
       "command": "npx",
       "args": ["joplin-mcp-server"],
       "env": {
+        "JOPLIN_TOKEN": "your_actual_token_here",
         "JOPLIN_PORT": "41184",
-        "JOPLIN_TOKEN": "${JOPLIN_TOKEN}"
+        "JOPLIN_HOST": "127.0.0.1"
       }
     }
   }
 }
 ```
 
-Then set the `JOPLIN_TOKEN` environment variable in your system:
+**Option 2: Using Command-Line Arguments**
 
-```bash
-# On macOS/Linux
-export JOPLIN_TOKEN=your_actual_token_here
+```json
+{
+  "mcpServers": {
+    "joplin": {
+      "command": "npx",
+      "args": ["joplin-mcp-server", "--token", "your_actual_token_here", "--port", "41184", "--host", "127.0.0.1"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after updating the configuration.
 
-# On Windows
-set JOPLIN_TOKEN=your_actual_token_here
+#### Claude Code Configuration
+
+Claude Code supports environment variable expansion in `.mcp.json`.
+
+**1. Set environment variables in your shell** (add to `~/.bashrc` or `~/.zshrc`):
+
+```bash
+export JOPLIN_TOKEN="your_actual_token_here"
+export JOPLIN_PORT="41184"        # Optional, defaults to 41184
+export JOPLIN_HOST="127.0.0.1"    # Optional, defaults to 127.0.0.1
 ```
 
-Alternative using command-line arguments with environment expansion:
+**2. Use the included `.mcp.json` configuration**:
+
+The repository includes a working `.mcp.json` file that uses environment variable expansion:
 
 ```json
 {
   "mcpServers": {
     "joplin": {
       "command": "npx",
-      "args": ["joplin-mcp-server", "--port", "${JOPLIN_PORT}", "--token", "${JOPLIN_TOKEN}"],
+      "args": ["joplin-mcp-server"],
       "env": {
-        "JOPLIN_PORT": "41184",
-        "JOPLIN_TOKEN": "your_actual_token_here"
+        "JOPLIN_TOKEN": "${JOPLIN_TOKEN}"
       }
     }
   }
 }
 ```
 
-#### Other MCP Clients
+The server will automatically use `JOPLIN_PORT` and `JOPLIN_HOST` from your shell environment, or use the defaults (127.0.0.1:41184).
 
-Usage in mcp.json (Cursor and other tools):
+#### Other MCP Clients (Cursor, etc.)
+
+Most MCP clients support environment variable expansion (`${VAR}` syntax).
+
+**With environment variables:**
 
 ```json
 {
-  "joplin": {
-    "command": "npx",
-    "args": ["joplin-mcp-server", "--port", "41184", "--token", "your_joplin_token"]
+  "mcpServers": {
+    "joplin": {
+      "command": "npx",
+      "args": ["joplin-mcp-server"],
+      "env": {
+        "JOPLIN_TOKEN": "${JOPLIN_TOKEN}",
+        "JOPLIN_PORT": "${JOPLIN_PORT}",
+        "JOPLIN_HOST": "${JOPLIN_HOST}"
+      }
+    }
   }
 }
 ```
 
-Or using environment file:
+**With direct values:**
 
 ```json
 {
-  "joplin": {
-    "command": "npx",
-    "args": ["joplin-mcp-server", "--env-file", "/path/to/your/.env"]
+  "mcpServers": {
+    "joplin": {
+      "command": "npx",
+      "args": ["joplin-mcp-server", "--token", "your_joplin_token", "--port", "41184", "--host", "127.0.0.1"]
+    }
   }
 }
 ```
 
-### 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)
+**Using environment file:**
 
 ```json
-  "joplin":{
-      "command":"node",
-      "args":[
-        "/path/to/your/mcp-joplin/index.js",
-        "--env-file",
-        "/path/to/your/mcp-joplin/.env"
-      ]
+{
+  "mcpServers": {
+    "joplin": {
+      "command": "npx",
+      "args": ["joplin-mcp-server", "--env-file", "/path/to/your/.env"]
+    }
   }
+}
 ```
 
-### Logging
+## Logging
 
 The server logs all incoming commands and outgoing responses. Logs are stored in two places:
 
@@ -466,56 +484,36 @@ Successfully retrieved: 3
 
 ### 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
+# Install dependencies
+pnpm install
 
-1. Edit any `.js` files in the project
-2. Run tests: `npm test`
-3. Test the CLI: `npx joplin-mcp-server --help`
+# Build the project
+pnpm build
 
-No build step is required - changes are immediately available through the npm link.
+# Run tests
+pnpm test
 
-### Running Tests
+# Format code
+pnpm format
 
-Create a `.env.test.local` file with your test configuration, then run:
+# Run linter
+pnpm lint
 
-```bash
-npm test
+# Run validation (format + lint + test + build)
+pnpm validate
 ```
 
-### 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`
+### Testing Local Changes
 
-### Unlinking (if needed)
+```bash
+# Link for local development
+npm link
 
-To remove the local link:
+# Test the CLI
+npx joplin-mcp-server --help
 
-```bash
+# Unlink when done
 npm unlink -g joplin-mcp-server
 ```
 

package/dist/bin.d.ts

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