meshingly-mcp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Burak Uysal
+
+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

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# Meshingly MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Meshingly connects AI coding sessions through an end-to-end encrypted collaboration. You on Claude Code and a teammate on Codex, or any other tool that speaks MCP, can message each other, hand over work and review each other's changes. The relay in the middle only ever stores ciphertext. See [meshingly.com](https://meshingly.com).
+
+This repository holds the local MCP server. It is an npm package, a Claude Code plugin and a Claude Code marketplace at once.
+
+## Install
+
+Claude Code, as a plugin (MCP server and skill together):
+
+```
+/plugin marketplace add DrBurakUysal/meshingly-mcp
+/plugin install meshingly@meshingly
+```
+
+Any MCP tool, through npm (needs Node.js 22.18 or newer):
+
+```
+claude mcp add meshingly -- npx -y meshingly-mcp
+codex mcp add meshingly -- npx -y meshingly-mcp
+```
+
+Other tools take the same command as a local stdio server: `npx -y meshingly-mcp`. Restart the session so the tools load, then ask your agent to set up Meshingly. It asks whether you want to start a new collaboration from scratch or join one with a code and a password.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `meshingly_status` | Shows whether this project is connected |
+| `meshingly_create` | Starts a new collaboration and returns a code and a password |
+| `meshingly_join` | Joins with a code and a password |
+| `meshingly_peers` | Lists the other sessions in the collaboration |
+| `meshingly_send` | Sends an encrypted message to the others |
+| `meshingly_receive` | Reads new messages, optionally waiting for one |
+| `meshingly_handoff`, `meshingly_queue`, `meshingly_claim`, `meshingly_release`, `meshingly_done` | A work queue: park unfinished work, list it, take it over, give it back, finish it |
+| `meshingly_watch_start`, `meshingly_watch_stop`, `meshingly_watch_status` | Optional background watcher that restarts queued work (see below) |
+| `meshingly_settings` | Shows your preferences. Read-only |
+
+## Several computers and handing work over
+
+The same person can join one collaboration from several computers; each session is labelled with a computer name you choose (not the host name). When a session is about to run out of usage it can park its work in the queue, and any session, a teammate's or your own on another computer, can take it over.
+
+## The optional watcher
+
+A session that has ended cannot wake itself. If you want queued work to continue once a usage limit is back, you can run `npx -y meshingly-mcp watch` in the project folder, or turn on the `autoResume` setting. The watcher is a background process on your computer that checks the queue and starts a command you configure (default `claude -p`) with the handoff as its prompt. **It is off by default.** Nothing starts it unless you run it, enable `autoResume`, or enable `modelMayStartWatcher` to let your agent start it. By default it only runs handoffs written by your own session; `trustPeers` extends that to teammates, which means their text starts an agent on your computer, so enable it only for people you trust. Handoffs marked as a question for a person are never run.
+
+Settings live in your home folder, not in the project (so a repository cannot ship them), and are changed in a terminal: `npx -y meshingly-mcp settings` lists them and `settings set <key> <value>` changes one. The agent can read them with `meshingly_settings` but has no tool to change them.
+
+## What it runs, stores and sends
+
+Unless you start the watcher described above, the server runs locally over stdio and starts no other program. Creating a collaboration generates a random key on your machine. It is stored in `.meshingly/connection.json` in your project directory (the directory ignores itself in git) and never leaves it. The only network traffic goes to `https://api.meshingly.com`: a sealed copy of the key that only the password can open, and messages encrypted with the key. Message text, session names and tool names are encrypted before they leave the machine. The relay keeps messages for seven days. Set `MESHINGLY_URL` to use another relay and `MESHINGLY_DIR` to choose where the key is stored.
+
+Messages from other sessions are handed to your agent as untrusted input, never as instructions from you.
+
+## License
+
+MIT

package/dist/background.js

