webtool-log-cleaner-mcp 1.0.0 → 1.0.1

package/README.md

@@ -68,9 +68,95 @@ Notes:
 - The npm wrapper still needs Python 3.11+ installed.
 - On first run, it bootstraps the Python package with `pip --user` if missing.
 
+## Automatic MCP client installation
+
+Use the installer to configure one or many clients automatically.
+
+Interactive:
+
+```bash
+npx -y webtool-log-cleaner-mcp install
+```
+
+Non-interactive user-scope install:
+
+```bash
+npx -y webtool-log-cleaner-mcp install --clients codex,cursor,claude-desktop
+```
+
+Project-scope install for shareable repo config files:
+
+```bash
+npx -y webtool-log-cleaner-mcp install --scope project --clients cursor,claude-code,vscode
+```
+
+List supported clients:
+
+```bash
+npx -y webtool-log-cleaner-mcp install --list-clients
+```
+
+You can also use the dedicated global command after `npm i -g webtool-log-cleaner-mcp`:
+
+```bash
+webtool-log-cleaner-install --clients all
+```
+
+Current supported clients:
+- `codex`
+- `cursor`
+- `claude-desktop`
+- `claude-code`
+- `gemini-cli`
+- `qwen-code`
+- `vscode`
+
+Scope support:
+- `user`: all listed clients
+- `project`: `cursor`, `claude-code`, `vscode`
+
+Project-scope outputs:
+- Cursor: `.cursor/mcp.json`
+- Claude Code: `.mcp.json`
+- VS Code: `.vscode/mcp.json`
+
+Notes:
+- VS Code user installs use `code --add-mcp` when the CLI is available and otherwise write the user-level `mcp.json` file directly.
+- Windows launchers use `cmd /c npx -y webtool-log-cleaner-mcp` so stdio clients can start the npm wrapper reliably.
+
+## Shareable MCP Bundle
+
+This repo also includes an MCP Bundle manifest so you can package the server into a single `.mcpb` artifact for one-click distribution in bundle-aware clients.
+
+Build the bundle locally:
+
+```bash
+python3 scripts/build_mcpb.py
+```
+
+Or:
+
+```bash
+npm run bundle:mcpb
+```
+
+Output:
+
+```text
+dist/webtool-log-cleaner-1.0.1.mcpb
+```
+
+Bundle contents:
+- `manifest.json`
+- `pyproject.toml`
+- `uv.lock`
+- `README.md`
+- `src/webtool_log_cleaner/**`
+
 ## Local development
 
 ```bash
+node --test tests/*.test.cjs
 uv run pytest -q
 uv run webtool-log-cleaner
 ```

package/bin/install-mcp-clients.cjs

