@bazaar.ai/mcp-human-agents 0.1.0

package/.env.example

@@ -0,0 +1,15 @@
+# Platform API
+PLATFORM_API_URL=http://localhost:3000
+PLATFORM_API_KEY=your-api-key-here
+
+# VM Configuration
+VM_EXTERNAL_IP=auto  # "auto" to detect, or set explicitly
+
+# Behavior
+POLL_INTERVAL_MS=3000
+POLL_TIMEOUT_MS=300000
+CLEANUP_WARNING_SECONDS=30
+USE_MOCK_PLATFORM=true  # Set to true for local development without platform
+
+# State Persistence
+STATE_FILE_PATH=/var/lib/human-agents/state.json

package/README.md

@@ -0,0 +1,178 @@
+# Bazaar MCP Server
+
+The MCP server that lets an AI agent (Claude Code, etc.) **summon a real
+human contractor** when it gets stuck. Posts a gig to the Bazaar
+platform, waits for a contractor to be matched, provisions their
+access, and opens a reverse tunnel so the contractor can connect via
+the web terminal — no ngrok or public IP needed.
+
+---
+
+## Quick Setup (3 steps)
+
+### 1. Sign up & get an API key
+
+1. Create an account on the Bazaar dashboard
+2. Go to **API Keys** in the sidebar and click **Create Key**
+3. Copy the key (`bzr_live_...`) — you won't see it again
+
+### 2. Run the setup script
+
+```bash
+npx @bazaar.ai/mcp-human-agents --setup --api-key=bzr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+The setup script will:
+- Check for prerequisites (sshd, tmux, git) and offer to install them
+- Validate your API key against the platform
+- Configure sudo permissions for contractor provisioning
+- Register the MCP server with Claude Code
+
+### 3. Restart Claude Code
+
+Restart Claude Code so the new MCP server is picked up. Verify with:
+
+```bash
+claude mcp list
+# → bazaar    npx @bazaar.ai/mcp-human-agents
+```
+
+That's it. Ask Claude to _"summon a human contractor"_ and the platform
+handles matching, provisioning, and connectivity automatically.
+
+---
+
+## How It Works
+
+```
+Developer Machine                        Bazaar Platform
+├── Claude Code                          ├── human-layer API
+│   └── bazaar MCP server               │   ├── gig matching
+│       ├── creates local user           │   ├── ephemeral SSH keys
+│       ├── configures SSH + tmux        │   └── web terminal relay
+│       └── opens reverse tunnel ─────►  │
+│                                        └── Dashboard
+Contractor (anywhere)                        ├── gig notifications
+└── Browser ─► web terminal ─────────────────┘
+```
+
+1. Claude Code calls `summon_human` → MCP server creates a gig on the platform
+2. Platform auto-matches an available contractor
+3. MCP server provisions a Linux user, SSH key, and tmux session locally
+4. MCP server opens a **reverse WebSocket tunnel** back to the platform
+5. Contractor opens the web terminal in the dashboard
+6. Terminal traffic flows: browser → platform → tunnel → local sshd
+7. When done, Claude calls `dismiss_human` → cleanup + tunnel close
+
+### MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `summon_human` | Post a gig, match a contractor, provision access |
+| `dismiss_human` | Revoke access, optionally merge changes, report completion |
+| `list_humans` | List active contractors on this machine |
+| `message_human` | Send a message to a contractor's tmux session |
+
+---
+
+## Configuration
+
+The setup script handles configuration automatically. For reference,
+these are the environment variables used:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PLATFORM_API_URL` | `http://localhost:3000` | Bazaar platform API endpoint |
+| `PLATFORM_API_KEY` | _(required)_ | Your Bazaar API key |
+| `USE_MOCK_PLATFORM` | `false` | Set `true` for offline testing with mock data |
+| `TUNNEL_ENABLED` | `true` | Reverse tunnel mode (no ngrok needed) |
+| `PROVISIONING_USE_SUDO` | `false` | Use sudo for privileged commands |
+| `VM_EXTERNAL_IP` | `auto` | Only needed when `TUNNEL_ENABLED=false` |
+| `VM_EXTERNAL_SSH_PORT` | `22` | Only needed when `TUNNEL_ENABLED=false` |
+| `PLATFORM_PROJECT_ID` | _(auto)_ | Auto-created on first gig if omitted |
+| `POLL_TIMEOUT_MS` | `300000` | Max wait for contractor matching (5 min) |
+| `STATE_FILE_PATH` | `/var/lib/human-agents/state.json` | Crash recovery state |
+
+---
+
+## Advanced: Manual Setup
+
+If you prefer to configure everything manually instead of using the
+setup script:
+
+### 1. Install prerequisites
+
+```bash
+sudo apt-get update
+sudo apt-get install -y openssh-server tmux git curl
+sudo service ssh start
+```
+
+### 2. Configure sudoers (if not running as root)
+
+Replace `<youruser>` with your username (`whoami`):
+
+```bash
+sudo tee /etc/sudoers.d/bazaar-mcp >/dev/null <<'EOF'
+<youruser> ALL=(root)        NOPASSWD: /usr/sbin/useradd, /usr/sbin/userdel, /usr/sbin/usermod, /usr/bin/pkill
+<youruser> ALL=(root)        NOPASSWD: /usr/sbin/sshd, /bin/systemctl reload sshd, /bin/systemctl reload ssh, /usr/sbin/service ssh reload
+<youruser> ALL=(root)        NOPASSWD: /usr/bin/tee, /bin/chmod, /bin/chown, /bin/cp, /bin/mkdir
+<youruser> ALL=(ALL:ALL)     NOPASSWD: /usr/bin/tmux
+EOF
+sudo chmod 0440 /etc/sudoers.d/bazaar-mcp
+sudo visudo -c    # Must print "parsed OK"
+```
+
+### 3. Register with Claude Code
+
+```bash
+claude mcp add bazaar \
+  -e PLATFORM_API_URL=http://localhost:3000 \
+  -e PLATFORM_API_KEY=bzr_live_xxxx \
+  -e USE_MOCK_PLATFORM=false \
+  -e TUNNEL_ENABLED=true \
+  -e PROVISIONING_USE_SUDO=true \
+  -- npx @bazaar.ai/mcp-human-agents
+```
+
+### 4. Legacy direct-SSH mode (no tunnel)
+
+If you need contractors to SSH directly (e.g., for debugging), disable
+the tunnel and provide a public endpoint:
+
+```bash
+claude mcp add bazaar \
+  -e PLATFORM_API_URL=http://localhost:3000 \
+  -e PLATFORM_API_KEY=bzr_live_xxxx \
+  -e USE_MOCK_PLATFORM=false \
+  -e TUNNEL_ENABLED=false \
+  -e VM_EXTERNAL_IP=0.tcp.ngrok.io \
+  -e VM_EXTERNAL_SSH_PORT=17832 \
+  -e PROVISIONING_USE_SUDO=true \
+  -- npx @bazaar.ai/mcp-human-agents
+```
+
+---
+
+## Troubleshooting
+
+**`sudo: a password is required`**
+The sudoers file isn't being read. Run `sudo visudo -c` and check that
+`/etc/sudoers.d/bazaar-mcp` exists and has mode `0440`.
+
+**`tmux: server failed to start`**
+The contractor user's home directory may not exist. The MCP server runs
+`useradd -m` which creates it. If you're seeing this, something is
+wrong with your distro's `useradd` defaults.
+
+**Polling times out**
+No contractor is available, or the matching service isn't running.
+Check the platform logs for `autoMatch` messages.
+
+**Tunnel WebSocket keeps reconnecting**
+Check that the platform API is reachable from your machine. The tunnel
+client auto-reconnects with backoff on connection drops.
+
+**`useradd: user '<name>' already exists`**
+Leftover from a previous gig. Run `sudo userdel -r <name>` manually,
+or call `dismiss_human` to clean up properly.

