shipback-sftp 0.0.0-stage → 0.1.0

package/src/credentials.js

@@ -0,0 +1,32 @@
+'use strict';
+// Password storage. Windows → Credential Manager (Generic Credentials) via @napi-rs/keyring.
+// If the OS vault is unavailable, fall back to memory for this session only and say so.
+const SERVICE = 'shipback-sftp';
+
+class MemoryStore {
+  constructor() { this.map = new Map(); this.kind = 'memory'; }
+  async get(account) { return this.map.has(account) ? this.map.get(account) : null; }
+  async set(account, password) { this.map.set(account, password); }
+  async delete(account) { this.map.delete(account); }
+}
+
+class KeyringStore {
+  constructor(Entry) { this.Entry = Entry; this.kind = 'keyring'; }
+  async get(account) { try { return new this.Entry(SERVICE, account).getPassword() ?? null; } catch { return null; } }
+  async set(account, password) { new this.Entry(SERVICE, account).setPassword(password); }
+  async delete(account) { try { new this.Entry(SERVICE, account).deletePassword(); } catch { /* not there */ } }
+}
+
+/** Pick the best available store. Returns { store, note } */
+function createCredentialStore() {
+  try {
+    const { Entry } = require('@napi-rs/keyring');
+    // probe: the vault must be readable, otherwise fall back
+    new Entry(SERVICE, '__probe__').getPassword();
+    return { store: new KeyringStore(Entry), note: process.platform === 'win32' ? 'Passwords are kept in Windows Credential Manager.' : 'Passwords are kept in the OS keychain.' };
+  } catch (e) {
+    return { store: new MemoryStore(), note: `OS credential vault unavailable (${e.message.split('\n')[0]}). Passwords are kept in memory for this session only.` };
+  }
+}
+
+module.exports = { MemoryStore, KeyringStore, createCredentialStore, SERVICE };

package/src/deploy.js

