mcp-twin 1.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "name": "prax-tools",
+  "owner": {
+    "name": "nothinginfinity",
+    "email": "nothinginfinity@github.com"
+  },
+  "plugins": [
+    {
+      "name": "mcp-twin",
+      "source": {
+        "source": "url",
+        "url": "https://github.com/nothinginfinity/mcp-twin.git"
+      },
+      "description": "Zero-downtime MCP server updates. Hot-reload your MCP servers without restarting Claude Code.",
+      "version": "1.0.0",
+      "author": {
+        "name": "Prax Labs"
+      },
+      "license": "MIT",
+      "keywords": ["mcp", "hot-reload", "zero-downtime", "developer-tools"]
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 PHI Labs
+
+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/PLUGIN_SPEC.md

@@ -0,0 +1,388 @@
+# MCP Twin Plugin - Claude Marketplace Spec
+
+> Zero-downtime MCP server updates for Claude Code developers
+
+---
+
+## Plugin Metadata
+
+```json
+{
+  "name": "mcp-twin",
+  "displayName": "MCP Twin - Hot Reload",
+  "version": "1.0.0",
+  "description": "Zero-downtime updates for MCP servers. No more restarting Claude Code when you change server code.",
+  "author": "Prax Labs",
+  "repository": "github.com/nothinginfinity/mcp-twin",
+  "keywords": ["mcp", "hot-reload", "development", "zero-downtime"],
+  "license": "MIT"
+}
+```
+
+---
+
+## Value Proposition
+
+### The Problem
+Every time you edit an MCP server, you have to:
+1. Stop Claude Code
+2. Restart the MCP server
+3. Restart Claude Code
+4. Lose your conversation context
+
+**Pain level**: High for active MCP developers (5-20 restarts/day)
+
+### The Solution
+Twin servers running simultaneously:
+- Edit code → Reload standby → Swap traffic
+- Claude Code stays connected
+- Zero context loss
+
+---
+
+## Plugin Structure
+
+```
+mcp-twin-plugin/
+├── package.json
+├── README.md
+├── src/
+│   ├── index.ts              # Plugin entry point
+│   ├── twin-manager.ts       # Core MCPTwinManager (port from Python)
+│   ├── config-detector.ts    # Auto-detect MCP servers from claude config
+│   ├── file-watcher.ts       # Watch for server file changes
+│   └── ui/
+│       └── status-panel.ts   # Status display components
+├── skills/
+│   └── mcp-twin.md           # Skill definition
+├── hooks/
+│   └── on-file-change.ts     # Auto-reload hook
+└── commands/
+    ├── twin-start.ts
+    ├── twin-stop.ts
+    ├── twin-reload.ts
+    ├── twin-swap.ts
+    └── twin-status.ts
+```
+
+---
+
+## Slash Commands
+
+### `/twin start [server]`
+```
+Start twin servers for an MCP server.
+
+Usage:
+  /twin start                  # Interactive: pick from detected servers
+  /twin start inbox-collab     # Start specific server twins
+
+Output:
+  ✓ Started twins for inbox-collab
+    Active:  port 8101 (PID 12345)
+    Standby: port 8102 (PID 12346)
+
+  Tip: Edit your server code, then run /twin reload
+```
+
+### `/twin reload [server]`
+```
+Reload standby server with updated code.
+
+Usage:
+  /twin reload inbox-collab
+
+Output:
+  ✓ Reloaded standby (port 8102)
+    Health check: passed
+    Ready to swap
+
+  Run /twin swap inbox-collab to switch traffic
+```
+
+### `/twin swap [server]`
+```
+Switch traffic to the standby server.
+
+Usage:
+  /twin swap inbox-collab
+
+Output:
+  ✓ Swapped inbox-collab
+    Previous: port 8101
+    Now active: port 8102
+
+  Your code changes are now live!
+```
+
+### `/twin status`
+```
+Show status of all twin servers.
+
+Output:
+  MCP Twin Status
+  ═══════════════════════════════════════
+
+  inbox-collab
+    Active:  A (port 8101) ● healthy
+    Standby: B (port 8102) ● healthy
+    Swaps: 3 | Last: 2 min ago
+
+  phi-proxy
+    Active:  B (port 8104) ● healthy
+    Standby: A (port 8103) ● healthy
+    Swaps: 1 | Last: 15 min ago
+
+  Available: zti-server, fsl-compression
+```
+
+### `/twin stop [server]`
+```
+Stop twin servers.
+
+Usage:
+  /twin stop inbox-collab
+  /twin stop --all
+
+Output:
+  ✓ Stopped inbox-collab twins
+    Killed PID 12345, 12346
+```
+
+---
+
+## Auto-Detection Feature
+
+### Read from claude_desktop_config.json
+```typescript
+// config-detector.ts
+
+interface MCPServerConfig {
+  name: string;
+  command: string;
+  args: string[];
+  scriptPath: string;  // Extracted from command/args
+}
+
+function detectMCPServers(): MCPServerConfig[] {
+  const configPath = path.join(
+    os.homedir(),
+    'Library/Application Support/Claude/claude_desktop_config.json'
+  );
+
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+
+  return Object.entries(config.mcpServers).map(([name, cfg]) => ({
+    name,
+    command: cfg.command,
+    args: cfg.args,
+    scriptPath: extractScriptPath(cfg)
+  }));
+}
+```
+
+### Auto-Assign Ports
+```typescript
+function assignPorts(serverName: string): [number, number] {
+  // Hash server name to deterministic port range
+  const hash = hashCode(serverName);
+  const basePort = 8100 + (hash % 100) * 2;
+  return [basePort, basePort + 1];
+}
+```
+
+---
+
+## File Watcher Hook (Premium Feature)
+
+### Auto-Reload on Save
+```typescript
+// hooks/on-file-change.ts
+
+import { watch } from 'chokidar';
+
+export function setupFileWatcher(twinManager: TwinManager) {
+  const servers = twinManager.getRunningServers();
+
+  for (const server of servers) {
+    watch(server.scriptPath).on('change', async (path) => {
+      console.log(`[MCP Twin] Detected change in ${path}`);
+
+      // Auto-reload standby
+      await twinManager.reloadStandby(server.name);
+
+      // Prompt user
+      const shouldSwap = await askUser(
+        `${server.name} updated. Swap to new version?`,
+        ['Yes, swap now', 'No, keep current']
+      );
+
+      if (shouldSwap) {
+        await twinManager.swap(server.name);
+      }
+    });
+  }
+}
+```
+
+---
+
+## Skill Definition
+
+```markdown
+# /skills/mcp-twin.md
+
+name: mcp-twin
+description: Manage MCP server twins for zero-downtime development
+triggers:
+  - /twin
+  - hot reload mcp
+  - restart mcp server
+  - mcp twin
+
+instructions: |
+  You help developers manage MCP server twins for zero-downtime updates.
+
+  Available commands:
+  - /twin start [server] - Start twin servers
+  - /twin reload [server] - Reload standby with new code
+  - /twin swap [server] - Switch traffic to standby
+  - /twin status - Show all twins
+  - /twin stop [server] - Stop twins
+
+  When user edits an MCP server file, suggest:
+  1. /twin reload to update standby
+  2. /twin swap to switch traffic
+
+  Always show clear status after operations.
+```
+
+---
+
+## Freemium Model
+
+### Free Tier
+- `/twin start` - Start twins (max 2 servers)
+- `/twin stop` - Stop twins
+- `/twin status` - View status
+- `/twin swap` - Manual swap
+- `/twin reload` - Manual reload
+
+### Prax Chat Pro (Coming Soon)
+- Unlimited servers
+- **Auto-reload on file save**
+- **Auto-swap option**
+- Health dashboard
+- Swap history & rollback
+- Slack/Discord notifications
+- Team sharing (shared twin configs)
+
+### Upsell Prompts
+```
+Free user runs /twin reload for 5th time today:
+
+"You're on fire today! 🔥
+
+ 5 reloads and counting. Prax Chat Pro coming soon
+ with auto-reload on save.
+
+ [Notify Me] [Maybe Later]"
+```
+
+---
+
+## Installation
+
+### For Users
+```bash
+# Via Claude Code
+/install mcp-twin
+
+# Or manually
+git clone github.com/phi-labs/mcp-twin ~/.claude/plugins/mcp-twin
+```
+
+### First Run
+```
+Welcome to MCP Twin! 🔄
+
+I detected these MCP servers in your config:
+  1. inbox-collab (/Users/you/mcp-servers/inbox/server.py)
+  2. my-api-server (/Users/you/projects/api/mcp_server.py)
+
+Would you like to enable twins for these servers?
+  [Yes, all] [Select specific] [Skip for now]
+```
+
+---
+
+## Marketing Copy
+
+### One-Liner
+> "Hot reload your MCP servers without restarting Claude Code"
+
+### Elevator Pitch
+> Every MCP developer knows the pain: edit server code, restart everything,
+> lose your conversation. MCP Twin fixes this with blue-green deployments
+> for your dev environment. Edit, reload, swap - zero downtime, zero context loss.
+
+### README Hero
+```
+# MCP Twin 🔄
+
+Stop restarting Claude Code every time you change your MCP server.
+
+## Before MCP Twin
+1. Edit server.py
+2. Cmd+C to stop Claude Code
+3. Restart MCP server
+4. Restart Claude Code
+5. Lose conversation context
+6. Repeat 10x/day 😫
+
+## After MCP Twin
+1. Edit server.py
+2. /twin reload && /twin swap
+3. Keep working ✨
+
+[Install Now] [View Demo]
+```
+
+---
+
+## Technical Notes
+
+### Port Allocation Strategy
+- Base port: 8100
+- Each server gets 2 consecutive ports
+- Stored in `~/.mcp-twin/ports.json` to avoid conflicts
+
+### Health Checks
+- TCP socket check for HTTP servers
+- Process alive check for stdio MCP servers
+- Configurable timeout (default 2s)
+
+### State Persistence
+- `~/.mcp-twin/state.json` - Running twins, active server, swap history
+- Survives Claude Code restarts
+- Auto-cleanup of stale PIDs on startup
+
+---
+
+## Roadmap
+
+### v1.0 (Launch)
+- [x] Core twin management
+- [x] Slash commands
+- [x] Auto-detect MCP servers
+- [ ] Basic status UI
+
+### v1.1
+- [ ] File watcher (Pro)
+- [ ] Auto-swap option
+- [ ] Rollback to previous
+
+### v2.0
+- [ ] Web dashboard
+- [ ] Team configs
+- [ ] CI/CD integration (deploy to twins in production)