npm - @meldocio/mcp-stdio-proxy - Versions diffs - 1.0.28 → 1.1.0 - Mend

@meldocio/mcp-stdio-proxy 1.0.28 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/.claude-plugin/marketplace.json +1 -1
package/.claude-plugin/plugin.json +1 -1
package/README.md +3 -3
package/bin/cli.js +2 -1
package/bin/meldoc-mcp-proxy.js +178 -134
package/lib/cli/commands.js +19 -8
package/lib/core/auth.js +35 -16
package/lib/core/oauth-pkce.js +279 -0
package/lib/http/proxy.js +230 -0
package/lib/mcp/handlers.js +16 -165
package/lib/mcp/tools-call.js +16 -18
package/lib/protocol/tools-schema.js +15 -169
package/package.json +1 -1

package/lib/core/oauth-pkce.js ADDED Viewed

@@ -0,0 +1,279 @@
+/**
+ * OAuth 2.1 PKCE Authentication Flow
+ *
+ * Implements OAuth 2.1 authorization code flow with PKCE for agent authentication.
+ * Uses a loopback redirect URI per RFC 8252.
+ *
+ * Server endpoints:
+ *   POST /mcp/oauth/register  - dynamic client registration
+ *   GET  /mcp/oauth/authorize - authorization page (in browser)
+ *   POST /mcp/oauth/token     - code exchange + refresh token rotation
+ */
+const crypto = require('crypto')
+const http = require('http')
+const axios = require('axios')
+const https = require('https')
+const { URL, URLSearchParams } = require('url')
+const { writeCredentials } = require('./credentials')
+const { getApiUrl, getAppUrl } = require('./constants')
+const { exec } = require('child_process')
+/**
+ * Generate a cryptographically random PKCE code verifier (base64url, 43-128 chars).
+ * @returns {string}
+ */
+function generateCodeVerifier() {
+  return crypto.randomBytes(32).toString('base64url')
+}
+/**
+ * Derive code challenge from verifier using S256 method.
+ * @param {string} verifier
+ * @returns {string} Base64url-encoded SHA-256 hash
+ */
+function generateCodeChallenge(verifier) {
+  return crypto.createHash('sha256').update(verifier).digest('base64url')
+}
+/**
+ * Start a local HTTP server on a random loopback port to receive the OAuth redirect.
+ * @returns {Promise<{server, port, getCode}>}
+ */
+function startCallbackServer() {
+  return new Promise((resolve, reject) => {
+    let resolveCode
+    const codePromise = new Promise((res) => { resolveCode = res })
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1')
+      const code = url.searchParams.get('code')
+      const state = url.searchParams.get('state')
+      const error = url.searchParams.get('error')
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+      if (error) {
+        res.end('<html><body><h2>Authentication failed: ' + error + '</h2><p>You can close this tab.</p></body></html>')
+      } else {
+        res.end('<html><body><h2>Authentication successful!</h2><p>You can close this tab and return to the terminal.</p></body></html>')
+      }
+      resolveCode({ code, state, error })
+    })
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        server,
+        port: server.address().port,
+        getCode: () => codePromise
+      })
+    })
+    server.on('error', reject)
+  })
+}
+/**
+ * Open a URL in the default browser (best-effort, ignores errors).
+ * @param {string} url
+ */
+function openBrowser(url) {
+  let command
+  if (process.platform === 'darwin') {
+    command = `open "${url}"`
+  } else if (process.platform === 'win32') {
+    command = `start "" "${url}"`
+  } else {
+    command = `xdg-open "${url}"`
+  }
+  exec(command, () => {}) // Ignore errors
+}
+/**
+ * Register a new OAuth client with the server (dynamic client registration).
+ * @param {string} apiBaseUrl
+ * @param {string} redirectUri
+ * @returns {Promise<string>} client_id
+ */
+async function registerClient(apiBaseUrl, redirectUri) {
+  const response = await axios.post(`${apiBaseUrl}/mcp/oauth/register`, {
+    redirect_uris: [redirectUri],
+    client_name: 'meldoc-mcp-proxy'
+  }, {
+    timeout: 10000,
+    httpsAgent: new https.Agent({ keepAlive: true })
+  })
+  if (!response.data.client_id) {
+    throw new Error('OAuth registration failed: no client_id in response')
+  }
+  return response.data.client_id
+}
+/**
+ * Exchange an authorization code for access + refresh tokens.
+ * @param {string} apiBaseUrl
+ * @param {string} code
+ * @param {string} codeVerifier
+ * @param {string} clientId
+ * @param {string} redirectUri
+ * @returns {Promise<{accessToken, refreshToken, expiresAt}>}
+ */
+async function exchangeCode(apiBaseUrl, code, codeVerifier, clientId, redirectUri) {
+  const params = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    code_verifier: codeVerifier,
+    client_id: clientId,
+    redirect_uri: redirectUri
+  })
+  const response = await axios.post(`${apiBaseUrl}/mcp/oauth/token`, params.toString(), {
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    timeout: 10000,
+    httpsAgent: new https.Agent({ keepAlive: true })
+  })
+  const data = response.data
+  if (!data.access_token) {
+    throw new Error('Token exchange failed: no access_token in response')
+  }
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token || null,
+    expiresAt: new Date(Date.now() + (data.expires_in || 3600) * 1000).toISOString()
+  }
+}
+/**
+ * Refresh tokens using OAuth 2.1 refresh token rotation.
+ * The server issues a new refresh token on each use (old token is revoked).
+ * @param {string} apiBaseUrl
+ * @param {string} refreshToken
+ * @param {string} clientId
+ * @returns {Promise<{accessToken, refreshToken, expiresAt}>}
+ */
+async function refreshOAuthToken(apiBaseUrl, refreshToken, clientId) {
+  const params = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: refreshToken,
+    client_id: clientId
+  })
+  const response = await axios.post(`${apiBaseUrl}/mcp/oauth/token`, params.toString(), {
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    timeout: 10000,
+    httpsAgent: new https.Agent({ keepAlive: true })
+  })
+  const data = response.data
+  if (!data.access_token) {
+    throw new Error('Token refresh failed: no access_token in response')
+  }
+  return {
+    accessToken: data.access_token,
+    refreshToken: data.refresh_token || refreshToken, // Server rotates the token
+    expiresAt: new Date(Date.now() + (data.expires_in || 3600) * 1000).toISOString()
+  }
+}
+/**
+ * Perform interactive OAuth 2.1 PKCE login.
+ * Opens browser, starts loopback callback server, exchanges code for tokens.
+ * @param {Object} options
+ * @param {string} [options.apiBaseUrl]
+ * @param {string} [options.appUrl]
+ * @param {number} [options.timeout=120000]
+ * @returns {Promise<Object>} Credentials object
+ */
+async function pkceLogin(options = {}) {
+  const {
+    apiBaseUrl = null,
+    appUrl = null,
+    timeout = 120000
+  } = options
+  const apiUrl = apiBaseUrl || getApiUrl()
+  const frontendUrl = appUrl || getAppUrl()
+  const { server, port, getCode } = await startCallbackServer()
+  const redirectUri = `http://127.0.0.1:${port}/callback`
+  try {
+    process.stderr.write('Registering OAuth client...\n')
+    const clientId = await registerClient(apiUrl, redirectUri)
+    const codeVerifier = generateCodeVerifier()
+    const codeChallenge = generateCodeChallenge(codeVerifier)
+    const state = crypto.randomBytes(16).toString('hex')
+    const authParams = new URLSearchParams({
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+      state,
+      response_type: 'code'
+    })
+    const authUrl = `${frontendUrl}/mcp/oauth/authorize?${authParams.toString()}`
+    process.stderr.write('\n╔═══════════════════════════════════════════════════════╗\n')
+    process.stderr.write('║                                                       ║\n')
+    process.stderr.write('║   🔐 Meldoc Authentication Required                  ║\n')
+    process.stderr.write('║                                                       ║\n')
+    process.stderr.write('╚═══════════════════════════════════════════════════════╝\n\n')
+    process.stderr.write(`🌐 Visit: ${authUrl}\n\n`)
+    process.stderr.write('🚀 Opening browser automatically...\n\n')
+    openBrowser(authUrl)
+    process.stderr.write('⏳ Waiting for authorization...\n\n')
+    const timeoutPromise = new Promise((_, reject) =>
+      setTimeout(() => reject(new Error('Authentication timeout. Please try again.')), timeout)
+    )
+    const { code, state: returnedState, error: callbackError } = await Promise.race([
+      getCode(),
+      timeoutPromise
+    ])
+    if (callbackError) throw new Error('OAuth error: ' + callbackError)
+    if (returnedState !== state) throw new Error('OAuth state mismatch - possible CSRF attack')
+    if (!code) throw new Error('No authorization code received')
+    const tokens = await exchangeCode(apiUrl, code, codeVerifier, clientId, redirectUri)
+    const credentials = {
+      type: 'user_session',
+      auth_method: 'pkce',
+      client_id: clientId,
+      apiBaseUrl: apiUrl,
+      tokens: {
+        accessToken: tokens.accessToken,
+        accessExpiresAt: tokens.expiresAt,
+        refreshToken: tokens.refreshToken
+      },
+      updatedAt: new Date().toISOString()
+    }
+    writeCredentials(credentials)
+    process.stderr.write('\n✅ Successfully authenticated!\n\n')
+    return credentials
+  } finally {
+    server.close()
+  }
+}
+module.exports = {
+  pkceLogin,
+  refreshOAuthToken,
+  generateCodeVerifier,
+  generateCodeChallenge
+}