@@ -0,0 +1,129 @@
+'use strict';
+// Deploy orchestrator: scan → plan → backup → upload → (delete) → manifest.
+const path = require('node:path');
+const posix = path.posix;
+const { scanLocal, loadIgnore, dropIgnored, sha256File } = require('./manifest');
+const { plan: makePlan, resolveVerify, MANIFEST_NAME, BACKUP_PREFIX } = require('./diff');
+const { backupFiles, makeStamp, freeBackupDir, writeBackupInfo } = require('./backup');
+
+const isBackupDir = name => name.startsWith(BACKUP_PREFIX);
+
+async function readRemoteManifest(remoteFs, root) {
+  try { return JSON.parse((await remoteFs.readFile(`${root}/${MANIFEST_NAME}`)).toString('utf8')); }
+  catch { return null; }
+}
+
+/** Preview only: scan both sides and return the plan. */
+async function previewDeploy({ localDir, remoteRoot, remoteFs, mirror = false, ignore, onEvent = () => {} }) {
+  const root = remoteRoot.replace(/\/$/, '');
+  onEvent({ type: 'scan', side: 'local', dir: localDir });
+  const local = await scanLocal(localDir, { ignore });
+  onEvent({ type: 'scan', side: 'remote', dir: root });
+  const rootStat = await remoteFs.stat(root);
+  if (rootStat && !rootStat.isDir) throw new Error(`Remote path is a file, not a folder: ${root}`);
+  // ignored paths are hands-off on the server too: never counted as extra, never mirror-deleted
+  const remoteListing = rootStat ? dropIgnored(await remoteFs.listRecursive(root, { skipDir: isBackupDir }), await loadIgnore(localDir, ignore)) : [];
+  const remoteManifest = rootStat ? await readRemoteManifest(remoteFs, root) : null;
+  const plan = makePlan({ local, remoteManifest, remoteListing, mirror });
+  if (plan.verify.length) await resolveVerify(plan, { readFile: p => remoteFs.readFile(`${root}/${p}`), onEvent });
+  onEvent({ type: 'plan', plan, localCount: local.length, remoteCount: remoteListing.length, remoteExists: !!rootStat });
+  return { local, plan, remoteExists: !!rootStat };
+}
+
+/**
+ * runDeploy({ localDir, remoteRoot, remoteFs, dryRun, backup, mirror, ignore, now, onEvent })
+ * → { dryRun, plan, uploaded, backedUp, backupDir, deleted, bytes }
+ */
+async function runDeploy({ localDir, remoteRoot, remoteFs, dryRun = false, backup = true, mirror = false, ignore, now = new Date(), onEvent = () => {} }) {
+  const root = remoteRoot.replace(/\/$/, '');
+  const summary = { dryRun, plan: null, uploaded: [], backedUp: [], backupDir: null, deleted: [], bytes: 0 };
+  try {
+    const { local, plan, remoteExists } = await previewDeploy({ localDir, remoteRoot: root, remoteFs, mirror, ignore, onEvent });
+    summary.plan = plan;
+    if (dryRun) { onEvent({ type: 'done', summary }); return summary; }
+
+    if (!remoteExists) { await remoteFs.mkdirp(root); onEvent({ type: 'mkdir', path: root }); }
+
+    // 1. backup everything about to be overwritten or deleted, plus .backup.json so restore can undo this run
+    if (backup && (plan.upload.length || plan.delete.length)) {
+      const backupDir = await freeBackupDir(remoteFs, root, makeStamp(now));
+      const targets = [...plan.upload.filter(u => u.reason === 'changed').map(u => u.path), ...plan.delete];
+      const res = await backupFiles({ remoteFs, root, paths: targets, backupDir, onEvent });
+      const copied = new Set(res.copied);
+      const sha = new Map(local.map(f => [f.path, f.sha256]));
+      await writeBackupInfo({ remoteFs, backupDir, info: {
+        action: 'deploy', at: now.toISOString(),
+        overwritten: plan.upload.filter(u => copied.has(u.path)).map(u => ({ path: u.path, sha256: sha.get(u.path) })),
+        added: plan.upload.filter(u => !copied.has(u.path)).map(u => ({ path: u.path, sha256: sha.get(u.path) })),
+        deleted: plan.delete.filter(p => copied.has(p)).map(p => ({ path: p })),
+      } });
+      summary.backedUp = res.copied;
+      summary.backupDir = backupDir;
+    }
+
+    // 2. upload new + changed
+    const madeDirs = new Set([root]);
+    for (const u of plan.upload) {
+      const dest = `${root}/${u.path}`;
+      const dir = posix.dirname(dest);
+      if (!madeDirs.has(dir)) { await remoteFs.mkdirp(dir); madeDirs.add(dir); }
+      await remoteFs.uploadFile(path.join(localDir, ...u.path.split('/')), dest);
+      summary.uploaded.push(u.path); summary.bytes += u.size;
+      onEvent({ type: 'upload', path: u.path, bytes: u.size, reason: u.reason, done: summary.uploaded.length, total: plan.upload.length });
+    }
+
+    // 3. mirror deletes
+    for (const p of plan.delete) {
+      await remoteFs.remove(`${root}/${p}`);
+      summary.deleted.push(p);
+      onEvent({ type: 'delete', path: p });
+    }
+
+    // 4. manifest for next time
+    const files = {};
+    for (const f of local) files[f.path] = { sha256: f.sha256, size: f.size, mtime: f.mtime };
+    await remoteFs.writeFile(`${root}/${MANIFEST_NAME}`, JSON.stringify({ version: 1, deployedAt: new Date().toISOString(), files }, null, 1));
+    onEvent({ type: 'manifest', path: MANIFEST_NAME, count: local.length });
+    onEvent({ type: 'done', summary });
+    return summary;
+  } catch (err) {
+    onEvent({ type: 'error', message: err.message, summary });
+    throw err;
+  }
+}
+
+/** Ad-hoc upload of named local files into a remote dir (with backup of anything overwritten). */
+async function uploadFiles({ files, remoteDir, remoteFs, backup = true, now = new Date(), onEvent = () => {} }) {
+  // files: [{ name, localPath, size }]
+  const root = remoteDir.replace(/\/$/, '');
+  const summary = { uploaded: [], backedUp: [], backupDir: null, bytes: 0 };
+  try {
+    await remoteFs.mkdirp(root);
+    if (backup && files.length) {
+      const backupDir = await freeBackupDir(remoteFs, root, makeStamp(now));
+      const res = await backupFiles({ remoteFs, root, paths: files.map(f => f.name), backupDir, onEvent });
+      const copied = new Set(res.copied);
+      const shas = new Map();
+      for (const f of files) shas.set(f.name, await sha256File(f.localPath));
+      await writeBackupInfo({ remoteFs, backupDir, info: {
+        action: 'upload', at: now.toISOString(),
+        overwritten: files.filter(f => copied.has(f.name)).map(f => ({ path: f.name, sha256: shas.get(f.name) })),
+        added: files.filter(f => !copied.has(f.name)).map(f => ({ path: f.name, sha256: shas.get(f.name) })),
+        deleted: [],
+      } });
+      summary.backedUp = res.copied; summary.backupDir = backupDir;
+    }
+    for (const f of files) {
+      await remoteFs.uploadFile(f.localPath, `${root}/${f.name}`);
+      summary.uploaded.push(f.name); summary.bytes += f.size || 0;
+      onEvent({ type: 'upload', path: f.name, bytes: f.size || 0, reason: 'upload', done: summary.uploaded.length, total: files.length });
+    }
+    onEvent({ type: 'done', summary });
+    return summary;
+  } catch (err) {
+    onEvent({ type: 'error', message: err.message, summary });
+    throw err;
+  }
+}
+
+module.exports = { runDeploy, previewDeploy, uploadFiles, MANIFEST_NAME };