@@ -0,0 +1,183 @@
+import { spawn, spawnSync } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveSettings } from "./settings.js";
+
+const MAX_LOG_BYTES = 1_000_000;
+/** The watcher process writes a heartbeat this often; a pid alone is not proof that the process is still our watcher. */
+export const BEAT_MS = 30_000;
+const BEAT_STALE_MS = 5 * 60_000;
+const START_GRACE_MS = 30_000;
+
+                         
+              
+                    
+                  
+                     
+ 
+
+                               
+                   
+                         
+                  
+ 
+
+const dir = (root        ) => join(root, ".meshingly");
+const recordFile = (root        ) => join(dir(root), "watch.json");
+const beatFile = (root        ) => join(dir(root), "watch.beat");
+const logFile = (root        ) => join(dir(root), "watch.log");
+const lockFile = (root        ) => join(dir(root), "watch.lock");
+export const stateFile = (root        ) => join(dir(root), "watch-state.json");
+
+/** The handoff a watcher was running when it stopped (killed, crashed): the caller gives it back. */
+export function takeCurrentRun(root        )                     {
+  try {
+    if (!existsSync(stateFile(root))) return undefined;
+    const raw = JSON.parse(readFileSync(stateFile(root), "utf8"))                           ;
+    if (typeof raw.current !== "string") return undefined;
+    const id = raw.current;
+    delete raw.current;
+    writeFileSync(stateFile(root), JSON.stringify(raw));
+    return id;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeBeat(root        )       {
+  try {
+    mkdirSync(dir(root), { recursive: true });
+    writeFileSync(beatFile(root), String(Date.now()));
+  } catch {
+    /* a missed beat only makes the watcher look stale for a moment */
+  }
+}
+
+export function clearBeat(root        )       {
+  rmSync(beatFile(root), { force: true });
+}
+
+function alive(pid        )          {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM means the process exists but is not ours to signal.
+    return (err                         ).code === "EPERM";
+  }
+}
+
+/** Ends a process and everything it started: with `shell: true` the pid is the shell's, and a plain kill would leave the agent running. */
+export function killTree(pid        )       {
+  if (process.platform === "win32") {
+    spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+    return;
+  }
+  // Children are started detached (their own process group), so the negative pid reaches the whole group.
+  for (const target of [-pid, pid]) {
+    try {
+      process.kill(target, "SIGTERM");
+      return;
+    } catch {
+      /* try the single process, then give up: it is already gone */
+    }
+  }
+}
+
+/**
+ * A watcher counts as running only when its pid is alive AND it has a fresh heartbeat (or has only just been started).
+ * After a crash or a reboot the pid may belong to an unrelated process; without the heartbeat check Meshingly would
+ * refuse to start a new watcher and, worse, stop would kill a stranger.
+ */
+export function watcherState(root        )               {
+  const file = recordFile(root);
+  if (!existsSync(file)) return { running: false, logFile: logFile(root) };
+  try {
+    const record = JSON.parse(readFileSync(file, "utf8"))                 ;
+    if (!alive(record.pid)) return { running: false, record, logFile: logFile(root) };
+    const now = Date.now();
+    const beat = existsSync(beatFile(root)) ? now - statSync(beatFile(root)).mtimeMs : Infinity;
+    const young = now - Date.parse(record.startedAt) < START_GRACE_MS;
+    return { running: beat < BEAT_STALE_MS || young, record, logFile: logFile(root) };
+  } catch {
+    return { running: false, logFile: logFile(root) };
+  }
+}
+
+/** Starts `meshingly-mcp watch` detached, so it keeps running after this session (and its MCP server) ended. */
+export function startWatcher(root        , entry        )         {
+  const state = watcherState(root);
+  if (state.running) return `The watcher is already running (pid ${state.record .pid}, since ${state.record .startedAt}). Log: ${state.logFile}`;
+  if (!entry || !existsSync(entry)) throw new Error("cannot find the script that starts the watcher");
+
+  // Two servers starting together (two sessions in one project) must not both start a watcher: one would be orphaned.
+  mkdirSync(dir(root), { recursive: true });
+  let lock        ;
+  try {
+    lock = openSync(lockFile(root), "wx");
+  } catch {
+    if (existsSync(lockFile(root)) && Date.now() - statSync(lockFile(root)).mtimeMs < 30_000) return "A watcher is being started right now.";
+    rmSync(lockFile(root), { force: true }); // left behind by a start that died
+    lock = openSync(lockFile(root), "wx");
+  }
+  try {
+    const again = watcherState(root);
+    if (again.running) return `The watcher is already running (pid ${again.record .pid}, since ${again.record .startedAt}). Log: ${again.logFile}`;
+    return launch(root, entry);
+  } finally {
+    closeSync(lock);
+    rmSync(lockFile(root), { force: true });
+  }
+}
+
+function launch(root        , entry        )         {
+
+  // The watcher reads the same settings itself; the flags pin what this start saw, so a later edit needs a restart.
+  const { resumeCommand: command, trustPeers: fromPeers, onQuestion, maxAttempts, checkIntervalSeconds, settleMinutes } = resolveSettings(root).values;
+  mkdirSync(dir(root), { recursive: true });
+  writeFileSync(join(dir(root), ".gitignore"), "*\n");
+  const log = logFile(root);
+  if (existsSync(log) && statSync(log).size > MAX_LOG_BYTES) rmSync(log);
+  const fd = openSync(log, "a", 0o600);
+  try {
+    const args = [
+      entry, "watch", "--dir", root, "--cmd", command, "--on-question", onQuestion,
+      "--max-attempts", String(maxAttempts), "--interval", String(checkIntervalSeconds), "--settle-minutes", String(settleMinutes),
+      ...(fromPeers ? ["--from-peers"] : []),
+    ];
+    const child = spawn(process.execPath, args, { detached: true, stdio: ["ignore", fd, fd], windowsHide: true, env: process.env });
+    // Without a listener a failed spawn would be an uncaught exception that takes the MCP server down with it.
+    child.on("error", (err) => console.error(`meshingly: the watcher process failed: ${err.message}`));
+    child.unref();
+    if (!child.pid) throw new Error("the watcher process did not start");
+    const record                = { pid: child.pid, startedAt: new Date().toISOString(), command, fromPeers };
+    writeFileSync(recordFile(root), JSON.stringify(record, null, 2), { mode: 0o600 });
+  } finally {
+    closeSync(fd);
+  }
+  return [
+    `Watcher started. It checks the queue every ${checkIntervalSeconds} s and, once a handoff is ready, runs: ${command}`,
+    onQuestion === "recommended" ? "If a run would ask a question it takes the recommended option and notes the assumption." : "If a run would need an answer it parks the question for a person.",
+    fromPeers ? "It also runs handoffs written by other sessions (trustPeers)." : "It runs only handoffs written by this project's own session.",
+    `It keeps running after this session ends, for as long as this computer is on. Log: ${log}. Stop it with meshingly_watch_stop. Settings: meshingly_settings.`,
+  ].join("\n");
+}
+
+export function stopWatcher(root        )         {
+  const state = watcherState(root);
+  rmSync(recordFile(root), { force: true });
+  if (!state.running || !state.record) {
+    clearBeat(root);
+    return "No watcher is running.";
+  }
+  const { pid } = state.record;
+  killTree(pid);
+  clearBeat(root);
+  return `Watcher stopped (pid ${pid}).`;
+}
+
+export function describeWatcher(root        )         {
+  const s = watcherState(root);
+  if (!s.running || !s.record) return "No watcher is running.";
+  return `Watcher running (pid ${s.record.pid}, since ${s.record.startedAt}), command: ${s.record.command}${s.record.fromPeers ? ", also for peers' handoffs" : ", own handoffs only"}. Log: ${s.logFile}`;
+}