reflect-mcp 1.0.13 → 1.0.15

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,7 @@ export declare class PKCEOAuthProxy {
     private tokens;
     private recentlyExchangedCodes;
     private cleanupInterval;
+    private activeConnections;
     constructor(options: PKCEOAuthProxyConfig);
     private loadTokensFromDisk;
     private saveTokensToDisk;
@@ -85,7 +89,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,8 @@ export class PKCEOAuthProxy {
     // Track tokens that have been exchanged but allow brief retry window
     recentlyExchangedCodes = new Map();
     cleanupInterval = null;
+    // Active connections counter for debugging
+    activeConnections = 0;
     constructor(options) {
         this.config = {
             baseUrl: options.baseUrl,
@@ -60,8 +115,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 +127,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 ${Object.keys(toStore).length} tokens to disk`);
         }
         catch (error) {
             console.error("[PKCEProxy] Failed to save tokens to disk:", error);
@@ -106,8 +166,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 +182,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 ${Object.keys(toStore).length} transactions to disk`);
         }
         catch (error) {
             console.error("[PKCEProxy] Failed to save transactions to disk:", error);
@@ -164,6 +228,23 @@ export class PKCEOAuthProxy {
                 headers: { "Content-Type": "application/json" },
             });
         }
+        // If we already have a valid token, skip the full OAuth dance.
+        // Issue a proxy code immediately so subsequent clients never need a browser.
+        const existingToken = this.getFirstValidToken();
+        if (existingToken) {
+            console.log("[PKCEProxy] Valid token exists — issuing proxy code directly (skipping OAuth)");
+            const proxyCode = this.generateId();
+            this.tokens.set(proxyCode, { ...existingToken });
+            await this.saveTokensToDisk();
+            const clientRedirect = new URL(params.redirect_uri);
+            clientRedirect.searchParams.set("code", proxyCode);
+            clientRedirect.searchParams.set("state", params.state || "");
+            console.log("[PKCEProxy] Redirecting client directly to:", clientRedirect.toString());
+            return new Response(null, {
+                status: 302,
+                headers: { Location: clientRedirect.toString() },
+            });
+        }
         // Generate our own PKCE for upstream
         const pkce = this.generatePKCE();
         const transactionId = this.generateId();
@@ -179,7 +260,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 +309,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 +346,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 +366,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);
@@ -302,24 +384,26 @@ 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) + "..."));
+            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);
-        this.saveTokensToDisk(); // Persist to disk
-        // Store the exchange for retry tolerance (30 seconds)
+        // 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
+        await this.saveTokensToDisk();
         const expiresIn = Math.floor((tokenData.expiresAt.getTime() - Date.now()) / 1000);
-        console.log("[PKCEProxy] Issuing access token, expires in:", expiresIn, "seconds");
+        console.log(`[PKCEProxy] Issued access token (expires in ${expiresIn}s) for code: ${params.code.slice(0, 8)}...`);
         return {
             access_token: accessToken,
             token_type: "Bearer",
@@ -349,9 +433,17 @@ export class PKCEOAuthProxy {
         };
     }
     // Load upstream tokens for a given proxy token
-    loadUpstreamTokens(proxyToken) {
+    async loadUpstreamTokens(proxyToken) {
         const data = this.tokens.get(proxyToken);
         if (!data) {
+            // Token not found — check if this is a stale/rotated token from a previous session.
+            // For a local server, all clients share the same Reflect credentials, so we can
+            // fall back to any currently-valid token rather than forcing a re-auth loop.
+            const validToken = this.getFirstValidToken();
+            if (validToken) {
+                console.warn("[PKCEProxy] Stale token presented, mapping to current valid token:", proxyToken.slice(0, 8) + "...");
+                return validToken;
+            }
             console.warn("[PKCEProxy] Token not found:", proxyToken.slice(0, 8) + "...");
             console.warn("[PKCEProxy] Total tokens in store:", this.tokens.size);
             return null;
@@ -360,7 +452,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 +472,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 +497,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.15",
   "description": "MCP server for Reflect Notes - connect your notes to Claude Desktop. Just run: npx reflect-mcp",
   "type": "module",
   "main": "dist/server.js",