package/src/diff.js

@@ -0,0 +1,65 @@
+'use strict';
+// Compare a local manifest against the server and decide what to upload / skip / delete.
+const MANIFEST_NAME = '.deploy-manifest.json';
+const BACKUP_PREFIX = '_backup-';
+
+function isProtectedRemote(p) {
+  return p === MANIFEST_NAME || p.startsWith(BACKUP_PREFIX) || p.includes('/' + BACKUP_PREFIX);
+}
+
+/**
+ * plan({ local, remoteManifest, remoteListing, mirror })
+ *  local:          [{ path, size, mtime, sha256 }]
+ *  remoteManifest: { files: { path: { sha256 } } } | null   (written by the last deploy)
+ *  remoteListing:  [{ path, size, mtime }]                  (files actually on the server)
+ * → { upload: [{ path, size, reason }], skip: [path], verify: [{ path, size, sha256 }], extra: [path], delete: [path], uploadBytes }
+ * `verify` = same size on both sides but no manifest hash to compare; resolveVerify() settles those.
+ */
+function plan({ local, remoteManifest, remoteListing, mirror = false }) {
+  const remote = new Map(remoteListing.map(f => [f.path, f]));
+  const manifest = (remoteManifest && remoteManifest.files) || {};
+  const upload = [], skip = [], verify = [];
+  const localSet = new Set();
+  for (const f of [...local].sort((a, b) => a.path.localeCompare(b.path))) {
+    localSet.add(f.path);
+    const r = remote.get(f.path);
+    if (!r) { upload.push({ path: f.path, size: f.size, reason: 'new' }); continue; }
+    const m = manifest[f.path];
+    if (m && m.sha256 === f.sha256 && r.size === f.size) {
+      skip.push(f.path);                 // exactly what we deployed last time
+    } else if (r.size !== f.size) {
+      upload.push({ path: f.path, size: f.size, reason: 'changed' });
+    } else {
+      // same size but no manifest hash to trust (never deployed by us, or the folder was pulled since): read the server copy
+      verify.push({ path: f.path, size: f.size, sha256: f.sha256 });
+    }
+  }
+  const extra = [...remote.keys()].filter(p => !localSet.has(p) && !isProtectedRemote(p)).sort();
+  return finalise({ upload, skip, verify, extra, delete: mirror ? [...extra] : [] });
+}
+
+function finalise(p) {
+  p.upload.sort((a, b) => a.path.localeCompare(b.path));
+  p.skip.sort();
+  p.uploadBytes = p.upload.reduce((n, u) => n + u.size, 0);
+  return p;
+}
+
+/**
+ * Resolve the `verify` list by hashing the server copies. Files above `maxBytes` are assumed
+ * unchanged (same size, too big to be worth a download). Mutates and returns the plan.
+ */
+async function resolveVerify(plan, { readFile, maxBytes = 8 * 1024 * 1024, onEvent = () => {} }) {
+  const crypto = require('node:crypto');
+  for (const v of plan.verify) {
+    if (v.size > maxBytes) { plan.skip.push(v.path); continue; }
+    onEvent({ type: 'verify', path: v.path });
+    const remoteHash = crypto.createHash('sha256').update(await readFile(v.path)).digest('hex');
+    if (remoteHash === v.sha256) plan.skip.push(v.path);
+    else plan.upload.push({ path: v.path, size: v.size, reason: 'changed' });
+  }
+  plan.verify = [];
+  return finalise(plan);
+}
+
+module.exports = { plan, resolveVerify, MANIFEST_NAME, BACKUP_PREFIX, isProtectedRemote };

package/src/history.js

