@akms/mcp 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@akms/mcp`.
+
+## 0.1.0 — Unreleased
+
+### Added
+
+- One terminal menu for database, SSH and WSL connection setup, using the selection and rendering behavior of the existing MCP packages.
+- Client selection for Claude Code, Codex, Claude Desktop and Cursor, plus direct commands such as `akms-mcp db --target codex`.
+- A fresh npm `latest` lookup before every launch. The selected version runs through npm without making the MCP packages runtime dependencies of the launcher.
+- Every child opens through its `config` command. Exiting the child returns to the launcher menu.
+- `.npmignore` controls the published package contents, excluding source, tests and development files.

package/LICENSE.md

@@ -0,0 +1,11 @@
+## MIT License
+
+The MIT License (MIT)
+
+Copyright © 2026 Alkemic Studio.
+
+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,62 @@
-# Temporary Holding Version
+# @akms/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.
+One terminal menu for configuring AKMS database, SSH and WSL MCP connections in your AI client.
+
+```sh
+npx -y --prefer-online @akms/mcp@latest
+```
+
+Requires **Node.js 22+ and npm**. WSL setup runs from Windows.
+
+```text
+? AKMS MCP · Connection setup
+❯ Database  PostgreSQL connections
+  SSH       Remote hosts
+  WSL       Local Linux distros · Windows
+  ────────────────────────
+  Client    Automatically selected by each MCP
+  Quit
+
+↑↓ move · enter select · esc back
+```
+
+Choose a server type to open its current setup screen. Exiting that screen returns to this menu. Use **Client** to select Claude Code, Codex, Claude Desktop or Cursor for subsequent launches. With Automatic, each MCP detects the client using its own setup behavior.
+
+## Install and run
+
+```sh
+npm install -g @akms/mcp
+akms-mcp
+```
+
+`akms-mcp config` and `akms-mcp setup` open the same menu. You can also jump straight into a setup screen:
+
+```sh
+akms-mcp db --target codex
+akms-mcp ssh --target claude-code
+akms-mcp wsl --target cursor
+```
+
+Use `--help` for the command reference and `--version` for the launcher's version.
+
+## Latest on every launch
+
+Each time you choose a server, the launcher queries npm for that package's `latest` tag, then runs the exact version returned. This applies even when you select the same server twice in one session. If the lookup fails, setup does not start with a cached older version. An internet connection to your configured npm registry is required.
+
+The MCP packages are **not dependencies** of this package. npm downloads the selected release into its execution cache when needed; it does not install it into this package or globally. Updating an MCP does not require a new launcher release while its setup command remains compatible.
+
+| Selection | Package | Setup command |
+|---|---|---|
+| Database | `@akms/mcp-db` | `config` |
+| SSH | `@akms/mcp-ssh` | `config` |
+| WSL | `@akms/mcp-wsl` | `config` |
+
+The selected MCP owns connection editing, validation and client configuration writes. Entries saved for your AI client follow that MCP's own behavior; this launcher checks versions when opening setup.
+
+## Terminal controls
+
+Use arrow keys and Enter, or number keys to move to a row. Esc returns to the previous menu; Esc at the main menu exits. The menu uses the same selection and rendering code as the SSH and WSL packages.
+
+Outside an interactive terminal, menus show numbers and accept a number, key or label. For scripted setup, the direct command is easiest: `akms-mcp db --target codex` passes stdin to the database setup screen.
+
+See [development notes](./README_DEV.md) for build and test instructions.

package/lib/cli.js

@@ -0,0 +1,767 @@
+#!/usr/bin/env node
+
+// src/_defs/index.ts
+var MCP_PACKAGES = {
+  db: { label: "Database", packageName: "@akms/mcp-db", command: "akms-mcp-db", setupCommand: "config" },
+  ssh: { label: "SSH", packageName: "@akms/mcp-ssh", command: "akms-mcp-ssh", setupCommand: "config" },
+  wsl: { label: "WSL", packageName: "@akms/mcp-wsl", command: "akms-mcp-wsl", setupCommand: "config" }
+};
+var CLIENT_LABELS = {
+  "claude-code": "Claude Code",
+  codex: "Codex",
+  "claude-desktop": "Claude Desktop",
+  cursor: "Cursor"
+};
+
+// src/modules/launcher/arguments.ts
+function parseArguments(argv) {
+  const parsed = { showHelp: false, showVersion: false };
+  let commandSeen = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--help" || argument === "-h") {
+      parsed.showHelp = true;
+      continue;
+    }
+    if (argument === "--version" || argument === "-v") {
+      parsed.showVersion = true;
+      continue;
+    }
+    if (argument === "--target" || argument.startsWith("--target=") == true) {
+      let target = argument.slice("--target=".length);
+      if (argument === "--target") {
+        index += 1;
+        target = argv[index];
+      }
+      if (target == null || Object.hasOwn(CLIENT_LABELS, target) == false) {
+        throw new Error("--target needs one of: claude-code, codex, claude-desktop, cursor");
+      }
+      parsed.targetId = target;
+      continue;
+    }
+    if ((argument === "setup" || argument === "config") && commandSeen == false && parsed.mcpId == null) {
+      commandSeen = true;
+      continue;
+    }
+    if (Object.hasOwn(MCP_PACKAGES, argument) == true && parsed.mcpId == null) {
+      parsed.mcpId = argument;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${argument}. Run akms-mcp --help for usage.`);
+  }
+  return parsed;
+}
+
+// src/modules/launcher/prompter.ts
+var PromptClosedError = class extends Error {
+  constructor() {
+    super("input closed before the prompt was answered");
+    this.name = "PromptClosedError";
+  }
+};
+var PromptBackError = class extends Error {
+  constructor() {
+    super("prompt left with esc");
+    this.name = "PromptBackError";
+  }
+};
+var ESC = "\x1B";
+var KEY_UP = [`${ESC}[A`, `${ESC}OA`];
+var KEY_DOWN = [`${ESC}[B`, `${ESC}OB`];
+var KEY_HOME = [`${ESC}[H`, `${ESC}OH`, `${ESC}[1~`, "
"];
+var KEY_END = [`${ESC}[F`, `${ESC}OF`, `${ESC}[4~`, ""];
+var KEY_ENTER = ["\r", "\n"];
+var KEY_CTRL_C = "";
+var KEY_CTRL_D = "";
+function splitKeys(chunk) {
+  const keys = [];
+  let index = 0;
+  while (index < chunk.length) {
+    const isSequence = chunk[index] === ESC && (chunk[index + 1] === "[" || chunk[index + 1] === "O");
+    if (isSequence == true) {
+      let end = index + 2;
+      while (end < chunk.length && /[0-9;]/.test(chunk[end]) == true) {
+        end += 1;
+      }
+      keys.push(chunk.slice(index, end + 1));
+      index = end + 1;
+      continue;
+    }
+    const codePoint = chunk.codePointAt(index) ?? 0;
+    const character = String.fromCodePoint(codePoint);
+    keys.push(character);
+    index += character.length;
+  }
+  return keys;
+}
+function charWidth(codePoint) {
+  if (codePoint < 4352) {
+    return 1;
+  }
+  const isWide = codePoint <= 4447 || codePoint === 9001 || codePoint === 9002 || codePoint >= 11904 && codePoint <= 42191 && codePoint !== 12351 || codePoint >= 44032 && codePoint <= 55203 || codePoint >= 63744 && codePoint <= 64255 || codePoint >= 65072 && codePoint <= 65103 || codePoint >= 65280 && codePoint <= 65376 || codePoint >= 65504 && codePoint <= 65510 || codePoint >= 127744 && codePoint <= 128591 || codePoint >= 129280 && codePoint <= 129535 || codePoint >= 131072 && codePoint <= 262141;
+  if (isWide == true) {
+    return 2;
+  }
+  return 1;
+}
+function displayWidth(text) {
+  let width = 0;
+  for (const character of text) {
+    width += charWidth(character.codePointAt(0) ?? 0);
+  }
+  return width;
+}
+function padToWidth(text, width) {
+  const missing = width - displayWidth(text);
+  if (missing <= 0) {
+    return text;
+  }
+  return `${text}${" ".repeat(missing)}`;
+}
+function groupLabelWidths(items) {
+  const widths = items.map(() => 0);
+  let groupStart = 0;
+  for (let index = 0; index <= items.length; index += 1) {
+    const atBoundary = index === items.length || "value" in items[index] == false;
+    if (atBoundary == false) {
+      continue;
+    }
+    let groupWidth = 0;
+    for (let member = groupStart; member < index; member += 1) {
+      const item = items[member];
+      groupWidth = Math.max(groupWidth, displayWidth(item.label));
+    }
+    for (let member = groupStart; member < index; member += 1) {
+      widths[member] = groupWidth;
+    }
+    groupStart = index + 1;
+  }
+  return widths;
+}
+function supportsUnicode() {
+  if (process.platform !== "win32") {
+    return true;
+  }
+  return process.env.WT_SESSION != null || process.env.TERM_PROGRAM === "vscode" || process.env.TERMINAL_EMULATOR === "JetBrains-JediTerm" || process.env.ConEmuTask != null;
+}
+function createStyle(enabled) {
+  const paint = (open, close) => {
+    return (text) => {
+      if (enabled == false || text === "") {
+        return text;
+      }
+      return `${ESC}[${open}m${text}${ESC}[${close}m`;
+    };
+  };
+  return {
+    accent: paint(36, 39),
+    success: paint(32, 39),
+    dim: paint(2, 22),
+    bold: paint(1, 22)
+  };
+}
+var Prompter = class {
+  constructor(input, output) {
+    this.input = input;
+    this.output = output;
+    const ttyInput = input;
+    const ttyOutput = output;
+    this.interactive = ttyInput.isTTY == true && ttyInput.setRawMode != null && ttyOutput.isTTY == true;
+    this.style = createStyle(this.interactive == true && process.env.NO_COLOR == null);
+    if (supportsUnicode() == true) {
+      this.symbols = { question: "?", pointer: "\u276F", tick: "\u2714", rule: "\u2500" };
+    } else {
+      this.symbols = { question: "?", pointer: ">", tick: "\u221A", rule: "-" };
+    }
+    this.inputEnded = input.readableEnded;
+    input.setEncoding("utf8");
+    input.on("data", this.onInputData);
+    input.on("end", this.onInputEnd);
+  }
+  input;
+  output;
+  lineBuffer = "";
+  pendingLines = [];
+  lineWaiter = null;
+  inputEnded = false;
+  onInputData = (chunk) => {
+    this.onData(chunk);
+  };
+  onInputEnd = () => {
+    this.inputEnded = true;
+    if (this.lineWaiter != null) {
+      const waiter = this.lineWaiter;
+      this.lineWaiter = null;
+      waiter(null);
+    }
+    if (this.keyHandler != null) {
+      this.keyHandler(KEY_CTRL_D);
+    }
+  };
+  /** Set while a key-driven prompt owns the input. */
+  keyHandler = null;
+  interactive;
+  style;
+  symbols;
+  /** Stops reading so the process can exit once the command is done. */
+  close() {
+    if (this.interactive == true) {
+      this.input.setRawMode?.(false);
+      this.output.write(`${ESC}[?25h`);
+    }
+    this.input.pause();
+    this.input.off("data", this.onInputData);
+    this.input.off("end", this.onInputEnd);
+  }
+  takePendingInput() {
+    const text = this.pendingLines.map((line) => line + "\n").join("") + this.lineBuffer;
+    this.pendingLines.length = 0;
+    this.lineBuffer = "";
+    return text;
+  }
+  /**
+   * Picks one of `items`. On a TTY: ↑/↓ move, 1–9 jump, Enter picks, Esc goes back. Off a
+   * TTY: a numbered list, answered by number, key or label.
+   *
+   * @throws {PromptBackError} On Esc without a `cancelValue`.
+   * @throws {PromptClosedError} On Ctrl+C or when the input closes.
+   */
+  async select(question, items, options) {
+    const choices = items.filter((item) => "value" in item);
+    if (choices.length === 0) {
+      throw new Error("select needs at least one choice");
+    }
+    let startIndex = items.findIndex((item) => "value" in item && item.value === options?.defaultValue);
+    if (startIndex < 0) {
+      startIndex = items.findIndex((item) => "value" in item);
+    }
+    this.input.resume();
+    let picked;
+    if (this.interactive == true) {
+      picked = await this.selectWithKeys(question, items, startIndex);
+    } else {
+      picked = await this.selectWithLines(question, items, startIndex);
+    }
+    if (picked != null) {
+      return picked;
+    }
+    if (options?.cancelValue != null) {
+      return options.cancelValue;
+    }
+    throw new PromptBackError();
+  }
+  readLine() {
+    const queued = this.pendingLines.shift();
+    if (queued != null) {
+      return Promise.resolve(queued);
+    }
+    if (this.inputEnded == true) {
+      return Promise.resolve(null);
+    }
+    return new Promise((resolve) => {
+      this.lineWaiter = resolve;
+    });
+  }
+  onData(chunk) {
+    if (this.keyHandler != null) {
+      for (const key of splitKeys(chunk)) {
+        if (this.keyHandler == null) {
+          break;
+        }
+        this.keyHandler(key);
+      }
+      return;
+    }
+    this.lineBuffer += chunk;
+    let newlineIndex = this.lineBuffer.indexOf("\n");
+    while (newlineIndex >= 0) {
+      const line = this.lineBuffer.slice(0, newlineIndex).replace(/\r$/, "");
+      this.lineBuffer = this.lineBuffer.slice(newlineIndex + 1);
+      if (this.lineWaiter != null) {
+        const waiter = this.lineWaiter;
+        this.lineWaiter = null;
+        waiter(line);
+      } else {
+        this.pendingLines.push(line);
+      }
+      newlineIndex = this.lineBuffer.indexOf("\n");
+    }
+  }
+  async selectWithLines(question, items, startIndex) {
+    const choices = items.filter((item) => "value" in item);
+    const labelWidths = groupLabelWidths(items);
+    this.output.write(`${this.symbols.question} ${question}
+`);
+    let number = 0;
+    for (let index = 0; index < items.length; index += 1) {
+      const item = items[index];
+      if ("value" in item == false) {
+        this.output.write("\n");
+        continue;
+      }
+      number += 1;
+      let line = `  ${String(number).padStart(2)}) ${padToWidth(item.label, labelWidths[index])}`;
+      if (item.hint != null && item.hint !== "") {
+        line += `  ${item.hint}`;
+      }
+      this.output.write(`${line.trimEnd()}
+`);
+    }
+    const defaultChoice = items[startIndex];
+    const defaultNumber = choices.indexOf(defaultChoice) + 1;
+    for (; ; ) {
+      this.output.write(`Choice (${defaultNumber}): `);
+      const line = await this.readLine();
+      if (line == null) {
+        throw new PromptClosedError();
+      }
+      if (line === ESC) {
+        return null;
+      }
+      const answer = line.trim();
+      if (answer === "") {
+        return defaultChoice.value;
+      }
+      const index = Number(answer);
+      if (Number.isInteger(index) == true && index >= 1 && index <= choices.length) {
+        return choices[index - 1].value;
+      }
+      const lowered = answer.toLowerCase();
+      const matched = choices.find((choice) => {
+        const key = choice.key ?? choice.value;
+        return key.toLowerCase() === lowered || choice.label.toLowerCase() === lowered;
+      });
+      if (matched != null) {
+        return matched.value;
+      }
+      this.output.write(`  Pick a number from 1 to ${choices.length}.
+`);
+    }
+  }
+  // ── TTY rendering ──────────────────────────────────────────────────────
+  columns() {
+    const columns = this.output.columns;
+    if (columns == null || columns < 20) {
+      return 80;
+    }
+    return columns;
+  }
+  /** Joins styled parts, cutting the text (not the styles) once `width` columns are used. */
+  fitLine(parts, width) {
+    let used = 0;
+    let line = "";
+    for (const part of parts) {
+      let text = "";
+      for (const character of part.text) {
+        const characterWidth = charWidth(character.codePointAt(0) ?? 0);
+        if (used + characterWidth > width) {
+          break;
+        }
+        used += characterWidth;
+        text += character;
+      }
+      if (part.paint != null) {
+        line += part.paint(text);
+      } else {
+        line += text;
+      }
+      if (used >= width) {
+        break;
+      }
+    }
+    return line;
+  }
+  /** The one-line record an answered prompt leaves behind on a TTY. */
+  writeAnswered(question, answer) {
+    if (this.interactive == false) {
+      return;
+    }
+    this.output.write(`${this.style.success(this.symbols.tick)} ${question} ${this.style.dim("\xB7")} ${this.style.accent(answer)}
+`);
+  }
+  /** @returns The picked value, or null on Esc. */
+  selectWithKeys(question, items, startIndex) {
+    const ttyInput = this.input;
+    const selectableIndexes = items.flatMap((item, index) => {
+      if ("value" in item) {
+        return [index];
+      }
+      return [];
+    });
+    const labelWidths = groupLabelWidths(items);
+    const ruleWidth = Math.min(Math.max(...labelWidths), 24);
+    let active = startIndex;
+    let renderedLines = 0;
+    const draw = (lines) => {
+      let text = "";
+      if (renderedLines > 1) {
+        text += `${ESC}[${renderedLines - 1}A`;
+      }
+      text += `\r${ESC}[J${lines.join("\n")}`;
+      this.output.write(text);
+      renderedLines = lines.length;
+    };
+    const buildLines = () => {
+      const width = this.columns() - 1;
+      const lines = [
+        this.fitLine([
+          { text: this.symbols.question, paint: this.style.accent },
+          { text: " " },
+          { text: question, paint: this.style.bold }
+        ], width)
+      ];
+      for (let index = 0; index < items.length; index += 1) {
+        const item = items[index];
+        if ("value" in item == false) {
+          lines.push(this.fitLine([{ text: `  ${this.symbols.rule.repeat(ruleWidth)}`, paint: this.style.dim }], width));
+          continue;
+        }
+        const isActive = index === active;
+        const parts = [];
+        if (isActive == true) {
+          parts.push({ text: `${this.symbols.pointer} `, paint: this.style.accent });
+          parts.push({ text: padToWidth(item.label, labelWidths[index]), paint: this.style.accent });
+        } else {
+          parts.push({ text: "  " });
+          parts.push({ text: padToWidth(item.label, labelWidths[index]) });
+        }
+        if (item.hint != null && item.hint !== "") {
+          parts.push({ text: `  ${item.hint}`, paint: this.style.dim });
+        }
+        lines.push(this.fitLine(parts, width));
+      }
+      lines.push(this.fitLine([{ text: "\u2191\u2193 move \xB7 enter select \xB7 esc back", paint: this.style.dim }], width));
+      return lines;
+    };
+    const move = (step) => {
+      const position = selectableIndexes.indexOf(active);
+      const next = (position + step + selectableIndexes.length) % selectableIndexes.length;
+      active = selectableIndexes[next];
+    };
+    return new Promise((resolve, reject) => {
+      const finish = () => {
+        this.keyHandler = null;
+        ttyInput.setRawMode?.(false);
+        draw([]);
+        this.output.write(`${ESC}[?25h`);
+      };
+      this.keyHandler = (key) => {
+        if (key === KEY_CTRL_C || key === KEY_CTRL_D) {
+          finish();
+          reject(new PromptClosedError());
+          return;
+        }
+        if (KEY_ENTER.includes(key) == true) {
+          const picked = items[active];
+          finish();
+          this.writeAnswered(question, picked.label);
+          resolve(picked.value);
+          return;
+        }
+        if (key === ESC) {
+          finish();
+          resolve(null);
+          return;
+        }
+        if (KEY_UP.includes(key) == true) {
+          move(-1);
+        } else if (KEY_DOWN.includes(key) == true) {
+          move(1);
+        } else if (KEY_HOME.includes(key) == true) {
+          active = selectableIndexes[0];
+        } else if (KEY_END.includes(key) == true) {
+          active = selectableIndexes[selectableIndexes.length - 1];
+        } else if (/^[1-9]$/.test(key) == true && Number(key) <= selectableIndexes.length) {
+          active = selectableIndexes[Number(key) - 1];
+        } else {
+          return;
+        }
+        draw(buildLines());
+      };
+      ttyInput.setRawMode?.(true);
+      this.output.write(`${ESC}[?25l`);
+      draw(buildLines());
+    });
+  }
+};
+
+// src/modules/launcher/menu.ts
+async function runMenu(options) {
+  let targetId = options.targetId;
+  let defaultValue = "db";
+  for (; ; ) {
+    const prompter = new Prompter(options.input, options.output);
+    let selected = "quit";
+    try {
+      for (; ; ) {
+        let clientLabel = "Automatically selected by each MCP";
+        if (targetId != null) {
+          clientLabel = CLIENT_LABELS[targetId];
+        }
+        const picked = await prompter.select("AKMS MCP \xB7 Connection setup", [
+          { value: "db", label: "Database", hint: "PostgreSQL connections" },
+          { value: "ssh", label: "SSH", hint: "Remote hosts" },
+          { value: "wsl", label: "WSL", hint: "Local Linux distros \xB7 Windows" },
+          { separator: true },
+          { value: "client", label: "Client", hint: clientLabel },
+          { value: "quit", label: "Quit" }
+        ], { defaultValue, cancelValue: "quit" });
+        if (picked !== "client") {
+          selected = picked;
+          break;
+        }
+        const clients = [
+          { value: "auto", label: "Automatic", hint: "Let each MCP detect the client" },
+          { value: "claude-code", label: CLIENT_LABELS["claude-code"] },
+          { value: "codex", label: CLIENT_LABELS.codex },
+          { value: "claude-desktop", label: CLIENT_LABELS["claude-desktop"] },
+          { value: "cursor", label: CLIENT_LABELS.cursor },
+          { separator: true },
+          { value: "back", label: "Back" }
+        ];
+        const client = await prompter.select("Client", clients, { defaultValue: targetId ?? "auto", cancelValue: "back" });
+        if (client === "auto") {
+          targetId = void 0;
+        } else if (client !== "back") {
+          targetId = client;
+        }
+      }
+    } catch (error) {
+      if (error instanceof PromptClosedError) {
+        return 0;
+      }
+      throw error;
+    } finally {
+      prompter.close();
+    }
+    if (selected === "quit") {
+      return 0;
+    }
+    defaultValue = selected;
+    try {
+      const code = await options.launch({ mcpId: selected, targetId, pendingInput: prompter.takePendingInput() });
+      if (code === 130) {
+        return 0;
+      }
+      if (code !== 0) {
+        options.output.write(`
+Setup exited with code ${code}.
+
+`);
+      }
+    } catch (error) {
+      options.output.write(`
+${String(error)}
+
+`);
+    }
+  }
+}
+
+// src/modules/launcher/npm.ts
+import { execFile, spawn } from "child_process";
+import { existsSync } from "fs";
+import { mkdtemp, realpath, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { basename, delimiter, dirname, join } from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+async function findNpmCli() {
+  const candidates = [];
+  const npmExecPath = process.env.npm_execpath;
+  if (npmExecPath != null && ["npm-cli.js", "npx-cli.js"].includes(basename(npmExecPath)) == true) {
+    candidates.push(join(dirname(npmExecPath), "npm-cli.js"));
+  }
+  candidates.push(join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js"));
+  for (const directory of (process.env.PATH ?? "").split(delimiter)) {
+    if (directory === "") {
+      continue;
+    }
+    if (process.platform === "win32") {
+      candidates.push(join(directory, "node_modules", "npm", "bin", "npm-cli.js"));
+    } else {
+      candidates.push(join(directory, "npm"));
+    }
+  }
+  for (const candidate of candidates) {
+    if (existsSync(candidate) == true) {
+      const resolved = await realpath(candidate);
+      return resolved;
+    }
+  }
+  throw new Error("npm could not be found. Install Node.js with npm, then reopen your terminal.");
+}
+async function resolveLatestVersion(options) {
+  const metadataCache = await mkdtemp(join(tmpdir(), "akms-mcp-latest-"));
+  try {
+    const result = await execFileAsync(process.execPath, [
+      options.npmCli,
+      "view",
+      `${options.packageName}@latest`,
+      "version",
+      "--json",
+      "--prefer-online",
+      "--prefer-offline=false",
+      "--offline=false",
+      "--fetch-retries=0",
+      "--fetch-timeout=15000",
+      "--update-notifier=false",
+      "--cache",
+      metadataCache
+    ], { signal: options.signal, timeout: 2e4, windowsHide: true });
+    const version = JSON.parse(result.stdout);
+    if (typeof version !== "string" || /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version) == false) {
+      throw new Error("npm returned an invalid latest version.");
+    }
+    return version;
+  } finally {
+    await rm(metadataCache, { recursive: true, force: true });
+  }
+}
+async function launchMcp(options) {
+  const selected = MCP_PACKAGES[options.mcpId];
+  if (options.mcpId === "wsl" && process.platform !== "win32") {
+    throw new Error("WSL setup must run from Windows.");
+  }
+  const npmCli = await findNpmCli();
+  const cancellation = new AbortController();
+  const cancelLookup = () => {
+    cancellation.abort();
+  };
+  process.on("SIGINT", cancelLookup);
+  process.on("SIGTERM", cancelLookup);
+  let version;
+  try {
+    process.stdout.write(`
+Checking the latest ${selected.packageName} release...
+`);
+    version = await resolveLatestVersion({ npmCli, packageName: selected.packageName, signal: cancellation.signal });
+  } catch (error) {
+    if (cancellation.signal.aborted == true) {
+      return 130;
+    }
+    throw new Error(`Could not check the latest ${selected.packageName} release; setup was not started.
+${String(error)}`, { cause: error });
+  } finally {
+    process.off("SIGINT", cancelLookup);
+    process.off("SIGTERM", cancelLookup);
+  }
+  const argumentsList = [
+    npmCli,
+    "exec",
+    "--yes",
+    "--prefer-online",
+    "--prefer-offline=false",
+    "--offline=false",
+    `--package=${selected.packageName}@${version}`,
+    "--",
+    selected.command,
+    selected.setupCommand
+  ];
+  if (options.targetId != null) {
+    argumentsList.push("--target", options.targetId);
+  }
+  process.stdout.write(`Opening ${selected.packageName} ${version}
+
+`);
+  return new Promise((resolve, reject) => {
+    const interactiveInput = process.stdin.isTTY === true;
+    let inputMode = "pipe";
+    if (interactiveInput == true) {
+      inputMode = "inherit";
+    }
+    const child = spawn(process.execPath, argumentsList, {
+      stdio: [inputMode, "inherit", "inherit"],
+      windowsHide: true
+    });
+    const interrupt = () => {
+      child.kill("SIGINT");
+    };
+    const terminate = () => {
+      child.kill("SIGTERM");
+    };
+    process.on("SIGINT", interrupt);
+    process.on("SIGTERM", terminate);
+    if (child.stdin != null) {
+      child.stdin.on("error", (error) => {
+        if (error.code !== "EPIPE" && error.code !== "ERR_STREAM_DESTROYED") {
+          reject(error);
+        }
+      });
+      if (options.pendingInput != null) {
+        child.stdin.write(options.pendingInput);
+      }
+      process.stdin.pipe(child.stdin);
+    }
+    const cleanup = () => {
+      process.off("SIGINT", interrupt);
+      process.off("SIGTERM", terminate);
+      if (child.stdin != null) {
+        process.stdin.unpipe(child.stdin);
+        process.stdin.pause();
+      }
+    };
+    child.once("error", (error) => {
+      cleanup();
+      reject(error);
+    });
+    child.once("close", (code, signal) => {
+      cleanup();
+      if (signal != null) {
+        resolve(130);
+        return;
+      }
+      resolve(code ?? 1);
+    });
+  });
+}
+
+// src/cli.ts
+var HELP_TEXT = [
+  "AKMS MCP \u2014 connection setup for Database, SSH and WSL",
+  "",
+  "Usage:",
+  "  akms-mcp                          Open the setup menu",
+  "  akms-mcp [setup|config]            Open the same menu",
+  "  akms-mcp [setup|config] <mcp>      Open db, ssh or wsl setup directly",
+  "",
+  "Options:",
+  "  --target <client>                 claude-code | codex | claude-desktop | cursor",
+  "  -h, --help                        Print this help",
+  "  -v, --version                     Print the launcher version",
+  "",
+  "Each launch checks npm for the selected package's latest release.",
+  "Node.js 22+ and npm are required. WSL setup runs on Windows."
+].join("\n");
+async function main() {
+  const argumentsList = parseArguments(process.argv.slice(2));
+  if (argumentsList.showHelp == true) {
+    process.stdout.write(`${HELP_TEXT}
+`);
+    return;
+  }
+  if (argumentsList.showVersion == true) {
+    let version = "development";
+    if (true) {
+      version = "0.1.0";
+    }
+    process.stdout.write(`${version}
+`);
+    return;
+  }
+  if (argumentsList.mcpId != null) {
+    process.exitCode = await launchMcp({ mcpId: argumentsList.mcpId, targetId: argumentsList.targetId });
+    return;
+  }
+  process.exitCode = await runMenu({
+    input: process.stdin,
+    output: process.stdout,
+    targetId: argumentsList.targetId,
+    launch: launchMcp
+  });
+}
+main().catch((error) => {
+  process.stderr.write(`akms-mcp: ${String(error)}
+`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,32 @@
 {
-  "name": "@akms/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@akms/mcp",
+    "version": "0.1.0",
+    "description": "Interactive launcher for configuring the latest AKMS database, SSH and WSL MCP servers.",
+    "keywords": ["mcp", "model-context-protocol", "cli", "setup", "akms"],
+    "license": "MIT",
+    "type": "module",
+    "bin": {
+        "akms-mcp": "lib/cli.js"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsc --noEmit && tsup",
+        "dev": "tsx src/cli.ts",
+        "start": "node lib/cli.js",
+        "pretest": "npm run build",
+        "test": "vitest run",
+        "prepack": "npm run build"
+    },
+    "devDependencies": {
+        "@types/node": "^24.19.0",
+        "tsup": "^8.5.1",
+        "tsx": "^4.23.15",
+        "typescript": "^5.9.3",
+        "vitest": "^4.1.11"
+    }
+}