poke-gate 0.0.1

package/README.md

@@ -0,0 +1,107 @@
+# poke-gate
+
+Expose your machine to your [Poke](https://poke.com) AI assistant via MCP tunnel.
+
+Run `poke-gate` on your machine, then ask Poke from iMessage, Telegram, or SMS to run commands, read files, check system status — anything you'd do in a terminal.
+
+## Quick start
+
+```bash
+npx poke-gate
+```
+
+On first run, you'll paste your API key from [poke.com/kitchen/api-keys](https://poke.com/kitchen/api-keys).
+
+## How it works
+
+```mermaid
+flowchart TD
+    A["You message Poke\nfrom iMessage / Telegram / SMS"] --> B["Poke Agent"]
+    B --> C["Agent calls MCP tool"]
+    C --> D["MCP Tunnel (WebSocket)"]
+    D --> E["poke-gate on your machine"]
+    E --> F["Runs command / reads file / etc."]
+    F --> D
+    D --> B
+    B --> A
+```
+
+poke-gate runs a local MCP server and tunnels it to Poke's cloud. When you ask Poke something that needs your machine, the agent calls the tools, poke-gate executes them locally, and the result flows back to your chat.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `run_command` | Execute any shell command (ls, git, brew, python, curl, etc.) |
+| `read_file` | Read a file's contents |
+| `write_file` | Write content to a file |
+| `list_directory` | List files and directories |
+| `system_info` | OS, hostname, architecture, uptime, memory |
+
+## Examples
+
+From iMessage/Telegram, ask Poke:
+
+- "What's running on port 3000?"
+- "Show me the last 5 git commits in my project"
+- "How much disk space do I have left?"
+- "Read my ~/.zshrc and suggest improvements"
+- "Create a new file called notes.txt with today's meeting notes"
+- "Run the tests in my project"
+
+## Setup
+
+### Option 1: Interactive (recommended)
+
+```bash
+npx poke-gate
+```
+
+### Option 2: Environment variable
+
+```bash
+export POKE_API_KEY=your_key_here
+npx poke-gate
+```
+
+## Security
+
+**poke-gate grants full shell access to your Poke agent.** This means:
+
+- Any command can be run with your user's permissions
+- Files can be read and written anywhere your user has access
+- Only your Poke agent (authenticated by your API key) can reach the tunnel
+
+Only run poke-gate on machines and networks you trust. Stop it with `Ctrl-C` when you don't need it.
+
+## Configuration
+
+Config is stored at `~/.config/poke-gate/config.json`:
+
+```json
+{
+  "apiKey": "your_key_here"
+}
+```
+
+To reset, delete the file and run `npx poke-gate` again.
+
+## Project structure
+
+```
+bin/
+  poke-gate.js       Entry point, onboarding
+src/
+  app.js             Startup: MCP server + tunnel
+  mcp-server.js      JSON-RPC MCP handler with OS tools
+  tunnel.js          PokeTunnel wrapper
+```
+
+## Credits
+
+- [Poke](https://poke.com) by [The Interaction Company of California](https://interaction.co)
+- [Poke SDK](https://www.npmjs.com/package/poke)
+
+## License
+
+MIT

package/bin/poke-gate.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+
+const CONFIG_DIR = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+const CONFIG_PATH = join(CONFIG_DIR, "poke-gate", "config.json");
+
+function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function saveConfig(config) {
+  mkdirSync(join(CONFIG_DIR, "poke-gate"), { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+}
+
+function resolveToken() {
+  if (process.env.POKE_API_KEY) return process.env.POKE_API_KEY;
+  const config = loadConfig();
+  if (config.apiKey) return config.apiKey;
+  return null;
+}
+
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function onboarding() {
+  console.log();
+  console.log("  poke-gate — expose your machine to Poke");
+  console.log();
+  console.log("  Your Poke agent will be able to run commands,");
+  console.log("  read/write files, and access system info on this machine.");
+  console.log();
+  console.log("  ⚠  This grants full shell access. Only run on trusted networks.");
+  console.log();
+  console.log("  To get started, you need a Poke API key:");
+  console.log();
+  console.log("  1. Go to https://poke.com/kitchen/api-keys");
+  console.log("  2. Generate a new key");
+  console.log("  3. Paste it below");
+  console.log();
+
+  const key = await ask("  API key: ");
+
+  if (!key) {
+    console.log();
+    console.log("  No key provided. Set it later:");
+    console.log("    export POKE_API_KEY=your_key_here");
+    console.log();
+    process.exit(1);
+  }
+
+  saveConfig({ apiKey: key });
+  console.log();
+  console.log("  Saved! Starting poke-gate...");
+  console.log();
+
+  return key;
+}
+
+async function main() {
+  let token = resolveToken();
+
+  if (!token) {
+    token = await onboarding();
+  }
+
+  process.env.POKE_API_KEY = token;
+  await import("../src/app.js");
+}
+
+main();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "poke-gate",
+  "version": "0.0.1",
+  "description": "Expose your machine to your Poke AI assistant via MCP tunnel",
+  "type": "module",
+  "bin": {
+    "poke-gate": "./bin/poke-gate.js"
+  },
+  "scripts": {
+    "start": "node src/app.js"
+  },
+  "keywords": [
+    "poke",
+    "mcp",
+    "tunnel",
+    "shell",
+    "terminal",
+    "ai",
+    "cli",
+    "remote",
+    "os"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "poke": "^0.4.2"
+  }
+}

package/src/app.js

@@ -0,0 +1,82 @@
+import { startMcpServer } from "./mcp-server.js";
+import { startTunnel } from "./tunnel.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+function resolveToken() {
+  if (process.env.POKE_API_KEY) return process.env.POKE_API_KEY;
+
+  const configDir = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+
+  try {
+    const cfg = JSON.parse(readFileSync(join(configDir, "poke-gate", "config.json"), "utf-8"));
+    if (cfg.apiKey) return cfg.apiKey;
+  } catch {}
+
+  return null;
+}
+
+function log(msg) {
+  const ts = new Date().toISOString().slice(11, 19);
+  console.log(`[${ts}] ${msg}`);
+}
+
+const API_KEY = resolveToken();
+
+if (!API_KEY) {
+  console.error("No credentials found. Run: npx poke-gate");
+  process.exit(1);
+}
+
+async function main() {
+  log("poke-gate starting...");
+
+  const { port } = await startMcpServer();
+  log(`MCP server on port ${port}`);
+
+  const mcpUrl = `http://localhost:${port}/mcp`;
+
+  log("Connecting tunnel to Poke...");
+  try {
+    const { info } = await startTunnel({
+      apiKey: API_KEY,
+      mcpUrl,
+      onEvent: (type, data) => {
+        switch (type) {
+          case "connected":
+            log(`Tunnel connected (${data.connectionId})`);
+            log("Ready — your Poke agent can now access this machine.");
+            break;
+          case "disconnected":
+            log("Tunnel disconnected. Reconnecting...");
+            break;
+          case "error":
+            log(`Tunnel error: ${data}`);
+            break;
+          case "tools-synced":
+            log(`Tools synced: ${data}`);
+            break;
+          case "oauth-required":
+            log(`OAuth required: ${data}`);
+            break;
+        }
+      },
+    });
+  } catch (err) {
+    log(`Failed to connect: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+process.on("SIGINT", () => {
+  log("Shutting down...");
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  log("Shutting down...");
+  process.exit(0);
+});
+
+main();

package/src/mcp-server.js

@@ -0,0 +1,267 @@
+import http from "node:http";
+import { execSync, exec } from "node:child_process";
+import { readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { hostname, platform, arch, uptime, totalmem, freemem, homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+const SERVER_INFO = { name: "poke-gate", version: "0.0.1" };
+
+const COMMAND_TIMEOUT = 30_000;
+
+const TOOLS = [
+  {
+    name: "run_command",
+    description:
+      "Execute a shell command on the user's machine and return stdout, stderr, and exit code. " +
+      "Use this to run any CLI command (ls, cat, git, brew, python, curl, etc.). " +
+      "Commands run in a shell with a 30-second timeout.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "The shell command to execute" },
+        cwd: { type: "string", description: "Working directory (optional, defaults to home)" },
+      },
+      required: ["command"],
+    },
+  },
+  {
+    name: "read_file",
+    description: "Read the contents of a file on the user's machine.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute or relative path to the file" },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "write_file",
+    description: "Write content to a file on the user's machine. Creates the file if it doesn't exist, overwrites if it does.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute or relative path to the file" },
+        content: { type: "string", description: "Content to write" },
+      },
+      required: ["path", "content"],
+    },
+  },
+  {
+    name: "list_directory",
+    description: "List files and directories at a given path on the user's machine.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory path (defaults to home)" },
+      },
+    },
+  },
+  {
+    name: "system_info",
+    description: "Get system information: OS, hostname, architecture, uptime, memory, and home directory.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+function runCommand(command, cwd) {
+  return new Promise((res) => {
+    const dir = cwd || homedir();
+    const child = exec(command, {
+      cwd: dir,
+      timeout: COMMAND_TIMEOUT,
+      maxBuffer: 1024 * 1024,
+      shell: true,
+    }, (error, stdout, stderr) => {
+      res({
+        stdout: stdout.slice(0, 50_000),
+        stderr: stderr.slice(0, 10_000),
+        exitCode: error ? (error.code ?? 1) : 0,
+      });
+    });
+  });
+}
+
+function handleToolCall(name, args) {
+  switch (name) {
+    case "run_command": {
+      return runCommand(args.command, args.cwd).then((result) => ({
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      }));
+    }
+
+    case "read_file": {
+      try {
+        const p = resolve(args.path.replace(/^~/, homedir()));
+        const text = readFileSync(p, "utf-8");
+        return { content: [{ type: "text", text: text.slice(0, 100_000) }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+      }
+    }
+
+    case "write_file": {
+      try {
+        const p = resolve(args.path.replace(/^~/, homedir()));
+        writeFileSync(p, args.content);
+        return { content: [{ type: "text", text: `Written to ${p}` }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+      }
+    }
+
+    case "list_directory": {
+      try {
+        const dir = resolve((args.path || "~").replace(/^~/, homedir()));
+        const entries = readdirSync(dir).map((name) => {
+          try {
+            const s = statSync(join(dir, name));
+            return `${s.isDirectory() ? "d" : "-"} ${name}`;
+          } catch {
+            return `? ${name}`;
+          }
+        });
+        return { content: [{ type: "text", text: entries.join("\n") }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+      }
+    }
+
+    case "system_info": {
+      const info = {
+        hostname: hostname(),
+        platform: platform(),
+        arch: arch(),
+        uptime: `${Math.floor(uptime() / 3600)}h ${Math.floor((uptime() % 3600) / 60)}m`,
+        totalMemory: `${Math.round(totalmem() / 1024 / 1024 / 1024)}GB`,
+        freeMemory: `${Math.round(freemem() / 1024 / 1024 / 1024)}GB`,
+        homeDir: homedir(),
+        nodeVersion: process.version,
+      };
+      return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
+    }
+
+    default:
+      return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+  }
+}
+
+function handleJsonRpc(msg) {
+  const { id, method, params } = msg;
+
+  switch (method) {
+    case "initialize":
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: params?.protocolVersion || "2024-11-05",
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: SERVER_INFO,
+          instructions:
+            "This server gives you access to the user's machine. " +
+            "You can run shell commands, read/write files, list directories, and get system info. " +
+            "Use these tools to help the user with OS-level tasks.",
+        },
+      };
+
+    case "notifications/initialized":
+      return null;
+
+    case "tools/list":
+      return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+
+    case "tools/call": {
+      const result = handleToolCall(params.name, params.arguments || {});
+      if (result instanceof Promise) {
+        return result.then((r) => ({ jsonrpc: "2.0", id, result: r }));
+      }
+      return { jsonrpc: "2.0", id, result };
+    }
+
+    case "ping":
+      return { jsonrpc: "2.0", id, result: {} };
+
+    default:
+      if (!id) return null;
+      return {
+        jsonrpc: "2.0",
+        id,
+        error: { code: -32601, message: `Method not found: ${method}` },
+      };
+  }
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+    req.on("error", reject);
+  });
+}
+
+export function startMcpServer(port = 0) {
+  return new Promise((resolve, reject) => {
+    const httpServer = http.createServer(async (req, res) => {
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization, Mcp-Session-Id, Accept");
+      res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      const url = new URL(req.url, "http://localhost");
+
+      if (url.pathname === "/mcp" && req.method === "POST") {
+        try {
+          const body = await readBody(req);
+          const parsed = JSON.parse(body);
+
+          if (Array.isArray(parsed)) {
+            const results = [];
+            for (const msg of parsed) {
+              const r = handleJsonRpc(msg);
+              const resolved = r instanceof Promise ? await r : r;
+              if (resolved) results.push(resolved);
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(results));
+          } else {
+            let result = handleJsonRpc(parsed);
+            if (result instanceof Promise) result = await result;
+            if (result) {
+              res.writeHead(200, { "Content-Type": "application/json" });
+              res.end(JSON.stringify(result));
+            } else {
+              res.writeHead(204);
+              res.end();
+            }
+          }
+        } catch (err) {
+          res.writeHead(400, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32700, message: "Parse error" }, id: null }));
+        }
+        return;
+      }
+
+      if (url.pathname === "/health") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok" }));
+        return;
+      }
+
+      res.writeHead(404);
+      res.end("Not found");
+    });
+
+    httpServer.on("error", reject);
+    httpServer.listen(port, "127.0.0.1", () => {
+      resolve({ httpServer, port: httpServer.address().port });
+    });
+  });
+}

package/src/tunnel.js

@@ -0,0 +1,20 @@
+import { PokeTunnel, getToken } from "poke";
+
+export async function startTunnel({ apiKey, mcpUrl, onEvent }) {
+  const token = getToken();
+
+  const tunnel = new PokeTunnel({
+    url: mcpUrl,
+    name: "poke-gate",
+    token: token || apiKey,
+  });
+
+  tunnel.on("connected", (info) => onEvent("connected", info));
+  tunnel.on("disconnected", () => onEvent("disconnected"));
+  tunnel.on("error", (err) => onEvent("error", err.message));
+  tunnel.on("toolsSynced", ({ toolCount }) => onEvent("tools-synced", toolCount));
+  tunnel.on("oauthRequired", ({ authUrl }) => onEvent("oauth-required", authUrl));
+
+  const info = await tunnel.start();
+  return { tunnel, info };
+}