reflect-mcp 1.0.13 → 1.0.14

package/dist/cli.js

@@ -34,55 +34,18 @@ 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 {
-        let pids;
-        if (platform === "darwin") {
-            pids = execSync(`lsof -ti:${port}`, { encoding: "utf-8" }).trim();
-        }
-        else {
-            // Linux: try lsof first, fall back to fuser
-            try {
-                pids = execSync(`lsof -ti:${port}`, { encoding: "utf-8" }).trim();
-            }
-            catch {
-                pids = execSync(`fuser ${port}/tcp 2>/dev/null`, { encoding: "utf-8" }).trim();
-            }
-        }
-        if (pids) {
-            console.log(`⚠️  Port ${port} in use by PID(s): ${pids.replace(/\n/g, ", ")}`);
-            for (const pid of pids.split(/\s+/)) {
-                if (pid) {
-                    try {
-                        process.kill(parseInt(pid), "SIGKILL");
-                    }
-                    catch { /* already dead */ }
-                }
-            }
-            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();
@@ -180,9 +143,6 @@ async function install(installArgs) {
     const nodePath = process.execPath;
     const cliPath = process.argv[1];
     console.log("📦 Installing Reflect MCP Server as auto-start service...\n");
-    // Kill any stale processes on the port
-    killProcessOnPort(port);
-    await new Promise((resolve) => setTimeout(resolve, 300));
     if (platform === "darwin") {
         installDarwin(nodePath, cliPath, expandedDbPath, port);
     }
@@ -203,7 +163,7 @@ async function install(installArgs) {
   "mcpServers": {
     "reflect": {
       "command": "npx",
-      "args": ["-y", "mcp-remote", "--port", "4209", "http://localhost:${port}/mcp"]
+      "args": ["-y", "mcp-remote", "http://localhost:${port}/mcp", "--port", "4209"]
     }
   }
 }`);
@@ -401,10 +361,10 @@ function statusLinux() {
 }
 async function runServer(serverArgs) {
     let dbPath;
-    let port = 3000;
+    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];
@@ -418,22 +378,27 @@ async function runServer(serverArgs) {
         }
         dbPath = DEFAULT_DB_PATH;
     }
-    // Ensure port is free before starting
+    // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reflect-mcp",
-  "version": "1.0.13",
+  "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",