@@ -0,0 +1,37 @@
+'use strict';
+// deploys.jsonl — one line per deploy / upload / pull, so "what went up and when" is answerable later.
+const fs = require('node:fs/promises');
+
+async function appendHistory(file, record) {
+  await fs.appendFile(file, JSON.stringify(record) + '\n');
+}
+
+async function readHistory(file, { site, limit = 50 } = {}) {
+  let text;
+  try { text = await fs.readFile(file, 'utf8'); } catch (e) { if (e.code === 'ENOENT') return []; throw e; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { const r = JSON.parse(line); if (!site || r.site === site) out.push(r); } catch { /* skip corrupt line */ }
+  }
+  return out.reverse().slice(0, limit);
+}
+
+/** Build a compact history record from a run summary (deploy / upload / pull). */
+function recordFromSummary({ action, site, trigger = 'ui', localDir, remoteDir, startedAt, summary = {}, error }) {
+  const plan = summary.plan || {};
+  return {
+    at: new Date().toISOString(), startedAt, action, site, trigger, ok: !error, error: error || undefined,
+    localDir, remoteDir, dryRun: !!summary.dryRun,
+    uploaded: summary.uploaded || undefined, downloaded: summary.downloaded || undefined, deleted: summary.deleted || undefined,
+    pruned: summary.pruned ? summary.pruned.map(p => p.name) : undefined, refused: Array.isArray(summary.refused) ? summary.refused.map(r => r.name) : undefined,
+    restoredFrom: action === 'restore' ? summary.backup : undefined,
+    restored: action === 'restore' ? summary.put : undefined, removed: action === 'restore' ? summary.remove : undefined,
+    refusedConflicts: summary.conflicts && summary.refused ? summary.conflicts.length : undefined,
+    backedUp: summary.backedUp ? summary.backedUp.length : undefined, backupDir: summary.backupDir || summary.undoBackupDir || undefined,
+    bytes: summary.bytes || 0,
+    unchanged: plan.skip ? plan.skip.length : undefined, extra: plan.extra ? plan.extra.length : undefined,
+  };
+}
+
+module.exports = { appendHistory, readHistory, recordFromSummary };

package/src/manifest.js