package/dist/mcp-server/src/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/mcp-server/src/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../../src/bin.ts"],"names":[],"mappings":""}

package/dist/mcp-server/src/bin.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+if (process.argv.includes("--setup")) {
+    import("./cli/setup.js").then((m) => m.runSetup());
+}
+else {
+    import("./index.js");
+}
+//# sourceMappingURL=bin.js.map

package/dist/mcp-server/src/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../../src/bin.ts"],"names":[],"mappings":";;;AAEA,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;IACrC,MAAM,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;AACrD,CAAC;KAAM,CAAC;IACN,MAAM,CAAC,YAAY,CAAC,CAAC;AACvB,CAAC"}

package/dist/mcp-server/src/cli/setup.d.ts

@@ -0,0 +1,2 @@
+export declare function runSetup(): Promise<void>;
+//# sourceMappingURL=setup.d.ts.map

package/dist/mcp-server/src/cli/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../../src/cli/setup.ts"],"names":[],"mappings":"AAyNA,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAmG9C"}

package/dist/mcp-server/src/cli/setup.js

@@ -0,0 +1,274 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSetup = runSetup;
+const promises_1 = require("node:readline/promises");
+const node_child_process_1 = require("node:child_process");
+const node_process_1 = require("node:process");
+// TEMPORARY: ngrok tunnel for early testing. Replace with production URL
+// (e.g. https://api.bazaar.ai) before public launch.
+const PLATFORM_API_URL_DEFAULT = "https://ingrid-hypocycloidal-kaliyah.ngrok-free.dev";
+// ── Helpers ──────────────────────────────────────────────────────────
+function log(msg) {
+    node_process_1.stderr.write(`${msg}\n`);
+}
+function success(msg) {
+    node_process_1.stderr.write(`\x1b[32m✓\x1b[0m ${msg}\n`);
+}
+function warn(msg) {
+    node_process_1.stderr.write(`\x1b[33m!\x1b[0m ${msg}\n`);
+}
+function fail(msg) {
+    node_process_1.stderr.write(`\x1b[31m✗\x1b[0m ${msg}\n`);
+}
+function run(cmd, opts) {
+    const result = (0, node_child_process_1.execSync)(cmd, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"], ...opts });
+    return String(result).trim();
+}
+function canRun(cmd) {
+    try {
+        run(cmd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ── Setup Steps ──────────────────────────────────────────────────────
+async function checkClaude() {
+    if (canRun("claude --version")) {
+        success("Claude Code CLI found");
+        return true;
+    }
+    fail("Claude Code CLI not found. Install it first: https://docs.anthropic.com/en/docs/claude-code");
+    return false;
+}
+function checkPrereqs() {
+    const required = [
+        { cmd: "sshd -v 2>&1 || true", name: "openssh-server" },
+        { cmd: "which tmux", name: "tmux" },
+        { cmd: "which git", name: "git" },
+    ];
+    const missing = [];
+    for (const { cmd, name } of required) {
+        if (canRun(cmd)) {
+            success(`${name} found`);
+        }
+        else {
+            warn(`${name} not found`);
+            missing.push(name);
+        }
+    }
+    return { missing };
+}
+async function promptApiKey(rl) {
+    // Check CLI args first
+    const keyArg = process.argv.find((a) => a.startsWith("--api-key="));
+    if (keyArg) {
+        const key = keyArg.split("=")[1];
+        if (key && key.startsWith("bzr_live_")) {
+            return key;
+        }
+    }
+    log("");
+    log("You need a Bazaar API key. Get one from the dashboard:");
+    log("  → Go to API Keys in the sidebar, then click Create Key");
+    log("");
+    while (true) {
+        const key = await rl.question("Paste your API key (bzr_live_...): ");
+        const trimmed = key.trim();
+        if (trimmed.startsWith("bzr_live_") && trimmed.length > 20) {
+            return trimmed;
+        }
+        warn("API key should start with 'bzr_live_' — try again");
+    }
+}
+async function promptPlatformUrl(rl) {
+    // Check CLI args
+    const urlArg = process.argv.find((a) => a.startsWith("--platform-url="));
+    if (urlArg) {
+        return urlArg.split("=").slice(1).join("=");
+    }
+    log("");
+    const url = await rl.question(`Platform API URL [${PLATFORM_API_URL_DEFAULT}]: `);
+    return url.trim() || PLATFORM_API_URL_DEFAULT;
+}
+async function validateApiKey(apiKey, platformUrl) {
+    try {
+        const res = await fetch(`${platformUrl}/api/users/me`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (res.ok) {
+            const data = (await res.json());
+            success(`Authenticated as ${data.email || data.name || "user"}`);
+            return true;
+        }
+        fail(`API key validation failed: ${res.status}`);
+        return false;
+    }
+    catch (err) {
+        fail(`Cannot reach platform at ${platformUrl}: ${err}`);
+        return false;
+    }
+}
+async function configureSudoers(rl) {
+    const user = run("whoami");
+    if (user === "root") {
+        success("Running as root — no sudoers configuration needed");
+        return;
+    }
+    log("");
+    log("The MCP server needs sudo access for contractor provisioning");
+    log("(user creation, SSH config, tmux). This writes a NOPASSWD sudoers");
+    log(`rule scoped to specific commands for user '${user}'.`);
+    log("");
+    const answer = await rl.question("Configure sudoers now? [Y/n]: ");
+    if (answer.trim().toLowerCase() === "n") {
+        warn("Skipped sudoers — you'll need to configure this manually or run as root");
+        return;
+    }
+    const sudoersContent = `# Bazaar MCP server — contractor provisioning
+${user} ALL=(root)        NOPASSWD: /usr/sbin/useradd, /usr/sbin/userdel, /usr/sbin/usermod, /usr/bin/pkill
+${user} ALL=(root)        NOPASSWD: /usr/sbin/sshd, /bin/systemctl reload sshd, /bin/systemctl reload ssh, /usr/sbin/service ssh reload
+${user} ALL=(root)        NOPASSWD: /usr/bin/tee, /bin/chmod, /bin/chown, /bin/cp, /bin/mkdir
+${user} ALL=(ALL:ALL)     NOPASSWD: /usr/bin/tmux
+`;
+    try {
+        (0, node_child_process_1.execSync)(`echo '${sudoersContent.replace(/'/g, "'\\''")}' | sudo tee /etc/sudoers.d/bazaar-mcp > /dev/null && sudo chmod 0440 /etc/sudoers.d/bazaar-mcp`, { stdio: "pipe" });
+        // Validate
+        run("sudo visudo -c");
+        success("Sudoers rule installed at /etc/sudoers.d/bazaar-mcp");
+    }
+    catch (err) {
+        warn(`Failed to configure sudoers: ${err}`);
+        warn("You may need to run this manually — see the README");
+    }
+}
+function createStateDir() {
+    try {
+        run("sudo mkdir -p /var/lib/human-agents && sudo chmod 777 /var/lib/human-agents");
+        success("State directory created at /var/lib/human-agents");
+    }
+    catch {
+        warn("Could not create /var/lib/human-agents — state will use fallback");
+    }
+}
+function registerMcpServer(apiKey, platformUrl) {
+    const isRoot = run("whoami") === "root";
+    // Build the env vars for claude mcp add
+    const envFlags = [
+        `-e PLATFORM_API_URL=${platformUrl}`,
+        `-e PLATFORM_API_KEY=${apiKey}`,
+        `-e USE_MOCK_PLATFORM=false`,
+        `-e TUNNEL_ENABLED=true`,
+        isRoot ? "" : `-e PROVISIONING_USE_SUDO=true`,
+    ]
+        .filter(Boolean)
+        .join(" ");
+    // Use npx to run the package (works whether installed locally or globally)
+    const cmd = `claude mcp add bazaar ${envFlags} -- npx -y @bazaar.ai/mcp-human-agents`;
+    try {
+        run(cmd, { stdio: "pipe" });
+        success("MCP server registered with Claude Code");
+        return true;
+    }
+    catch (err) {
+        // If `claude mcp add` isn't available, show the manual command
+        warn("Could not auto-register. Run this manually:");
+        log("");
+        log(`  ${cmd}`);
+        log("");
+        return false;
+    }
+}
+// ── Main ─────────────────────────────────────────────────────────────
+async function runSetup() {
+    const rl = (0, promises_1.createInterface)({ input: node_process_1.stdin, output: node_process_1.stderr });
+    try {
+        log("");
+        log("╔══════════════════════════════════════════╗");
+        log("║       Bazaar MCP Server Setup            ║");
+        log("╚══════════════════════════════════════════╝");
+        log("");
+        // 1. Check Claude CLI
+        const hasClaude = await checkClaude();
+        // 2. Check system prereqs
+        log("");
+        log("Checking system prerequisites...");
+        const { missing } = checkPrereqs();
+        if (missing.length > 0) {
+            log("");
+            const answer = await rl.question(`Install missing packages (${missing.join(", ")})? [Y/n]: `);
+            if (answer.trim().toLowerCase() !== "n") {
+                try {
+                    run(`sudo apt-get update -qq && sudo apt-get install -y ${missing.join(" ")}`, {
+                        stdio: "inherit",
+                    });
+                    success("Packages installed");
+                }
+                catch {
+                    warn("Failed to install packages — please install manually");
+                }
+            }
+        }
+        // 3. Get API key
+        const apiKey = await promptApiKey(rl);
+        // 4. Get platform URL
+        const platformUrl = await promptPlatformUrl(rl);
+        // 5. Validate API key
+        log("");
+        log("Validating API key...");
+        const valid = await validateApiKey(apiKey, platformUrl);
+        if (!valid) {
+            warn("Continuing anyway — you can fix the API key later");
+        }
+        // 6. Configure sudoers
+        await configureSudoers(rl);
+        // 7. Create state directory
+        createStateDir();
+        // 8. Start sshd if not running
+        try {
+            run("pgrep sshd > /dev/null || sudo service ssh start");
+            success("sshd is running");
+        }
+        catch {
+            warn("Could not start sshd — contractor SSH access may not work");
+        }
+        // 9. Register MCP server
+        log("");
+        log("Registering MCP server with Claude Code...");
+        if (hasClaude) {
+            registerMcpServer(apiKey, platformUrl);
+        }
+        else {
+            warn("Claude CLI not found — showing manual command:");
+            log("");
+            const isRoot = run("whoami") === "root";
+            const envFlags = [
+                `-e PLATFORM_API_URL=${platformUrl}`,
+                `-e PLATFORM_API_KEY=${apiKey}`,
+                `-e USE_MOCK_PLATFORM=false`,
+                `-e TUNNEL_ENABLED=true`,
+                isRoot ? "" : `-e PROVISIONING_USE_SUDO=true`,
+            ]
+                .filter(Boolean)
+                .join(" ");
+            log(`  claude mcp add bazaar ${envFlags} -- npx -y @bazaar.ai/mcp-human-agents`);
+            log("");
+        }
+        // Done
+        log("");
+        log("╔══════════════════════════════════════════╗");
+        log("║            Setup Complete!               ║");
+        log("╚══════════════════════════════════════════╝");
+        log("");
+        log("Next steps:");
+        log("  1. Restart Claude Code to load the new MCP server");
+        log('  2. Ask Claude to "summon a human contractor"');
+        log("  3. The contractor connects via the web terminal on the dashboard");
+        log("");
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=setup.js.map

package/dist/mcp-server/src/cli/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../../../src/cli/setup.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/src/config/defaults.d.ts

@@ -0,0 +1,16 @@
+/** Default timeout for shell commands (ms). */
+export declare const EXEC_TIMEOUT_MS = 30000;
+/** How often to poll the platform for contractor assignment (ms). */
+export declare const DEFAULT_POLL_INTERVAL_MS = 3000;
+/** Max time to wait for a contractor to be assigned (ms). */
+export declare const DEFAULT_POLL_TIMEOUT_MS = 300000;
+/** Seconds to warn a contractor before killing their tmux session. */
+export declare const DEFAULT_CLEANUP_WARNING_SECONDS = 30;
+/** Marker comments for sshd_config blocks managed by human-layer. */
+export declare const SSHD_MARKER_PREFIX = "# BEGIN human-layer:";
+export declare const SSHD_MARKER_SUFFIX = "# END human-layer:";
+/** Path to sshd_config. */
+export declare const SSHD_CONFIG_PATH = "/etc/ssh/sshd_config";
+/** tmux session name prefix. */
+export declare const TMUX_SESSION_PREFIX = "hl-";
+//# sourceMappingURL=defaults.d.ts.map

package/dist/mcp-server/src/config/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../../../src/config/defaults.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAE/C,sEAAsE;AACtE,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD,qEAAqE;AACrE,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AACzD,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,2BAA2B;AAC3B,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD,gCAAgC;AAChC,eAAO,MAAM,mBAAmB,QAAQ,CAAC"}

package/dist/mcp-server/src/config/defaults.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TMUX_SESSION_PREFIX = exports.SSHD_CONFIG_PATH = exports.SSHD_MARKER_SUFFIX = exports.SSHD_MARKER_PREFIX = exports.DEFAULT_CLEANUP_WARNING_SECONDS = exports.DEFAULT_POLL_TIMEOUT_MS = exports.DEFAULT_POLL_INTERVAL_MS = exports.EXEC_TIMEOUT_MS = void 0;
+/** Default timeout for shell commands (ms). */
+exports.EXEC_TIMEOUT_MS = 30_000;
+/** How often to poll the platform for contractor assignment (ms). */
+exports.DEFAULT_POLL_INTERVAL_MS = 3_000;
+/** Max time to wait for a contractor to be assigned (ms). */
+exports.DEFAULT_POLL_TIMEOUT_MS = 300_000;
+/** Seconds to warn a contractor before killing their tmux session. */
+exports.DEFAULT_CLEANUP_WARNING_SECONDS = 30;
+/** Marker comments for sshd_config blocks managed by human-layer. */
+exports.SSHD_MARKER_PREFIX = "# BEGIN human-layer:";
+exports.SSHD_MARKER_SUFFIX = "# END human-layer:";
+/** Path to sshd_config. */
+exports.SSHD_CONFIG_PATH = "/etc/ssh/sshd_config";
+/** tmux session name prefix. */
+exports.TMUX_SESSION_PREFIX = "hl-";
+//# sourceMappingURL=defaults.js.map

package/dist/mcp-server/src/config/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../../../src/config/defaults.ts"],"names":[],"mappings":";;;AAAA,+CAA+C;AAClC,QAAA,eAAe,GAAG,MAAM,CAAC;AAEtC,qEAAqE;AACxD,QAAA,wBAAwB,GAAG,KAAK,CAAC;AAE9C,6DAA6D;AAChD,QAAA,uBAAuB,GAAG,OAAO,CAAC;AAE/C,sEAAsE;AACzD,QAAA,+BAA+B,GAAG,EAAE,CAAC;AAElD,qEAAqE;AACxD,QAAA,kBAAkB,GAAG,sBAAsB,CAAC;AAC5C,QAAA,kBAAkB,GAAG,oBAAoB,CAAC;AAEvD,2BAA2B;AACd,QAAA,gBAAgB,GAAG,sBAAsB,CAAC;AAEvD,gCAAgC;AACnB,QAAA,mBAAmB,GAAG,KAAK,CAAC"}

package/dist/mcp-server/src/config/env.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+declare const EnvSchema: z.ZodObject<{
+    PLATFORM_API_URL: z.ZodDefault<z.ZodString>;
+    PLATFORM_API_KEY: z.ZodDefault<z.ZodString>;
+    /**
+     * Hostname or IP the contractor will SSH into. Only needed when
+     * TUNNEL_ENABLED=false (legacy direct-SSH mode). When the dev box is
+     * exposed via `ngrok tcp`, set this to the ngrok host (e.g.
+     * `0.tcp.ngrok.io`). Default `"auto"` triggers cloud metadata + local
+     * network detection.
+     */
+    VM_EXTERNAL_IP: z.ZodDefault<z.ZodString>;
+    /**
+     * Public SSH port. Only needed when TUNNEL_ENABLED=false.
+     */
+    VM_EXTERNAL_SSH_PORT: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Optional explicit project ID to attach gigs to. If unset, the API
+     * will auto-create a default project for the user behind the API key.
+     */
+    PLATFORM_PROJECT_ID: z.ZodOptional<z.ZodString>;
+    POLL_INTERVAL_MS: z.ZodDefault<z.ZodNumber>;
+    POLL_TIMEOUT_MS: z.ZodDefault<z.ZodNumber>;
+    CLEANUP_WARNING_SECONDS: z.ZodDefault<z.ZodNumber>;
+    USE_MOCK_PLATFORM: z.ZodDefault<z.ZodEffects<z.ZodString, boolean, string>>;
+    STATE_FILE_PATH: z.ZodDefault<z.ZodString>;
+    /**
+     * When true, the provisioning code prepends `sudo -n` to privileged
+     * commands. Set this to `true` when the MCP server is NOT running as
+     * root and instead has NOPASSWD sudo for the relevant commands.
+     * See `human-layer/mcp-server/README.md` for the sudoers template.
+     */
+    PROVISIONING_USE_SUDO: z.ZodDefault<z.ZodEffects<z.ZodString, boolean, string>>;
+    /**
+     * When true, the MCP server opens a reverse WebSocket tunnel to the
+     * platform so contractors can connect without ngrok or public IPs.
+     * When false, falls back to legacy direct-SSH mode using
+     * VM_EXTERNAL_IP / VM_EXTERNAL_SSH_PORT.
+     */
+    TUNNEL_ENABLED: z.ZodDefault<z.ZodEffects<z.ZodString, boolean, string>>;
+}, "strip", z.ZodTypeAny, {
+    PLATFORM_API_URL: string;
+    PLATFORM_API_KEY: string;
+    VM_EXTERNAL_IP: string;
+    VM_EXTERNAL_SSH_PORT: number;
+    POLL_INTERVAL_MS: number;
+    POLL_TIMEOUT_MS: number;
+    CLEANUP_WARNING_SECONDS: number;
+    USE_MOCK_PLATFORM: boolean;
+    STATE_FILE_PATH: string;
+    PROVISIONING_USE_SUDO: boolean;
+    TUNNEL_ENABLED: boolean;
+    PLATFORM_PROJECT_ID?: string | undefined;
+}, {
+    PLATFORM_API_URL?: string | undefined;
+    PLATFORM_API_KEY?: string | undefined;
+    VM_EXTERNAL_IP?: string | undefined;
+    VM_EXTERNAL_SSH_PORT?: number | undefined;
+    PLATFORM_PROJECT_ID?: string | undefined;
+    POLL_INTERVAL_MS?: number | undefined;
+    POLL_TIMEOUT_MS?: number | undefined;
+    CLEANUP_WARNING_SECONDS?: number | undefined;
+    USE_MOCK_PLATFORM?: string | undefined;
+    STATE_FILE_PATH?: string | undefined;
+    PROVISIONING_USE_SUDO?: string | undefined;
+    TUNNEL_ENABLED?: string | undefined;
+}>;
+export type Env = z.infer<typeof EnvSchema>;
+export declare function getEnv(): Env;
+/** For testing: override the cached env. */
+export declare function setEnv(env: Env): void;
+export {};
+//# sourceMappingURL=env.d.ts.map

package/dist/mcp-server/src/config/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,QAAA,MAAM,SAAS;;;IAGb;;;;;;OAMG;;IAEH;;OAEG;;IAEH;;;OAGG;;;;;;;IAYH;;;;;OAKG;;IAKH;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKH,CAAC;AAEH,MAAM,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAI5C,wBAAgB,MAAM,IAAI,GAAG,CAK5B;AAED,4CAA4C;AAC5C,wBAAgB,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAErC"}