remnote-mcp-server 0.1.3 → 0.3.0

package/README.md

@@ -1,15 +1,27 @@
 # RemNote MCP Server
 
-[![CI](https://github.com/robert7/remnote-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/robert7/remnote-mcp-server/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/remnote-mcp-server.svg)](https://www.npmjs.com/package/remnote-mcp-server)
+![Status](https://img.shields.io/badge/status-beta-yellow) ![License](https://img.shields.io/badge/license-MIT-blue)
+![CI](https://github.com/robert7/remnote-mcp-server/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/robert7/remnote-mcp-server/branch/main/graph/badge.svg)](https://codecov.io/gh/robert7/remnote-mcp-server)
 
-MCP server that bridges Claude Code (and other MCP clients) to [RemNote](https://remnote.com/) via the [RemNote MCP
-Bridge plugin](https://github.com/robert7/remnote-mcp-bridge).
+MCP server that bridges AI agents (e.g. Claude Code) to [RemNote](https://remnote.com/) via the [RemNote MCP Bridge
+plugin](https://github.com/robert7/remnote-mcp-bridge).
 
 ## Demo
 
 See Claude Code in action with RemNote: **[View Demo →](docs/demo.md)**
 
+## Two-Component Architecture
+
+This system consists of **two separate components** that work together:
+
+1. **[RemNote MCP Bridge](https://github.com/robert7/remnote-mcp-bridge)** - A RemNote plugin that runs in your browser
+   or RemNote desktop app and exposes RemNote API functionality via WebSocket
+2. **RemNote MCP Server** (this repository) - A standalone server that connects your AI assistant to the bridge using
+   MCP protocol
+
+**Both components are required** for AI integration with RemNote.
+
 ## What is This?
 
 The RemNote MCP Server enables AI assistants like Claude Code to interact directly with your RemNote knowledge base
@@ -19,15 +31,35 @@ notes, and maintain your daily journal—all through conversational commands.
 **Architecture:**
 
 ```text
-AI agent (e.g. Claude Code, MCP Client) ↔ MCP Server (stdio) ↔ WebSocket Server :3002 ↔ RemNote Plugin ↔ RemNote
+AI agents (HTTP) ↔ MCP HTTP Server :3001 ↔ WebSocket Server :3002 ↔ RemNote Plugin ↔ RemNote
 ```
 
 The server acts as a bridge:
 
-- Communicates with Claude Code via stdio transport (MCP protocol)
-- Runs a WebSocket server (port 3002) that the RemNote browser plugin connects to
+- Communicates with AI agents via Streamable HTTP transport (MCP protocol)
+- HTTP server (port 3001) manages MCP sessions for multiple concurrent agents
+- WebSocket server (port 3002) connects to the RemNote browser plugin
 - Translates MCP tool calls into RemNote API actions
 
+**About Streamable HTTP Transport**
+
+This MCP server uses [Streamable HTTP
+transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#http-with-sse), a communication
+mechanism for MCP that supports multiple concurrent clients.
+
+**Key characteristics:**
+
+- **Lifecycle management**: You must start the server independently (`npm start` or `npm run dev`). Claude Code connects
+  to the running server via HTTP.
+- **Message protocol**: Communication uses JSON-RPC over HTTP POST for requests and Server-Sent Events (SSE) for
+  notifications.
+- **Multi-client support**: Multiple AI agents can connect simultaneously, each with their own MCP session.
+- **Session management**: Server tracks sessions via `mcp-session-id` headers and UUID-based request correlation.
+
+This architecture enables multiple Claude Code windows to access RemNote concurrently while maintaining process
+isolation and security boundaries. For technical details, see the [MCP
+specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports).
+
 ## Features
 
 - **Create Notes** - Create new notes with optional parent hierarchy and tags
@@ -37,41 +69,25 @@ The server acts as a bridge:
 - **Journal Entries** - Append timestamped entries to daily documents
 - **Connection Status** - Check server and plugin connection health
 
-## Important Limitations
-
-**This MCP server enforces a strict 1:1:1 relationship:** one AI agent ↔ one MCP server instance ↔ one RemNote plugin
-connection.
+## Multi-Agent Support
 
-### Multi-Agent Constraints
+**Multiple AI agents can now connect simultaneously!** The server uses Streamable HTTP transport, allowing multiple
+Claude Code sessions (or other MCP clients) to access the same RemNote knowledge base concurrently.
 
-You **cannot** use multiple AI agents (e.g., two Claude Code sessions) with the same RemNote knowledge base
-simultaneously. Three architectural constraints prevent this:
+### How It Works
 
-1. **stdio transport is point-to-point** - Each MCP server process communicates with exactly one AI agent via
-   stdin/stdout. The transport protocol doesn't support multiple clients.
-2. **WebSocket enforces single-client** - The server explicitly rejects multiple RemNote plugin connections. Only one
-   plugin instance can connect to port 3002 at a time (connection code: 1008).
-3. **Port binding conflict** - Multiple server instances attempting to use the default port 3002 will fail with
-   `EADDRINUSE`.
+- One long-running server process on ports 3001 (HTTP) and 3002 (WebSocket)
+- Multiple AI agents connect via HTTP and get independent MCP sessions
+- All sessions share the same WebSocket bridge to RemNote
+- Concurrent requests are handled via UUID-based correlation
 
-### Practical Implications
+### Limitations
 
-- **One agent at a time** - Close one Claude Code session before starting another if both need RemNote access
-- **No concurrent access** - Cannot have multiple AI assistants modifying your RemNote knowledge base simultaneously
-- **Separate workspaces don't help** - Even with different ports, only one plugin instance can connect to RemNote at a
-  time
+The WebSocket bridge still enforces a **single RemNote plugin connection**. This means:
 
-### Alternative Approach
-
-If you need multiple AI agents with separate note-taking systems, use separate RemNote accounts/workspaces and configure
-each with its own MCP server instance on different ports.
-
-### Future Plans
-
-**HTTP transport migration planned** - The single-agent limitation is a temporary architectural constraint. A future
-version will migrate from stdio transport to HTTP transport (SSE), which would allow multiple AI agents to connect
-to the same MCP server instance simultaneously. This would remove constraint #1 above while maintaining the existing
-WebSocket bridge to RemNote.
+- Multiple AI agents can connect to the server
+- But only one RemNote app instance can be connected at a time
+- This is a RemNote plugin limitation, not an MCP server limitation
 
 ## Prerequisites
 
@@ -85,6 +101,8 @@ WebSocket bridge to RemNote.
 
 **From npm (recommended for most users):**
 
+See [MCP Server npm Package](https://www.npmjs.com/package/remnote-mcp-server).
+
 ```bash
 # Install globally
 npm install -g remnote-mcp-server
@@ -107,151 +125,176 @@ npm uninstall -g remnote-mcp-server
 git clone https://github.com/robert7/remnote-mcp-server.git
 cd remnote-mcp-server
 npm install
-npm run build
+```
 
-# Creates global symlink: makes remnote-mcp-server command available system-wide
-npm link
+### 2. Install RemNote MCP Bridge Plugin
 
-# Verify it worked
-which remnote-mcp-server
-# Should output e.g.: /Users/<username>/.nvm/versions/node/<version>/bin/remnote-mcp-server
+Install the [RemNote MCP Bridge plugin](https://github.com/robert7/remnote-mcp-bridge) in your RemNote app:
+
+1. Open RemNote
+2. Navigate to plugin installation (see plugin repository for instructions)
+
+### 3. Start the Server
+
+**IMPORTANT:** You must start the server before using it with Claude Code.
+
+```bash
+# Start with default settings
+remnote-mcp-server
+
+# With custom ports
+remnote-mcp-server --ws-port 4002 --http-port 4001
+
+# With verbose logging
+remnote-mcp-server --verbose
+
+# With file logging
+remnote-mcp-server --log-file /tmp/remnote-mcp.log --log-level-file debug
+
+# OR development mode (with hot reload)
+npm run dev
+# you can also pass CLI options after `--`, e.g.
+npm run dev -- -h
+```
+
+**CLI Options:**
+
+Server Configuration:
+- `--ws-port <number>` - WebSocket port (default: 3002, env: REMNOTE_WS_PORT)
+- `--http-port <number>` - HTTP MCP port (default: 3001, env: REMNOTE_HTTP_PORT)
+
+Logging Configuration:
+- `--log-level <level>` - Console log level: debug, info, warn, error (default: info)
+- `--log-level-file <level>` - File log level (default: same as --log-level)
+- `--verbose` - Shorthand for --log-level debug
+- `--log-file <path>` - Log to file (default: console only)
+- `--request-log <path>` - Log all WebSocket requests to file (JSON Lines)
+- `--response-log <path>` - Log all WebSocket responses to file (JSON Lines)
+
+Information:
+- `-h, --help` - Display help message
+- `-v, --version` - Display version number
+
+Expected output:
 ```
+RemNote MCP Server v0.2.1 listening { wsPort: 3002, httpPort: 3001 }
+```
+
+Keep this terminal running. The server must be running for Claude Code to connect.
 
-**What npm link does:** Creates a symbolic link from your global `node_modules` bin directory to this project's
-executable, allowing Claude Code to launch `remnote-mcp-server` from anywhere without publishing to npm.
+## Configuration of AI Agents
 
-**Important:** Claude Code CLI must have access to the same Node.js environment where you ran `npm link`. If Claude Code
-uses a different Node.js version or environment (e.g., different shell PATH), it won't find the command. Ensure your
-shell configuration (`.bashrc`, `.zshrc`) properly exposes your Node.js environment.
+### Claude Code CLI
 
-**Unlinking the source installation:**
+Use the `claude mcp` CLI commands to add, test, and remove the MCP server.
 
-When you no longer want the global `remnote-mcp-server` command to point to your local repository:
+**Add the server:**
 
 ```bash
-# Remove the global symlink
-npm unlink -g remnote-mcp-server
+# goto your project directory
+cd /Users/username/Projects/sample-project
+claude mcp add remnote --transport http http://localhost:3001/mcp
+```
 
-# Verify it's removed
-which remnote-mcp-server
-# Should output nothing if successfully unlinked
+Example output:
+
+```text
+Added HTTP MCP server remnote with URL: http://localhost:3001/mcp to local config
+File modified: /Users/username/.claude.json [project: /Users/username/Projects/sample-project]
 ```
 
-After unlinking, you can install the published npm package globally with `npm install -g remnote-mcp-server` if needed.
+**Verify connection:**
 
-**About stdio transport**
+```bash
+claude mcp list
+```
 
-This MCP server uses [stdio transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio),
-the preferred communication mechanism for MCP. In stdio transport, Claude Code launches the server as a subprocess and
-exchanges JSON-RPC messages via standard input/output streams.
+Example output:
 
-**Key characteristics:**
+```text
+remnote: http://localhost:3001/mcp (HTTP) - ✓ Connected
+```
 
-- **Lifecycle management**: Claude Code automatically starts the server when it launches and stops it on exit. The
-  server is launched as a subprocess, not a standalone service.
-- **Message protocol**: Communication uses newline-delimited JSON-RPC messages on stdin (client → server) and stdout
-  (server → client). No HTTP/REST endpoints are exposed.
-- **Logging constraint**: stdout is reserved exclusively for MCP protocol messages. All logging must go to stderr, which
-  is why the codebase uses `console.error()` for logs.
+As alternative you can use `/mcp` command in any Claude Code session to check the connection health.
 
-This architecture provides tight integration with Claude Code while maintaining process isolation and security
-boundaries. For technical details, see the [MCP
-specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports).
+**Using the server:**
 
-### 2. Install RemNote MCP Bridge Plugin
+Once configured, Claude Code automatically loads RemNote tools in your sessions. See the [Example Usage](#example-usage)
+section below for conversational commands.
 
-Install the [RemNote MCP Bridge plugin](https://github.com/robert7/remnote-mcp-bridge) in your RemNote app:
+```bash
+# In any Claude Code session
+claude
 
-1. Open RemNote
-2. Navigate to plugin installation (see plugin repository for instructions)
-3. Configure WebSocket URL: `ws://127.0.0.1:3002`
-4. Enable auto-reconnect
+prompt:
+show remnote note titles related do AI assisted coding
+...
+remnote - remnote_search (MCP)(query: "AI assisted coding", limit: 20, includeContent: false)
+...
+Found 20 notes related to "AI assisted coding". The main results include:
 
-### 3. Configure Claude Code CLI
+  Primary note:
+  - AI assisted coding (remId: qtVwh5XBQbJM2HfSp)
 
-MCP servers are configured in `~/.claude.json` under the `mcpServers` key within project-specific sections.
+  Related tools/platforms:
+  - Claude Code
+  - Gemini CLI
+  ...
+```
 
-**Add to your `~/.claude.json`:**
+**Remove the server:**
 
-```json
-{
-  "projects": {
-    "/Users/username": {
-      "mcpServers": {
-        "remnote": {
-          "type": "stdio",
-          "command": "remnote-mcp-server",
-          "args": [],
-          "env": {
-            "REMNOTE_WS_PORT": "3002"
-          }
-        }
-      }
-    }
-  }
-}
+```bash
+claude mcp remove remnote
+```
+
+Example output:
+
+```text
+✓ Removed MCP server "remnote"
+  Config: /Users/username/.claude.json
 ```
 
-**Configuration Notes:**
+### Claude Code CLI (manual configuration)
+
+If you prefer to manually configure the MCP server in Claude Code CLI instead of using `claude mcp add`, you can
+directly edit your `~/.claude.json` file.
 
-- **Global availability:** Use your home directory path (`/Users/username`) to make RemNote tools available in all
-  projects
-- **Project-specific:** Use a specific project path to limit availability to that project
-- **Multiple projects:** Add `mcpServers` configuration under each project path as needed
+MCP servers are configured in `~/.claude.json` under the `mcpServers` key within project-specific sections.
 
-**Example with multiple projects:**
+**Add to your `~/.claude.json`:**
 
 ```json
 {
   "projects": {
     "/Users/username": {
+      ...
       "mcpServers": {
         "remnote": {
-          "type": "stdio",
-          "command": "remnote-mcp-server",
-          "args": [],
-          "env": {
-            "REMNOTE_WS_PORT": "3002"
-          }
+          "type": "http",
+          "url": "http://localhost:3001/mcp"
         }
-      }
-    },
-    "/Users/username/Projects/my-project": {
-      "mcpServers": {
-        "remnote": {
-          "type": "stdio",
-          "command": "remnote-mcp-server",
-          "args": [],
-          "env": {
-            "REMNOTE_WS_PORT": "3002"
-          }
-        }
-      }
-    }
-  }
+   ...     
 }
 ```
 
-### 4. Restart Claude Code
-
-Restart Claude Code completely to load the MCP server configuration. The server will start automatically when Claude
-Code launches.
+Restart Claude Code completely to load the MCP server configuration. Claude Code will connect to the running server.
 
 ## Verification
 
 ### Check Server is Running
 
-After Claude Code restarts, verify the server started:
+Verify both ports are listening:
 
 ```bash
-# Check process is running
-ps aux | grep remnote-mcp-server
+# Check HTTP port (MCP)
+lsof -i :3001
 
-# Check WebSocket port is listening
+# Check WebSocket port (RemNote bridge)
 lsof -i :3002
 ```
 
-You should see the `remnote-mcp-server` process running.
+You should see the `node` process listening on both ports.
 
 ### Check RemNote Plugin Connection
 
@@ -272,12 +315,11 @@ Use remnote_status to check the connection
 Expected response:
 
 ```json
-{
-  "connected": true,
-  "actionsProcessed": 0,
-  "pluginVersion": "1.1.0",
-  "timestamp": "2026-02-07T..."
-}
+⏺ remnote - remnote_status (MCP)
+  ⎿ {
+       "connected": true,
+       "pluginVersion": "0.3.2"
+     }
 ```
 
 ### Test RemNote Integration
@@ -343,30 +385,24 @@ Check if RemNote is connected
 
 ### Environment Variables
 
+- `REMNOTE_HTTP_PORT` - HTTP MCP server port (default: 3001)
 - `REMNOTE_WS_PORT` - WebSocket server port (default: 3002)
 
-**Example with custom port:**
+**Example with custom ports:**
 
-```json
-{
-  "projects": {
-    "/Users/username": {
-      "mcpServers": {
-        "remnote": {
-          "type": "stdio",
-          "command": "remnote-mcp-server",
-          "args": [],
-          "env": {
-            "REMNOTE_WS_PORT": "3003"
-          }
-        }
-      }
-    }
-  }
-}
+```bash
+# Set environment variables before starting
+export REMNOTE_HTTP_PORT=3003
+export REMNOTE_WS_PORT=3004
+npm start
+# you can pass CLI options after `--`, e.g.
+npm start -- -h
 ```
 
-**Note:** If you change the port, you must also update the WebSocket URL in the RemNote MCP Bridge plugin settings.
+Then update your `~/.claude.json` and RemNote plugin settings to use the new ports.
+
+**Note:** If you change the WebSocket port, you must also update the WebSocket URL in the RemNote MCP Bridge plugin
+settings.
 
 ### RemNote Plugin Settings
 
@@ -379,43 +415,35 @@ Configure in the plugin control panel:
 
 ### Server Not Starting
 
-1. **Check if installed globally:**
-   ```bash
-   which remnote-mcp-server
-   ```
-   Should return a path to the executable.
-
-2. **Reinstall if needed:**
-
-   **For npm installation:**
+1. **Verify the server is running:**
    ```bash
-   npm install -g remnote-mcp-server
+   lsof -i :3001
+   lsof -i :3002
    ```
+Both ports should show active listeners.
 
-   **For source installation:**
-   ```bash
-   cd ~/Projects/_private/remnote-mcp-server
-   npm link
-   ```
-
-3. **Check Claude Code logs:**
-   ```bash
-   tail -f ~/.claude/debug/mcp-*.log
-   ```
+2. **Check server output:**
+   - You should see: `[HTTP Server] Listening on port 3001`
+   - And: `[WebSocket Server] Listening on port 3002`
+3. **If server fails to start:**
+   - Check if ports are already in use (see "Port Already in Use" below)
+   - Verify installation: `which remnote-mcp-server`
+   - Check server logs for errors
 
-### Port 3002 Already in Use
+### Port Already in Use
 
-If you see "EADDRINUSE" error:
+If you see "EADDRINUSE" error for port 3001 or 3002:
 
 ```bash
-# Find what's using the port
+# Find what's using the ports
+lsof -i :3001
 lsof -i :3002
 
 # Kill the process if needed
 kill -9 <PID>
 ```
 
-Alternatively, configure a different port in both `~/.claude.json` and the RemNote plugin settings.
+Alternatively, configure different ports using environment variables (see Configuration section).
 
 ### Plugin Won't Connect
 
@@ -447,32 +475,34 @@ Alternatively, configure a different port in both `~/.claude.json` and the RemNo
 
 ### Configuration Not Working
 
-**Common issue:** Using the old `~/.claude/.mcp.json` file format
+**Common issues:**
+
+❌ **Wrong transport type:**
+```json
+"type": "stdio"  // OLD - doesn't work anymore
+```
+
+✅ **Correct transport type:**
+```json
+"type": "http"  // NEW - required
+```
 
-❌ **Old format (deprecated):**
+❌ **Using command instead of URL:**
 ```json
-// File: ~/.claude/.mcp.json
 {
-  "remnote": { ... }
+  "type": "stdio",
+  "command": "remnote-mcp-server"  // OLD
 }
 ```
 
-✅ **Correct format:**
+✅ **Correct configuration:**
 ```json
-// File: ~/.claude.json
 {
-  "projects": {
-    "/Users/username": {
-      "mcpServers": {
-        "remnote": { ... }
-      }
-    }
-  }
+  "type": "http",
+  "url": "http://127.0.0.1:3001/mcp"  // NEW
 }
 ```
 
-The `enabledMcpjsonServers` setting in `~/.claude/settings.json` is also deprecated and no longer needed.
-
 ## Development
 
 ### Setup
@@ -507,37 +537,9 @@ npm run lint         # ESLint only
 npm run format       # Format code
 ```
 
-### Before Committing
-
-Run `./code-quality.sh` to ensure all checks pass.
-
-### Manual Testing
-
-To test the server independently (without Claude Code):
-
-```bash
-# Stop Claude Code first to free port 3002
-cd ~/Projects/_private/remnote-mcp-server
-npm run dev
-```
-
-Expected output:
-```
-[WebSocket Server] Listening on port 3002
-[MCP Server] Server started on stdio
-```
-
-When the RemNote plugin connects:
-```
-[WebSocket Server] Client connected
-[RemNote Bridge] RemNote plugin connected
-```
-
-Press Ctrl+C to stop.
-
 ### Development Documentation
 
-- **[IMPLEMENTATION.md](./IMPLEMENTATION.md)** - Technical implementation details
+- **[docs/architecture.md](./docs/architecture.md)** - Architecture and design rationale
 - **[AGENTS.md](./AGENTS.md)** - AI agent and developer guidance
 - **[CHANGELOG.md](./CHANGELOG.md)** - Version history
 

package/dist/cli.d.ts

@@ -0,0 +1,14 @@
+export interface CliOptions {
+    wsPort?: number;
+    httpPort?: number;
+    logLevel?: string;
+    logLevelFile?: string;
+    verbose?: boolean;
+    logFile?: string;
+    requestLog?: string;
+    responseLog?: string;
+}
+/**
+ * Parse CLI arguments and return typed options
+ */
+export declare function parseCliArgs(): CliOptions;