@hotwired-sh/hotwired-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hotwired-sh
+
+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,147 @@
+# hotwired-mcp
+
+![Hotwired](hotwired-sh.png)
+
+MCP (Model Context Protocol) server for [Hotwired](https://hotwired.sh) multi-agent workflow orchestration.
+
+## Why Open Source?
+
+This MCP server runs on your machine. We open source it so you can:
+
+- **Audit** exactly what code runs on your machine
+- **Verify** there are no external network calls
+- **Trust** that there's no hidden behavior
+- **Build from source** if you prefer
+
+## Hotwired.sh Architecture
+
+**Everything runs locally on your machine.** There are no external service dependencies.
+
+```mermaid
+flowchart TB
+    subgraph agents["AI Coding Agents"]
+        claude["Claude Code"] ~~~ gemini["Gemini CLI"] ~~~ other["Other Agents"]
+    end
+
+    subgraph mcp["hotwired-mcp"]
+        tools["MCP Tools"] --> ipc["IPC Client"]
+    end
+
+    subgraph desktop["Hotwired Desktop App"]
+        socket["Unix Socket<br/>~/.hotwired/hotwired.sock"] <--> core["Hotwired Core"]
+    end
+
+    agents -->|"spawns"| mcp
+    ipc <-->|"local only"| socket
+```
+
+### How it works
+
+1. **Hotwired Desktop App** runs locally and creates a Unix socket at `~/.hotwired/hotwired.sock`
+2. **AI agents** (Claude Code, Gemini, etc.) run `hotwired-mcp` as their MCP server
+3. **hotwired-mcp** communicates with the desktop app via the local Unix socket
+4. **No external network calls** - all communication stays on your machine
+
+The only external connection the Hotwired Desktop App makes is for **authentication**. All workflow orchestration, message passing, and coordination happens entirely locally.
+
+## Installation
+
+### For Claude Code Users
+
+**Just install the [Hotwired Claude Plugin](https://github.com/hotwired-sh/claude-plugin)** - it handles everything automatically:
+
+```bash
+claude plugin install hotwired
+```
+
+The plugin runs `npx @hotwired-sh/hotwired-mcp@latest` under the hood, so you'll always have the latest version. No manual installation needed.
+
+### For Other MCP-Compatible Agents
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "hotwired": {
+      "command": "npx",
+      "args": ["@hotwired-sh/hotwired-mcp@latest"]
+    }
+  }
+}
+```
+
+### Building from Source
+
+If you prefer to audit and build the code yourself:
+
+```bash
+cargo install --git https://github.com/hotwired-sh/hotwired-mcp
+```
+
+## Prerequisites
+
+- [Hotwired Desktop App](https://hotwired.sh) - Must be running
+- [Zellij](https://zellij.dev) - Terminal multiplexer for session management
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_protocol` | Fetch workflow protocol and role instructions |
+| `get_run_status` | Check current run status |
+| `report_status` | Update your working state |
+| `send_message` | Send message to other participants |
+| `request_input` | Ask human for input |
+| `report_impediment` | Signal you're blocked |
+| `handoff` | Hand work to another agent |
+| `task_complete` | Mark a task as complete |
+
+## Security
+
+### Why Unix Sockets (Not HTTP/localhost)
+
+We deliberately use **Unix sockets** instead of HTTP on localhost. This is a critical security design choice.
+
+Many MCP tools have been vulnerable to **DNS rebinding attacks** and **0.0.0.0 bypass exploits** because they expose HTTP servers on localhost. These vulnerabilities allow malicious websites to:
+
+- Send requests to localhost services via DNS rebinding
+- Bypass browser same-origin policy through the 0.0.0.0 loophole
+- Achieve remote code execution with no user interaction
+
+**Unix sockets are immune to these attacks:**
+
+- ❌ No TCP/HTTP listener - browsers cannot connect
+- ❌ No DNS rebinding possible - not a network protocol
+- ❌ No 0.0.0.0 bypass - sockets are filesystem-based
+- ✅ Protected by filesystem permissions
+- ✅ Only local processes can connect
+
+### What This MCP Server Does NOT Do
+
+- **Does NOT open any network ports** - no HTTP, no TCP, no localhost
+- **Does NOT make any external network requests**
+- **Does NOT read or modify files** outside its scope
+- Connects **only** to the local Unix socket (`~/.hotwired/hotwired.sock`)
+- Source code is fully auditable
+
+## Development
+
+```bash
+# Build
+cargo build --release
+
+# Test
+cargo test
+
+# Run locally
+cargo run
+```
+
+## License
+
+MIT - See [LICENSE](LICENSE)
+
+## Learn More
+
+Visit [hotwired.sh](https://hotwired.sh) for documentation, tutorials, and more information about multi-agent workflow orchestration.

package/bin/hotwired-mcp

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const PLATFORMS = {
+  "darwin-arm64": "@hotwired-sh/mcp-darwin-arm64",
+  "darwin-x64": "@hotwired-sh/mcp-darwin-x64",
+  "linux-x64": "@hotwired-sh/mcp-linux-x64",
+  "linux-arm64": "@hotwired-sh/mcp-linux-arm64",
+  "win32-x64": "@hotwired-sh/mcp-win32-x64",
+};
+
+function getBinaryPath() {
+  const platformKey = `${process.platform}-${process.arch}`;
+  const packageName = PLATFORMS[platformKey];
+
+  if (!packageName) {
+    console.error(`Unsupported platform: ${platformKey}`);
+    console.error(`Supported platforms: ${Object.keys(PLATFORMS).join(", ")}`);
+    process.exit(1);
+  }
+
+  // Try to find the binary in node_modules
+  const binaryName = process.platform === "win32" ? "hotwired-mcp.exe" : "hotwired-mcp";
+
+  // Check in the platform package
+  const paths = [
+    // When installed as a dependency
+    path.join(__dirname, "..", "node_modules", packageName, "bin", binaryName),
+    // When installed globally or via npx
+    path.join(__dirname, "..", "node_modules", packageName, "bin", binaryName),
+    // Relative to this package
+    require.resolve(`${packageName}/bin/${binaryName}`),
+  ];
+
+  for (const binPath of paths) {
+    try {
+      if (fs.existsSync(binPath)) {
+        return binPath;
+      }
+    } catch {}
+  }
+
+  // Try require.resolve as last resort
+  try {
+    const pkgPath = require.resolve(`${packageName}/package.json`);
+    const pkgDir = path.dirname(pkgPath);
+    const binPath = path.join(pkgDir, "bin", binaryName);
+    if (fs.existsSync(binPath)) {
+      return binPath;
+    }
+  } catch {}
+
+  console.error(`Could not find binary for platform: ${platformKey}`);
+  console.error(`Expected package: ${packageName}`);
+  process.exit(1);
+}
+
+const binaryPath = getBinaryPath();
+
+try {
+  execFileSync(binaryPath, process.argv.slice(2), {
+    stdio: "inherit",
+  });
+} catch (error) {
+  if (error.status !== null) {
+    process.exit(error.status);
+  }
+  throw error;
+}

package/npm/darwin-arm64/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hotwired-sh/mcp-darwin-arm64",
+  "version": "1.0.0",
+  "description": "hotwired-mcp binary for macOS ARM64",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hotwired-sh/hotwired-mcp.git"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "files": [
+    "bin/hotwired-mcp"
+  ]
+}

