mobilecoder-mcp 1.0.2 → 1.0.3

package/README.md

@@ -0,0 +1,335 @@
+# MobileCoder MCP
+
+> MCP server for MobileCoderMCP - enables mobile to desktop coding
+
+Transform your mobile device into a powerful coding companion for Cursor, Windsurf, and VSCode. Connect your phone to your IDE and code from anywhere with WebRTC-powered real-time communication.
+
+## Features
+
+- 🚀 **QR Code Quick Connect** - Scan and connect in seconds
+- 🔐 **End-to-End Encryption** - DTLS-secured WebRTC connections
+- 📱 **Universal IDE Support** - Works with Cursor, Windsurf, and VSCode
+- ⚡ **Real-Time Sync** - Low-latency signaling over WebSocket
+- 🛡️ **Security Hardened** - HMAC integrity, SDP validation, replay protection
+
+---
+
+## What's New in v1.0.2
+
+### 🔐 Security Hardening & Stability
+
+This version brings critical security improvements to ensure robust WebRTC signaling and data integrity.
+
+- **HMAC Message Integrity**: Added Hash-based Message Authentication Code (HMAC) to verify that signaling messages haven't been tampered with during transit.
+
+- **SDP Validation**: Strict Session Description Protocol (SDP) validation to prevent malicious payload injection.
+
+- **DTLS Fingerprint Check**: Added validation for DTLS fingerprints to ensure secure end-to-end encrypted media streams.
+
+- **Replay Attack Protection**: Implemented message nonces and tracking to block unauthorized session re-use.
+
+- **Memory Leak Prevention**: Optimized event listeners and connection cleanup cycles for long-running sessions.
+
+- **HTTPS Enforcement**: Enhanced origin validation to ensure secure contexts (HTTPS) for all WebRTC operations.
+
+---
+
+## Installation
+
+### Global Install
+
+```bash
+npm install -g mobilecoder-mcp@latest
+```
+
+### Using npx (No Install Required)
+
+```bash
+npx mobilecoder-mcp@latest init
+```
+
+---
+
+## Quick Start
+
+### 1. Initialize Connection
+
+```bash
+mobilecoder-mcp init
+```
+
+This will:
+- Generate a unique 6-character pairing code
+- Display a QR code for mobile scanning
+- Automatically configure your IDEs (Cursor, Windsurf, VSCode)
+- Start the MCP server
+
+### 2. Connect Mobile Device
+
+1. Visit [https://mobilecoder.xyz/connect](https://mobilecoder.xyz/connect) on your mobile device
+2. Enter the pairing code displayed in terminal
+3. Alternatively, scan the QR code shown in terminal
+
+### 3. Start Coding
+
+Your mobile device is now connected! Use it to:
+- Generate code with AI assistance
+- Execute terminal commands
+- Browse and edit files
+- Get real-time feedback
+
+---
+
+## Commands
+
+### `mobilecoder-mcp init`
+
+Initialize a new connection, generate QR code, and start the agent.
+
+```bash
+mobilecoder-mcp init
+```
+
+**Options:**
+- `-s, --signaling <url>` - Custom signaling server URL (default: https://api.mobilecoder.xyz/api)
+- `--debug` - Enable debug logging
+
+### `mobilecoder-mcp start`
+
+Start the agent with an existing connection code.
+
+```bash
+mobilecoder-mcp start --code=ABC123
+```
+
+**Options:**
+- `-c, --code <code>` - Your 6-character connection code (required)
+- `-s, --signaling <url>` - Custom signaling server URL
+- `--debug` - Enable debug logging
+
+### `mobilecoder-mcp reset`
+
+Remove MobileCoderMCP configuration from IDEs.
+
+```bash
+mobilecoder-mcp reset
+```
+
+**Options:**
+- `-i, --ide <ide>` - Specific IDE to reset (cursor, windsurf, vscode, all)
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MCP_SIGNALING_URL` | Signaling server URL | `https://api.mobilecoder.xyz/api` |
+| `MOBILE_CODER_WEB_URL` | Web app URL for QR codes | `https://mobilecoder.xyz` |
+| `MCP_CONNECTION_CODE` | Pre-defined connection code | Auto-generated |
+
+---
+
+## How It Works
+
+```
+┌─────────────┐         WebRTC (P2P)         ┌─────────────┐
+│   Desktop   │◄──────────────────────────────►│   Mobile    │
+│   (IDE)     │     Encrypted Data Stream      │   Device    │
+│             │                                │             │
+│  MCP Server │         Signaling              │  Web App    │
+└─────────────┘◄──────────────────────────────►└─────────────┘
+                  (WebSocket + Redis)
+```
+
+1. **Desktop**: MCP server starts, generates pairing code
+2. **Mobile**: User enters code on web app
+3. **Signaling**: Server facilitates WebRTC handshake
+4. **P2P Connection**: Direct peer-to-peer connection established
+5. **Data Flow**: Commands/results flow directly (no server middleman)
+
+---
+
+## IDE Configuration
+
+The `init` command automatically configures supported IDEs:
+
+### Cursor
+```json
+~/.cursor/mcp.json
+```
+
+### Windsurf
+```json
+~/.codeium/windsurf/mcp_config.json
+```
+
+### VSCode
+```json
+~/.vscode/mcp.json
+```
+
+Manual configuration example:
+
+```json
+{
+  "mcpServers": {
+    "mobile-coder": {
+      "command": "npx",
+      "args": ["mobilecoder-mcp", "start", "--code", "YOUR_CODE", "--signaling", "https://api.mobilecoder.xyz/api"],
+      "env": {
+        "MCP_CONNECTION_CODE": "YOUR_CODE",
+        "MCP_SIGNALING_URL": "https://api.mobilecoder.xyz/api"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Security
+
+### End-to-End Encryption
+
+- **DTLS 1.2/1.3**: All WebRTC media encrypted
+- **HMAC-SHA256**: Message integrity verification
+- **SDP Validation**: Malicious payload prevention
+- **Nonce Tracking**: Replay attack protection
+
+### Data Privacy
+
+- **No Server Storage**: Signaling only, no message logging
+- **P2P Architecture**: Data flows directly between devices
+- **Ephemeral Keys**: Session-specific encryption keys
+
+### Best Practices
+
+1. **Use HTTPS**: Always in production (enforced by default)
+2. **Secure Codes**: Connection codes expire after 5 minutes
+3. **Rate Limiting**: Signaling endpoints protected
+4. **CORS Whitelist**: Only authorized origins allowed
+
+---
+
+## Troubleshooting
+
+### Connection Issues
+
+**Problem**: "Connection timeout" or "Cannot connect to signaling server"
+
+**Solutions**:
+- Check internet connection on both devices
+- Verify `MCP_SIGNALING_URL` is correct
+- Ensure signaling server is running: `curl https://api.mobilecoder.xyz/api/health`
+
+### WebRTC Handshake Fails
+
+**Problem**: "ICE connection failed" or "No remote candidate"
+
+**Solutions**:
+- Check firewall settings (UDP ports 3478, 5349)
+- Verify TURN server is accessible
+- Try different network (disable VPN if needed)
+
+### Code Already in Use
+
+**Problem**: "Connection code is already in use"
+
+**Solution**:
+- Wait 2 minutes for code to expire
+- Or generate new code: `mobilecoder-mcp init`
+
+---
+
+## Development
+
+### Build from Source
+
+```bash
+git clone https://github.com/hasmetdurak/mobilecoder-mcp.git
+cd mobilecoder-mcp/mcp-server
+npm install
+npm run build
+npm link
+```
+
+### Run in Development Mode
+
+```bash
+npm run dev  # Watch mode with auto-rebuild
+```
+
+### Run Debug Mode
+
+```bash
+mobilecoder-mcp init --debug
+```
+
+---
+
+## Architecture
+
+### MCP Server
+
+```
+mcp-server/
+├── src/
+│   ├── index.ts          # CLI entry point
+│   ├── agent.ts          # Universal MCP agent
+│   ├── webrtc.ts         # WebRTC connection manager
+│   ├── security.ts       # HMAC & validation
+│   ├── mcp-handler.ts    # MCP tool handlers
+│   ├── tool-detector.ts  # IDE tool detection
+│   └── adapters/
+│       └── cli-adapter.ts # CLI-specific adapters
+├── dist/                 # Compiled JavaScript
+└── package.json
+```
+
+### Dependencies
+
+- `@modelcontextprotocol/sdk` - MCP protocol implementation
+- `simple-peer` - WebRTC wrapper for Node.js
+- `@roamhq/wrtc` - Native WebRTC bindings
+- `commander` - CLI framework
+- `qrcode-terminal` - Terminal QR codes
+
+---
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## License
+
+MIT License - see LICENSE file for details
+
+---
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/hasmetdurak/mobilecoder-mcp/issues)
+- **Web App**: [https://mobilecoder.xyz](https://mobilecoder.xyz)
+- **API Docs**: [https://api.mobilecoder.xyz](https://api.mobilecoder.xyz)
+
+---
+
+## Acknowledgments
+
+Built with:
+- [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
+- [Simple Peer](https://github.com/feross/simple-peer)
+- [WebRTC](https://webrtc.org/)
+
+---
+
+**Version**: 1.0.2 | **Author**: @hasmetdurak | **License**: MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobilecoder-mcp",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "description": "MCP server for MobileCoderMCP - enables mobile to desktop coding",
   "main": "dist/index.js",