mcp-fs-shell-windows 0.2.20 → 0.2.29

package/dist/compat/schema.js

@@ -0,0 +1,97 @@
+// compat/schema.ts — argument schemas for the 9 Beledarian-compatible alias tools.
+// (MCP filesystem fork v0.2.28 — Beledarian-parity project, Stage 5 / task 3.)
+//
+// Purpose: same-named drop-ins for the Beledarian plugin tools so the fork can
+// shadow/replace Beledarian with zero behavior change for existing prompts.
+// Parameter names are kept EXACTLY as Beledarian's (reference:
+// .beledarians-llm-toolbox/dev-src/beledarians-lm-studio-tools/src/toolsProvider.ts),
+// plus the fork's own optional `cwd` where noted.
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Timeout caps.
+//
+// The fork's native shell tools cap at 28 s (SHELL_MAX_TIMEOUT_SEC) to stay under
+// the MCP client's request-kill window. Beledarian's execute_command / run_python
+// / run_javascript all cap at 60 s (verified: the client window is >63 s).
+// To be a zero-behavior-change drop-in, the compat tools keep Beledarian's 60 s cap.
+// ---------------------------------------------------------------------------
+export const COMPAT_SYNC_TIMEOUT_SEC = 60; // execute_command, run_python, run_javascript
+// ---------------------------------------------------------------------------
+// execute_command — compat alias of shell_run (bounded synchronous execution),
+// with Beledarian's 60 s cap. Params match Beledarian exactly:
+//   command, input?, timeout_seconds? (reference toolsProvider.ts L1155-1176).
+// ---------------------------------------------------------------------------
+export const ExecuteCommandArgsSchema = z.object({
+    command: z.string().describe("The shell command to execute (Windows cmd.exe syntax)."),
+    input: z.string().optional().describe("Input text to pipe to the command's stdin."),
+    timeout_seconds: z.number().min(0.1).max(COMPAT_SYNC_TIMEOUT_SEC).optional().describe("Timeout in seconds (default: 5, max: 60)."),
+});
+// ---------------------------------------------------------------------------
+// run_in_terminal — compat alias of shell_terminal (visible console window).
+// Params match Beledarian exactly: command (reference L1317-1332).
+// ---------------------------------------------------------------------------
+export const RunInTerminalArgsSchema = z.object({
+    command: z.string().describe("Command to run in the new terminal window."),
+});
+// ---------------------------------------------------------------------------
+// run_test_command — compat alias of shell_test (test wrapper, CI=true, never
+// errors on a failing test). Params match Beledarian exactly: command
+// (reference L2303-2345).
+// ---------------------------------------------------------------------------
+export const RunTestCommandArgsSchema = z.object({
+    command: z.string().describe("The test command to run (e.g. 'npm test', 'pytest')."),
+});
+// ---------------------------------------------------------------------------
+// run_background_command — compat alias of shell_start (background job).
+// Beledarian: command, timeout_hours (MANDATORY, max 10), name (MANDATORY)
+// (reference L930-1010). Fork variant: name stays REQUIRED (as in Beledarian),
+// timeout_hours gets the fork's default of 10 (max 10), and the fork's cwd
+// override is available.
+// ---------------------------------------------------------------------------
+export const RunBackgroundCommandArgsSchema = z.object({
+    command: z.string().describe("The command to run as a background job (Windows cmd.exe syntax)."),
+    name: z.string().describe("MANDATORY: A short, descriptive name for the background task (e.g. 'Vite Dev Server')."),
+    timeout_hours: z.number().max(10).optional().default(10).describe("Auto-kill the job after this many hours (default 10, max 10)."),
+    cwd: z.string().optional().describe("Working directory override (default: the shell_cwd default)."),
+});
+// ---------------------------------------------------------------------------
+// check_background_command — compat alias of shell_check.
+// Params match Beledarian exactly: id (reference L1013-1033).
+// ---------------------------------------------------------------------------
+export const CheckBackgroundCommandArgsSchema = z.object({
+    id: z.string().describe("Job ID returned by run_background_command or run_in_terminal."),
+});
+// ---------------------------------------------------------------------------
+// cancel_background_command — compat alias of shell_cancel.
+// Params match Beledarian exactly: id (reference L1036-1054).
+// ---------------------------------------------------------------------------
+export const CancelBackgroundCommandArgsSchema = z.object({
+    id: z.string().describe("Job ID returned by run_background_command or run_in_terminal."),
+});
+// ---------------------------------------------------------------------------
+// run_python — compat alias of shell_python (temp .py + system python),
+// with Beledarian's 60 s cap. Beledarian params: python, timeout_seconds?
+// (reference L692-712); the fork's cwd override is available.
+// ---------------------------------------------------------------------------
+export const RunPythonArgsSchema = z.object({
+    python: z.string().describe("Python code to execute (requires system Python on PATH)."),
+    timeout_seconds: z.number().min(0.1).max(COMPAT_SYNC_TIMEOUT_SEC).optional().describe("Timeout in seconds (default: 5, max: 60)."),
+    cwd: z.string().optional().describe("Working directory override (default: the shell_cwd default)."),
+});
+// ---------------------------------------------------------------------------
+// run_javascript — the CONFINED variant (NOT an alias of run_javascript_free).
+// Beledarian params: javascript, timeout_seconds? (reference L612-633, impl
+// L544-610). No cwd param (the reference confines to its working directory,
+// which is the fork's shell_cwd default here).
+// ---------------------------------------------------------------------------
+export const RunJavascriptArgsSchema = z.object({
+    javascript: z.string().describe("JavaScript (or TypeScript) code to execute. Runs as a Deno script confined to the working directory: Deno.* APIs and console.log work; network, env, sys, run, and ffi are denied."),
+    timeout_seconds: z.number().min(0.1).max(COMPAT_SYNC_TIMEOUT_SEC).optional().describe("Timeout in seconds (default: 5, max: 60)."),
+});
+// ---------------------------------------------------------------------------
+// save_memory — STANDALONE (no fork equivalent; not an alias).
+// Beledarian param: fact (reference L509-542).
+// ---------------------------------------------------------------------------
+export const SaveMemoryArgsSchema = z.object({
+    fact: z.string().describe("The specific fact or piece of information to remember."),
+});