package/lib/http/proxy.js ADDED Viewed

@@ -0,0 +1,230 @@
+/**
+ * Streamable HTTP Proxy for MCP
+ *
+ * Implements MCP Streamable HTTP transport (spec 2025-03-26).
+ * Mirrors the Go implementation in meldoc.cli/cli/internal/mcp/proxy.go
+ */
+const https = require('https')
+const http = require('http')
+const { URL } = require('url')
+const REQUEST_TIMEOUT = 60000
+/**
+ * StreamableHTTPProxy forwards JSON-RPC requests from stdio to a remote MCP HTTP server.
+ */
+class StreamableHTTPProxy {
+  /**
+   * @param {string} remoteURL - Full URL of the MCP endpoint (e.g. https://api.meldoc.io/mcp)
+   * @param {Function} getToken - Async function that returns the auth token string (or null)
+   */
+  constructor(remoteURL, getToken) {
+    this.remoteURL = remoteURL
+    this.getToken = getToken
+    this.sessionId = null
+  }
+  /**
+   * Send the initialize request and store the session ID.
+   * @param {*} id - Request ID
+   * @param {*} params - Initialize params (may be null)
+   * @returns {Promise<Object>} Full JSON-RPC response object (not just result)
+   */
+  async initialize(id, params) {
+    const body = { jsonrpc: '2.0', id, method: 'initialize' }
+    if (params) body.params = params
+    const { response, newSessionId } = await this._doRequest(body, '')
+    if (newSessionId) this.sessionId = newSessionId
+    const text = await this._readBody(response)
+    let parsed
+    try {
+      parsed = JSON.parse(text)
+    } catch (e) {
+      throw new Error('Failed to parse initialize response: ' + text)
+    }
+    if (parsed.error) {
+      throw new Error(`Initialize error ${parsed.error.code}: ${parsed.error.message}`)
+    }
+    return parsed
+  }
+  /**
+   * Forward a JSON-RPC request to the remote server and write all responses to stdout.
+   * Handles session expiry (HTTP 404) by re-initializing and retrying once.
+   * For SSE responses each event is written as a separate newline-delimited line.
+   * @param {Object} request - JSON-RPC request object
+   */
+  async forwardAndWrite(request) {
+    const body = {
+      jsonrpc: request.jsonrpc || '2.0',
+      id: request.id,
+      method: request.method
+    }
+    if (request.params !== undefined) body.params = request.params
+    let result
+    try {
+      result = await this._doRequest(body, this.sessionId || '')
+    } catch (err) {
+      if (err.statusCode === 404) {
+        // Session expired — re-initialize and retry once
+        try {
+          await this.initialize(0, null)
+        } catch (reinitErr) {
+          this._writeError(request.id, -32603, 'Session re-initialization failed: ' + reinitErr.message)
+          return
+        }
+        try {
+          result = await this._doRequest(body, this.sessionId || '')
+        } catch (retryErr) {
+          this._writeError(request.id, -32603, retryErr.message)
+          return
+        }
+      } else if (err.statusCode === 401 || err.statusCode === 403) {
+        this._writeError(request.id, -32002, 'Authentication failed: ' + (err.body || 'unauthorized'))
+        return
+      } else {
+        this._writeError(request.id, -32603, err.message)
+        return
+      }
+    }
+    const { response, newSessionId } = result
+    if (newSessionId) this.sessionId = newSessionId
+    const contentType = response.headers['content-type'] || ''
+    if (contentType.includes('text/event-stream')) {
+      await this._streamSSE(response)
+    } else {
+      const text = await this._readBody(response)
+      if (text.trim()) process.stdout.write(text.trim() + '\n')
+    }
+  }
+  /**
+   * Perform the raw HTTP POST to the remote server.
+   * @param {Object} body - JSON body to send
+   * @param {string} sessionId - Session ID header value (empty string to omit)
+   * @returns {Promise<{response: IncomingMessage, newSessionId: string}>}
+   */
+  async _doRequest(body, sessionId) {
+    const token = await this.getToken()
+    const data = JSON.stringify(body)
+    const url = new URL(this.remoteURL)
+    const isHttps = url.protocol === 'https:'
+    const port = url.port ? parseInt(url.port) : (isHttps ? 443 : 80)
+    const headers = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json, text/event-stream',
+      'Content-Length': Buffer.byteLength(data)
+    }
+    if (token) headers['Authorization'] = 'Bearer ' + token
+    if (sessionId) headers['Mcp-Session-Id'] = sessionId
+    return new Promise((resolve, reject) => {
+      const options = {
+        hostname: url.hostname,
+        port,
+        path: url.pathname + (url.search || ''),
+        method: 'POST',
+        headers,
+        timeout: REQUEST_TIMEOUT
+      }
+      const mod = isHttps ? https : http
+      const req = mod.request(options, (res) => {
+        const newSessionId = res.headers['mcp-session-id'] || ''
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          let errBody = ''
+          res.on('data', (chunk) => { errBody += chunk })
+          res.on('end', () => {
+            const err = new Error(`HTTP ${res.statusCode}: ${errBody.trim()}`)
+            err.statusCode = res.statusCode
+            err.body = errBody.trim()
+            reject(err)
+          })
+          return
+        }
+        resolve({ response: res, newSessionId })
+      })
+      req.on('timeout', () => {
+        req.destroy()
+        const err = new Error('Request timeout')
+        err.statusCode = 408
+        reject(err)
+      })
+      req.on('error', reject)
+      req.write(data)
+      req.end()
+    })
+  }
+  /**
+   * Stream an SSE response, writing each data event as a line to stdout.
+   * @param {IncomingMessage} response
+   */
+  _streamSSE(response) {
+    return new Promise((resolve, reject) => {
+      let buffer = ''
+      response.on('data', (chunk) => {
+        buffer += chunk.toString()
+        const lines = buffer.split('\n')
+        buffer = lines.pop() // Keep incomplete last line
+        for (const line of lines) {
+          if (line.startsWith('data: ')) {
+            const data = line.slice(6)
+            if (data && data !== '[DONE]') process.stdout.write(data + '\n')
+          }
+        }
+      })
+      response.on('end', () => {
+        if (buffer.startsWith('data: ')) {
+          const data = buffer.slice(6)
+          if (data && data !== '[DONE]') process.stdout.write(data + '\n')
+        }
+        resolve()
+      })
+      response.on('error', reject)
+    })
+  }
+  /**
+   * Read full response body as a string.
+   * @param {IncomingMessage} response
+   * @returns {Promise<string>}
+   */
+  _readBody(response) {
+    return new Promise((resolve, reject) => {
+      let body = ''
+      response.on('data', (chunk) => { body += chunk })
+      response.on('end', () => resolve(body))
+      response.on('error', reject)
+    })
+  }
+  /**
+   * Write a JSON-RPC error to stdout.
+   */
+  _writeError(id, code, message) {
+    process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n')
+  }
+}
+module.exports = { StreamableHTTPProxy }

