@meldocio/mcp-stdio-proxy 1.0.4 → 1.0.6

package/README.md

@@ -6,17 +6,23 @@ MCP stdio proxy for meldoc - connects Claude Desktop to meldoc MCP API without r
 
 This npm package provides a lightweight proxy that bridges JSON-RPC communication between Claude Desktop and the meldoc MCP API. It reads JSON-RPC requests from stdin and forwards them to the meldoc API over HTTP, then returns the responses via stdout.
 
+The package follows MCP best practices:
+
+- ✅ Pure stdio communication (no interactive prompts)
+- ✅ All logs go to stderr (stdout is clean JSON-RPC only)
+- ✅ No required arguments at startup
+- ✅ Graceful error handling with proper JSON-RPC error codes
+- ✅ Configurable logging levels
+
 ## Installation
 
-The package is designed to be used via `npx`, so no installation is required. However, if you want to install it globally:
+### Using Claude Desktop MCP Command
 
 ```bash
-npm install -g @meldocio/mcp-stdio-proxy
+claude mcp add meldoc npx @meldocio/mcp-stdio-proxy@latest
 ```
 
-## Usage
-
-### Claude Desktop Configuration
+### Manual Configuration
 
 Add the following configuration to your `claude_desktop_config.json` file:
 
@@ -43,9 +49,9 @@ Add the following configuration to your `claude_desktop_config.json` file:
   "mcpServers": {
     "meldoc": {
       "command": "npx",
-      "args": ["-y", "@meldocio/mcp-stdio-proxy"],
+      "args": ["-y", "@meldocio/mcp-stdio-proxy@latest"],
       "env": {
-        "MELDOC_MCP_TOKEN": "your_token_here"
+        "MELDOC_TOKEN": "your_token_here"
       }
     }
   }
@@ -54,68 +60,119 @@ Add the following configuration to your `claude_desktop_config.json` file:
 
 After adding the configuration, restart Claude Desktop.
 
-### Environment Variables
+## Authentication
+
+Meldoc MCP requires an access token. The token is checked in this order:
+
+1. `MELDOC_TOKEN` environment variable (recommended)
+2. `MELDOC_MCP_TOKEN` environment variable (backward compatibility)
+3. `~/.meldoc/config.json` file
+4. If none found, tools will return an authentication error
+
+### Option 1: Environment variable (recommended)
+
+Set the token as an environment variable:
+
+```bash
+export MELDOC_TOKEN=your_token_here
+```
 
-- **MELDOC_MCP_TOKEN** (required): Your meldoc MCP authentication token
-- **MELDOC_API_URL** (optional): Base URL for the meldoc API. Defaults to `https://api.meldoc.io`
+For permanent setup (macOS/Linux):
 
-Example with custom API URL:
+```bash
+echo 'export MELDOC_TOKEN=your_token_here' >> ~/.zshrc  # or ~/.bashrc
+source ~/.zshrc
+```
+
+For Claude Desktop, add it to your configuration:
 
 ```json
 {
   "mcpServers": {
     "meldoc": {
       "command": "npx",
-      "args": ["-y", "@meldocio/mcp-stdio-proxy"],
+      "args": ["-y", "@meldocio/mcp-stdio-proxy@latest"],
       "env": {
-        "MELDOC_MCP_TOKEN": "your_token_here",
-        "MELDOC_API_URL": "https://custom.api.example.com"
+        "MELDOC_TOKEN": "your_token_here"
       }
     }
   }
 }
 ```
 
-### Command Line Testing
+### Option 2: Meldoc CLI
 
-You can test the proxy directly from the command line:
+If you have the Meldoc CLI installed, run:
 
 ```bash
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
-  MELDOC_MCP_TOKEN=your_token_here npx @meldocio/mcp-stdio-proxy
+meldoc auth login
 ```
 
