@meldocio/mcp-stdio-proxy 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meldoc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# @meldocio/mcp-stdio-proxy
+
+MCP stdio proxy for meldoc - connects Claude Desktop to meldoc MCP API without requiring CLI installation.
+
+## Description
+
+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.
+
+## Installation
+
+The package is designed to be used via `npx`, so no installation is required. However, if you want to install it globally:
+
+```bash
+npm install -g @meldocio/mcp-stdio-proxy
+```
+
+## Usage
+
+### Claude Desktop Configuration
+
+Add the following configuration to your `claude_desktop_config.json` file:
+
+**macOS:**
+
+```
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+**Windows:**
+
+```
+%APPDATA%\Claude\claude_desktop_config.json
+```
+
+**Linux:**
+
+```
+~/.config/Claude/claude_desktop_config.json
+```
+
+```json
+{
+  "mcpServers": {
+    "meldoc": {
+      "command": "npx",
+      "args": ["-y", "@meldocio/mcp-stdio-proxy"],
+      "env": {
+        "MELDOC_MCP_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+After adding the configuration, restart Claude Desktop.
+
+### Environment Variables
+
+- **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`
+
+Example with custom API URL:
+
+```json
+{
+  "mcpServers": {
+    "meldoc": {
+      "command": "npx",
+      "args": ["-y", "@meldocio/mcp-stdio-proxy"],
+      "env": {
+        "MELDOC_MCP_TOKEN": "your_token_here",
+        "MELDOC_API_URL": "https://custom.api.example.com"
+      }
+    }
+  }
+}
+```
+
+### Command Line Testing
+
+You can test the proxy directly from the command line:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
+  MELDOC_MCP_TOKEN=your_token_here npx @meldocio/mcp-stdio-proxy
+```
+
+Or with a custom API URL:
+
+```bash
+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
+```
+
+## 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
+
+### Supported Features
+
+- ✅ JSON-RPC 2.0 protocol
+- ✅ Single and batch requests
+- ✅ Proper error handling with JSON-RPC error codes
+- ✅ Request timeout handling (30 seconds)
+- ✅ Network error recovery
+- ✅ Line-by-line processing for streaming
+
+## JSON-RPC Error Codes
+
+The proxy uses standard JSON-RPC 2.0 error codes:
+
+- `-32700`: Parse error (invalid JSON)
+- `-32600`: Invalid Request (malformed JSON-RPC)
+- `-32601`: Method not found
+- `-32602`: Invalid params
+- `-32603`: Internal error (network errors, timeouts, etc.)
+- `-32000`: Server error (HTTP 4xx/5xx responses)
+
+## Troubleshooting
+
+### Error: MELDOC_MCP_TOKEN environment variable is required
+
+**Solution:** Make sure you've set the `MELDOC_MCP_TOKEN` in the `env` section of your Claude Desktop configuration.
+
+### Connection timeout
+
+**Solution:** Check your internet connection and verify that `https://api.meldoc.io` is accessible. You can test with:
+
+```bash
+curl https://api.meldoc.io/mcp/v1/rpc \
+  -H "Authorization: Bearer your_token" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+### Invalid token error
+
+**Solution:** Verify that your `MELDOC_MCP_TOKEN` is correct and hasn't expired. You can get a new token from the meldoc dashboard.
+
+### Claude Desktop not connecting
+
+**Solution:**
+
+1. Verify the configuration JSON is valid (use a JSON validator)
+2. Check that the file path is correct for your operating system
+3. Restart Claude Desktop completely
+4. Check Claude Desktop logs for error messages
+
+### Testing the proxy manually
+
+To debug issues, you can test the proxy directly:
+
+```bash
+# Test with a simple request
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
+  MELDOC_MCP_TOKEN=your_token npx @meldocio/mcp-stdio-proxy
+
+# Test with verbose output (if needed)
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
+  MELDOC_MCP_TOKEN=your_token \
+  DEBUG=1 \
+  npx @meldocio/mcp-stdio-proxy
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 14.0.0
+- npm
+
+### Setup
+
+```bash
+git clone https://github.com/meldoc/mcp-stdio-proxy.git
+cd mcp-stdio-proxy
+npm install
+```
+
+### Running Tests
+
+```bash
+npm test
+```
+
+### Building
+
+No build step is required - the package uses plain JavaScript.
+
+### Publishing
+
+```bash
+npm publish --access public
+```
+
+## Requirements
+
+- Node.js >= 14.0.0
+- Valid meldoc MCP token
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+For issues, questions, or contributions, please visit:
+
+- GitHub Issues: <https://github.com/meldoc/mcp-stdio-proxy/issues>
+- Documentation: <https://docs.meldoc.io>
+
+## Related
+
+- [meldoc MCP Documentation](https://docs.meldoc.io/integrations/mcp)
+- [Claude Desktop MCP Guide](https://docs.anthropic.com/claude/docs/mcp)

package/bin/meldoc-mcp-proxy.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+
+const axios = require('axios');
+const { URL } = require('url');
+
+// JSON-RPC error codes
+const JSON_RPC_ERROR_CODES = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  SERVER_ERROR: -32000
+};
+
+// Configuration
+const token = process.env.MELDOC_MCP_TOKEN;
+const apiUrl = process.env.MELDOC_API_URL || 'https://api.meldoc.io';
+const rpcEndpoint = `${apiUrl}/mcp/v1/rpc`;
+const REQUEST_TIMEOUT = 30000; // 30 seconds
+
+// Validate token
+if (!token) {
+  console.error('Error: MELDOC_MCP_TOKEN environment variable is required');
+  process.exit(1);
+}
+
+// Buffer for incomplete lines
+let buffer = '';
+
+// Set stdin encoding
+process.stdin.setEncoding('utf8');
+
+// Handle stdin data
+process.stdin.on('data', (chunk) => {
+  buffer += chunk;
+  const lines = buffer.split('\n');
+  // Keep the last incomplete line in buffer
+  buffer = lines.pop() || '';
+  
+  // Process complete lines
+  for (const line of lines) {
+    if (line.trim()) {
+      handleLine(line.trim());
+    }
+  }
+});
+
+// Handle end of input
+process.stdin.on('end', () => {
+  // Process any remaining buffer
+  if (buffer.trim()) {
+    handleLine(buffer.trim());
+  }
+});
+
+// Handle errors
+process.stdin.on('error', (error) => {
+  sendError(null, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, `Input error: ${error.message}`);
+  process.exit(1);
+});
+
+/**
+ * Handle a single line from stdin
+ */
+function handleLine(line) {
+  try {
+    const request = JSON.parse(line);
+    handleRequest(request);
+  } catch (parseError) {
+    // Invalid JSON - send parse error
+    sendError(null, JSON_RPC_ERROR_CODES.PARSE_ERROR, `Parse error: ${parseError.message}`);
+  }
+}
+
+/**
+ * Validate JSON-RPC request
+ */
+function validateRequest(request) {
+  if (!request || typeof request !== 'object') {
+    return { valid: false, error: 'Request must be an object' };
+  }
+  
+  if (request.jsonrpc !== '2.0') {
+    return { valid: false, error: 'jsonrpc must be "2.0"' };
+  }
+  
+  if (!request.method && !Array.isArray(request)) {
+    return { valid: false, error: 'Request must have a method or be a batch array' };
+  }
+  
+  return { valid: true };
+}
+
+/**
+ * Handle a JSON-RPC request
+ */
+async function handleRequest(request) {
+  // Handle batch requests (array of requests)
+  if (Array.isArray(request)) {
+    // Process batch requests sequentially
+    for (const req of request) {
+      if (req) {
+        await processSingleRequest(req);
+      }
+    }
+    return;
+  }
+  
+  // Validate single request
+  const validation = validateRequest(request);
+  if (!validation.valid) {
+    sendError(request.id, JSON_RPC_ERROR_CODES.INVALID_REQUEST, validation.error);
+    return;
+  }
+  
+  await processSingleRequest(request);
+}
+
+/**
+ * Process a single JSON-RPC request
+ */
+async function processSingleRequest(request) {
+  try {
+    // Make HTTP request to MCP API
+    const response = await axios.post(rpcEndpoint, request, {
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      },
+      timeout: REQUEST_TIMEOUT,
+      validateStatus: (status) => status < 500 // Don't throw on 4xx errors
+    });
+    
+    // Handle successful response
+    if (response.status >= 200 && response.status < 300) {
+      const responseData = response.data;
+      
+      // Ensure response has jsonrpc and id if original request had id
+      if (responseData && typeof responseData === 'object') {
+        if (!responseData.jsonrpc) {
+          responseData.jsonrpc = '2.0';
+        }
+        if (request.id !== undefined && responseData.id === undefined) {
+          responseData.id = request.id;
+        }
+      }
+      
+      process.stdout.write(JSON.stringify(responseData) + '\n');
+    } else {
+      // HTTP error status
+      const errorMessage = response.data?.error?.message || 
+                          response.data?.message || 
+                          `HTTP ${response.status}: ${response.statusText}`;
+      sendError(request.id, JSON_RPC_ERROR_CODES.SERVER_ERROR, errorMessage);
+    }
+  } catch (error) {
+    // Handle different types of errors
+    if (error.response) {
+      // Server responded with error status
+      const status = error.response.status;
+      const errorData = error.response.data;
+      const errorMessage = errorData?.error?.message || 
+                          errorData?.message || 
+                          `HTTP ${status}: ${error.response.statusText}`;
+      
+      let errorCode = JSON_RPC_ERROR_CODES.SERVER_ERROR;
+      if (status === 401) {
+        errorCode = JSON_RPC_ERROR_CODES.INTERNAL_ERROR;
+      } else if (status === 404) {
+        errorCode = JSON_RPC_ERROR_CODES.METHOD_NOT_FOUND;
+      }
+      
+      sendError(request.id, errorCode, errorMessage);
+    } else if (error.request) {
+      // Request was made but no response received
+      sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, 
+                `Network error: ${error.message || 'No response from server'}`);
+    } else if (error.code === 'ECONNABORTED') {
+      // Timeout
+      sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, 
+                `Request timeout after ${REQUEST_TIMEOUT}ms`);
+    } else {
+      // Other errors
+      sendError(request.id, JSON_RPC_ERROR_CODES.INTERNAL_ERROR, 
+                `Internal error: ${error.message || 'Unknown error'}`);
+    }
+  }
+}
+
+/**
+ * Send JSON-RPC error response
+ */
+function sendError(id, code, message) {
+  const errorResponse = {
+    jsonrpc: '2.0',
+    id: id !== undefined ? id : null,
+    error: {
+      code: code,
+      message: message
+    }
+  };
+  
+  process.stdout.write(JSON.stringify(errorResponse) + '\n');
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@meldocio/mcp-stdio-proxy",
+  "version": "1.0.0",
+  "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"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "meldoc",
+    "claude",
+    "stdio",
+    "proxy",
+    "json-rpc"
+  ],
+  "author": "Meldoc",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meldoc/mcp-stdio-proxy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/meldoc/mcp-stdio-proxy/issues"
+  },
+  "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"
+    ]
+  }
+}