@meldocio/mcp-stdio-proxy 1.0.3 → 1.0.5

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,66 +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:
 
-- **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`
+```bash
+export MELDOC_TOKEN=your_token_here
+```
+
+For permanent setup (macOS/Linux):
+
+```bash
+echo 'export MELDOC_TOKEN=your_token_here' >> ~/.zshrc  # or ~/.bashrc
+source ~/.zshrc
+```
 
-Example with custom API URL:
+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_TOKEN=your_token_here npx @meldocio/mcp-stdio-proxy@latest
+
+# Test with debug logging
 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 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
-- ✅ Request timeout handling (30 seconds)
+- ✅ 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`)
+- ✅ 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)
@@ -122,11 +181,67 @@ 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:
+
+- **`server_info`** - Get information about the server configuration, available projects, and token capabilities
+- **`docs_list`** - List available documentation
+- **`docs_get`** - Get specific documentation content
+- And other tools as provided by the API
+
+### Example: Using `server_info`
+
+You can get server information using the `server_info` tool:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"server_info","arguments":{}}}' | \
+  MELDOC_MCP_TOKEN=your_token_here npx @meldocio/mcp-stdio-proxy
+```
+
+The response includes:
+
+- Server name (from token)
+- Token description (if provided)
+- Available projects with IDs, names, and aliases
+- Token capabilities (read, update, create, delete)
+- Usage hints
+
+### Response Metadata
+
+All tool responses now include a `_meta` field with contextual information:
+
+```json
+{
+  "items": [...],
+  "_meta": {
+    "server": "My Token",
+    "projects": ["Frontend Docs", "Backend API"],
+    "capabilities": ["read"],
+    "hint": "Read permission required for this operation"
+  }
+}
+```
+
+This metadata helps AI assistants understand the context and limitations of the current token.
+
 ## 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
 
@@ -157,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
@@ -201,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/meldoc-mcp-proxy.js

@@ -3,6 +3,26 @@
 const axios = require('axios');
 const https = require('https');
 const { URL } = require('url');
+const path = require('path');
+const fs = require('fs');
+
+// Get package info - try multiple paths for different installation scenarios
+let pkg;
+try {
+  // Try relative path first (development)
+  pkg = require('../package.json');
+} catch (e) {
+  try {
+    // Try from node_modules (when installed)
+    pkg = require(path.join(__dirname, '../../package.json'));
+  } catch (e2) {
+    // Fallback to hardcoded values
+    pkg = {
+      name: '@meldocio/mcp-stdio-proxy',
+      version: '1.0.5'
+    };
+  }
+}
 
 // JSON-RPC error codes
 const JSON_RPC_ERROR_CODES = {
@@ -14,16 +34,73 @@ const JSON_RPC_ERROR_CODES = {
   SERVER_ERROR: -32000
 };
 
+// Custom error codes
+const CUSTOM_ERROR_CODES = {
+  AUTH_REQUIRED: -32001,
+  NOT_FOUND: -32002,
+  RATE_LIMIT: -32003
+};
+
+// Log levels
+const LOG_LEVELS = {
+  ERROR: 0,
+  WARN: 1,
+  INFO: 2,
+  DEBUG: 3
+};
+
+// Get token from environment or config file
+// Priority: 1) MELDOC_TOKEN env var, 2) ~/.meldoc/config.json
+function getToken() {
+  // First, try environment variable (recommended)
+  if (process.env.MELDOC_TOKEN) {
+    return process.env.MELDOC_TOKEN;
+  }
+  
+  // Fallback: try MELDOC_MCP_TOKEN for backward compatibility
+  if (process.env.MELDOC_MCP_TOKEN) {
+    return process.env.MELDOC_MCP_TOKEN;
+  }
+  
+  // Then, try config file
+  try {
+    const os = require('os');
+    const configPath = path.join(os.homedir(), '.meldoc', 'config.json');
+    if (fs.existsSync(configPath)) {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (config.token) {
+        return config.token;
+      }
+    }
+  } catch (e) {
+    // Silently ignore config file errors
+  }
+  
+  return null;
+}
+
 // Configuration
-const token = process.env.MELDOC_MCP_TOKEN;
+const token = getToken();
 const apiUrl = process.env.MELDOC_API_URL || 'https://api.meldoc.io';
 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');
 
-// Validate token
-if (!token) {
-  console.error('Error: MELDOC_MCP_TOKEN environment variable is required');
-  process.exit(1);
+// Get log level from environment
+function getLogLevel(level) {
+  const upper = (level || '').toUpperCase();
+  return LOG_LEVELS[upper] !== undefined ? LOG_LEVELS[upper] : LOG_LEVELS.ERROR;
+}
+
+// Logging function - all logs go to stderr
+function log(level, message, ...args) {
+  if (LOG_LEVEL >= level) {
+    const prefix = `[${Object.keys(LOG_LEVELS)[level]}]`;
+    process.stderr.write(`${prefix} ${message}\n`);
+    if (args.length > 0 && LOG_LEVEL >= LOG_LEVELS.DEBUG) {
+      process.stderr.write(JSON.stringify(args, null, 2) + '\n');
+    }
+  }
 }
 
 // Buffer for incomplete lines
@@ -73,6 +150,23 @@ process.stdout.on('error', (error) => {
   }
 });
 
+// Handle SIGINT/SIGTERM for graceful shutdown
+let isShuttingDown = false;
+function gracefulShutdown(signal) {
+  if (isShuttingDown) {
+    return;
+  }
+  isShuttingDown = true;
+  log(LOG_LEVELS.INFO, `Received ${signal}, shutting down gracefully...`);
+  // Give a moment for any pending requests to complete
+  setTimeout(() => {
+    process.exit(0);
+  }, 100);
+}
+
+process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+
 /**
  * Handle a single line from stdin
  */
@@ -90,7 +184,7 @@ function handleLine(line) {
     // For parse errors, we can't reliably get the id, so we skip the response
     // to avoid Zod validation errors in Claude Desktop (it doesn't accept id: null)
     // This is acceptable per JSON-RPC spec - parse errors can be ignored if id is unknown
-    console.error(`Parse error: ${parseError.message}`, { to: 'stderr' });
+    log(LOG_LEVELS.ERROR, `Parse error: ${parseError.message}`);
   }
 }
 
@@ -199,12 +293,13 @@ function handleInitialize(request) {
         resources: {}
       },
       serverInfo: {
-        name: '@meldocio/mcp-stdio-proxy',
-        version: '1.0.2'
+        name: pkg.name,
+        version: pkg.version
       }
     }
   };
   
+  log(LOG_LEVELS.DEBUG, 'Initialize request received');
   process.stdout.write(JSON.stringify(response) + '\n');
   if (process.stdout.isTTY) {
     process.stdout.flush();
@@ -251,6 +346,13 @@ function handleResourcesList(request) {
  * Forwards the request to the backend MCP API
  */
 async function processSingleRequest(request) {
+  // Check token before making request
+  if (!token) {
+    sendError(request.id, CUSTOM_ERROR_CODES.AUTH_REQUIRED, 
+              'Meldoc token not found. Set MELDOC_TOKEN environment variable or run: meldoc auth login');
+    return;
+  }
+  
   try {
     // Ensure request has jsonrpc field
     const requestWithJsonRpc = {
@@ -258,12 +360,14 @@ async function processSingleRequest(request) {
       jsonrpc: request.jsonrpc || '2.0'
     };
     
+    log(LOG_LEVELS.DEBUG, `Forwarding request: ${request.method || 'unknown'}`);
+    
     // Make HTTP request to MCP API
     const response = await axios.post(rpcEndpoint, requestWithJsonRpc, {
       headers: {
         'Authorization': `Bearer ${token}`,
         'Content-Type': 'application/json',
-        'User-Agent': '@meldocio/mcp-stdio-proxy/1.0.0'
+        'User-Agent': `${pkg.name}/${pkg.version}`
       },
       timeout: REQUEST_TIMEOUT,
       validateStatus: (status) => status < 500, // Don't throw on 4xx errors
@@ -310,24 +414,39 @@ async function processSingleRequest(request) {
       
       let errorCode = JSON_RPC_ERROR_CODES.SERVER_ERROR;
       if (status === 401) {
-        errorCode = JSON_RPC_ERROR_CODES.INTERNAL_ERROR;
+        errorCode = CUSTOM_ERROR_CODES.AUTH_REQUIRED;
       } else if (status === 404) {
-        errorCode = JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND;
+        errorCode = CUSTOM_ERROR_CODES.NOT_FOUND;
+      } else if (status === 429) {
+        errorCode = CUSTOM_ERROR_CODES.RATE_LIMIT;
       }
       
-      sendError(request.id, errorCode, errorMessage);
+      log(LOG_LEVELS.WARN, `HTTP error ${status}: ${errorMessage}`);
+      sendError(request.id, errorCode, errorMessage, {
+        status,
+        code: errorData?.error?.code || `HTTP_${status}`
+      });
     } else if (error.request) {
       // Request was made but no response received
+      log(LOG_LEVELS.ERROR, `Network error: ${error.message || 'No response from server'}`);
       sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, 
-                `Network error: ${error.message || 'No response from server'}`);
+                `Network error: ${error.message || 'No response from server'}`, {
+                  code: 'NETWORK_ERROR'
+                });
     } else if (error.code === 'ECONNABORTED') {
       // Timeout
+      log(LOG_LEVELS.WARN, `Request timeout after ${REQUEST_TIMEOUT}ms`);
       sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, 
-                `Request timeout after ${REQUEST_TIMEOUT}ms`);
+                `Request timeout after ${REQUEST_TIMEOUT}ms`, {
+                  code: 'TIMEOUT'
+                });
     } else {
       // Other errors
+      log(LOG_LEVELS.ERROR, `Internal error: ${error.message || 'Unknown error'}`);
       sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, 
-                `Internal error: ${error.message || 'Unknown error'}`);
+                `Internal error: ${error.message || 'Unknown error'}`, {
+                  code: 'INTERNAL_ERROR'
+                });
     }
   }
 }
@@ -335,7 +454,7 @@ async function processSingleRequest(request) {
 /**
  * Send JSON-RPC error response
  */
-function sendError(id, code, message) {
+function sendError(id, code, message, details) {
   // Only send error response if id is defined (not for notifications)
   // Claude Desktop's Zod schema doesn't accept null for id
   if (id === undefined || id === null) {
@@ -353,6 +472,11 @@ function sendError(id, code, message) {
     }
   };
   
+  // Add details if provided (for debugging)
+  if (details && LOG_LEVEL >= LOG_LEVELS.DEBUG) {
+    errorResponse.error.data = details;
+  }
+  
   process.stdout.write(JSON.stringify(errorResponse) + '\n');
   // Flush stdout to ensure data is sent immediately
   if (process.stdout.isTTY) {

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@meldocio/mcp-stdio-proxy",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "MCP stdio proxy for meldoc - connects Claude Desktop to meldoc MCP API",
-  "main": "bin/meldoc-mcp-proxy.js",
   "bin": {
-    "meldoc-mcp-proxy": "bin/meldoc-mcp-proxy.js"
-  },
-  "scripts": {
-    "test": "jest",
-    "prepublishOnly": "npm test"
+    "meldoc-mcp": "bin/meldoc-mcp-proxy.js"
   },
+  "files": [
+    "bin/**",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "keywords": [
     "mcp",
@@ -33,17 +33,5 @@
   "homepage": "https://github.com/meldoc/mcp-stdio-proxy#readme",
   "dependencies": {
     "axios": "^1.6.0"
-  },
-  "devDependencies": {
-    "jest": "^29.7.0"
-  },
-  "jest": {
-    "testEnvironment": "node",
-    "testMatch": [
-      "**/__tests__/**/*.test.js"
-    ],
-    "collectCoverageFrom": [
-      "bin/**/*.js"
-    ]
   }
-}
+}