@meldocio/mcp-stdio-proxy 1.0.18 → 1.0.20

package/README.md

@@ -5,6 +5,25 @@
 
 This package allows you to connect Claude Desktop to your Meldoc account, so you can use all your documentation directly in Claude.
 
+## 🚀 Quick Start - Install from Claude Marketplace
+
+The easiest way to install Meldoc MCP is through the Claude Marketplace:
+
+```bash
+# Add the marketplace
+claude plugin marketplace add meldoc-io/mcp-stdio-proxy
+
+# Install the plugin
+claude plugin install meldoc-mcp@meldoc-mcp
+```
+
+After installation:
+
+1. Restart Claude Desktop (or your MCP client)
+2. Run `npx @meldocio/mcp-stdio-proxy@latest auth login` to authenticate
+
+Done! 🎉 Now you can ask Claude to work with your Meldoc documentation.
+
 ## What is this?
 
 This is a bridge between Claude Desktop and Meldoc. After setup, Claude will be able to:
@@ -20,20 +39,7 @@ This is a bridge between Claude Desktop and Meldoc. After setup, Claude will be
 
 ### Via Claude Marketplace (Recommended) 🚀
 
-The easiest way to install Meldoc MCP is through the Claude Marketplace:
-
-```bash
-# Add the marketplace
-claude plugin marketplace add meldoc/mcp-stdio-proxy
-
-# Install the plugin
-claude plugin install meldoc-mcp@meldoc
-```
-
-After installation:
-
-1. Restart Claude Desktop (or your MCP client)
-2. Run `npx @meldocio/mcp-stdio-proxy@latest auth login` to authenticate
+See [Quick Start](#-quick-start---install-from-claude-marketplace) section above for the easiest installation method.
 
 ### Via NPM
 
@@ -481,7 +487,7 @@ If you're experiencing connection errors:
 ### Setup
 
 ```bash
-git clone https://github.com/meldoc/mcp-stdio-proxy.git
+git clone https://github.com/meldoc-io/mcp-stdio-proxy.git
 cd mcp-stdio-proxy
 npm install
 ```
@@ -545,7 +551,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 For issues, questions, or contributions, please visit:
 
-- GitHub Issues: <https://github.com/meldoc/mcp-stdio-proxy/issues>
+- GitHub Issues: <https://github.com/meldoc-io/mcp-stdio-proxy/issues>
 - Documentation: <https://docs.meldoc.io>
 
 ## Related

package/bin/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-const { deviceFlowLogin } = require('../lib/device-flow');
+const { interactiveLogin } = require('../lib/device-flow');
 const { readCredentials, deleteCredentials } = require('../lib/credentials');
 const { getAuthStatus } = require('../lib/auth');
 const { setWorkspaceAlias, getWorkspaceAlias } = require('../lib/config');
@@ -30,31 +30,15 @@ if (process.env.MELDOC_APP_URL) {
  */
 async function handleAuthLogin() {
   try {
-    logger.section('🔐 Authentication');
-    await deviceFlowLogin(
-      (url, code) => {
-        console.log('\n' + logger.label('Visit this URL:'));
-        console.log('  ' + logger.url(url));
-        console.log('\n' + logger.label('Enter this code:'));
-        console.log('  ' + logger.code(code) + '\n');
-        logger.info('Waiting for authentication...');
-      },
-      (status) => {
-        if (status === 'denied') {
-          logger.error('Login denied by user');
-          process.exit(1);
-        } else if (status === 'expired') {
-          logger.error('Authentication code expired');
-          process.exit(1);
-        }
-      },
-      API_URL,
-      APP_URL
-    );
-    logger.success('Login successful!');
+    await interactiveLogin({
+      autoOpen: true,
+      showQR: false,
+      timeout: 120000,
+      apiBaseUrl: API_URL,
+      appUrl: APP_URL
+    });
     process.exit(0);
   } catch (error) {
-    logger.error(`Login failed: ${error.message}`);
     process.exit(1);
   }
 }

package/bin/meldoc-mcp-proxy.js

@@ -66,15 +66,21 @@ const LOG_LEVELS = {
 // Import new auth and workspace modules
 const { getAccessToken, getAuthStatus } = require('../lib/auth');
 const { resolveWorkspaceAlias } = require('../lib/workspace');
-const { getApiUrl } = require('../lib/constants');
+const { getApiUrl, getAppUrl } = require('../lib/constants');
 const { setWorkspaceAlias, getWorkspaceAlias } = require('../lib/config');
+const { interactiveLogin, canOpenBrowser } = require('../lib/device-flow');
 
 // Configuration
 const apiUrl = getApiUrl();
+const appUrl = getAppUrl();
 const rpcEndpoint = `${apiUrl}/mcp/v1/rpc`;
 const REQUEST_TIMEOUT = 25000; // 25 seconds (less than Claude Desktop's 30s timeout)
 const LOG_LEVEL = getLogLevel(process.env.LOG_LEVEL || 'ERROR');
 
+// Track if we've attempted auto-authentication
+let autoAuthAttempted = false;
+let autoAuthInProgress = false;
+
 // Get log level from environment
 function getLogLevel(level) {
   const upper = (level || '').toUpperCase();
@@ -803,13 +809,74 @@ async function handleToolsCall(request) {
   }
 }
 
+/**
+ * Attempt automatic authentication if conditions are met
+ * @returns {Promise<boolean>} True if authentication was attempted and succeeded
+ */
+async function attemptAutoAuth() {
+  // Only attempt once per session
+  if (autoAuthAttempted || autoAuthInProgress) {
+    return false;
+  }
+  
+  // Only in interactive mode (TTY) and not in CI
+  if (!canOpenBrowser()) {
+    return false;
+  }
+  
+  // Check if NO_AUTO_AUTH is set
+  if (process.env.NO_AUTO_AUTH === '1' || process.env.NO_AUTO_AUTH === 'true') {
+    return false;
+  }
+  
+  // Check if token already exists
+  const tokenInfo = await getAccessToken();
+  if (tokenInfo) {
+    return false;
+  }
+  
+  autoAuthAttempted = true;
+  autoAuthInProgress = true;
+  
+  try {
+    log(LOG_LEVELS.INFO, '🔐 First time setup - authentication required');
+    process.stderr.write('\n');
+    
+    await interactiveLogin({
+      autoOpen: true,
+      showQR: false,
+      timeout: 120000,
+      apiBaseUrl: apiUrl,
+      appUrl: appUrl
+    });
+    
+    autoAuthInProgress = false;
+    return true;
+  } catch (error) {
+    autoAuthInProgress = false;
+    log(LOG_LEVELS.WARN, `Auto-authentication failed: ${error.message}`);
+    log(LOG_LEVELS.INFO, 'You can authenticate manually: npx @meldocio/mcp-stdio-proxy@latest auth login');
+    return false;
+  }
+}
+
 /**
  * Process a single JSON-RPC request
  * Forwards the request to the backend MCP API
  */
 async function processSingleRequest(request) {
   // Get access token with priority and auto-refresh
-  const tokenInfo = await getAccessToken();
+  let tokenInfo = await getAccessToken();
+  
+  // If no token and we haven't attempted auto-auth, try it
+  if (!tokenInfo && !autoAuthAttempted && !autoAuthInProgress) {
+    const authSucceeded = await attemptAutoAuth();
+    if (authSucceeded) {
+      // Retry getting token after successful auth
+      tokenInfo = await getAccessToken();
+    }
+  }
+  
   if (!tokenInfo) {
     sendError(request.id, CUSTOM_ERROR_CODES.AUTH_REQUIRED, 
               'Meldoc token not found. Set MELDOC_ACCESS_TOKEN environment variable or run: npx @meldocio/mcp-stdio-proxy@latest auth login', {

package/lib/device-flow.js

@@ -3,6 +3,8 @@ const https = require('https');
 const { writeCredentials } = require('./credentials');
 const { getApiUrl, getAppUrl } = require('./constants');
 const logger = require('./logger');
+const os = require('os');
+const { exec } = require('child_process');
 
 /**
  * Start device flow authentication
@@ -256,8 +258,321 @@ async function deviceFlowLogin(onCodeDisplay, onStatusChange = null, apiBaseUrl
   throw new Error('Device code expired');
 }
 
+/**
+ * Check if browser can be opened automatically
+ * @returns {boolean} True if browser can be opened
+ */
+function canOpenBrowser() {
+  return process.stdout.isTTY && !process.env.CI && !process.env.NO_BROWSER;
+}
+
+/**
+ * Open browser automatically
+ * @param {string} url - URL to open
+ * @returns {Promise<void>}
+ */
+async function openBrowser(url) {
+  try {
+    // Try using 'open' package first (cross-platform)
+    const open = require('open');
+    await open(url);
+  } catch (error) {
+    // Fallback to platform-specific commands
+    try {
+      const platform = os.platform();
+      let command;
+      
+      if (platform === 'darwin') {
+        command = `open "${url}"`;
+      } else if (platform === 'win32') {
+        command = `start "" "${url}"`;
+      } else {
+        command = `xdg-open "${url}"`;
+      }
+      
+      exec(command, (err) => {
+        if (err) {
+          // Silent fail - browser opening is optional
+        }
+      });
+    } catch (fallbackError) {
+      // Silent fail - browser opening is optional
+    }
+  }
+}
+
+/**
+ * Copy text to clipboard
+ * @param {string} text - Text to copy
+ * @returns {Promise<void>}
+ */
+async function copyToClipboard(text) {
+  try {
+    const clipboardy = require('clipboardy');
+    await clipboardy.write(text);
+  } catch (error) {
+    // Silent fail - clipboard copy is optional
+  }
+}
+
+/**
+ * Show QR code for mobile authentication
+ * @param {string} url - URL to encode in QR code
+ */
+function showQRCode(url) {
+  try {
+    const qrcode = require('qrcode-terminal');
+    qrcode.generate(url, { small: true });
+  } catch (error) {
+    // Silent fail - QR code is optional
+  }
+}
+
+/**
+ * Sleep utility
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Poll for tokens with spinner and progress
+ * @param {string} deviceCode - Device code
+ * @param {number} interval - Polling interval in seconds
+ * @param {number} timeout - Timeout in milliseconds
+ * @param {string} apiBaseUrl - API base URL
+ * @returns {Promise<Object>} Credentials object
+ */
+async function pollForTokens({ deviceCode, interval, timeout, apiBaseUrl }) {
+  const startTime = Date.now();
+  const spinner = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let spinnerIndex = 0;
+  let spinnerInterval = null;
+  
+  // Start spinner animation if stderr is TTY
+  if (process.stderr.isTTY) {
+    spinnerInterval = setInterval(() => {
+      const elapsed = Math.floor((Date.now() - startTime) / 1000);
+      process.stderr.write(
+        `\r${spinner[spinnerIndex]} Waiting for authorization... (${elapsed}s)`
+      );
+      spinnerIndex = (spinnerIndex + 1) % spinner.length;
+    }, 100);
+  }
+  
+  try {
+    while (true) {
+      // Check timeout
+      if (Date.now() - startTime > timeout) {
+        throw new Error('Authentication timeout. Please try again.');
+      }
+      
+      try {
+        // Poll for status
+        const pollResponse = await pollDeviceFlow(deviceCode, apiBaseUrl);
+        
+        if (pollResponse.status === 'approved') {
+          // Clear spinner
+          if (spinnerInterval) {
+            clearInterval(spinnerInterval);
+            process.stderr.write('\r✅ Authorization confirmed!                    \n');
+          }
+          
+          // Validate that we have required fields
+          if (!pollResponse.accessToken) {
+            throw new Error(`Invalid poll response: missing accessToken. Response: ${JSON.stringify(pollResponse)}`);
+          }
+          
+          return pollResponse;
+        }
+        
+        if (pollResponse.status === 'denied') {
+          throw new Error('Authorization denied by user');
+        }
+        
+        if (pollResponse.status === 'expired') {
+          throw new Error('Device code expired');
+        }
+        
+        // status === 'pending' - continue polling
+        await sleep(interval * 1000);
+        
+      } catch (error) {
+        // If network error, retry
+        if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT' || error.message.includes('No response')) {
+          await sleep(interval * 1000);
+          continue;
+        }
+        throw error;
+      }
+    }
+  } finally {
+    if (spinnerInterval) {
+      clearInterval(spinnerInterval);
+      process.stderr.write('\r                                                \r');
+    }
+  }
+}
+
+/**
+ * Interactive login with automatic browser opening and enhanced UX
+ * @param {Object} options - Login options
+ * @param {boolean} options.autoOpen - Automatically open browser (default: true)
+ * @param {boolean} options.showQR - Show QR code (default: false)
+ * @param {number} options.timeout - Timeout in milliseconds (default: 120000)
+ * @param {string} options.apiBaseUrl - API base URL
+ * @param {string} options.appUrl - App URL
+ * @returns {Promise<Object>} Credentials object
+ */
+async function interactiveLogin(options = {}) {
+  const {
+    autoOpen = true,
+    showQR = false,
+    timeout = 120000,
+    apiBaseUrl = null,
+    appUrl = null
+  } = options;
+  
+  const url = apiBaseUrl || getApiUrl();
+  const frontendUrl = appUrl || getAppUrl();
+  
+  try {
+    // Step 1: Get device code from server
+    const startResponse = await startDeviceFlow(url);
+    const { deviceCode, userCode, verificationUrl, expiresIn, interval } = startResponse;
+    
+    // Step 2: Build full URL
+    let displayUrl = verificationUrl;
+    
+    // Check if verificationUrl already contains code in query parameter
+    let urlHasCode = false;
+    try {
+      const urlObj = new URL(verificationUrl);
+      if (urlObj.searchParams.has('code')) {
+        urlHasCode = true;
+      }
+    } catch (e) {
+      // URL parsing failed, continue
+    }
+    
+    if (process.env.MELDOC_APP_URL || appUrl) {
+      try {
+        const urlObj = new URL(verificationUrl);
+        const appUrlObj = new URL(frontendUrl);
+        displayUrl = `${appUrlObj.origin}${urlObj.pathname}${urlObj.search}`;
+      } catch (e) {
+        displayUrl = verificationUrl;
+      }
+    }
+    
+    // If URL doesn't have code, add it as path parameter
+    let fullUrl = displayUrl;
+    if (!urlHasCode) {
+      if (displayUrl.endsWith('/')) {
+        fullUrl = `${displayUrl}${userCode}`;
+      } else {
+        fullUrl = `${displayUrl}/${userCode}`;
+      }
+    }
+    
+    // Step 3: Display authentication UI
+    process.stderr.write('\n');
+    process.stderr.write('╔═══════════════════════════════════════════════════════╗\n');
+    process.stderr.write('║                                                       ║\n');
+    process.stderr.write('║   🔐 Meldoc Authentication Required                  ║\n');
+    process.stderr.write('║                                                       ║\n');
+    process.stderr.write('╚═══════════════════════════════════════════════════════╝\n');
+    process.stderr.write('\n');
+    
+    // Show QR code if requested
+    if (showQR) {
+      process.stderr.write('📱 Scan QR code with your phone:\n\n');
+      showQRCode(fullUrl);
+      process.stderr.write('\n');
+    }
+    
+    // Show URL and code
+    process.stderr.write(`🌐 Visit: ${fullUrl}\n`);
+    process.stderr.write(`📝 Enter this code: ${userCode}\n\n`);
+    process.stderr.write('───────────────────────────────────────────────────────\n\n');
+    
+    // Step 4: Automatically open browser if enabled
+    const shouldOpenBrowser = autoOpen && canOpenBrowser();
+    if (shouldOpenBrowser) {
+      process.stderr.write('🚀 Opening browser automatically...\n\n');
+      await openBrowser(fullUrl);
+    } else if (!canOpenBrowser()) {
+      process.stderr.write('⚠️  Please open the link manually in your browser\n\n');
+    }
+    
+    // Step 5: Copy code to clipboard
+    try {
+      await copyToClipboard(userCode);
+      process.stderr.write('✅ Code copied to clipboard!\n\n');
+    } catch (error) {
+      // Silent fail
+    }
+    
+    // Step 6: Poll for authorization with spinner
+    process.stderr.write('⏳ Waiting for authorization...\n\n');
+    
+    const pollResponse = await pollForTokens({
+      deviceCode,
+      interval,
+      timeout,
+      apiBaseUrl: url
+    });
+    
+    // Step 7: Save credentials
+    const credentials = {
+      type: 'user_session',
+      apiBaseUrl: url,
+      user: pollResponse.user,
+      tokens: {
+        accessToken: pollResponse.accessToken,
+        accessExpiresAt: pollResponse.expiresAt || new Date(Date.now() + 3600000).toISOString(),
+        refreshToken: pollResponse.refreshToken || null
+      },
+      updatedAt: new Date().toISOString()
+    };
+    
+    writeCredentials(credentials);
+    
+    process.stderr.write('\n✅ Successfully authenticated!\n\n');
+    
+    return credentials;
+    
+  } catch (error) {
+    // Handle specific errors with helpful messages
+    if (error.code === 'ECONNREFUSED' || error.message.includes('No response')) {
+      process.stderr.write('\n❌ Cannot connect to Meldoc API\n');
+      process.stderr.write('   Please check your internet connection\n\n');
+    } else if (error.message.includes('timeout')) {
+      process.stderr.write('\n⏱️  Authentication timed out\n');
+      process.stderr.write('   Please try again or authenticate manually:\n');
+      process.stderr.write('   npx @meldocio/mcp-stdio-proxy@latest auth login\n\n');
+    } else if (error.message.includes('denied')) {
+      process.stderr.write('\n🚫 Authentication was denied\n');
+      process.stderr.write('   Please try again if this was a mistake\n\n');
+    } else {
+      process.stderr.write(`\n❌ Authentication failed: ${error.message}\n\n`);
+      process.stderr.write('   Manual authentication:\n');
+      process.stderr.write('   npx @meldocio/mcp-stdio-proxy@latest auth login\n\n');
+    }
+    
+    throw error;
+  }
+}
+
 module.exports = {
   startDeviceFlow,
   pollDeviceFlow,
-  deviceFlowLogin
+  deviceFlowLogin,
+  interactiveLogin,
+  openBrowser,
+  copyToClipboard,
+  showQRCode,
+  canOpenBrowser
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meldocio/mcp-stdio-proxy",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "MCP stdio proxy for meldoc - connects Claude Desktop to meldoc MCP API",
   "bin": {
     "meldoc-mcp": "bin/meldoc-mcp-proxy.js"