package/lib/mcp/handlers.js CHANGED Viewed

@@ -1,81 +1,15 @@
 /**
  * MCP Protocol Method Handlers
  *
- * Handles MCP protocol methods (initialize, ping, tools/list, etc.)
- * These are handled locally and not proxied to the backend.
+ * Handles only the minimal set of MCP protocol methods that must be
+ * processed locally (notifications and ping).
+ * initialize, tools/list and all other methods are forwarded to the server.
  */
-const { sendResponse, sendError } = require('../protocol/json-rpc');
-const { getToolsList } = require('../protocol/tools-schema');
-const { JSON_RPC_ERROR_CODES } = require('../protocol/error-codes');
-const { LOG_LEVELS, MCP_PROTOCOL_VERSION, SERVER_CAPABILITIES } = require('../core/constants');
+const { sendResponse } = require('../protocol/json-rpc');
 /**
- * Get log level
- */
-function getLogLevel() {
-  const level = (process.env.LOG_LEVEL || 'ERROR').toUpperCase();
-  return LOG_LEVELS[level] !== undefined ? LOG_LEVELS[level] : LOG_LEVELS.ERROR;
-}
-const LOG_LEVEL = getLogLevel();
-/**
- * Log message
- */
-function log(level, message) {
-  if (LOG_LEVEL >= level) {
-    const levelName = Object.keys(LOG_LEVELS)[level] || 'UNKNOWN';
-    process.stderr.write(`[${levelName}] ${message}\n`);
-  }
-}
-/**
- * Get package info
- */
-function getPackageInfo() {
-  try {
-    const pkg = require('../../package.json');
-    return { name: pkg.name, version: pkg.version };
-  } catch (error) {
-    return { name: '@meldocio/mcp-stdio-proxy', version: '1.0.0' };
-  }
-}
-/**
- * Handle MCP initialize method
- * @param {Object} request - JSON-RPC request
- */
-function handleInitialize(request) {
-  const pkg = getPackageInfo();
-  const result = {
-    protocolVersion: MCP_PROTOCOL_VERSION,
-    capabilities: {
-      tools: SERVER_CAPABILITIES.TOOLS ? {} : undefined,
-      resources: SERVER_CAPABILITIES.RESOURCES ? {} : undefined,
-      prompts: SERVER_CAPABILITIES.PROMPTS ? {} : undefined,
-      logging: SERVER_CAPABILITIES.LOGGING ? {} : undefined
-    },
-    serverInfo: {
-      name: pkg.name,
-      version: pkg.version
-    }
-  };
-  // Remove undefined capabilities
-  Object.keys(result.capabilities).forEach(key => {
-    if (result.capabilities[key] === undefined) {
-      delete result.capabilities[key];
-    }
-  });
-  log(LOG_LEVELS.DEBUG, 'Initialize request received');
-  sendResponse(request.id, result);
-}
-/**
- * Handle MCP ping method (keep-alive)
+ * Handle MCP ping method (keep-alive).
  * @param {Object} request - JSON-RPC request
  */
 function handlePing(request) {
@@ -83,103 +17,20 @@ function handlePing(request) {
 }
 /**
- * Handle resources/list method
- * Returns empty list as resources are not supported yet
- * @param {Object} request - JSON-RPC request
+ * Check if a method is a notification that requires no response.
+ * @param {string} method
+ * @returns {boolean}
  */
-function handleResourcesList(request) {
-  sendResponse(request.id, {
-    resources: []
-  });
-}
-/**
- * Handle tools/list method
- * Always returns static list locally, never proxies to backend
- * @param {Object} request - JSON-RPC request
- */
-function handleToolsList(request) {
-  try {
-    const tools = getToolsList();
-    // Log tool names for debugging
-    const toolNames = tools.map(t => t.name).join(', ');
-    log(LOG_LEVELS.INFO, `Returning ${tools.length} tools locally: ${toolNames}`);
-    sendResponse(request.id, {
-      tools: tools
-    });
-  } catch (error) {
-    // This should never happen, but if it does, send error response
-    log(LOG_LEVELS.ERROR, `Unexpected error in handleToolsList: ${error.message || 'Unknown error'}`);
-    log(LOG_LEVELS.DEBUG, `Error stack: ${error.stack || 'No stack trace'}`);
-    sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR,
-              `Failed to get tools list: ${error.message || 'Unknown error'}`, {
-                code: 'INTERNAL_ERROR'
-              });
-  }
-}
-/**
- * Check if a method should be handled locally
- * @param {string} method - Method name
- * @returns {boolean} True if should be handled locally
- */
-function isLocalMethod(method) {
-  const localMethods = [
-    'initialize',
-    'initialized',
-    'notifications/initialized',
-    'notifications/cancelled',
-    'ping',
-    'resources/list',
-    'tools/list'
-  ];
-  return localMethods.includes(method);
-}
-/**
- * Route request to appropriate local handler
- * @param {Object} request - JSON-RPC request
- * @returns {boolean} True if handled, false if should be proxied
- */
-function handleLocalMethod(request) {
-  const method = request.method;
-  switch (method) {
-    case 'initialize':
-      handleInitialize(request);
-      return true;
-    case 'initialized':
-    case 'notifications/initialized':
-    case 'notifications/cancelled':
-      // Notifications - no response needed
-      return true;
-    case 'ping':
-      handlePing(request);
-      return true;
-    case 'resources/list':
-      handleResourcesList(request);
-      return true;
-    case 'tools/list':
-      handleToolsList(request);
-      return true;
-    default:
-      return false; // Not a local method
-  }
+function isNotification(method) {
+  return (
+    method === 'initialized' ||
+    method === 'notifications/initialized' ||
+    method === 'notifications/cancelled' ||
+    method === 'notifications/progress'
+  );
 }
 module.exports = {
-  handleInitialize,
   handlePing,
-  handleResourcesList,
-  handleToolsList,
-  isLocalMethod,
-  handleLocalMethod
+  isNotification
 };