package/dist/gh/handler.js

@@ -0,0 +1,406 @@
+// gh/handler.ts — gh CLI wrappers for the 8 gh_* tools (MCP filesystem fork).
+//
+// Design: spawn the `gh` binary directly (no new dependency; `git push` for
+// gh_push spawns the git CLI). Every tool operates against the repo at the
+// server process's current working directory (process.cwd()) — the same
+// "current working directory context" the git/shell tools use — and takes NO
+// working-directory parameter (matching the reference Beledarian tools: the
+// reference's gh spawns inherit the plugin process cwd, and gh itself resolves
+// the repo from that cwd's git remote). All argument values (titles, bodies,
+// labels, branch names, issue/PR numbers) are passed as individual argv
+// elements (no shell), so quotes / Unicode / special characters pass through
+// verbatim. Long issue/PR bodies are written to a temp file in the working
+// directory and passed via --body-file (mirroring the reference); the temp
+// file is always removed afterwards.
+//
+// gh binary resolution (port of the reference's checkGhInstalled, with a
+// documented fallback): PATH lookup via `where gh` (win32) / `which gh` first;
+// if gh is not on the server process's PATH, fall back to the known portable
+// install <home>/tools/gh/bin/gh.exe (this machine's layout — gh 2.99.0,
+// authenticated to github.com). If neither is found, the reference's
+// "not installed" error string is returned.
+//
+// gh_auth: runs `gh auth status`; on failure it opens a detached terminal
+// window (cmd /k) for interactive `gh auth login --git-protocol=https` exactly
+// as the reference does — spawned with {detached: true, stdio: "ignore"} so it
+// survives the MCP call returning, using the RESOLVED gh path so the window
+// works even when gh is not on the inherited PATH. The window persists for the
+// user (cmd /k) and can be closed manually.
+//
+// Return shape mirrors the reference implementation: each handler returns a JSON
+// text string carrying the reference's fields ({success, ...} / {error} /
+// {issues} / {pull_requests} / {comments} / {diff} / raw_output) instead of
+// throwing, so a missing gh, a bad remote, or a bad branch yields a clear
+// structured error string rather than a crash or hang.
+import { spawn } from "child_process";
+import fs from "fs";
+import nodeOs from "os";
+import nodePath from "path";
+/** Run `<bin> <args>` with the given cwd. Never rejects; spawn failures resolve with code -1. */
+function runCmd(bin, args, cwd) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(bin, args, { cwd });
+        }
+        catch (e) {
+            resolve({ code: -1, stdout: "", stderr: e instanceof Error ? e.message : String(e) });
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ code, stdout, stderr });
+        };
+        if (child.stdout) {
+            child.stdout.on("data", (d) => {
+                stdout += d.toString("utf8");
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on("data", (d) => {
+                stderr += d.toString("utf8");
+            });
+        }
+        child.on("error", (e) => {
+            // e.g. ENOENT when the binary cannot be found
+            stderr += (stderr ? "\n" : "") + (e.message || String(e));
+            finish(-1);
+        });
+        child.on("close", (code) => finish(code === null ? -1 : code));
+    });
+}
+/** Run a shell one-liner (e.g. `where gh`). Never rejects. */
+function runShellLine(cmd) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(cmd, [], { shell: true });
+        }
+        catch (e) {
+            resolve({ code: -1, stdout: "", stderr: e instanceof Error ? e.message : String(e) });
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve({ code, stdout, stderr });
+        };
+        if (child.stdout) {
+            child.stdout.on("data", (d) => {
+                stdout += d.toString("utf8");
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on("data", (d) => {
+                stderr += d.toString("utf8");
+            });
+        }
+        child.on("error", (e) => {
+            stderr += (stderr ? "\n" : "") + (e.message || String(e));
+            finish(-1);
+        });
+        child.on("close", (code) => finish(code === null ? -1 : code));
+    });
+}
+const GH_NOT_INSTALLED = "GitHub CLI ('gh') is not installed. Please ask the user to install it from https://cli.github.com/";
+/** Absolute path of gh on the PATH (first hit of `where gh` / `which gh`), or null. */
+async function findGhOnPath() {
+    const r = await runShellLine(process.platform === "win32" ? "where gh" : "which gh");
+    if (!r.stdout.trim())
+        return null;
+    const first = r.stdout
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .find((s) => s.length > 0);
+    if (!first)
+        return null;
+    try {
+        if (fs.existsSync(first))
+            return first;
+    }
+    catch {
+        // fall through
+    }
+    return null;
+}
+/** Known portable-install locations, checked in order (documented fallback). */
+function findGhKnownPaths() {
+    const home = nodeOs.homedir();
+    const candidates = [nodePath.join(home, "tools", "gh", "bin", "gh.exe")];
+    for (const c of candidates) {
+        try {
+            if (fs.existsSync(c))
+                return c;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return null;
+}
+/** Resolve the gh executable (absolute path): PATH first, then known portable install; null if absent. */
+async function resolveGh() {
+    const onPath = await findGhOnPath();
+    if (onPath)
+        return onPath;
+    return findGhKnownPaths();
+}
+/** The repo context for all gh_* tools: the server process's current working directory. */
+function ghCwd() {
+    return process.cwd();
+}
+/** Detail text for a non-zero exit: stderr first, then stdout, then the exit code. */
+function detail(out) {
+    return out.stderr.trim() || out.stdout.trim() || `gh exited with code ${out.code}`;
+}
+// ---------------------------------------------------------------- gh_auth
+export async function handleGhAuth() {
+    const dir = ghCwd();
+    const ghBin = await resolveGh();
+    if (!ghBin)
+        return JSON.stringify({ error: GH_NOT_INSTALLED });
+    try {
+        const st = await runCmd(ghBin, ["auth", "status"], dir);
+        if (st.code === 0) {
+            return JSON.stringify({ success: true, message: "Already authenticated with GitHub." });
+        }
+        // Not authenticated: open a detached terminal window for interactive login,
+        // exactly as the reference does. The window is spawned detached with ignored
+        // stdio so it outlives this call; cmd /k keeps it open for the user.
+        // The resolved absolute gh path is used so the window works even when gh is
+        // not on the server process's PATH.
+        const escapedDir = dir.replace(/"/g, '""');
+        const shellCommand = `start "" /D "${escapedDir}" cmd.exe /k "${ghBin} auth login --git-protocol=https & exit"`;
+        try {
+            spawn("cmd.exe", ["/c", shellCommand], { detached: true, stdio: "ignore", cwd: dir });
+        }
+        catch (e) {
+            return JSON.stringify({
+                error: `Auth check failed: ${e instanceof Error ? e.message : String(e)}`,
+            });
+        }
+        return JSON.stringify({
+            success: true,
+            message: "Opened a terminal window for GitHub authentication. Please sign in there.",
+        });
+    }
+    catch (e) {
+        return JSON.stringify({ error: `Auth check failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
+// ----------------------------------------------------------- gh_create_issue
+export async function handleGhCreateIssue(title, body, labels) {
+    const dir = ghCwd();
+    const ghBin = await resolveGh();
+    if (!ghBin)
+        return JSON.stringify({ error: GH_NOT_INSTALLED });
+    try {
+        let tempFilePath = "";
+        const ghArgs = ["issue", "create", "--title", title];
+        if (body) {
+            tempFilePath = nodePath.join(dir, `gh_issue_body_${Date.now()}.md`);
+            fs.writeFileSync(tempFilePath, body, "utf-8");
+            ghArgs.push("--body-file", tempFilePath);
+        }
+        if (labels) {
+            for (const label of labels) {
+                ghArgs.push("-l", label);
+            }
+        }
+        const out = await runCmd(ghBin, ghArgs, dir);
+        if (tempFilePath) {
+            try {
+                fs.rmSync(tempFilePath, { force: true });
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+        if (out.code === 0)
+            return JSON.stringify({ success: true, url: out.stdout.trim() });
+        return JSON.stringify({ error: `Failed to create issue: ${detail(out)}` });
+    }
+    catch (e) {
+        return JSON.stringify({ error: `Create issue failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
+// ------------------------------------------------------------ gh_list_issues
+export async function handleGhListIssues(state, labels, limit) {
+    const dir = ghCwd();
+    const ghBin = await resolveGh();
+    if (!ghBin)
+        return JSON.stringify({ error: GH_NOT_INSTALLED });
+    const st = state ?? "open";
+    const lim = typeof limit === "number" && Number.isFinite(limit) && limit >= 1
+        ? Math.min(50, Math.floor(limit))
+        : 10;
+    try {
+        const ghArgs = [
+            "issue",
+            "list",
+            "--state",
+            st,
+            "--limit",
+            String(lim),
+            "--json",
+            "number,title,state,url,labels",
+        ];
+        if (labels) {
+            for (const label of labels) {
+                ghArgs.push("-l", label);
+            }
+        }
+        const out = await runCmd(ghBin, ghArgs, dir);
+        if (out.code === 0) {
+            try {
+                return JSON.stringify({ issues: JSON.parse(out.stdout) });
+            }
+            catch {
+                return JSON.stringify({ error: "Failed to parse issue list output" });
+            }
+        }
+        return JSON.stringify({ error: `List issues failed: ${detail(out)}` });
+    }
+    catch (e) {
+        return JSON.stringify({ error: `List issues failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
+// ---------------------------------------------------------- gh_view_comments
+export async function handleGhViewComments(number, type) {
+    const dir = ghCwd();
+    const ghBin = await resolveGh();
+    if (!ghBin)
+        return JSON.stringify({ error: GH_NOT_INSTALLED });
+    try {
+        // Fallback to standard gh command for reliable JSON parsing of comments
+        const ghArgs = type === "pr"
+            ? ["pr", "view", String(number), "--json", "comments"]
+            : ["issue", "view", String(number), "--json", "comments"];
+        const out = await runCmd(ghBin, ghArgs, dir);
+        if (out.code === 0) {
+            try {
+                const data = JSON.parse(out.stdout);
+                return JSON.stringify({ comments: data.comments || [] });
+            }
+            catch {
+                return JSON.stringify({ raw_output: out.stdout });
+            }
+        }
+        return JSON.stringify({ error: `View comments failed: ${detail(out)}` });
+    }
+    catch (e) {
+        return JSON.stringify({ error: `View comments failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
+// ------------------------------------------------------------- gh_create_pr
+export async function handleGhCreatePr(title, body, head_branch, base_branch) {
+    const dir = ghCwd();
+    const ghBin = await resolveGh();
+    if (!ghBin)
+        return JSON.stringify({ error: GH_NOT_INSTALLED });
+    const base = base_branch || "main";
+    try {
+        let tempFilePath = "";
+        const ghArgs = ["pr", "create", "--title", title, "--head", head_branch, "--base", base];
+        if (body) {
+            tempFilePath = nodePath.join(dir, `gh_pr_body_${Date.now()}.md`);
+            fs.writeFileSync(tempFilePath, body, "utf-8");
+            ghArgs.push("--body-file", tempFilePath);
+        }
+        const out = await runCmd(ghBin, ghArgs, dir);
+        if (tempFilePath) {
+            try {
+                fs.rmSync(tempFilePath, { force: true });
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+        if (out.code === 0)
+            return JSON.stringify({ success: true, url: out.stdout.trim() });
+        return JSON.stringify({ error: `Failed to create PR: ${detail(out)}` });
+    }
+    catch (e) {
+        return JSON.stringify({ error: `Create PR failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
+// -------------------------------------------------------------- gh_list_prs
+export async function handleGhListPrs(state, limit) {
+    const dir = ghCwd();
+    const ghBin = await resolveGh();
+    if (!ghBin)
+        return JSON.stringify({ error: GH_NOT_INSTALLED });
+    const st = state ?? "open";
+    const lim = typeof limit === "number" && Number.isFinite(limit) && limit >= 1
+        ? Math.min(50, Math.floor(limit))
+        : 10;
+    try {
+        const ghArgs = [
+            "pr",
+            "list",
+            "--state",
+            st,
+            "--limit",
+            String(lim),
+            "--json",
+            "number,title,state,url,headRefName,baseRefName",
+        ];
+        const out = await runCmd(ghBin, ghArgs, dir);
+        if (out.code === 0) {
+            try {
+                return JSON.stringify({ pull_requests: JSON.parse(out.stdout) });
+            }
+            catch {
+                return JSON.stringify({ error: "Failed to parse PR list output" });
+            }
+        }
+        return JSON.stringify({ error: `List PRs failed: ${detail(out)}` });
+    }
+    catch (e) {
+        return JSON.stringify({ error: `List PRs failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
+// ---------------------------------------------------------- gh_view_pr_diff
+export async function handleGhViewPrDiff(number) {
+    const dir = ghCwd();
+    const ghBin = await resolveGh();
+    if (!ghBin)
+        return JSON.stringify({ error: GH_NOT_INSTALLED });
+    try {
+        const out = await runCmd(ghBin, ["pr", "diff", String(number)], dir);
+        if (out.code === 0) {
+            return JSON.stringify({
+                diff: out.stdout.substring(0, 50000) + (out.stdout.length > 50000 ? "\n... (truncated)" : ""),
+            });
+        }
+        return JSON.stringify({ error: `Fetch PR diff failed: ${detail(out)}` });
+    }
+    catch (e) {
+        return JSON.stringify({ error: `Fetch PR diff failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}
+// ----------------------------------------------------------------- gh_push
+export async function handleGhPush(branch) {
+    const dir = ghCwd();
+    try {
+        const gitArgs = ["push", "origin"];
+        if (branch)
+            gitArgs.push(branch);
+        const out = await runCmd("git", gitArgs, dir);
+        if (out.code === 0)
+            return JSON.stringify({ success: true, message: "Pushed successfully." });
+        return JSON.stringify({ error: `Git push failed: ${detail(out)}` });
+    }
+    catch (e) {
+        return JSON.stringify({ error: `Git push failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}

package/dist/gh/schema.js

@@ -0,0 +1,36 @@
+// gh/schema.ts — argument schemas for the 8 gh_* tools.
+// (MCP filesystem fork; thin gh CLI wrappers that operate against the repo at the
+// server process's current working directory — no working-directory parameter, same
+// "current working directory context" as the git/shell tools.)
+import { z } from "zod";
+export const GhAuthArgsSchema = z.object({});
+export const GhCreateIssueArgsSchema = z.object({
+    title: z.string(),
+    body: z.string().optional(),
+    labels: z.array(z.string()).optional(),
+});
+export const GhListIssuesArgsSchema = z.object({
+    state: z.enum(["open", "closed"]).optional().default("open"),
+    labels: z.array(z.string()).optional(),
+    limit: z.number().min(1).max(50).optional().default(10),
+});
+export const GhViewCommentsArgsSchema = z.object({
+    number: z.number().describe("The issue or PR number"),
+    type: z.enum(["issue", "pr"]).default("issue").describe("Whether it's an issue or a pull request"),
+});
+export const GhCreatePrArgsSchema = z.object({
+    title: z.string(),
+    body: z.string().optional(),
+    head_branch: z.string().describe("The branch containing your changes"),
+    base_branch: z.string().default("main").describe("The branch you want to merge into (e.g., main, master)"),
+});
+export const GhListPrsArgsSchema = z.object({
+    state: z.enum(["open", "closed"]).optional().default("open"),
+    limit: z.number().min(1).max(50).optional().default(10),
+});
+export const GhViewPrDiffArgsSchema = z.object({
+    number: z.number().describe("The PR number"),
+});
+export const GhPushArgsSchema = z.object({
+    branch: z.string().optional().describe("Optional: The branch to push. Defaults to current branch."),
+});