-Or with a custom API URL:
+This will store the token in `~/.meldoc/config.json`, which the MCP proxy will automatically use.
+
+### Option 3: Manual config file
+
+Create `~/.meldoc/config.json` manually:
+
+```json
+{
+  "token": "your_token_here"
+}
+```
+
+### Environment Variables
+
+- **MELDOC_TOKEN** (recommended): Your meldoc authentication token
+- **MELDOC_MCP_TOKEN** (optional): Alternative token variable (for backward compatibility)
+- **LOG_LEVEL** (optional): Logging level - `ERROR`, `WARN`, `INFO`, or `DEBUG` (default: `ERROR`)
+
+### Command Line Testing
+
+You can test the proxy directly from the command line:
 
 ```bash
+# Test initialize (works without token)
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | \
+  npx @meldocio/mcp-stdio-proxy@latest
+
+# Test tools/list (requires token)
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
-  MELDOC_MCP_TOKEN=your_token_here \
-  MELDOC_API_URL=https://custom.api.example.com \
-  npx @meldocio/mcp-stdio-proxy
+  MELDOC_TOKEN=your_token_here npx @meldocio/mcp-stdio-proxy@latest
+
+# Test with debug logging
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
+  MELDOC_TOKEN=your_token_here LOG_LEVEL=DEBUG npx @meldocio/mcp-stdio-proxy@latest
 ```
 
 ## How It Works
 
 1. The proxy reads JSON-RPC requests from `stdin` (newline-delimited JSON)
-2. Each request is forwarded to `https://api.meldoc.io/mcp/v1/rpc` (or custom URL)
-3. The `Authorization: Bearer {token}` header is automatically added
-4. Responses are written to `stdout` in JSON-RPC format
-5. Errors are handled and returned as proper JSON-RPC error responses
+2. Protocol methods (`initialize`, `ping`, `resources/list`) are handled locally
+3. Tool requests are forwarded to `https://api.meldoc.io/mcp/v1/rpc`
+4. The `Authorization: Bearer {token}` header is automatically added
+5. Responses are written to `stdout` in JSON-RPC format (stdout is clean - only JSON-RPC)
+6. All logs and diagnostics go to `stderr`
+7. Errors are handled and returned as proper JSON-RPC error responses
 
 ### Supported Features
 
 - ✅ JSON-RPC 2.0 protocol
 - ✅ Single and batch requests
 - ✅ Proper error handling with JSON-RPC error codes
+- ✅ Custom error codes: `AUTH_REQUIRED`, `NOT_FOUND`, `RATE_LIMIT`
 - ✅ Request timeout handling (25 seconds)
 - ✅ Network error recovery
 - ✅ Line-by-line processing for streaming
 - ✅ Automatic support for all MCP tools (including `server_info`)
-- ✅ Metadata (`_meta`) in responses for better context
+- ✅ Configurable logging levels (ERROR, WARN, INFO, DEBUG)
+- ✅ Graceful shutdown on SIGINT/SIGTERM
+- ✅ No required arguments at startup
 
 ## JSON-RPC Error Codes
 
-The proxy uses standard JSON-RPC 2.0 error codes:
+The proxy uses standard JSON-RPC 2.0 error codes plus custom codes:
+
+### Standard JSON-RPC 2.0 Codes
 
 - `-32700`: Parse error (invalid JSON)
 - `-32600`: Invalid Request (malformed JSON-RPC)
@@ -124,6 +181,18 @@ The proxy uses standard JSON-RPC 2.0 error codes:
 - `-32603`: Internal error (network errors, timeouts, etc.)
 - `-32000`: Server error (HTTP 4xx/5xx responses)
 
+### Custom Error Codes
+
+- `-32001`: Authentication required (`AUTH_REQUIRED`) - Token missing or invalid
+- `-32002`: Not found (`NOT_FOUND`) - Resource not found
+- `-32003`: Rate limit exceeded (`RATE_LIMIT`) - Too many requests
+
+Error responses include:
+
+- `code`: Error code
+- `message`: Human-readable error message
+- `data` (optional, DEBUG level only): Additional error details
+
 ## Available Tools
 
 The proxy automatically supports all tools provided by the meldoc MCP API, including:
@@ -143,6 +212,7 @@ echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"server_inf
 ```
 
 The response includes:
+
 - Server name (from token)
 - Token description (if provided)
 - Available projects with IDs, names, and aliases
@@ -169,9 +239,9 @@ This metadata helps AI assistants understand the context and limitations of the
 
 ## Troubleshooting
 
-### Error: MELDOC_MCP_TOKEN environment variable is required
+### Error: AUTH_REQUIRED - Meldoc token not found
 
-**Solution:** Make sure you've set the `MELDOC_MCP_TOKEN` in the `env` section of your Claude Desktop configuration.
+**Solution:** Set the `MELDOC_TOKEN` environment variable or run `meldoc auth login` to store the token in `~/.meldoc/config.json`. The token is checked when tools are called, not at startup.
 
 ### Connection timeout
 
@@ -202,15 +272,19 @@ curl https://api.meldoc.io/mcp/v1/rpc \
 To debug issues, you can test the proxy directly:
 
 ```bash
+# Test initialize (works without token)
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | \
+  npx @meldocio/mcp-stdio-proxy@latest
+
 # Test with a simple request
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
-  MELDOC_MCP_TOKEN=your_token npx @meldocio/mcp-stdio-proxy
+  MELDOC_TOKEN=your_token npx @meldocio/mcp-stdio-proxy@latest
 
-# Test with verbose output (if needed)
+# Test with debug logging
 echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