@@ -0,0 +1,648 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const readline = require("node:readline/promises");
+const { stdin, stdout } = require("node:process");
+
+const SERVER_KEY = "webtool-log-cleaner";
+const SERVER_PACKAGE = "webtool-log-cleaner-mcp";
+const DEFAULT_SCOPE = "user";
+
+const CLIENTS = [
+  {
+    id: "codex",
+    name: "OpenAI Codex CLI",
+    scopes: ["user"],
+    install: installCodex,
+  },
+  {
+    id: "cursor",
+    name: "Cursor",
+    scopes: ["user", "project"],
+    install: installCursor,
+  },
+  {
+    id: "claude-desktop",
+    name: "Claude Desktop",
+    scopes: ["user"],
+    install: installClaudeDesktop,
+  },
+  {
+    id: "claude-code",
+    name: "Claude Code",
+    scopes: ["user", "project"],
+    install: installClaudeCode,
+  },
+  {
+    id: "gemini-cli",
+    name: "Gemini CLI",
+    scopes: ["user"],
+    install: installGemini,
+  },
+  {
+    id: "qwen-code",
+    name: "Qwen Code",
+    scopes: ["user"],
+    install: installQwen,
+  },
+  {
+    id: "vscode",
+    name: "VS Code",
+    scopes: ["user", "project"],
+    install: installVsCode,
+  },
+];
+
+function log(message) {
+  stdout.write(`${message}\n`);
+}
+
+function error(message) {
+  stdout.write(`[error] ${message}\n`);
+}
+
+function expandHome(filePath) {
+  if (!filePath) {
+    return filePath;
+  }
+
+  if (filePath.startsWith("~")) {
+    return path.join(os.homedir(), filePath.slice(1));
+  }
+
+  return filePath;
+}
+
+function ensureParentDirectory(targetPath) {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+}
+
+function resolveProjectPath(projectPath) {
+  const resolved = path.resolve(projectPath || process.cwd());
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isDirectory()) {
+    throw new Error(`project path must be an existing directory: ${resolved}`);
+  }
+  return resolved;
+}
+
+function getLauncher(platform = process.platform) {
+  if (platform === "win32") {
+    return {
+      command: "cmd",
+      args: ["/c", "npx", "-y", SERVER_PACKAGE],
+    };
+  }
+
+  return {
+    command: "npx",
+    args: ["-y", SERVER_PACKAGE],
+  };
+}
+
+function getStdioServerConfig(options = {}) {
+  const launcher = getLauncher(options.platform);
+  if (options.includeType) {
+    return {
+      type: "stdio",
+      ...launcher,
+    };
+  }
+  return launcher;
+}
+
+function writeJsonConfig(targetPath, updater) {
+  const resolved = expandHome(targetPath);
+  let data = {};
+
+  if (fs.existsSync(resolved)) {
+    const raw = fs.readFileSync(resolved, "utf-8").trim();
+    if (raw) {
+      data = JSON.parse(raw);
+    }
+  }
+
+  const next = updater(data);
+  ensureParentDirectory(resolved);
+  fs.writeFileSync(resolved, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+  return resolved;
+}
+
+function upsertTomlSection(content, header, block) {
+  const lines = content.length > 0 ? content.split(/\r?\n/) : [];
+  const startIndex = lines.findIndex((line) => line.trim() === header);
+
+  if (startIndex >= 0) {
+    let endIndex = lines.length;
+    for (let i = startIndex + 1; i < lines.length; i += 1) {
+      if (lines[i].trim().startsWith("[")) {
+        endIndex = i;
+        break;
+      }
+    }
+
+    return [
+      ...lines.slice(0, startIndex),
+      ...block.split("\n"),
+      ...lines.slice(endIndex),
+    ].join("\n");
+  }
+
+  let next = content;
+  if (next.trim().length > 0 && !next.endsWith("\n")) {
+    next += "\n";
+  }
+  if (next.trim().length > 0) {
+    next += "\n";
+  }
+  next += `${block}\n`;
+  return next;
+}
+
+function getVsCodeUserConfigPath(platform = process.platform, env = process.env) {
+  if (platform === "darwin") {
+    return "~/Library/Application Support/Code/User/mcp.json";
+  }
+
+  if (platform === "win32") {
+    const appData = env.APPDATA;
+    if (!appData) {
+      throw new Error("APPDATA is not set; cannot resolve VS Code MCP config path.");
+    }
+    return path.win32.join(appData, "Code", "User", "mcp.json");
+  }
+
+  return "~/.config/Code/User/mcp.json";
+}
+
+function getProjectClientConfigPath(clientId, projectPath) {
+  if (clientId === "cursor") {
+    return path.join(projectPath, ".cursor", "mcp.json");
+  }
+  if (clientId === "claude-code") {
+    return path.join(projectPath, ".mcp.json");
+  }
+  if (clientId === "vscode") {
+    return path.join(projectPath, ".vscode", "mcp.json");
+  }
+  return null;
+}
+
+function unsupportedScope(client, scope) {
+  return {
+    ok: false,
+    message: `${client.name} only supports ${client.scopes.join("/")} installs.`,
+  };
+}
+
+function installCursor(options) {
+  const target = options.scope === "project"
+    ? getProjectClientConfigPath("cursor", options.projectPath)
+    : "~/.cursor/mcp.json";
+  const serverConfig = getStdioServerConfig({ includeType: true });
+
+  const location = writeJsonConfig(target, (config) => {
+    const next = { ...(config || {}) };
+    next.mcpServers = { ...(next.mcpServers || {}) };
+    next.mcpServers[SERVER_KEY] = serverConfig;
+    return next;
+  });
+
+  return { ok: true, message: `Updated ${location}` };
+}
+
+function installClaudeDesktop(options) {
+  if (options.scope !== "user") {
+    return unsupportedScope(CLIENTS.find((client) => client.id === "claude-desktop"), options.scope);
+  }
+
+  let target;
+  if (process.platform === "darwin") {
+    target = "~/Library/Application Support/Claude/claude_desktop_config.json";
+  } else if (process.platform === "win32") {
+    const appData = process.env.APPDATA;
+    if (!appData) {
+      return { ok: false, message: "APPDATA is not set; cannot resolve Claude Desktop config path." };
+    }
+    target = path.join(appData, "Claude", "claude_desktop_config.json");
+  } else {
+    target = "~/.config/Claude/claude_desktop_config.json";
+  }
+
+  const serverConfig = getStdioServerConfig();
+  const location = writeJsonConfig(target, (config) => {
+    const next = { ...(config || {}) };
+    next.mcpServers = { ...(next.mcpServers || {}) };
+    next.mcpServers[SERVER_KEY] = serverConfig;
+    return next;
+  });
+
+  return { ok: true, message: `Updated ${location}` };
+}
+
+function installGemini(options) {
+  if (options.scope !== "user") {
+    return unsupportedScope(CLIENTS.find((client) => client.id === "gemini-cli"), options.scope);
+  }
+
+  const serverConfig = getStdioServerConfig();
+  const location = writeJsonConfig("~/.gemini/settings.json", (config) => {
+    const next = { ...(config || {}) };
+    next.mcpServers = { ...(next.mcpServers || {}) };
+    next.mcpServers[SERVER_KEY] = serverConfig;
+    return next;
+  });
+
+  return { ok: true, message: `Updated ${location}` };
+}
+
+function installQwen(options) {
+  if (options.scope !== "user") {
+    return unsupportedScope(CLIENTS.find((client) => client.id === "qwen-code"), options.scope);
+  }
+
+  const serverConfig = getStdioServerConfig();
+  const location = writeJsonConfig("~/.qwen/settings.json", (config) => {
+    const next = { ...(config || {}) };
+    next.mcpServers = { ...(next.mcpServers || {}) };
+    next.mcpServers[SERVER_KEY] = serverConfig;
+    return next;
+  });
+
+  return { ok: true, message: `Updated ${location}` };
+}
+
+function installVsCodeProject(options) {
+  const target = getProjectClientConfigPath("vscode", options.projectPath);
+  const serverConfig = getStdioServerConfig({ includeType: true });
+
+  const location = writeJsonConfig(target, (config) => {
+    const next = { ...(config || {}) };
+    next.servers = { ...(next.servers || {}) };
+    next.servers[SERVER_KEY] = serverConfig;
+    return next;
+  });
+
+  return { ok: true, message: `Updated ${location}` };
+}
+
+function installVsCodeUser() {
+  const serverConfig = {
+    name: SERVER_KEY,
+    ...getStdioServerConfig({ includeType: true }),
+  };
+
+  const cliResult = spawnSync("code", ["--add-mcp", JSON.stringify(serverConfig)], {
+    stdio: "inherit",
+  });
+
+  if (!cliResult.error && cliResult.status === 0) {
+    return { ok: true, message: "Added server via `code --add-mcp ...`" };
+  }
+
+  if (cliResult.error && cliResult.error.code !== "ENOENT") {
+    return {
+      ok: false,
+      message: `VS Code CLI failed: ${cliResult.error.message}`,
+    };
+  }
+
+  let target;
+  try {
+    target = getVsCodeUserConfigPath();
+  } catch (err) {
+    return { ok: false, message: err.message };
+  }
+
+  const location = writeJsonConfig(target, (config) => {
+    const next = { ...(config || {}) };
+    next.servers = { ...(next.servers || {}) };
+    next.servers[SERVER_KEY] = getStdioServerConfig({ includeType: true });
+    return next;
+  });
+
+  return { ok: true, message: `Updated ${location}` };
+}
+
+function installVsCode(options) {
+  if (options.scope === "project") {
+    return installVsCodeProject(options);
+  }
+  return installVsCodeUser();
+}
+
+function installCodex(options) {
+  if (options.scope !== "user") {
+    return unsupportedScope(CLIENTS.find((client) => client.id === "codex"), options.scope);
+  }
+
+  const target = expandHome("~/.codex/config.toml");
+  ensureParentDirectory(target);
+
+  const launcher = getLauncher();
+  const header = `[mcp_servers.${SERVER_KEY}]`;
+  const block = [
+    header,
+    `command = "${launcher.command}"`,
+    `args = [${launcher.args.map((value) => JSON.stringify(value)).join(", ")}]`,
+    "startup_timeout_ms = 40_000",
+  ].join("\n");
+
+  let content = "";
+  if (fs.existsSync(target)) {
+    content = fs.readFileSync(target, "utf-8");
+  }
+
+  let nextContent = upsertTomlSection(content, header, block);
+  if (!nextContent.endsWith("\n")) {
+    nextContent += "\n";
+  }
+
+  fs.writeFileSync(target, nextContent, "utf-8");
+  return { ok: true, message: `Updated ${target}` };
+}
+
+function installClaudeCodeUser() {
+  const launcher = getLauncher();
+  const command = [
+    "mcp",
+    "add",
+    "--scope",
+    "user",
+    SERVER_KEY,
+    "--",
+    launcher.command,
+    ...launcher.args,
+  ];
+
+  const result = spawnSync("claude", command, {
+    stdio: "inherit",
+  });
+
+  if (result.error) {
+    if (result.error.code === "ENOENT") {
+      return {
+        ok: false,
+        message: "`claude` CLI not found. Install Claude Code CLI or configure manually.",
+      };
+    }
+
+    return {
+      ok: false,
+      message: `Claude Code CLI failed: ${result.error.message}`,
+    };
+  }
+
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      message: "`claude mcp add --scope user ...` failed. Run it manually to inspect CLI output.",
+    };
+  }
+
+  return { ok: true, message: "Added server via `claude mcp add --scope user ...`" };
+}
+
+function installClaudeCodeProject(options) {
+  const target = getProjectClientConfigPath("claude-code", options.projectPath);
+  const serverConfig = getStdioServerConfig();
+
+  const location = writeJsonConfig(target, (config) => {
+    const next = { ...(config || {}) };
+    next.mcpServers = { ...(next.mcpServers || {}) };
+    next.mcpServers[SERVER_KEY] = serverConfig;
+    return next;
+  });
+
+  return { ok: true, message: `Updated ${location}` };
+}
+
+function installClaudeCode(options) {
+  if (options.scope === "project") {
+    return installClaudeCodeProject(options);
+  }
+
+  return installClaudeCodeUser();
+}
+
+function parseClientSelection(raw) {
+  const input = (raw || "").trim();
+  if (!input || input.toLowerCase() === "all") {
+    return CLIENTS.map((client) => client.id);
+  }
+
+  const tokens = input
+    .split(/[\s,]+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+
+  const ids = new Set();
+  for (const token of tokens) {
+    const maybeIndex = Number(token);
+    if (Number.isInteger(maybeIndex) && maybeIndex >= 1 && maybeIndex <= CLIENTS.length) {
+      ids.add(CLIENTS[maybeIndex - 1].id);
+      continue;
+    }
+
+    const byId = CLIENTS.find((client) => client.id === token);
+    if (byId) {
+      ids.add(byId.id);
+      continue;
+    }
+
+    throw new Error(`Unknown client selector: ${token}`);
+  }
+
+  return Array.from(ids);
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    list: false,
+    clients: null,
+    projectPath: process.cwd(),
+    scope: DEFAULT_SCOPE,
+    yes: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--list-clients") {
+      parsed.list = true;
+      continue;
+    }
+
+    if (arg === "--yes" || arg === "-y") {
+      parsed.yes = true;
+      continue;
+    }
+
+    if (arg.startsWith("--clients=")) {
+      parsed.clients = arg.split("=", 2)[1] || "";
+      continue;
+    }
+
+    if (arg === "--clients") {
+      parsed.clients = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--scope=")) {
+      parsed.scope = arg.split("=", 2)[1] || "";
+      continue;
+    }
+
+    if (arg === "--scope") {
+      parsed.scope = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith("--project-path=")) {
+      parsed.projectPath = arg.split("=", 2)[1] || "";
+      continue;
+    }
+
+    if (arg === "--project-path") {
+      parsed.projectPath = argv[index + 1] || "";
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (!["user", "project"].includes(parsed.scope)) {
+    throw new Error(`Unknown scope: ${parsed.scope}`);
+  }
+
+  return parsed;
+}
+
+function printClients() {
+  log("Supported clients:");
+  CLIENTS.forEach((client, idx) => {
+    log(`${idx + 1}. ${client.name} (${client.id}) [${client.scopes.join("/")}]`);
+  });
+}
+
+async function promptForClients() {
+  printClients();
+  log("");
+  log("Select one, many, or all clients.");
+  log("Examples: `1`, `1,3,5`, `codex,cursor`, or `all`");
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    return await rl.question("Clients to configure: ");
+  } finally {
+    rl.close();
+  }
+}
+
+async function runInstall(argv = []) {
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (err) {
+    error(err.message);
+    return 1;
+  }
+
+  if (parsed.list) {
+    printClients();
+    return 0;
+  }
+
+  let selectedRaw = parsed.clients;
+  if (!selectedRaw && !parsed.yes) {
+    selectedRaw = await promptForClients();
+  }
+
+  if (!selectedRaw && parsed.yes) {
+    selectedRaw = "all";
+  }
+
+  let selectedIds;
+  try {
+    selectedIds = parseClientSelection(selectedRaw || "all");
+  } catch (err) {
+    error(err.message);
+    return 1;
+  }
+
+  const selectedClients = CLIENTS.filter((client) => selectedIds.includes(client.id));
+  if (selectedClients.length === 0) {
+    error("No clients selected.");
+    return 1;
+  }
+
+  let projectPath;
+  try {
+    projectPath = resolveProjectPath(parsed.projectPath);
+  } catch (err) {
+    error(err.message);
+    return 1;
+  }
+
+  log(
+    `Installing ${SERVER_KEY} MCP config into ${selectedClients.length} client(s) ` +
+    `with scope=${parsed.scope}...`
+  );
+
+  let failures = 0;
+  for (const client of selectedClients) {
+    try {
+      if (!client.scopes.includes(parsed.scope)) {
+        failures += 1;
+        log(`- ${client.name}: FAILED (${client.name} does not support scope=${parsed.scope})`);
+        continue;
+      }
+
+      const result = client.install({
+        projectPath,
+        scope: parsed.scope,
+      });
+
+      if (result.ok) {
+        log(`- ${client.name}: OK (${result.message})`);
+      } else {
+        failures += 1;
+        log(`- ${client.name}: FAILED (${result.message})`);
+      }
+    } catch (err) {
+      failures += 1;
+      log(`- ${client.name}: FAILED (${err.message})`);
+    }
+  }
+
+  if (failures > 0) {
+    error(`${failures} client install(s) failed.`);
+    return 1;
+  }
+
+  log("All selected clients updated.");
+  return 0;
+}
+
+if (require.main === module) {
+  runInstall(process.argv.slice(2)).then((code) => {
+    process.exit(code);
+  });
+}
+
+module.exports = {
+  CLIENTS,
+  getLauncher,
+  getProjectClientConfigPath,
+  getStdioServerConfig,
+  getVsCodeUserConfigPath,
+  parseArgs,
+  parseClientSelection,
+  runInstall,
+  upsertTomlSection,
+};