package/npm/darwin-x64/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hotwired-sh/mcp-darwin-x64",
+  "version": "1.0.0",
+  "description": "hotwired-mcp binary for macOS x64",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hotwired-sh/hotwired-mcp.git"
+  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "files": [
+    "bin/hotwired-mcp"
+  ]
+}

package/npm/linux-arm64/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hotwired-sh/mcp-linux-arm64",
+  "version": "1.0.0",
+  "description": "hotwired-mcp binary for Linux ARM64",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hotwired-sh/hotwired-mcp.git"
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "files": [
+    "bin/hotwired-mcp"
+  ]
+}

package/npm/linux-x64/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@hotwired-sh/mcp-linux-x64",
+  "version": "1.0.0",
+  "description": "hotwired-mcp binary for Linux x64",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hotwired-sh/hotwired-mcp.git"
+  },
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "files": [
+    "bin/hotwired-mcp"
+  ]
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@hotwired-sh/hotwired-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Hotwired multi-agent workflow orchestration",
+  "author": "Hotwired <hello@hotwired.sh>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hotwired-sh/hotwired-mcp.git"
+  },
+  "homepage": "https://hotwired.sh",
+  "bugs": {
+    "url": "https://github.com/hotwired-sh/hotwired-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "claude",
+    "hotwired",
+    "multi-agent",
+    "workflow"
+  ],
+  "bin": {
+    "hotwired-mcp": "bin/hotwired-mcp"
+  },
+  "files": [
+    "bin",
+    "npm"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "cargo test",
+    "prepare": "husky"
+  },
+  "optionalDependencies": {
+    "@hotwired-sh/mcp-darwin-arm64": "1.0.0",
+    "@hotwired-sh/mcp-darwin-x64": "1.0.0",
+    "@hotwired-sh/mcp-linux-x64": "1.0.0",
+    "@hotwired-sh/mcp-linux-arm64": "1.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.0.0",
+    "@commitlint/config-conventional": "^19.0.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "conventional-changelog-conventionalcommits": "^7.0.2",
+    "husky": "^9.0.0",
+    "semantic-release": "^24.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}