@myatkyawthu/mcp-connect 0.2.1 → 0.3.1

package/README.md

@@ -1,170 +1,394 @@
 # mcp-connect
 
-> Dead simple MCP (Model Context Protocol) server for exposing your app functions to AI agents
+> Dead simple MCP server framework. Define your tools as async functions — it handles the protocol, transport, security, and dashboard.
 
-[![npm version](https://badge.fury.io/js/mcp-connect.svg)](https://www.npmjs.com/package/mcp-connect)
+[![npm version](https://img.shields.io/npm/v/@myatkyawthu/mcp-connect.svg)](https://www.npmjs.com/package/@myatkyawthu/mcp-connect)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## 🚀 Claude Desktop Setup (5 Minutes)
-
-### Step 1: Install mcp-connect
-
-```bash
-npm install -g @myatkyawthu/mcp-connect
-```
-### Step 2: Create mcp.config.js
+---
 
-### Step 2: Create Your MCP Server
+## What is this?
 
-```bash
-# Navigate to your project directory
-cd your-project
+**Model Context Protocol (MCP)** is the standard way AI tools (Claude, Cursor, Cline, etc.) call your app's functions. Think of it like a plugin system — any MCP-compatible AI can discover and call your tools.
 
-# Generate sample config
-mcp-connect init
-```
+`mcp-connect` removes all the boilerplate. You write async functions. It handles the rest: JSON-RPC wiring, transport, schema advertisement, rate limiting, auth, error handling, and a live inspector dashboard.
 
-This creates `mcp.config.js` with example tools:
-
-```javascript
+```js
 import { defineMCP } from "@myatkyawthu/mcp-connect";
 
 export default defineMCP({
-  name: "My MCP App",
+  name: "my-server",
   version: "1.0.0",
   tools: [
     ["hello", async ({ name = "World" }) => `Hello ${name}!`],
-    ["echo", async ({ message }) => `Echo: ${message}`]
+    {
+      name: "echo",
+      description: "Echo back the input",
+      schema: {
+        type: "object",
+        properties: { message: { type: "string" } },
+        required: ["message"]
+      },
+      handler: async ({ message }) => `Echo: ${message}`
+    }
   ]
 });
 ```
-### Step 3: Test Locally
 
-### Step 3: Configure Claude Desktop
+---
+
+## Install
+
+```bash
+# Global CLI (recommended)
+npm install -g @myatkyawthu/mcp-connect
+
+# Or as a project dependency
+npm install @myatkyawthu/mcp-connect
+```
+
+Requires **Node.js 18+**.
 
-Open Claude Desktop config file:
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+---
 
-Add your MCP server:
+## Quick Start
+
+```bash
+# 1. Create a config file
+mcp-connect init
+
+# 2. Edit mcp.config.js and add your tools
+
+# 3. Run it
+mcp-connect                  # STDIO mode (for Claude Desktop)
+mcp-connect --port 3000      # SSE/HTTP mode (for web clients, IDEs)
+```
+
+---
+
+## Three Modes — Pick One
+
+### Mode 1 — STDIO (Local, for Claude Desktop)
+
+Your AI tool spawns the process. Communication happens via stdin/stdout pipes. No port, no HTTP.
+
+```bash
+mcp-connect mcp.config.js
+```
 
+**Claude Desktop config** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
     "my-app": {
       "command": "mcp-connect",
-      "args": ["C:/full/path/to/your/mcp.config.js"]
+      "args": ["/absolute/path/to/mcp.config.js"]
     }
   }
 }
 ```
 
-**Important**: Use the full absolute path to your `mcp.config.js` file.
+---
+
+### Mode 2 — SSE / HTTP (Deployed on a Server)
+
+Starts an HTTP server. AI clients connect to `/sse` and send requests to `/message`. **This is the mode for deploying on a VPS or cloud** so any client can reach it over the internet.
+
+```bash
+mcp-connect mcp.config.js --port 3000
+```
+
+Once deployed behind HTTPS, clients connect to:
+```
+https://yourserver.com/sse
+```
 
-### Step 4: Start & Test
+**Client compatibility:**
 
-1. **Restart Claude Desktop** completely
-2. **Test connection**: Ask Claude *"What tools do you have available?"*
-3. **Use your tools**: Try *"Hello there!"* or *"Echo this message"*
+| Client | SSE Support |
+| :--- | :---: |
+| Claude.ai (web) | ✅ |
+| Cursor | ✅ |
+| Cline (VS Code) | ✅ |
+| Windsurf | ✅ |
+| Continue.dev | ✅ |
+| Zed | ✅ |
+| Claude Desktop | ❌ (STDIO only) |
 
-✅ **Done!** Your functions are now available to Claude Desktop.
+**Endpoints exposed:**
+
+| Endpoint | Description |
+| :--- | :--- |
+| `GET /sse` | AI client connects here (long-lived SSE stream) |
+| `POST /message` | AI client sends JSON-RPC requests |
+| `GET /health` | JSON health check with tool list |
+| `GET /` | Live inspector dashboard |
 
 ---
 
-## 📖 Tool Definition Guide
+### Mode 3 — Tunnel (Behind NAT, No Open Port)
+
+If your machine can't receive inbound connections (home laptop, office network), use the tunnel. Run a tiny relay on any $5/month VPS — your local machine connects outbound to it. Remote clients hit the VPS and get proxied to your machine.
+
+**Step 1 — Start the relay on your VPS (one-time setup):**
+```bash
+mcp-connect relay --port 4000
+```
 
-### Simple Format (Recommended)
+**Step 2 — Start your server on your local machine:**
+```bash
+mcp-connect mcp.config.js --port 3111 --tunnel
+```
 
-```javascript
-// Just name and function
-["toolName", async (args) => "result"]
+Your terminal will print:
+```
+MCP Tunnel bridge active!
+Remote SSE endpoint: http://your-vps.com/t/<tunnelId>/sse
 ```
-## 🔧 CLI Usage
 
-### Advanced Format (With Validation)
+Share that URL with any MCP client. Done.
 
-```javascript
+> The relay auto-reconnects if the tunnel drops. All payloads can be AES-256-GCM encrypted end-to-end (see Security section below).
+
+---
+
+## Tool Definition Formats
+
+### Short format (tuple)
+For simple one-liner tools:
+```js
+["toolName", async (args) => result]
+```
+
+### Full format (object)
+For tools that need schema validation, descriptions, or a security confirmation gate:
+```js
 {
-  name: "toolName",
-  description: "What this tool does",
+  name: "delete_record",
+  description: "Permanently delete a record by ID",
   schema: {
     type: "object",
     properties: {
-      param: { type: "string", description: "Parameter description" }
+      id: { type: "string", description: "Record ID to delete" }
     },
-    required: ["param"]
+    required: ["id"]
   },
-  handler: async ({ param }) => `Result: ${param}`
+  confirm: true,   // asks "y/N?" in terminal before executing
+  handler: async ({ id }) => {
+    await db.delete(id);
+    return `Deleted ${id}`;
+  }
 }
 ```
 
-## 🛠 Development Commands
+The AI receives the schema and knows exactly what arguments to pass. You don't have to document it separately.
+
+---
+
+## Security
+
+All security features are optional — enable only what you need.
+
+### Bearer Token Auth
+
+Protect the `/sse` and `/message` endpoints. Any request without the correct token gets a `401`.
 
 ```bash
-# Start with auto-reload during development
-npm run dev
+# Set via environment variable
+MCP_TUNNEL_TOKEN=my-secret-token mcp-connect mcp.config.js --port 3000
+```
+
+Or in config:
+```js
+server: {
+  tunnel: { token: "my-secret-token" }
+}
+```
+
+Clients must send: `Authorization: Bearer my-secret-token`
 
-# Start server with specific config file
-mcp-connect /path/to/your/mcp.config.js
+---
 
-# Format code
-npm run format
+### CORS Origin Allowlist
 
-# Lint code
-npm run lint
+Restrict which origins can connect. Without this, all origins are allowed (`*`).
+
+```js
+server: {
+  cors: {
+    origins: ["https://claude.ai", "https://cursor.sh"]
+  }
+}
 ```
 
-## 🔧 Troubleshooting
+Requests from unlisted origins get `403 Origin not allowed`.
 
-### Config File Not Found
-```bash
-# Create sample config
-mcp-connect init
+---
+
+### End-to-End Encryption (Tunnel mode)
+
+Encrypt all payloads over the tunnel so the relay server only sees ciphertext. Uses AES-256-GCM.
+
+```js
+server: {
+  tunnel: {
+    encryptionKey: "my-32-char-passphrase-or-64hex"
+  }
+}
 ```
 
-### Claude Desktop Not Connecting
-1. Check config file path is absolute
-2. Restart Claude Desktop completely
-3. Check Claude Desktop logs for errors
+The relay cannot read your tool calls or responses even if it's compromised.
 
-### Tool Not Working
-1. Verify tool syntax in `mcp.config.js`
-2. Check server logs for errors
-3. Test with simple tools first
+---
 
-## 📋 Examples
+### Confirm Gate for Dangerous Tools
 
-### File Operations
-```javascript
-["readFile", async ({ path }) => {
-  const fs = await import('fs/promises');
-  return await fs.readFile(path, 'utf8');
-}]
+Add `confirm: true` to any tool. Before it runs, the terminal prompts you:
 ```
+⚠️  [MCP SECURITY] Allow tool "delete_record" execution? (y/N):
+```
+
+The tool only runs if you type `y`. Otherwise it's rejected with an error.
 
-### API Calls
-```javascript
-["getWeather", async ({ city }) => {
-  const response = await fetch(`https://api.weather.com/${city}`);
-  return await response.json();
-}]
+---
+
+## Built-in Protections (Always On)
+
+These run automatically without any config:
+
+| Protection | Detail |
+| :--- | :--- |
+| **Rate limiting** | 100 requests/minute per server |
+| **Tool timeout** | 30 seconds max per tool call |
+| **Response size cap** | 1MB max, truncated if exceeded |
+| **Error sanitization** | Stack traces stripped before returning to AI |
+| **Circular reference guard** | Safe JSON serialization |
+
+---
+
+## Inspector Dashboard
+
+Available at `http://localhost:<port>/` whenever running in SSE mode.
+
+- **Logs tab** — live feed of every tool call with timestamp, duration, pass/fail status. Click any row to see full request args and response.
+- **Test Tool tab** — pick a tool, fill in args as JSON, hit Execute. See the response immediately. No AI client needed for debugging.
+
+The dashboard connects to `/api/events` over SSE — it updates in real-time without refreshing.
+
+---
+
+## Full Config Reference
+
+```js
+import { defineMCP } from "@myatkyawthu/mcp-connect";
+
+export default defineMCP({
+  name: "my-server",       // required
+  version: "1.0.0",        // required
+  description: "...",      // optional
+
+  server: {
+    port: 3000,            // optional — same as --port flag
+
+    cors: {
+      origins: [           // optional — allowlist of origins
+        "https://claude.ai",
+        "http://localhost:5173"
+      ]
+    },
+
+    tunnel: {
+      enabled: true,       // optional — same as --tunnel flag
+      relayUrl: "http://your-vps.com:4000",  // relay address
+      token: "secret",     // bearer token for auth
+      encryptionKey: "..."  // AES-256-GCM key (passphrase or 64-char hex)
+    }
+  },
+
+  tools: [
+    // Short format
+    ["hello", async ({ name = "World" }) => `Hello ${name}!`],
+
+    // Full format
+    {
+      name: "echo",
+      description: "Echo back the input",
+      schema: {
+        type: "object",
+        properties: {
+          message: { type: "string" }
+        },
+        required: ["message"]
+      },
+      handler: async ({ message }) => `Echo: ${message}`
+    },
+
+    // Dangerous tool with confirmation gate
+    {
+      name: "delete_all",
+      description: "Wipe everything",
+      confirm: true,
+      handler: async () => {
+        await nuke();
+        return "Done.";
+      }
+    }
+  ]
+});
 ```
 
-### Database Queries
-```javascript
-["getUser", async ({ id }) => {
-  // Your database logic here
-  return { id, name: "John Doe", email: "john@example.com" };
-}]
+---
+
+## CLI Reference
+
+```bash
+mcp-connect init                        # Scaffold mcp.config.js in current directory
+mcp-connect [config.js]                 # Start in STDIO mode
+mcp-connect [config.js] --port <port>   # Start in SSE/HTTP mode
+mcp-connect [config.js] --tunnel        # Start with outbound tunnel
+mcp-connect relay --port <port>         # Run a relay gateway (deploy on VPS)
 ```
 
-## 🌐 Other MCP Clients
+Config file defaults to `mcp.config.js` in the current directory if not specified.
 
-Claude Desktop setup is covered above. Tutorials for other MCP clients coming soon:
-- VS Code extensions
-- Custom applications
-- Other AI platforms
+---
+
+## Deployment Recipes
+
+### Deploy on Railway / Render / Fly.io
+
+1. Push your repo with `mcp.config.js`
+2. Set start command: `mcp-connect mcp.config.js --port 3000`
+3. Set env var: `MCP_TUNNEL_TOKEN=your-secret`
+4. Add your domain/URL to your AI client as the MCP server URL: `https://yourapp.railway.app/sse`
+
+### Self-hosted VPS (nginx + HTTPS)
+
+```nginx
+location / {
+    proxy_pass http://localhost:3000;
+    proxy_http_version 1.1;
+    proxy_set_header Connection '';          # keep SSE alive
+    proxy_buffering off;                     # required for SSE streaming
+    proxy_cache off;
+    proxy_set_header Host $host;
+}
+```
+
+Then run: `mcp-connect mcp.config.js --port 3000`
+
+### Laptop behind NAT (tunnel setup)
+
+```bash
+# On VPS
+mcp-connect relay --port 4000
+
+# On laptop
+MCP_TUNNEL_TOKEN=secret mcp-connect mcp.config.js --port 3111 --tunnel
+```
+
+---
 
-## 📄 License
+## License
 
 MIT © [myat-kyaw-thu](https://github.com/myat-kyaw-thu)

package/package.json

@@ -1,18 +1,14 @@
 {
   "name": "@myatkyawthu/mcp-connect",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Dead simple MCP (Model Context Protocol) server for exposing your app functions to AI agents",
   "type": "module",
   "main": "./src/index.js",
-  "module": "./src/index.js",
   "exports": {
-    ".": {
-      "import": "./src/index.js",
-      "require": "./src/index.js"
-    }
+    ".": "./src/index.js"
   },
   "bin": {
-    "mcp-connect": "src/cli.js"
+    "mcp-connect": "./src/cli.js"
   },
   "files": [
     "src",
@@ -23,7 +19,7 @@
     "start": "node src/cli.js",
     "dev": "nodemon src/cli.js",
     "test": "node --test",
-    "test:unit": "node --test tests/unit",
+    "test:unit": "node --test tests/unit/*.test.js",
     "test:integration": "node --test tests/integration",
     "lint": "eslint src/",
     "format": "prettier --write src/"
@@ -53,11 +49,11 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.5.0"
+    "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {
-    "nodemon": "^3.0.0",
     "eslint": "^8.0.0",
+    "nodemon": "^3.0.0",
     "prettier": "^3.0.0"
   }
-}
+}

package/src/cli.js

@@ -23,7 +23,7 @@ export default defineMCP({
   tools: [
     // Simple tuple format: [name, handler]
     ["hello", async ({ name = "World" }) => \`Hello \${name}!\`],
-    
+
     // Object format with schema validation
     {
       name: "echo",
@@ -72,10 +72,31 @@ async function main() {
       return;
     }
 
+    if (process.argv[2] === 'relay') {
+      const portIndex = process.argv.indexOf('--port');
+      const relayPort = portIndex !== -1 ? parseInt(process.argv[portIndex + 1], 10) : 4000;
+      const { MCPRelayServer } = await import('./server/relay.js');
+      const relay = new MCPRelayServer();
+      await relay.start(relayPort);
+      return;
+    }
+
     console.error('Starting MCP-Connect CLI...');
 
-    const configArg = process.argv[2];
+    // Parse --port flag
+    let port = null;
+    const portIndex = process.argv.indexOf('--port');
+    if (portIndex !== -1) {
+      port = parseInt(process.argv[portIndex + 1], 10);
+      if (!port || port < 1 || port > 65535) {
+        console.error('Invalid port. Usage: mcp-connect --port 3000');
+        process.exit(1);
+      }
+    }
+
+    // Find config path (skip flags)
     let configPath = null;
+    const configArg = process.argv.find((a, i) => i >= 2 && !a.startsWith('--') && process.argv[i - 1] !== '--port' && a !== 'relay');
 
     if (configArg) {
       const fullPath = resolve(configArg);
@@ -158,7 +179,7 @@ export default defineMCP({
           error.message.includes('Cannot resolve') ||
           error.message.includes('MODULE_NOT_FOUND')
         ) {
-          console.error("Make sure 'mcp-connect' is installed: npm install mcp-connect");
+          console.error('Make sure \'@myatkyawthu/mcp-connect\' is installed: npm install mcp-connect');
         } else if (error.message.includes('SyntaxError')) {
           console.error('Config file has syntax errors. Check your JavaScript syntax.');
         } else if (error.message.includes('ERR_MODULE_NOT_FOUND')) {
@@ -185,7 +206,23 @@ export default defineMCP({
     }
 
     const server = new MCPConnectServer(validatedConfig);
-    await server.start();
+
+    const finalPort = port || validatedConfig.server?.port;
+    const useSSE = !!finalPort || validatedConfig.server?.transport === 'sse' || validatedConfig.server?.transport === 'hybrid';
+    const useTunnel = process.argv.includes('--tunnel') || !!validatedConfig.server?.tunnel?.enabled;
+    const relayUrl = process.env.MCP_RELAY_URL || validatedConfig.server?.tunnel?.relayUrl || 'http://localhost:4000';
+
+    if (useSSE) {
+      await server.startSSE(finalPort || 3000);
+    } else {
+      await server.start();
+    }
+
+    if (useTunnel) {
+      server.startTunnel(relayUrl).catch((err) => {
+        console.error('Tunnel failed to start:', err.message);
+      });
+    }
 
     process.on('SIGINT', async () => {
       console.error('Shutting down...');

package/src/defineMCP.js

@@ -33,7 +33,7 @@ export function defineMCP(config) {
         handler,
       };
     } else {
-      const { name, handler, description, schema } = tool;
+      const { name, handler, description, schema, confirm } = tool;
       return {
         name: name.trim(),
         description: description || `Tool: ${name}`,
@@ -43,6 +43,7 @@ export function defineMCP(config) {
           additionalProperties: true,
         },
         handler,
+        confirm: !!confirm,
       };
     }
   });
@@ -51,6 +52,7 @@ export function defineMCP(config) {
     name: config.name,
     version: config.version,
     description: config.description,
+    server: config.server || {},
     tools: mcpTools,
   };
 }

package/src/index.js

@@ -1,3 +1,5 @@
 export { defineMCP } from './defineMCP.js';
 export { MCPConnectServer } from './server/mcpServer.js';
+export { MCPRelayServer } from './server/relay.js';
+export { encrypt, decrypt } from './utils/crypto.js';
 export { isValidMCPConfig, isValidMCPTool, isValidToolDefinition } from './types/mcp.js';