package/bin/webtool-log-cleaner-mcp.cjs

@@ -59,9 +59,9 @@ function selectPython() {
 
   for (const candidate of candidates) {
     const probe = spawnSync(candidate.command, [...candidate.baseArgs, "--version"], {
-      stdio: "ignore",
+      encoding: "utf-8",
     });
-    if (probe.status === 0) {
+    if (probe.status === 0 && isSupportedPythonVersion(probe.stdout, probe.stderr)) {
       return candidate;
     }
   }
@@ -69,6 +69,18 @@ function selectPython() {
   return null;
 }
 
+function isSupportedPythonVersion(stdout = "", stderr = "") {
+  const text = `${stdout || ""} ${stderr || ""}`.trim();
+  const match = text.match(/Python\s+(\d+)\.(\d+)(?:\.(\d+))?/i);
+  if (!match) {
+    return false;
+  }
+
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  return major > 3 || (major === 3 && minor >= 11);
+}
+
 function ensurePythonPackageInstalled(python) {
   const importProbe = spawnSync(
     python.command,
@@ -153,6 +165,14 @@ function launchServer(python, forwardedArgs, envOverrides) {
 }
 
 function main() {
+  if (args[0] === "install") {
+    const installer = require("./install-mcp-clients.cjs");
+    installer.runInstall(args.slice(1)).then((code) => {
+      process.exit(code);
+    });
+    return;
+  }
+
   const python = selectPython();
   if (!python) {
     fail("Python 3.11+ is required but was not found in PATH.");

package/package.json

@@ -1,12 +1,18 @@
 {
   "name": "webtool-log-cleaner-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "npx launcher for the Python webtool-log-cleaner MCP server",
+  "scripts": {
+    "bundle:mcpb": "python3 scripts/build_mcpb.py",
+    "test:node": "node --test tests/*.test.cjs"
+  },
   "bin": {
-    "webtool-log-cleaner-mcp": "bin/webtool-log-cleaner-mcp.cjs"
+    "webtool-log-cleaner-mcp": "bin/webtool-log-cleaner-mcp.cjs",
+    "webtool-log-cleaner-install": "bin/install-mcp-clients.cjs"
   },
   "files": [
     "bin/webtool-log-cleaner-mcp.cjs",
+    "bin/install-mcp-clients.cjs",
     "README.md"
   ],
   "license": "MIT",