reflect-mcp 1.0.12 → 1.0.14

package/dist/cli.js

@@ -34,54 +34,52 @@ function isPortInUse(port) {
     });
 }
 /**
- * Kill any process using the specified port
+ * Find a free port starting from startPort.
+ * Returns the first available port within maxAttempts tries,
+ * or throws if none is found.
  */
-function killProcessOnPort(port) {
-    try {
-        // Get PID(s) using the port
-        const pids = execSync(`lsof -ti:${port}`, { encoding: "utf-8" }).trim();
-        if (pids) {
-            console.log(`⚠️  Port ${port} in use by PID(s): ${pids.replace(/\n/g, ", ")}`);
-            execSync(`lsof -ti:${port} | xargs kill -9`, { stdio: "ignore" });
-            console.log(`✅ Killed existing process(es) on port ${port}`);
-            return true;
-        }
-    }
-    catch {
-        // No process found on port, or kill failed - that's fine
-    }
-    return false;
-}
-/**
- * Ensure the port is free, killing any existing process if needed
- */
-async function ensurePortFree(port) {
-    if (await isPortInUse(port)) {
-        killProcessOnPort(port);
-        // Wait a moment for the port to be released
-        await new Promise((resolve) => setTimeout(resolve, 500));
-        // Check again
-        if (await isPortInUse(port)) {
-            throw new Error(`Port ${port} is still in use after attempting to free it`);
+async function findFreePort(startPort, maxAttempts = 10) {
+    for (let i = 0; i < maxAttempts; i++) {
+        const candidate = startPort + i;
+        if (!(await isPortInUse(candidate))) {
+            return candidate;
         }
     }
+    throw new Error(`No free port found in range ${startPort}–${startPort + maxAttempts - 1}`);
 }
 const REFLECT_CLIENT_ID = "55798f25d5a24efb95e4174fff3d219e";
+const platform = os.platform();
+// macOS LaunchAgent paths
 const LAUNCH_AGENT_LABEL = "com.reflect-mcp";
 const LAUNCH_AGENT_DIR = path.join(os.homedir(), "Library/LaunchAgents");
 const LAUNCH_AGENT_PATH = path.join(LAUNCH_AGENT_DIR, `${LAUNCH_AGENT_LABEL}.plist`);
+// Linux systemd user service paths
+const SYSTEMD_SERVICE_NAME = "reflect-mcp";
+const SYSTEMD_USER_DIR = path.join(os.homedir(), ".config/systemd/user");
+const SYSTEMD_SERVICE_PATH = path.join(SYSTEMD_USER_DIR, `${SYSTEMD_SERVICE_NAME}.service`);
+function requireSupportedPlatform() {
+    if (platform !== "darwin" && platform !== "linux") {
+        console.error(`❌ Service management is not supported on ${platform}.`);
+        console.error("   Supported platforms: macOS (darwin), Linux");
+        console.error("   You can still run the server directly: reflect-mcp [db-path]");
+        process.exit(1);
+    }
+}
 // Get the command and arguments
 const args = process.argv.slice(2);
 const command = args[0];
 // Handle commands
 (async () => {
     if (command === "install") {
+        requireSupportedPlatform();
         await install(args.slice(1));
     }
     else if (command === "uninstall") {
+        requireSupportedPlatform();
         uninstall();
     }
     else if (command === "status") {
+        requireSupportedPlatform();
         status();
     }
     else if (command === "--help" || command === "-h") {
@@ -93,6 +91,9 @@ const command = args[0];
     }
 })();
 function showHelp() {
+    const dbDefault = DEFAULT_DB_PATH
+        ? `(default: ${DEFAULT_DB_PATH})`
+        : "(required on Linux — no default path)";
     console.log(`
 Reflect MCP Server - Connect your Reflect notes to Claude
 
@@ -104,13 +105,13 @@ Usage:
 
 Arguments:
   db-path     Path to Reflect SQLite database
-              (default: ${DEFAULT_DB_PATH})
+              ${dbDefault}
 
 Options:
   --port <port>   Port to run server on (default: 3000)
 
 Examples:
-  reflect-mcp install                       # Install with default db path
+  reflect-mcp install                       # Install with default db path (macOS)
   reflect-mcp install ~/my/reflect/db       # Install with custom db path
   reflect-mcp uninstall                     # Remove auto-start
   reflect-mcp                               # Run server manually
@@ -118,7 +119,7 @@ Examples:
     process.exit(0);
 }
 async function install(installArgs) {
-    let dbPath = DEFAULT_DB_PATH;
+    let dbPath;
     let port = 3000;
     // Parse install arguments
     for (let i = 0; i < installArgs.length; i++) {
@@ -129,11 +130,47 @@ async function install(installArgs) {
             dbPath = installArgs[i];
         }
     }
+    // On Linux there's no known default path -- require explicit db-path
+    if (!dbPath) {
+        if (platform === "linux") {
+            console.error("❌ On Linux, you must specify the database path:");
+            console.error("   reflect-mcp install /path/to/reflect.db");
+            process.exit(1);
+        }
+        dbPath = DEFAULT_DB_PATH;
+    }
     const expandedDbPath = expandPath(dbPath);
     const nodePath = process.execPath;
     const cliPath = process.argv[1];
     console.log("📦 Installing Reflect MCP Server as auto-start service...\n");
-    // Create Launch Agent directory if needed
+    if (platform === "darwin") {
+        installDarwin(nodePath, cliPath, expandedDbPath, port);
+    }
+    else {
+        installLinux(nodePath, cliPath, expandedDbPath, port);
+    }
+    console.log(`🚀 Reflect MCP Server will now auto-start on login`);
+    console.log(`   Server: http://localhost:${port}`);
+    console.log(`   Database: ${expandedDbPath}`);
+    if (platform === "darwin") {
+        console.log(`   Logs: tail -f /tmp/reflect-mcp.log\n`);
+    }
+    else {
+        console.log(`   Logs: journalctl --user -u ${SYSTEMD_SERVICE_NAME} -f\n`);
+    }
+    console.log(`📋 Add to Claude Desktop config (~/.config/claude/claude_desktop_config.json):`);
+    console.log(`{
+  "mcpServers": {
+    "reflect": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "http://localhost:${port}/mcp", "--port", "4209"]
+    }
+  }
+}`);
+    console.log(`   Note: Make sure the port (${port}) matches the port you used when installing the server.`);
+    console.log(`   Important: Add "--port", "4209" (or a different port like "4210", "4211", etc.) to avoid conflicts if you have multiple MCP clients running.`);
+}
+function installDarwin(nodePath, cliPath, expandedDbPath, port) {
     if (!fs.existsSync(LAUNCH_AGENT_DIR)) {
         fs.mkdirSync(LAUNCH_AGENT_DIR, { recursive: true });
     }
@@ -145,10 +182,6 @@ async function install(installArgs) {
     catch {
         // Ignore errors - service might not exist yet
     }
-    // Kill any stale processes on the port
-    killProcessOnPort(port);
-    await new Promise((resolve) => setTimeout(resolve, 300));
-    // Create plist content
     const plist = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -173,10 +206,8 @@ async function install(installArgs) {
     <string>/tmp/reflect-mcp.log</string>
 </dict>
 </plist>`;
-    // Write plist file
     fs.writeFileSync(LAUNCH_AGENT_PATH, plist);
     console.log(`✅ Created: ${LAUNCH_AGENT_PATH}`);
-    // Load and start the service
     try {
         execSync(`launchctl load ${LAUNCH_AGENT_PATH}`);
         execSync(`launchctl start ${LAUNCH_AGENT_LABEL}`);
@@ -186,40 +217,90 @@ async function install(installArgs) {
         console.error("❌ Failed to start service:", error);
         process.exit(1);
     }
-    console.log(`🚀 Reflect MCP Server will now auto-start on login`);
-    console.log(`   Server: http://localhost:${port}`);
-    console.log(`   Database: ${expandedDbPath}`);
-    console.log(`   Logs: tail -f /tmp/reflect-mcp.log\n`);
-    console.log(`📋 Add to Claude Desktop config (~/.config/claude/claude_desktop_config.json):`);
-    console.log(`{
-  "mcpServers": {
-    "reflect": {
-      "command": "npx",
-      "args": ["-y", "mcp-remote", "--port", "4209", "http://localhost:${port}/mcp"]
-    }
-  }
-}`);
-    console.log(`   Note: Make sure the port (${port}) matches the port you used when installing the server.`);
-    console.log(`   Important: Add "--port", "4209" (or a different port like "4210", "4211", etc.) to avoid conflicts if you have multiple MCP clients running.`);
 }
-function uninstall() {
-    console.log("🗑️  Removing Reflect MCP Server auto-start service...\n");
+function installLinux(nodePath, cliPath, expandedDbPath, port) {
+    if (!fs.existsSync(SYSTEMD_USER_DIR)) {
+        fs.mkdirSync(SYSTEMD_USER_DIR, { recursive: true });
+    }
+    // Stop existing service if running
     try {
-        execSync(`launchctl stop ${LAUNCH_AGENT_LABEL} 2>/dev/null`, { stdio: "ignore" });
-        execSync(`launchctl unload ${LAUNCH_AGENT_PATH} 2>/dev/null`, { stdio: "ignore" });
+        execSync(`systemctl --user stop ${SYSTEMD_SERVICE_NAME} 2>/dev/null`, { stdio: "ignore" });
+        execSync(`systemctl --user disable ${SYSTEMD_SERVICE_NAME} 2>/dev/null`, { stdio: "ignore" });
     }
     catch {
-        // Ignore errors
+        // Ignore errors - service might not exist yet
     }
-    if (fs.existsSync(LAUNCH_AGENT_PATH)) {
-        fs.unlinkSync(LAUNCH_AGENT_PATH);
-        console.log(`✅ Removed: ${LAUNCH_AGENT_PATH}`);
+    const unit = `[Unit]
+Description=Reflect MCP Server
+After=network.target
+
+[Service]
+ExecStart=${nodePath} ${cliPath} ${expandedDbPath} --port ${port}
+Restart=always
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target
+`;
+    fs.writeFileSync(SYSTEMD_SERVICE_PATH, unit);
+    console.log(`✅ Created: ${SYSTEMD_SERVICE_PATH}`);
+    try {
+        execSync("systemctl --user daemon-reload");
+        execSync(`systemctl --user enable --now ${SYSTEMD_SERVICE_NAME}`);
+        console.log("✅ Service installed and started!\n");
+    }
+    catch (error) {
+        console.error("❌ Failed to start service:", error);
+        console.error("   Make sure systemd user services are available (systemctl --user).");
+        process.exit(1);
+    }
+}
+function uninstall() {
+    console.log("🗑️  Removing Reflect MCP Server auto-start service...\n");
+    if (platform === "darwin") {
+        try {
+            execSync(`launchctl stop ${LAUNCH_AGENT_LABEL} 2>/dev/null`, { stdio: "ignore" });
+            execSync(`launchctl unload ${LAUNCH_AGENT_PATH} 2>/dev/null`, { stdio: "ignore" });
+        }
+        catch {
+            // Ignore errors
+        }
+        if (fs.existsSync(LAUNCH_AGENT_PATH)) {
+            fs.unlinkSync(LAUNCH_AGENT_PATH);
+            console.log(`✅ Removed: ${LAUNCH_AGENT_PATH}`);
+        }
+    }
+    else {
+        try {
+            execSync(`systemctl --user disable --now ${SYSTEMD_SERVICE_NAME} 2>/dev/null`, { stdio: "ignore" });
+        }
+        catch {
+            // Ignore errors
+        }
+        if (fs.existsSync(SYSTEMD_SERVICE_PATH)) {
+            fs.unlinkSync(SYSTEMD_SERVICE_PATH);
+            console.log(`✅ Removed: ${SYSTEMD_SERVICE_PATH}`);
+        }
+        try {
+            execSync("systemctl --user daemon-reload", { stdio: "ignore" });
+        }
+        catch {
+            // Ignore errors
+        }
     }
     console.log("✅ Service uninstalled. Server will no longer auto-start.");
 }
 function status() {
     console.log("📊 Reflect MCP Server Status\n");
-    // Check if plist exists
+    if (platform === "darwin") {
+        statusDarwin();
+    }
+    else {
+        statusLinux();
+    }
+}
+function statusDarwin() {
     if (fs.existsSync(LAUNCH_AGENT_PATH)) {
         console.log(`✅ Launch Agent installed: ${LAUNCH_AGENT_PATH}`);
     }
@@ -228,7 +309,6 @@ function status() {
         console.log("   Run: reflect-mcp install");
         return;
     }
-    // Check if service is running
     try {
         const result = execSync(`launchctl list | grep ${LAUNCH_AGENT_LABEL}`, { encoding: "utf-8" });
         if (result.includes(LAUNCH_AGENT_LABEL)) {
@@ -251,33 +331,74 @@ function status() {
     }
     console.log(`\n📝 Logs: tail -f /tmp/reflect-mcp.log`);
 }
+function statusLinux() {
+    if (!fs.existsSync(SYSTEMD_SERVICE_PATH)) {
+        console.log("❌ Systemd service not installed");
+        console.log("   Run: reflect-mcp install /path/to/reflect.db");
+        return;
+    }
+    console.log(`✅ Systemd service installed: ${SYSTEMD_SERVICE_PATH}`);
+    try {
+        const result = execSync(`systemctl --user is-active ${SYSTEMD_SERVICE_NAME} 2>/dev/null`, { encoding: "utf-8" }).trim();
+        if (result === "active") {
+            console.log("✅ Service running");
+        }
+        else {
+            console.log(`⚠️  Service not active (state: ${result})`);
+        }
+    }
+    catch {
+        // is-active exits non-zero when inactive/failed
+        try {
+            const result = execSync(`systemctl --user show ${SYSTEMD_SERVICE_NAME} --property=ActiveState --value 2>/dev/null`, { encoding: "utf-8" }).trim();
+            console.log(`❌ Service ${result || "not loaded"}`);
+        }
+        catch {
+            console.log("❌ Service not loaded");
+        }
+    }
+    console.log(`\n📝 Logs: journalctl --user -u ${SYSTEMD_SERVICE_NAME} -f`);
+}
 async function runServer(serverArgs) {
-    let dbPath = DEFAULT_DB_PATH;
-    let port = 3000;
+    let dbPath;
+    let requestedPort = 3000;
     for (let i = 0; i < serverArgs.length; i++) {
         if (serverArgs[i] === "--port" && serverArgs[i + 1]) {
-            port = parseInt(serverArgs[++i]);
+            requestedPort = parseInt(serverArgs[++i]);
         }
         else if (!serverArgs[i].startsWith("--")) {
             dbPath = serverArgs[i];
         }
     }
-    // Ensure port is free before starting
+    if (!dbPath) {
+        if (platform === "linux") {
+            console.error("❌ On Linux, you must specify the database path:");
+            console.error("   reflect-mcp /path/to/reflect.db");
+            process.exit(1);
+        }
+        dbPath = DEFAULT_DB_PATH;
+    }
+    // Find the first free port at or above the requested port.
+    // This allows multiple MCP clients to each get their own HTTP server
+    // without killing other running instances.
+    let port;
     try {
-        await ensurePortFree(port);
+        port = await findFreePort(requestedPort);
     }
     catch (err) {
-        console.error(`❌ ${err}`);
+        console.error(`[reflect-mcp] ${err}`);
         process.exit(1);
     }
+    if (port !== requestedPort) {
+        console.error(`[reflect-mcp] Requested port ${requestedPort} is in use — using port ${port} instead`);
+    }
     try {
         await startReflectMCPServer({
             clientId: REFLECT_CLIENT_ID,
             port,
             dbPath,
         });
-        console.log(`Reflect MCP Server running on http://localhost:${port}`);
-        console.log(`Database: ${dbPath}`);
+        console.error(`[reflect-mcp] HTTP server running on http://localhost:${port}`);
     }
     catch (err) {
         console.error("Failed to start server:", err);

package/dist/pkcehandler.d.ts

@@ -1,6 +1,9 @@
 /**
  * PKCE OAuth Proxy (No Client Secret Required)
  *
+ * Updated by Twice 🦸‍♂️
+ * Cloning capabilities enabled for multiple MCP clients
+ *
  * This module provides a custom OAuth proxy that uses PKCE for authentication
  * without requiring a client secret, suitable for public clients.
  */
@@ -25,6 +28,9 @@ export declare class PKCEOAuthProxy {
     private tokens;
     private recentlyExchangedCodes;
     private cleanupInterval;
+    private tokenMutex;
+    private tokenMutexBusy;
+    private activeConnections;
     constructor(options: PKCEOAuthProxyConfig);
     private loadTokensFromDisk;
     private saveTokensToDisk;
@@ -85,7 +91,7 @@ export declare class PKCEOAuthProxy {
         client_name?: string;
         redirect_uris?: string[];
     }>;
-    loadUpstreamTokens(proxyToken: string): TokenData | null;
+    loadUpstreamTokens(proxyToken: string): Promise<TokenData | null>;
     getFirstValidToken(): TokenData | null;
     private startCleanup;
     destroy(): void;

package/dist/pkcehandler.js

@@ -1,6 +1,9 @@
 /**
  * PKCE OAuth Proxy (No Client Secret Required)
  *
+ * Updated by Twice 🦸‍♂️
+ * Cloning capabilities enabled for multiple MCP clients
+ *
  * This module provides a custom OAuth proxy that uses PKCE for authentication
  * without requiring a client secret, suitable for public clients.
  */
@@ -10,6 +13,56 @@ import * as path from "path";
 import * as os from "os";
 import { OAuthProxyError } from "fastmcp/auth";
 // ============================================================================
+// Write Queue - Prevents concurrent file I/O operations
+// ============================================================================
+/**
+ * Simple in-memory write queue that batches and serializes file writes.
+ * This prevents race conditions when multiple clients trigger disk writes simultaneously.
+ */
+class WriteQueue {
+    queue = [];
+    isProcessing = false;
+    /**
+     * Add a write operation to the queue and wait for it to complete
+     */
+    async add(writeOperation) {
+        return new Promise((resolve, reject) => {
+            const operation = async () => {
+                try {
+                    await writeOperation();
+                    resolve();
+                }
+                catch (error) {
+                    reject(error);
+                }
+            };
+            this.queue.push(operation);
+            this.processQueue();
+        });
+    }
+    /**
+     * Process the queue one operation at a time
+     */
+    async processQueue() {
+        if (this.isProcessing || this.queue.length === 0) {
+            return;
+        }
+        this.isProcessing = true;
+        const operation = this.queue.shift();
+        try {
+            await operation();
+        }
+        finally {
+            this.isProcessing = false;
+            // Small delay to batch rapid writes together
+            await new Promise(resolve => setTimeout(resolve, 10));
+            this.processQueue();
+        }
+    }
+}
+// Global write queue instance shared across all PKCEProxy instances
+const globalWriteQueue = new WriteQueue();
+// ============================================================================
 // PKCEOAuthProxy Class
 // ============================================================================
 export class PKCEOAuthProxy {
@@ -21,6 +74,12 @@ export class PKCEOAuthProxy {
     // Track tokens that have been exchanged but allow brief retry window
     recentlyExchangedCodes = new Map();
     cleanupInterval = null;
+    // In-memory mutex to prevent race conditions during token operations
+    // This ensures only one client can exchange a code at a time
+    tokenMutex = new Map();
+    tokenMutexBusy = false;
+    // Active connections counter for debugging
+    activeConnections = 0;
     constructor(options) {
         this.config = {
             baseUrl: options.baseUrl,
@@ -60,8 +119,9 @@ export class PKCEOAuthProxy {
             console.warn("[PKCEProxy] Failed to load tokens from disk:", error);
         }
     }
-    // Save tokens to disk
-    saveTokensToDisk() {
+    // Save tokens to disk - ASYNC with write queue
+    // This prevents blocking the event loop and prevents race conditions
+    async saveTokensToDisk() {
         try {
             const toStore = {};
             for (const [key, value] of this.tokens) {
@@ -71,7 +131,11 @@ export class PKCEOAuthProxy {
                     expiresAt: value.expiresAt.toISOString(),
                 };
             }
-            fs.writeFileSync(this.config.tokenStoragePath, JSON.stringify(toStore, null, 2));
+            // Use the global write queue to serialize this write operation
+            await globalWriteQueue.add(async () => {
+                await fs.promises.writeFile(this.config.tokenStoragePath, JSON.stringify(toStore, null, 2), "utf-8");
+            });
+            console.log(`[PKCEProxy] Saved ${toStore.length} tokens to disk`);
         }
         catch (error) {
             console.error("[PKCEProxy] Failed to save tokens to disk:", error);
@@ -106,8 +170,8 @@ export class PKCEOAuthProxy {
             console.warn("[PKCEProxy] Failed to load transactions from disk:", error);
         }
     }
-    // Save transactions to disk (survives server restarts)
-    saveTransactionsToDisk() {
+    // Save transactions to disk (survives server restarts) - ASYNC with write queue
+    async saveTransactionsToDisk() {
         try {
             const toStore = {};
             for (const [key, value] of this.transactions) {
@@ -122,7 +186,11 @@ export class PKCEOAuthProxy {
                     expiresAt: value.expiresAt.toISOString(),
                 };
             }
-            fs.writeFileSync(this.config.transactionStoragePath, JSON.stringify(toStore, null, 2));
+            // Use the global write queue to serialize this write operation
+            await globalWriteQueue.add(async () => {
+                await fs.promises.writeFile(this.config.transactionStoragePath, JSON.stringify(toStore, null, 2), "utf-8");
+            });
+            console.log(`[PKCEProxy] Saved ${toStore.length} transactions to disk`);
         }
         catch (error) {
             console.error("[PKCEProxy] Failed to save transactions to disk:", error);
@@ -179,7 +247,7 @@ export class PKCEOAuthProxy {
             expiresAt: new Date(Date.now() + 600 * 1000), // 10 minutes
         };
         this.transactions.set(transactionId, transaction);
-        this.saveTransactionsToDisk(); // Persist to survive restarts
+        await this.saveTransactionsToDisk(); // Persist to survive restarts (async now)
         console.log("[PKCEProxy] Created transaction:", transactionId);
         // Build upstream authorization URL
         const authUrl = new URL(this.config.authorizationEndpoint);
@@ -228,7 +296,7 @@ export class PKCEOAuthProxy {
         }
         if (transaction.expiresAt < new Date()) {
             this.transactions.delete(state);
-            this.saveTransactionsToDisk();
+            await this.saveTransactionsToDisk();
             console.error("[PKCEProxy] Transaction expired, created:", transaction.createdAt, "expired:", transaction.expiresAt);
             return new Response(JSON.stringify({ error: "transaction_expired" }), {
                 status: 400,
@@ -265,14 +333,14 @@ export class PKCEOAuthProxy {
             refreshToken: tokens.refresh_token,
             expiresAt: new Date(Date.now() + (tokens.expires_in || 3600) * 1000),
         });
-        this.saveTokensToDisk(); // Persist to disk
+        await this.saveTokensToDisk(); // Persist to disk (async now)
         // Redirect back to client with our proxy token
         const clientRedirect = new URL(transaction.clientCallbackUrl);
         clientRedirect.searchParams.set("code", proxyToken);
         clientRedirect.searchParams.set("state", transaction.clientState);
         // Clean up transaction
         this.transactions.delete(state);
-        this.saveTransactionsToDisk();
+        await this.saveTransactionsToDisk();
         console.log("[PKCEProxy] Redirecting to client:", clientRedirect.toString());
         return new Response(null, {
             status: 302,
@@ -285,11 +353,12 @@ export class PKCEOAuthProxy {
         if (!params.code) {
             throw new OAuthProxyError("invalid_request", "Missing authorization code", 400);
         }
+        console.log(`[PKCEProxy] Exchange requested for code: ${params.code.slice(0, 8)}... (connections: ${this.activeConnections})`);
         // Check if this code was recently exchanged (retry tolerance)
         // This allows mcp-remote to retry if the first request timed out but actually succeeded
         const recentExchange = this.recentlyExchangedCodes.get(params.code);
         if (recentExchange && recentExchange.expiresAt > new Date()) {
-            console.log("[PKCEProxy] Returning cached token for retry of code:", params.code.slice(0, 8) + "...");
+            console.log(`[PKCEProxy] Returning cached token for retry of code: ${params.code.slice(0, 8)}...`);
             const tokenData = this.tokens.get(recentExchange.accessToken);
             if (tokenData) {
                 const expiresIn = Math.floor((tokenData.expiresAt.getTime() - Date.now()) / 1000);
@@ -300,33 +369,83 @@ export class PKCEOAuthProxy {
                 };
             }
         }
-        const tokenData = this.tokens.get(params.code);
-        if (!tokenData) {
-            console.error("[PKCEProxy] Token not found for code:", params.code);
-            console.error("[PKCEProxy] Available tokens:", Array.from(this.tokens.keys()).map(k => k.slice(0, 8) + "..."));
-            console.error("[PKCEProxy] Recently exchanged codes:", Array.from(this.recentlyExchangedCodes.keys()).map(k => k.slice(0, 8) + "..."));
-            throw new OAuthProxyError("invalid_grant", "Invalid or expired authorization code", 400);
-        }
-        // Remove the code but keep track of it for retry tolerance (30 second window)
-        this.tokens.delete(params.code);
-        // Generate a new access token for the client
-        const accessToken = this.generateId();
-        this.tokens.set(accessToken, tokenData);
-        this.saveTokensToDisk(); // Persist to disk
-        // Store the exchange for retry tolerance (30 seconds)
-        this.recentlyExchangedCodes.set(params.code, {
-            accessToken,
-            expiresAt: new Date(Date.now() + 30 * 1000),
-        });
-        const expiresIn = Math.floor((tokenData.expiresAt.getTime() - Date.now()) / 1000);
-        console.log("[PKCEProxy] Issuing access token, expires in:", expiresIn, "seconds");
-        return {
-            access_token: accessToken,
-            token_type: "Bearer",
-            expires_in: expiresIn > 0 ? expiresIn : 3600,
-            // Note: Not returning refresh_token since Reflect doesn't support refresh_token grant
-            // This tells the MCP client to re-authenticate via OAuth when the token expires
+        // Acquire mutex for this specific code to prevent race conditions
+        // This ensures only ONE client can exchange a given code at a time
+        let releaseMutex;
+        const acquireMutex = async () => {
+            const codeKey = `code_${params.code}`;
+            while (this.tokenMutex.has(codeKey)) {
+                // Wait for the current exchange to complete
+                await new Promise(resolve => setTimeout(resolve, 10));
+            }
+            // Create a pending promise to indicate we're acquiring the lock
+            const pending = new Promise(resolve => {
+                releaseMutex = resolve;
+                this.tokenMutex.set(codeKey, Promise.resolve());
+            });
+            // Check if we got the lock before another concurrent request took it
+            if (this.tokenMutex.get(codeKey) !== pending) {
+                this.tokenMutex.delete(codeKey);
+                return acquireMutex(); // Try again
+            }
+            await pending;
+        };
+        const releaseMutexForCode = (code) => {
+            const codeKey = `code_${code}`;
+            this.tokenMutex.delete(codeKey);
         };
+        try {
+            await acquireMutex();
+            // Check again after acquiring mutex - another request might have already processed this code
+            const cachedExchange = this.recentlyExchangedCodes.get(params.code);
+            if (cachedExchange && cachedExchange.expiresAt > new Date()) {
+                const cachedTokenData = this.tokens.get(cachedExchange.accessToken);
+                if (cachedTokenData) {
+                    const expiresIn = Math.floor((cachedTokenData.expiresAt.getTime() - Date.now()) / 1000);
+                    return {
+                        access_token: cachedExchange.accessToken,
+                        token_type: "Bearer",
+                        expires_in: expiresIn > 0 ? expiresIn : 3600,
+                    };
+                }
+            }
+            const tokenData = this.tokens.get(params.code);
+            if (!tokenData) {
+                console.error(`[PKCEProxy] Token not found for code: ${params.code}`);
+                console.error(`[PKCEProxy] Available tokens:`, Array.from(this.tokens.keys()).map(k => k.slice(0, 8) + "..."));
+                console.error(`[PKCEProxy] Recently exchanged codes:`, Array.from(this.recentlyExchangedCodes.keys()).map(k => k.slice(0, 8) + "..."));
+                throw new OAuthProxyError("invalid_grant", "Invalid or expired authorization code", 400);
+            }
+            // Remove the code but keep track of it for retry tolerance (30 second window)
+            // Mark as exchanged BEFORE saving to disk to prevent race conditions
+            this.tokens.delete(params.code);
+            // Generate a new access token for the client
+            const accessToken = this.generateId();
+            this.tokens.set(accessToken, tokenData);
+            // Store the exchange for retry tolerance (30 seconds) - mark as exchanged
+            this.recentlyExchangedCodes.set(params.code, {
+                accessToken,
+                expiresAt: new Date(Date.now() + 30 * 1000),
+            });
+            // Now save to disk - this is the only write operation during the critical section
+            await this.saveTokensToDisk();
+            const expiresIn = Math.floor((tokenData.expiresAt.getTime() - Date.now()) / 1000);
+            console.log(`[PKCEProxy] Issued access token (expires in ${expiresIn}s) for code: ${params.code.slice(0, 8)}...`);
+            return {
+                access_token: accessToken,
+                token_type: "Bearer",
+                expires_in: expiresIn > 0 ? expiresIn : 3600,
+                // Note: Not returning refresh_token since Reflect doesn't support refresh_token grant
+                // This tells the MCP client to re-authenticate via OAuth when the token expires
+            };
+        }
+        catch (error) {
+            throw error;
+        }
+        finally {
+            // Release the mutex
+            releaseMutexForCode(params.code);
+        }
     }
     // Handle refresh token exchange
     // Note: Reflect's API doesn't support standard refresh_token grant
@@ -349,7 +468,7 @@ export class PKCEOAuthProxy {
         };
     }
     // Load upstream tokens for a given proxy token
-    loadUpstreamTokens(proxyToken) {
+    async loadUpstreamTokens(proxyToken) {
         const data = this.tokens.get(proxyToken);
         if (!data) {
             console.warn("[PKCEProxy] Token not found:", proxyToken.slice(0, 8) + "...");
@@ -360,7 +479,7 @@ export class PKCEOAuthProxy {
         if (data.expiresAt < now) {
             console.warn("[PKCEProxy] Token expired:", proxyToken.slice(0, 8) + "...", "expired at:", data.expiresAt, "now:", now);
             this.tokens.delete(proxyToken);
-            this.saveTokensToDisk();
+            await this.saveTokensToDisk();
             return null;
         }
         const timeRemaining = Math.floor((data.expiresAt.getTime() - now.getTime()) / 1000);
@@ -380,8 +499,8 @@ export class PKCEOAuthProxy {
         return null;
     }
     // Cleanup expired transactions, tokens, and retry cache
-    startCleanup() {
-        this.cleanupInterval = setInterval(() => {
+    async startCleanup() {
+        const cleanup = async () => {
             const now = new Date();
             let tokensChanged = false;
             let transactionsChanged = false;
@@ -405,12 +524,15 @@ export class PKCEOAuthProxy {
                 }
             }
             if (tokensChanged) {
-                this.saveTokensToDisk();
+                await this.saveTokensToDisk();
             }
             if (transactionsChanged) {
-                this.saveTransactionsToDisk();
+                await this.saveTransactionsToDisk();
             }
-        }, 60000); // Every minute
+        };
+        this.cleanupInterval = setInterval(cleanup, 60000); // Every minute
+        // Run cleanup immediately on startup
+        await cleanup();
     }
     destroy() {
         if (this.cleanupInterval) {

package/dist/server.d.ts

@@ -1,6 +1,9 @@
 /**
  * Reflect MCP Server Factory
  *
+ * Updated by Twice 🦸‍♂️
+ * Now handling multiple concurrent clients!
+ *
  * Creates and configures the FastMCP server with PKCE OAuth
  */
 export interface ServerConfig {
@@ -9,5 +12,11 @@ export interface ServerConfig {
     dbPath?: string;
 }
 export declare function startReflectMCPServer(config: ServerConfig): Promise<void>;
+/**
+ * Start the Reflect MCP server in stdio mode.
+ * Used when an HTTP server is already running on the port (e.g. a second MCP client).
+ * Reads the cached OAuth token from disk instead of running the full OAuth flow.
+ */
+export declare function startReflectMCPServerStdio(config: ServerConfig): Promise<void>;
 export { PKCEOAuthProxy } from "./pkcehandler.js";
 export * from "./utils.js";

package/dist/server.js

@@ -1,6 +1,9 @@
 /**
  * Reflect MCP Server Factory
  *
+ * Updated by Twice 🦸‍♂️
+ * Now handling multiple concurrent clients!
+ *
  * Creates and configures the FastMCP server with PKCE OAuth
  */
 import { FastMCP } from "fastmcp";
@@ -44,7 +47,7 @@ export async function startReflectMCPServer(config) {
             }
             const token = authHeader.slice(7);
             try {
-                const tokenData = pkceProxy.loadUpstreamTokens(token);
+                const tokenData = await pkceProxy.loadUpstreamTokens(token);
                 if (!tokenData) {
                     console.warn("[Auth] Token validation failed for:", token.slice(0, 8) + "... - triggering 401");
                     // Throw Response to trigger re-authentication (per FastMCP docs)
@@ -85,6 +88,43 @@ export async function startReflectMCPServer(config) {
         transportType: "httpStream",
     });
 }
+/**
+ * Start the Reflect MCP server in stdio mode.
+ * Used when an HTTP server is already running on the port (e.g. a second MCP client).
+ * Reads the cached OAuth token from disk instead of running the full OAuth flow.
+ */
+export async function startReflectMCPServerStdio(config) {
+    const port = config.port || 3000;
+    const baseUrl = `http://localhost:${port}`;
+    // Instantiate proxy only to read tokens from disk — no HTTP server needed
+    const pkceProxy = new PKCEOAuthProxy({
+        baseUrl,
+        clientId: config.clientId,
+        authorizationEndpoint: "https://reflect.app/oauth",
+        tokenEndpoint: "https://reflect.app/api/oauth/token",
+        scopes: ["read:graph", "write:graph"],
+    });
+    const server = new FastMCP({
+        name: "Reflect MCP Server",
+        // For stdio, FastMCP calls authenticate(undefined). We load the token from disk.
+        authenticate: async (_request) => {
+            const tokenData = pkceProxy.getFirstValidToken();
+            if (!tokenData) {
+                console.error("[Auth] No valid token on disk. Connect via HTTP mode first to complete OAuth.");
+                throw new Error("No valid token. Please authenticate via HTTP mode first.");
+            }
+            const expiresIn = Math.floor((tokenData.expiresAt.getTime() - Date.now()) / 1000);
+            console.error("[Auth] Stdio mode: token loaded from disk, expires in:", expiresIn, "seconds");
+            return {
+                accessToken: tokenData.accessToken,
+                expiresIn,
+            };
+        },
+        version: "1.0.0",
+    });
+    registerTools(server, config.dbPath);
+    await server.start({ transportType: "stdio" });
+}
 // Also export for programmatic use
 export { PKCEOAuthProxy } from "./pkcehandler.js";
 export * from "./utils.js";

package/dist/utils.d.ts

@@ -6,12 +6,14 @@
  */
 export declare function expandPath(filePath: string): string;
 /**
- * Searches for the Reflect local database file
- * Returns the first valid database path found, or null if not found
+ * Searches for the Reflect local database file.
+ * Only works on macOS where the Reflect app path is known.
+ * Returns the first valid database path found, or null if not found.
  */
 export declare function findLocalDatabase(): string | null;
 /**
- * Gets the default database path, searching for it if not provided
+ * Gets the default database path, searching for it if not provided.
+ * Returns empty string on non-macOS platforms where no default is known.
  */
 export declare function getDefaultDbPath(): string;
 export declare const DEFAULT_DB_PATH: string;

package/dist/utils.js

@@ -4,8 +4,10 @@
 import * as path from "path";
 import * as os from "os";
 import * as fs from "fs";
-// Base path for Reflect local database
-const REFLECT_BASE_PATH = "~/Library/Application Support/Reflect/File System";
+// Base path for Reflect local database (macOS only; no known Linux path)
+const REFLECT_BASE_PATH = os.platform() === "darwin"
+    ? "~/Library/Application Support/Reflect/File System"
+    : null;
 /**
  * Expands ~ to the user's home directory
  */
@@ -16,10 +18,14 @@ export function expandPath(filePath) {
     return filePath;
 }
 /**
- * Searches for the Reflect local database file
- * Returns the first valid database path found, or null if not found
+ * Searches for the Reflect local database file.
+ * Only works on macOS where the Reflect app path is known.
+ * Returns the first valid database path found, or null if not found.
  */
 export function findLocalDatabase() {
+    if (!REFLECT_BASE_PATH) {
+        return null;
+    }
     const basePath = expandPath(REFLECT_BASE_PATH);
     if (!fs.existsSync(basePath)) {
         return null;
@@ -69,15 +75,18 @@ export function findLocalDatabase() {
     return null;
 }
 /**
- * Gets the default database path, searching for it if not provided
+ * Gets the default database path, searching for it if not provided.
+ * Returns empty string on non-macOS platforms where no default is known.
  */
 export function getDefaultDbPath() {
     const found = findLocalDatabase();
     if (found) {
         return found;
     }
-    // Fallback to a common path pattern
-    return expandPath("~/Library/Application Support/Reflect/File System/000/t/00/00000000");
+    if (os.platform() === "darwin") {
+        return expandPath("~/Library/Application Support/Reflect/File System/000/t/00/00000000");
+    }
+    return "";
 }
 // For backwards compatibility
 export const DEFAULT_DB_PATH = getDefaultDbPath();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reflect-mcp",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "MCP server for Reflect Notes - connect your notes to Claude Desktop. Just run: npx reflect-mcp",
   "type": "module",
   "main": "dist/server.js",
@@ -39,7 +39,7 @@
     "@modelcontextprotocol/sdk": "^1.25.1",
     "better-sqlite3": "^11.10.0",
     "fastmcp": "^3.25.4",
-    "reflect-mcp": "^1.0.11",
+    "reflect-mcp": "^1.0.12",
     "zod": "^4.1.13"
   },
   "devDependencies": {