@dotmcp/tunnel 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,212 @@
+# @dotmcp/tunnel
+
+Connect your local MCP servers to the [dotMCP Marketplace](https://dotmcp.io) without deploying code to the cloud.
+
+## Features
+
+- 🔌 **Expose local MCP servers** to the marketplace
+- 🔒 **Secure WebSocket connection** with TLS encryption
+- 🔄 **Auto-reconnect** with exponential backoff
+- 💻 **Works with any MCP server** - Node.js, Python, or any language
+- 🚀 **Zero cloud deployment** - keep your code on-premise or on your own cloud
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @dotmcp/tunnel
+
+# Or run directly with npx
+npx @dotmcp/tunnel --help
+```
+
+## Quick Start
+
+### 1. Create a Tunnel Server on dotMCP
+
+1. Go to [app.dotmcp.io](https://app.dotmcp.io) and log in
+2. Navigate to **Dashboard** → **My Servers** → **New Server**
+3. Select **"Tunnel (Local MCP Server)"**
+4. Enter your server name and description
+5. Copy your **Tunnel Key** from the server settings
+
+### 2. Create Configuration
+
+Create a `tunnel.yaml` file:
+
+```yaml
+key: "dott_your_tunnel_key_here"
+
+servers:
+  - id: "your-server-id"
+    command: "node"
+    args: ["./my-mcp-server.js"]
+```
+
+### 3. Start the Tunnel
+
+```bash
+dotmcp-tunnel -c tunnel.yaml
+```
+
+## Configuration Reference
+
+### Basic Configuration
+
+```yaml
+key: "dott_xxx..."
+
+servers:
+  - id: "server-id-from-dashboard"
+    command: "node"
+    args: ["server.js"]
+```
+
+### Full Configuration Options
+
+```yaml
+key: "dott_xxx..."
+
+# Optional: Custom relay URL (defaults to wss://relay.dotmcp.io)
+# relay: "wss://relay.dotmcp.io"
+
+servers:
+  - id: "server-id"
+    
+    # Option 1: Command-based (stdio transport)
+    command: "node"
+    args: ["./server.js", "--flag"]
+    cwd: "/path/to/working/directory"
+    env:
+      API_KEY: "secret"
+      DEBUG: "true"
+    
+    # Option 2: HTTP-based (for running servers)
+    # url: "http://localhost:3000/mcp"
+```
+
+## CLI Usage
+
+```bash
+# Start tunnel with config file
+dotmcp-tunnel -c tunnel.yaml
+
+# Start with verbose logging
+dotmcp-tunnel -c tunnel.yaml -v
+
+# Show help
+dotmcp-tunnel --help
+```
+
+## Examples
+
+### Node.js MCP Server
+
+```yaml
+key: "dott_xxx..."
+servers:
+  - id: "my-server"
+    command: "node"
+    args: ["server.js"]
+```
+
+### Using NPM Packages
+
+Expose the official MCP demo server:
+
+```yaml
+key: "dott_xxx..."
+servers:
+  - id: "demo-server"
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-everything"]
+```
+
+### Python MCP Server
+
+```yaml
+key: "dott_xxx..."
+servers:
+  - id: "python-server"
+    command: "python"
+    args: ["-m", "my_mcp_server"]
+    cwd: "/home/user/mcp-project"
+    env:
+      PYTHONPATH: "/home/user/mcp-project"
+```
+
+### Multiple Servers
+
+```yaml
+key: "dott_xxx..."
+servers:
+  - id: "weather-api"
+    command: "node"
+    args: ["./servers/weather.js"]
+  
+  - id: "database-tools"
+    command: "node"
+    args: ["./servers/database.js"]
+    env:
+      DB_HOST: "localhost"
+```
+
+## How It Works
+
+```
+┌─────────────────┐     WebSocket      ┌─────────────────┐
+│  dotmcp-tunnel  │◄──────────────────►│  Relay Server   │
+│  (your machine) │                    │  (Cloudflare)   │
+└────────┬────────┘                    └────────┬────────┘
+         │ stdio                                │
+         ▼                                      ▼
+┌─────────────────┐                    ┌─────────────────┐
+│ Local MCP Server│                    │  Proxy Worker   │
+│  (Node/Python)  │                    │   (deployed)    │
+└─────────────────┘                    └────────┬────────┘
+                                                │
+                                                ▼
+                                       ┌─────────────────┐
+                                       │  API Consumers  │
+                                       │ (Claude, apps)  │
+                                       └─────────────────┘
+```
+
+1. **Tunnel daemon** connects to relay via secure WebSocket
+2. **Relay** holds the connection and routes requests
+3. **Proxy worker** forwards API requests through relay to your tunnel
+4. **Local MCP server** processes requests and returns responses
+
+## Security
+
+- 🔑 **Tunnel keys** are scoped to your account
+- 🔐 **Traffic** is encrypted via WebSocket TLS
+- 🚫 **No inbound ports** required on your machine
+- 🔄 **Keys can be rotated** from the dashboard
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## Troubleshooting
+
+### "Config file not found"
+Create a `tunnel.yaml` file or specify the path with `-c path/to/config.yaml`
+
+### "Connection closed immediately"
+- Verify your tunnel key is correct
+- Check that the server ID matches your dashboard
+
+### "Tunnel connected but tools not syncing"
+- Ensure your MCP server responds to `initialize` and `tools/list`
+- Check server logs for errors with `-v` flag
+
+## Links
+
+- 📖 [Full Documentation](https://docs.dotmcp.io/publishers/tunnel)
+- 🌐 [dotMCP Marketplace](https://dotmcp.io)
+- 💬 [Support](mailto:hello@dotmcp.io)
+
+## License
+
+BUSL-1.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dotmcp/tunnel",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "type": "module",
     "description": "CLI daemon to connect local MCP servers to dotmcp.io",
     "author": "dotMCP <hello@dotmcp.io>",