-  MELDOC_MCP_TOKEN=your_token \
-  DEBUG=1 \
-  npx @meldocio/mcp-stdio-proxy
+  MELDOC_TOKEN=your_token \
+  LOG_LEVEL=DEBUG \
+  npx @meldocio/mcp-stdio-proxy@latest
 ```
 
 ## Development
@@ -246,8 +320,8 @@ npm publish --access public
 
 ## Requirements
 
-- Node.js >= 14.0.0
-- Valid meldoc MCP token
+- Node.js >= 18.0.0
+- Valid meldoc MCP token (required for tool calls, not for startup)
 
 ## License
 

package/bin/cli.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+
+const { deviceFlowLogin } = require('../lib/device-flow');
+const { readCredentials, deleteCredentials } = require('../lib/credentials');
+const { getAuthStatus } = require('../lib/auth');
+const { setWorkspaceAlias, getWorkspaceAlias } = require('../lib/config');
+const { getAccessToken } = require('../lib/auth');
+const { getApiUrl, getAppUrl } = require('../lib/constants');
+const axios = require('axios');
+const https = require('https');
+const chalk = require('chalk');
+const logger = require('../lib/logger');
+
+const API_URL = getApiUrl();
+const APP_URL = getAppUrl();
+
+// Support localhost testing
+if (process.env.MELDOC_API_URL) {
+  logger.debug(`Using API URL: ${process.env.MELDOC_API_URL}`);
+}
+if (process.env.MELDOC_APP_URL) {
+  logger.debug(`Using App URL: ${process.env.MELDOC_APP_URL}`);
+}
+
+/**
+ * Handle auth login command
+ */
+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!');
+    process.exit(0);
+  } catch (error) {
+    logger.error(`Login failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle auth status command
+ */
+async function handleAuthStatus() {
+  const status = await getAuthStatus();
+  if (!status || !status.authenticated) {
+    logger.error('Not authenticated');
+    console.log('\n' + logger.label('To authenticate, run:'));
+    console.log('  ' + logger.highlight('npx @meldoc/mcp auth login') + '\n');
+    process.exit(1);
+  }
+  
+  logger.section('🔑 Authentication Status');
+  
+  if (status.type === 'user_session' && status.user) {
+    logger.item('Email', logger.value(status.user.email));
+    if (status.expiresAt) {
+      logger.item('Token expires', logger.value(new Date(status.expiresAt).toLocaleString()));
+    }
+  } else {
+    logger.item('Type', logger.value(status.type));
+  }
+  
+  console.log();
+  process.exit(0);
+}
+
+/**
+ * Handle auth logout command
+ */
+async function handleAuthLogout() {
+  deleteCredentials();
+  logger.success('Logged out successfully');
+  process.exit(0);
+}
+
+/**
+ * Handle config set-workspace command
+ */
+function handleConfigSetWorkspace(alias) {
+  if (!alias) {
+    logger.error('Workspace alias is required');
+    console.log('\n' + logger.label('Usage:'));
+    console.log('  ' + logger.highlight('npx @meldoc/mcp config set-workspace <alias>') + '\n');
+    process.exit(1);
+  }
+  
+  try {
+    setWorkspaceAlias(alias);
+    logger.success(`Workspace set to: ${logger.highlight(alias)}`);
+    process.exit(0);
+  } catch (error) {
+    logger.error(`Failed to set workspace: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle config get-workspace command
+ */
+function handleConfigGetWorkspace() {
+  const alias = getWorkspaceAlias();
+  if (alias) {
+    console.log(logger.highlight(alias));
+  }
+  process.exit(0);
+}
+
+/**
+ * Handle config list-workspaces command
+ */
+async function handleConfigListWorkspaces() {
+  try {
+    const tokenInfo = await getAccessToken();
+    if (!tokenInfo) {
+      logger.error('Not authenticated');
+      console.log('\n' + logger.label('To authenticate, run:'));
+      console.log('  ' + logger.highlight('npx @meldoc/mcp auth login') + '\n');
+      process.exit(1);
+    }
+    
+    // Call MCP tool meldoc.list_workspaces via POST /mcp/v1/rpc
+    const response = await axios.post(`${API_URL}/mcp/v1/rpc`, {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'tools/call',
+      params: {
+        name: 'meldoc.list_workspaces',
+        arguments: {}
+      }
+    }, {
+      headers: {
+        'Authorization': `Bearer ${tokenInfo.token}`,
+        'Content-Type': 'application/json'
+      },
+      timeout: 10000,
+      httpsAgent: new https.Agent({ keepAlive: true })
+    });
+    
+    if (response.data.error) {
+      logger.error(`Error: ${response.data.error.message}`);
+      process.exit(1);
+    }
+    
+    const workspaces = response.data.result?.workspaces || [];
+    if (workspaces.length === 0) {
+      logger.info('No workspaces available');
+      process.exit(0);
+    }
+    
+    logger.section('📁 Available Workspaces');
+    for (const ws of workspaces) {
+      const role = ws.role || 'member';
+      const roleColor = role === 'owner' ? chalk.red : role === 'admin' ? chalk.yellow : chalk.gray;
+      logger.item(
+        `${logger.highlight(ws.alias)} ${chalk.gray('(' + ws.name + ')')}`,
+        roleColor(`[${role}]`)
+      );
+    }
+    console.log();
+    
+    process.exit(0);
+  } catch (error) {
+    if (error.response?.data?.error) {
+      const errorData = error.response.data.error;
+      if (errorData.code === 'AUTH_REQUIRED' || errorData.data?.code === 'AUTH_REQUIRED') {
+        logger.error('Not authenticated');
+        console.log('\n' + logger.label('To authenticate, run:'));
+        console.log('  ' + logger.highlight('npx @meldoc/mcp auth login') + '\n');
+        process.exit(1);
+      }
+      logger.error(`Error: ${errorData.message || error.message}`);
+    } else {
+      logger.error(`Error: ${error.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Handle help command
+ */
+function handleHelp() {
+  console.log('\n' + logger.section('📖 Meldoc MCP CLI Help'));
+  console.log();
+  
+  console.log(logger.label('Available Commands:'));
+  console.log();
+  
+  console.log('  ' + logger.highlight('auth login'));
+  console.log('    Authenticate with Meldoc using device flow');
+  console.log();
+  
+  console.log('  ' + logger.highlight('auth status'));
+  console.log('    Check authentication status');
+  console.log();
+  
+  console.log('  ' + logger.highlight('auth logout'));
+  console.log('    Log out and clear credentials');
+  console.log();
+  
+  console.log('  ' + logger.highlight('config set-workspace <alias>'));
+  console.log('    Set the active workspace alias');
+  console.log();
+  
+  console.log('  ' + logger.highlight('config get-workspace'));
+  console.log('    Get the current workspace alias');
+  console.log();
+  
+  console.log('  ' + logger.highlight('config list-workspaces'));
+  console.log('    List all available workspaces');
+  console.log();
+  
+  console.log('  ' + logger.highlight('help'));
+  console.log('    Show this help message');
+  console.log();
+  
+  console.log(logger.label('Examples:'));
+  console.log('  ' + logger.highlight('npx @meldoc/mcp auth login'));
+  console.log('  ' + logger.highlight('npx @meldoc/mcp config set-workspace my-workspace'));
+  console.log('  ' + logger.highlight('npx @meldoc/mcp config list-workspaces'));
+  console.log();
+  
+  process.exit(0);
+}
+
+/**
+ * Show usage hints when no arguments provided
+ */
+function showUsageHints() {
+  console.log('\n' + logger.section('🔧 Meldoc MCP CLI'));
+  console.log();
+  console.log(logger.label('Available commands:'));
+  console.log('  ' + logger.highlight('auth login') + '        - Authenticate with Meldoc');
+  console.log('  ' + logger.highlight('auth status') + '       - Check authentication status');
+  console.log('  ' + logger.highlight('auth logout') + '       - Log out');
+  console.log('  ' + logger.highlight('config set-workspace') + ' - Set workspace alias');
+  console.log('  ' + logger.highlight('config get-workspace') + ' - Get current workspace');
+  console.log('  ' + logger.highlight('config list-workspaces') + ' - List workspaces');
+  console.log('  ' + logger.highlight('help') + '              - Show detailed help');
+  console.log();
+  console.log(logger.label('For more information, run:'));
+  console.log('  ' + logger.highlight('npx @meldoc/mcp help') + '\n');
+  process.exit(0);
+}
+
+/**
+ * Main CLI handler
+ */
+function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length === 0) {
+    // No arguments - show usage hints
+    showUsageHints();
+    return;
+  }
+  
+  const command = args[0];
+  const subcommand = args[1];
+  const value = args[2];
+  
+  if (command === 'help' || command === '--help' || command === '-h') {
+    handleHelp();
+  } else if (command === 'auth') {
+    if (subcommand === 'login') {
+      handleAuthLogin();
+    } else if (subcommand === 'status') {
+      handleAuthStatus();
+    } else if (subcommand === 'logout') {
+      handleAuthLogout();
+    } else {
+      logger.error(`Unknown auth command: ${subcommand}`);
+      console.log('\n' + logger.label('Usage:'));
+      console.log('  ' + logger.highlight('npx @meldoc/mcp auth <login|status|logout>') + '\n');
+      process.exit(1);
+    }
+  } else if (command === 'config') {
+    if (subcommand === 'set-workspace') {
+      handleConfigSetWorkspace(value);
+    } else if (subcommand === 'get-workspace') {
+      handleConfigGetWorkspace();
+    } else if (subcommand === 'list-workspaces') {
+      handleConfigListWorkspaces();
+    } else {
+      logger.error(`Unknown config command: ${subcommand}`);
+      console.log('\n' + logger.label('Usage:'));
+      console.log('  ' + logger.highlight('npx @meldoc/mcp config <set-workspace|get-workspace|list-workspaces>') + '\n');
+      process.exit(1);
+    }
+  } else {
+    // Unknown command - might be for main proxy
+    // Return control to main proxy handler
+    return;
+  }
+}
+
+// Run main when this file is required (called from main proxy)
+// main() will handle commands and exit, so this is safe to call
+main();
+
+module.exports = {
+  handleAuthLogin,
+  handleAuthStatus,
+  handleAuthLogout,
+  handleConfigSetWorkspace,
+  handleConfigGetWorkspace,
+  handleConfigListWorkspaces
+};