@@ -0,0 +1,98 @@
+'use strict';
+// Local folder scan → manifest [{ path, size, mtime, sha256 }], with gitignore-style ignore rules.
+const fs = require('node:fs/promises');
+const { createReadStream } = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const DEFAULT_IGNORE = ['.git/', 'node_modules/', 'Thumbs.db', '.DS_Store', 'desktop.ini', '*.tmp', '.deployignore', '_backup-*/'];
+const IGNORE_FILE = '.deployignore';
+
+function parseIgnoreFile(text) {
+  return String(text || '').split(/\r?\n/).map(l => l.trim()).filter(l => l && !l.startsWith('#'));
+}
+
+function globToRegex(glob) {
+  let re = '';
+  for (const ch of glob) {
+    if (ch === '*') re += '[^/]*';
+    else if (ch === '?') re += '[^/]';
+    else re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return re;
+}
+
+/** makeMatcher(globs) → (relPosixPath, isDir) => boolean */
+function makeMatcher(globs) {
+  const rules = globs.map(g => {
+    let dirOnly = false, pattern = g;
+    if (pattern.endsWith('/')) { dirOnly = true; pattern = pattern.slice(0, -1); }
+    const anchored = pattern.includes('/');
+    if (anchored && pattern.startsWith('/')) pattern = pattern.slice(1);
+    const body = globToRegex(pattern);
+    // anchored patterns match from the root; bare names match at any depth
+    const re = anchored ? new RegExp('^' + body + '(/|$)') : new RegExp('(^|/)' + body + '(/|$)');
+    return { re, dirOnly };
+  });
+  return (rel, isDir) => {
+    for (const r of rules) {
+      const m = r.re.exec(rel);
+      if (!m) continue;
+      if (!r.dirOnly) return true;
+      // dir-only rule: matches if the matched segment is a directory (i.e. something follows it, or the entry itself is a dir)
+      const matchedToEnd = m[0].length === rel.length - m.index && !m[0].endsWith('/');
+      if (!matchedToEnd || isDir) return true;
+    }
+    return false;
+  };
+}
+
+function sha256File(p) {
+  return new Promise((resolve, reject) => {
+    const h = crypto.createHash('sha256');
+    createReadStream(p).on('data', d => h.update(d)).on('end', () => resolve(h.digest('hex'))).on('error', reject);
+  });
+}
+
+/**
+ * loadIgnore(dir, ignore) → (relPosixPath, isDir) => boolean
+ * The one set of ignore rules for a site: built-in defaults + the site's "ignore" list + the local .deployignore.
+ * Used for the local scan AND to filter the server listing, so an ignored path is hands-off in both directions
+ * (never uploaded, never pulled, never mirror-deleted).
+ */
+async function loadIgnore(dir, ignore = []) {
+  let globs = [...DEFAULT_IGNORE, ...(ignore || [])];
+  try { globs = globs.concat(parseIgnoreFile(await fs.readFile(path.join(dir, IGNORE_FILE), 'utf8'))); } catch { /* none */ }
+  return makeMatcher(globs);
+}
+
+/** dropIgnored(remoteListing, ignored) → the listing without ignored files ([{ path, ... }], paths relative to the root) */
+function dropIgnored(listing, ignored) {
+  return listing.filter(f => !ignored(f.path, false));
+}
+
+/** scanLocal(dir, { ignore }) → sorted manifest */
+async function scanLocal(dir, opts = {}) {
+  let st;
+  try { st = await fs.stat(dir); } catch (e) { throw new Error(`Local folder not found: ${dir}`); }
+  if (!st.isDirectory()) throw new Error(`Not a folder: ${dir}`);
+  const ignored = await loadIgnore(dir, opts.ignore);
+  const out = [];
+  async function walk(abs, rel) {
+    const entries = await fs.readdir(abs, { withFileTypes: true });
+    for (const e of entries) {
+      const r = rel ? rel + '/' + e.name : e.name;
+      if (e.isDirectory()) { if (!ignored(r, true)) await walk(path.join(abs, e.name), r); continue; }
+      if (!e.isFile()) continue;
+      if (ignored(r, false)) continue;
+      const full = path.join(abs, e.name);
+      const s = await fs.stat(full);
+      out.push({ path: r, size: s.size, mtime: Math.floor(s.mtimeMs), sha256: await sha256File(full) });
+    }
+  }
+  await walk(dir, '');
+  out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return out;
+}
+
+module.exports = { scanLocal, loadIgnore, dropIgnored, makeMatcher, parseIgnoreFile, DEFAULT_IGNORE, IGNORE_FILE, sha256File };

package/src/mcp.js

@@ -0,0 +1,237 @@
+'use strict';
+// MCP server (stdio, JSON-RPC 2.0, one message per line) so an AI agent can deploy, check and undo.
+//
+// Safety is in what is NOT here: no mirror (deleting server files), no backup switch, no pruning of
+// backups. Every deploy is backed up, every deploy can be restored. On top of that:
+//   · deploy and restore need the planId from preview_deploy / preview_restore. If anything changed
+//     in between (a local edit, someone editing the live site), the ids differ and nothing runs.
+//   · restore refuses when a live file was edited after the run being undone, unless force is passed.
+//   · passwords never pass through the model: they come from the OS keychain (stored by the CLI or
+//     the app the first time) or SFTP_PASSWORD in the server's environment.
+const crypto = require('node:crypto');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const { loadSites } = require('./config');
+const { createCredentialStore } = require('./credentials');
+const { SftpRemoteFs } = require('./remote-fs');
+const { previewDeploy, runDeploy } = require('./deploy');
+const { runPull } = require('./pull');
+const { runRestore, describeBackups } = require('./restore');
+const { appendHistory, readHistory, recordFromSummary } = require('./history');
+
+const VERSION = require('../package.json').version;
+const PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+const LIST_MAX = 200;
+
+const hash = v => crypto.createHash('sha256').update(JSON.stringify(v)).digest('hex').slice(0, 16);
+const cap = list => list.length > LIST_MAX ? [...list.slice(0, LIST_MAX), `… and ${list.length - LIST_MAX} more`] : list;
+
+const SITE = { site: { type: 'string', description: 'Site name from sites.json (see list_sites)' } };
+const LOCAL = { localDir: { type: 'string', description: "Local folder to deploy from / compare with. Defaults to the site's localDir." } };
+const TOOLS = [
+  { name: 'list_sites', description: 'List the configured sites: name, host, remote root and default local folder. No passwords.',
+    inputSchema: { type: 'object', properties: {} } },
+  { name: 'preview_deploy', description: 'Show what a deploy would upload (new and changed files). Changes nothing. Returns a planId that deploy needs.',
+    inputSchema: { type: 'object', properties: { ...SITE, ...LOCAL }, required: ['site'] } },
+  { name: 'deploy', description: 'Upload the previewed plan. Every file it overwrites is backed up on the server first, and the whole deploy can be undone with restore. Never deletes server files. Refuses if the plan changed since preview_deploy.',
+    inputSchema: { type: 'object', properties: { ...SITE, ...LOCAL, planId: { type: 'string', description: 'planId from preview_deploy' } }, required: ['site', 'planId'] } },
+  { name: 'check_server_changes', description: "Before editing a site's local files: list files that are different or only on the server (someone edited the live site). Changes nothing.",
+    inputSchema: { type: 'object', properties: { ...SITE, ...LOCAL }, required: ['site'] } },
+  { name: 'pull', description: 'Download the server-side changes into the local folder, so local is the truth before editing. Local files it overwrites are backed up in <localDir>/_backup-<stamp>/. Never deletes local files.',
+    inputSchema: { type: 'object', properties: { ...SITE, ...LOCAL }, required: ['site'] } },
+  { name: 'list_backups', description: 'List the backups on the server, newest first, with what each run overwrote, added and deleted.',
+    inputSchema: { type: 'object', properties: { ...SITE }, required: ['site'] } },
+  { name: 'preview_restore', description: 'Show what restoring a backup would put back and remove, and any conflicts (live files edited after that run). Changes nothing. Returns a planId that restore needs.',
+    inputSchema: { type: 'object', properties: { ...SITE, backup: { type: 'string', description: 'Backup folder name, e.g. _backup-2026-10-18-1400. Default: the newest.' } }, required: ['site'] } },
+  { name: 'restore', description: 'Undo a deploy: put the backed-up files back and remove the files that run added. Backs up the current live files first, so the restore can itself be restored. Refuses on conflicts unless force is true; only pass force when the user has seen the conflicts and said to go ahead.',
+    inputSchema: { type: 'object', properties: { ...SITE, backup: { type: 'string', description: 'Backup folder name from preview_restore' }, planId: { type: 'string', description: 'planId from preview_restore' }, force: { type: 'boolean', description: 'Restore over files edited on the server since that run (they are backed up first)' } }, required: ['site', 'backup', 'planId'] } },
+  { name: 'history', description: 'Recent deploys, pulls and restores from this machine.',
+    inputSchema: { type: 'object', properties: { site: { type: 'string' }, limit: { type: 'number' } } } },
+];
+
+class ToolError extends Error {}
+
+/** createMcp({ sitesFile, historyFile, credentials, connect, env, now }) → { handle(message) → response | null } */
+function createMcp(opts = {}) {
+  const sitesFile = opts.sitesFile || process.env.SHIPBACK_SITES || path.join(process.cwd(), 'sites.json');
+  const historyFile = opts.historyFile || path.join(path.dirname(sitesFile), 'deploys.jsonl');
+  const env = opts.env || process.env;
+  const now = opts.now || (() => new Date());
+  let credentials = opts.credentials;
+  const store = () => credentials || (credentials = createCredentialStore().store);
+
+  async function getSite(name) {
+    if (typeof name !== 'string' || !name) throw new ToolError('Say which site: "site" is required (see list_sites)');
+    const { sites } = await loadSites(sitesFile);
+    const s = sites.find(x => x.name === name);
+    if (!s) throw new ToolError(`Unknown site "${name}". Known: ${sites.map(x => x.name).join(', ') || '(none — add one to ' + sitesFile + ')'}`);
+    return s;
+  }
+  async function connect(site) {
+    if (opts.connect) return opts.connect(site);
+    const o = { host: site.host, port: site.port, username: site.username };
+    if (site.privateKeyPath) o.privateKey = await fs.readFile(site.privateKeyPath);
+    else {
+      o.password = env.SFTP_PASSWORD ?? await store().get(site.name);
+      if (o.password == null) throw new ToolError(`No stored password for "${site.name}". Ask the user to run this once in a terminal, which stores it in the OS keychain: shipback ${site.name} --backups (or node bin/cli.js ${site.name} --backups from a clone)`);
+    }
+    return SftpRemoteFs.connect(o);
+  }
+  async function withSite(args, fn) {
+    const site = await getSite(args.site);
+    const rfs = await connect(site);
+    try { return await fn(site, rfs); } finally { await rfs.close(); }
+  }
+  const record = rec => appendHistory(historyFile, recordFromSummary({ trigger: 'mcp', ...rec })).catch(() => {});
+  const localOf = (site, args) => {
+    const d = args.localDir || site.localDir;
+    if (!d) throw new ToolError(`No local folder: pass "localDir" or set localDir for "${site.name}" in sites.json`);
+    return d;
+  };
+  const deployPlanId = (site, localDir, local, plan) => {
+    const sha = new Map(local.map(f => [f.path, f.sha256]));
+    return hash({ site: site.name, localDir, root: site.remoteRoot, upload: plan.upload.map(u => [u.path, u.reason, sha.get(u.path)]) });
+  };
+  const restorePlanId = (site, s) => hash({ site: site.name, root: site.remoteRoot, backup: s.backup, put: s.put, remove: s.remove, conflicts: s.conflicts });
+
+  const tools = {
+    async list_sites() {
+      const { sites } = await loadSites(sitesFile);
+      return { sitesFile, sites: sites.map(s => ({ name: s.name, host: s.host, port: s.port, remoteRoot: s.remoteRoot, localDir: s.localDir })) };
+    },
+
+    preview_deploy: args => withSite(args, async (site, rfs) => {
+      const localDir = localOf(site, args);
+      const { local, plan } = await previewDeploy({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, ignore: site.ignore });
+      return {
+        planId: deployPlanId(site, localDir, local, plan), site: site.name, from: localDir, to: `${site.host}:${site.remoteRoot}`,
+        upload: cap(plan.upload.map(u => `${u.reason === 'new' ? '+' : '~'} ${u.path}`)), uploadBytes: plan.uploadBytes,
+        unchanged: plan.skip.length, onlyOnServer: plan.extra.length,
+        note: plan.upload.length ? `Files marked ~ will be backed up on the server before they are replaced. Nothing is deleted. Call deploy with this planId to go ahead.` : 'Nothing to upload.',
+      };
+    }),
+
+    deploy: args => withSite(args, async (site, rfs) => {
+      const localDir = localOf(site, args);
+      const { local, plan } = await previewDeploy({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, ignore: site.ignore });
+      if (deployPlanId(site, localDir, local, plan) !== args.planId) throw new ToolError('The plan changed since preview_deploy (a local file or the server changed). Nothing was uploaded. Call preview_deploy again and check the new plan.');
+      if (!plan.upload.length) return { uploaded: [], note: 'Nothing to upload.' };
+      const startedAt = new Date().toISOString();
+      try {
+        const s = await runDeploy({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, backup: true, mirror: false, ignore: site.ignore, now: now() });
+        await record({ action: 'deploy', site: site.name, localDir, remoteDir: site.remoteRoot, startedAt, summary: s });
+        const backup = s.backupDir && s.backupDir.split('/').pop();
+        return { uploaded: cap(s.uploaded), bytes: s.bytes, backedUp: cap(s.backedUp), backup, undo: backup ? `To undo this deploy: preview_restore with backup "${backup}", then restore.` : undefined };
+      } catch (e) { await record({ action: 'deploy', site: site.name, localDir, remoteDir: site.remoteRoot, startedAt, error: e.message }); throw e; }
+    }),
+
+    check_server_changes: args => withSite(args, async (site, rfs) => {
+      const localDir = localOf(site, args);
+      const s = await runPull({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, dryRun: true, ignore: site.ignore });
+      const changed = s.plan.download;
+      return {
+        site: site.name, serverAhead: changed.length > 0,
+        differentOnServer: cap(changed.filter(d => d.reason === 'changed').map(d => d.path)),
+        onlyOnServer: cap(changed.filter(d => d.reason === 'new').map(d => d.path)),
+        onlyLocal: s.plan.extra.length, same: s.plan.skip.length,
+        note: changed.length ? 'The server has files the local folder does not match. If those are live edits to keep, call pull before editing.' : 'Local folder matches the server.',
+      };
+    }),
+
+    pull: args => withSite(args, async (site, rfs) => {
+      const localDir = localOf(site, args);
+      const startedAt = new Date().toISOString();
+      const s = await runPull({ localDir, remoteRoot: site.remoteRoot, remoteFs: rfs, backup: true, mirror: false, ignore: site.ignore, now: now() });
+      await record({ action: 'pull', site: site.name, localDir, remoteDir: site.remoteRoot, startedAt, summary: s });
+      return { downloaded: cap(s.downloaded), bytes: s.bytes, localBackup: s.backupDir || undefined };
+    }),
+
+    list_backups: args => withSite(args, async (site, rfs) => ({ site: site.name, backups: await describeBackups({ remoteRoot: site.remoteRoot, remoteFs: rfs }) })),
+
+    preview_restore: args => withSite(args, async (site, rfs) => {
+      const s = await runRestore({ remoteRoot: site.remoteRoot, remoteFs: rfs, name: args.backup, dryRun: true });
+      return {
+        planId: restorePlanId(site, s), site: site.name, backup: s.backup, undoes: s.action, legacy: s.legacy || undefined,
+        putBack: cap(s.put), remove: cap(s.remove), alreadyRight: s.same.length, conflicts: s.conflicts,
+        note: s.conflicts.length ? 'Some live files were changed after that run. Show the user the conflicts; restore refuses them unless force is true.'
+          : s.put.length || s.remove.length ? 'Call restore with this backup and planId to go ahead. The current live files are backed up first.' : 'The site already matches this backup.',
+      };
+    }),
+
+    restore: args => withSite(args, async (site, rfs) => {
+      if (typeof args.backup !== 'string' || !args.backup) throw new ToolError('Say which backup: "backup" from preview_restore');
+      const dry = await runRestore({ remoteRoot: site.remoteRoot, remoteFs: rfs, name: args.backup, dryRun: true });
+      if (restorePlanId(site, dry) !== args.planId) throw new ToolError('The restore plan changed since preview_restore (the live site changed). Nothing was restored. Call preview_restore again.');
+      const startedAt = new Date().toISOString();
+      const s = await runRestore({ remoteRoot: site.remoteRoot, remoteFs: rfs, name: args.backup, force: args.force === true, now: now() });
+      await record({ action: 'restore', site: site.name, remoteDir: site.remoteRoot, startedAt, summary: s });
+      if (s.refused) throw new ToolError(`Refused: ${s.conflicts.length} live file(s) changed after that run, so nothing was restored: ${s.conflicts.map(c => `${c.path} (${c.why})`).join('; ')}. Only pass force: true if the user says so.`);
+      const undo = s.undoBackupDir && s.undoBackupDir.split('/').pop();
+      return { putBack: cap(s.put), removed: cap(s.remove), undo: undo ? `To undo this restore: preview_restore with backup "${undo}", then restore.` : undefined };
+    }),
+
+    async history(args) {
+      return { history: await readHistory(historyFile, { site: args.site || undefined, limit: Math.min(Number(args.limit) || 20, 100) }) };
+    },
+  };
+
+  async function callTool(name, args) {
+    if (!Object.hasOwn(tools, name)) return { content: [{ type: 'text', text: `Unknown tool "${name}"` }], isError: true };
+    try {
+      const out = await tools[name](args || {});
+      return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] };
+    } catch (e) {
+      return { content: [{ type: 'text', text: e.message }], isError: true };
+    }
+  }
+
+  async function handle(msg) {
+    const reply = result => ({ jsonrpc: '2.0', id: msg.id, result });
+    const fail = (code, message) => ({ jsonrpc: '2.0', id: msg.id ?? null, error: { code, message } });
+    if (!msg || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') return fail(-32600, 'Invalid request');
+    const isNotification = msg.id === undefined;
+    switch (msg.method) {
+      case 'initialize': {
+        const asked = msg.params && msg.params.protocolVersion;
+        return reply({
+          protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0],
+          capabilities: { tools: {} },
+          serverInfo: { name: 'shipback-sftp', version: VERSION },
+          instructions: 'Deploy to shared hosting over SFTP. preview_deploy then deploy; every deploy is backed up and can be undone with preview_restore then restore. Before editing a site, check_server_changes (and pull if the server is ahead).',
+        });
+      }
+      case 'ping': return reply({});
+      case 'tools/list': return reply({ tools: TOOLS });
+      case 'tools/call': return reply(await callTool(msg.params && msg.params.name, msg.params && msg.params.arguments));
+      default:
+        if (isNotification) return null; // notifications/initialized and friends need no answer
+        return fail(-32601, `Method not found: ${msg.method}`);
+    }
+  }
+
+  return { handle, TOOLS };
+}
+
+/** Wire createMcp to stdin/stdout, newline-delimited JSON. Logs go to stderr only. */
+function serveStdio(mcp, { input = process.stdin, output = process.stdout } = {}) {
+  let buf = '';
+  let chain = Promise.resolve();
+  input.setEncoding('utf8');
+  input.on('data', chunk => {
+    buf += chunk;
+    let i;
+    while ((i = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, i).trim(); buf = buf.slice(i + 1);
+      if (!line) continue;
+      chain = chain.then(async () => {
+        let msg;
+        try { msg = JSON.parse(line); } catch { output.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) + '\n'); return; }
+        const res = await mcp.handle(msg).catch(e => ({ jsonrpc: '2.0', id: msg.id ?? null, error: { code: -32603, message: e.message } }));
+        if (res) output.write(JSON.stringify(res) + '\n');
+      });
+    }
+  });
+  return new Promise(resolve => input.on('end', () => chain.then(resolve)));
+}
+
+module.exports = { createMcp, serveStdio, TOOLS };