mcp-fs-shell-windows 0.2.19 → 0.2.29

package/dist/query_database/handler.js

@@ -0,0 +1,27 @@
+// query_database/handler.ts — read-only SQLite queries (MCP filesystem fork).
+//
+// Port of the Beledarian query_database tool (beledarians-lm-studio-tools
+// src/toolsProvider.ts), with one substitution: the reference uses the native
+// better-sqlite3 module; this fork runs on system Node which ships the built-in
+// node:sqlite module (DatabaseSync), so no native dependency is added. Same
+// behavior: naive write-statement block, open READONLY, prepare + all(), close,
+// return { results } or { error }.
+import { DatabaseSync } from "node:sqlite";
+import { validatePath } from "../helpers/path.js";
+export async function handleQueryDatabase(dbPath, query, allowedDirectories) {
+    const fpath = await validatePath(dbPath, allowedDirectories);
+    // Safety: Attempt to block write operations (naive check)
+    if (/^\s*(INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|REPLACE)\b/i.test(query)) {
+        return JSON.stringify({ error: "Only SELECT/read queries are allowed for safety." });
+    }
+    try {
+        const db = new DatabaseSync(fpath, { readOnly: true });
+        const stmt = db.prepare(query);
+        const results = stmt.all();
+        db.close();
+        return JSON.stringify({ results });
+    }
+    catch (e) {
+        return JSON.stringify({ error: `Database query failed: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}

package/dist/query_database/schema.js

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export const QueryDatabaseArgsSchema = z.object({
+    db_path: z.string(),
+    query: z.string(),
+});

package/dist/rag/handler.js

@@ -0,0 +1,103 @@
+// rag/handler.ts — RAG tools (MCP filesystem fork).
+//
+// Port of the Beledarian rag_local_files (beledarians-lm-studio-tools
+// src/toolsProvider.ts L2389-2463) and rag_web_content (L1706-1754) tools.
+// Same behavior throughout: rag_local_files recursively scans up to 50 text
+// files, chunks on blank lines (>20 chars), keeps chunks scoring above
+// cosine similarity 0.4, and returns the top 10 with {file, score, content}
+// (score as a 3-decimal string, exactly like the reference). rag_web_content
+// fetches the URL, converts to plain text with html-to-text (the same
+// options the fork's fetch_web_content tool uses), and returns the top 5
+// chunks from performRagOnText. Embedding goes through the LM Studio
+// /v1/embeddings endpoint (see helpers.ts) instead of the SDK client.
+import fs from "fs/promises";
+import path from "path";
+import { validatePath } from "../helpers/path.js";
+import { chunkText, cosineSimilarity, embedStrings, performRagOnText } from "./helpers.js";
+export async function handleRagLocalFiles(query, searchPath, filePattern, allowedDirectories) {
+    try {
+        const targetDir = await validatePath(searchPath ?? ".", allowedDirectories);
+        const entries = await fs.readdir(targetDir, { recursive: true, withFileTypes: true });
+        const textFiles = entries.filter((e) => e.isFile() && !e.name.match(/\.(png|jpg|jpeg|gif|ico|exe|dll|bin)$/i));
+        // Filter by pattern if provided
+        const filteredFiles = filePattern
+            ? textFiles.filter((e) => e.name.includes(filePattern) || path.join(e.parentPath, e.name).includes(filePattern))
+            : textFiles;
+        // Limit to avoid massive reads. In a real 'Gemini Flow' robust
+        // implementation, we'd use an index. Here we'll read top 50 files max to be safe.
+        const filesToScan = filteredFiles.slice(0, 50);
+        let allChunks = [];
+        const [queryEmbedding] = await embedStrings([query]);
+        for (const file of filesToScan) {
+            try {
+                const fullPath = path.join(file.parentPath, file.name);
+                const content = await fs.readFile(fullPath, "utf-8");
+                // reuse chunking logic
+                const chunks = chunkText(content);
+                if (chunks.length === 0)
+                    continue;
+                // Batch embed chunks for this file
+                const chunkEmbeddings = await embedStrings(chunks);
+                chunks.forEach((chunk, i) => {
+                    const score = cosineSimilarity(queryEmbedding, chunkEmbeddings[i]);
+                    if (score > 0.4) { // Threshold
+                        allChunks.push({ chunk, score, file: file.name });
+                    }
+                });
+            }
+            catch {
+                // ignore read errors
+            }
+        }
+        // Sort all chunks
+        allChunks.sort((a, b) => b.score - a.score);
+        return JSON.stringify({
+            query,
+            results: allChunks.slice(0, 10).map((c) => ({
+                file: c.file,
+                score: c.score.toFixed(3),
+                content: c.chunk,
+            })),
+        });
+    }
+    catch (error) {
+        return JSON.stringify({
+            error: `Local RAG failed: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}
+export async function handleRagWebContent(url, query) {
+    try {
+        // 1. Fetch content
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        let text = await response.text();
+        // Same text extraction the fork's fetch_web_content tool uses
+        const { compile } = await import("html-to-text");
+        const compiledConvert = compile({
+            wordwrap: false,
+            selectors: [
+                { selector: "a", options: { ignoreHref: true } },
+                { selector: "img", format: "skip" },
+            ],
+        });
+        text = compiledConvert(text);
+        if (text.length === 0) {
+            return JSON.stringify({ error: "Could not extract any text from the URL." });
+        }
+        // 2. Perform RAG
+        const ragResults = await performRagOnText(text, query);
+        return JSON.stringify({
+            url: url,
+            query: query,
+            relevant_chunks: ragResults,
+        });
+    }
+    catch (error) {
+        return JSON.stringify({
+            error: `Failed during RAG web search: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+}

package/dist/rag/helpers.js

@@ -0,0 +1,126 @@
+// rag/helpers.ts — shared RAG helpers (MCP filesystem fork).
+//
+// Port of the Beledarian RAG core (beledarians-lm-studio-tools
+// src/toolsProvider.ts: cosineSimilarity L76-84, performRagOnText L86-110),
+// with one substitution: the reference embeds through the LM Studio SDK
+// client; this fork runs on plain Node, so embedding is a fetch against
+// LM Studio's OpenAI-compatible API: POST http://127.0.0.1:1234/v1/embeddings
+// with JSON { model, input: [strings] } and (when a token is available)
+// Authorization: Bearer <token>. The token is read from MCP_API_TOKEN_FILE
+// (or, when unset, the reference machine's overnight pipeline token file);
+// if that file is missing or empty the request is sent keyless. The endpoint
+// is MCP_RAG_EMBED_URL when set. All thresholds, chunking, and top-N
+// behavior are identical
+// to the reference.
+import fs from "fs";
+const DEFAULT_EMBEDDINGS_URL = "http://127.0.0.1:1234/v1/embeddings";
+// Reference machine's overnight pipeline token file (kept for back-compat;
+// on other machines the file is simply absent -> keyless request).
+const LEGACY_TOKEN_FILE = "C:/Users/Gerar/.beledarians-llm-toolbox/workspace/overnight/lm_api_token.txt";
+// Env overrides (v0.2.29 publish portability). When unset, behavior on the
+// reference machine is unchanged.
+function getEmbeddingsUrl() {
+    const o = process.env.MCP_RAG_EMBED_URL;
+    return o && o.trim() ? o.trim() : DEFAULT_EMBEDDINGS_URL;
+}
+function getTokenFile() {
+    const o = process.env.MCP_API_TOKEN_FILE;
+    return o && o.trim() ? o.trim() : LEGACY_TOKEN_FILE;
+}
+const DEFAULT_EMBED_MODEL = "text-embedding-nomic-embed-text-v1.5";
+// Read the API token fresh on every call (small file; rotation stays live).
+function readApiKey() {
+    try {
+        const token = fs.readFileSync(getTokenFile(), "utf-8").trim();
+        return token.length > 0 ? token : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Env override for the embedding model id (LM Studio resolves model ids the
+// same way for the /v1/embeddings endpoint).
+function getEmbedModel() {
+    const override = process.env.MCP_RAG_EMBED_MODEL;
+    return override && override.trim().length > 0 ? override.trim() : DEFAULT_EMBED_MODEL;
+}
+// Embed a batch of strings. Response shape: {data: [{embedding: number[], index}]}.
+// Results are mapped back to input order by `index`. One retry (2 attempts)
+// on transient network/API errors with a short backoff — the first embedding
+// call of a session can trigger an auto-load of the embedding model on its
+// own llama-server, which takes a few seconds.
+export async function embedStrings(strings) {
+    if (strings.length === 0)
+        return [];
+    let lastError = null;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const headers = {
+                "Content-Type": "application/json",
+            };
+            const token = readApiKey();
+            if (token)
+                headers["Authorization"] = `Bearer ${token}`;
+            const res = await fetch(getEmbeddingsUrl(), {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ model: getEmbedModel(), input: strings }),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => "");
+                throw new Error(`embeddings HTTP ${res.status}: ${body.slice(0, 300)}`);
+            }
+            const data = await res.json();
+            if (!data || !Array.isArray(data.data)) {
+                throw new Error("embeddings response missing data array");
+            }
+            const byIndex = new Map();
+            for (const item of data.data) {
+                byIndex.set(item.index, item.embedding);
+            }
+            return strings.map((_, i) => {
+                const e = byIndex.get(i);
+                if (!Array.isArray(e) || e.length === 0) {
+                    throw new Error(`embeddings response missing embedding for index ${i}`);
+                }
+                return e;
+            });
+        }
+        catch (e) {
+            lastError = e;
+            await new Promise((r) => setTimeout(r, 2000));
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+// Helper function for cosine similarity (identical to the reference).
+export function cosineSimilarity(vecA, vecB) {
+    const dotProduct = vecA.reduce((acc, val, i) => acc + val * vecB[i], 0);
+    const magA = Math.sqrt(vecA.reduce((acc, val) => acc + val * val, 0));
+    const magB = Math.sqrt(vecB.reduce((acc, val) => acc + val * val, 0));
+    if (magA === 0 || magB === 0) {
+        return 0;
+    }
+    return dotProduct / (magA * magB);
+}
+// Paragraph-based chunking (identical to the reference): split on blank
+// lines, keep chunks with more than 20 non-whitespace characters.
+export function chunkText(text) {
+    return text.split(/\n\s*\n/).filter((chunk) => chunk.trim().length > 20);
+}
+// Main RAG-on-text helper (identical behavior to the reference:
+// chunk, embed query + chunks, cosine similarity, sort, top 5).
+export async function performRagOnText(text, query) {
+    const chunks = chunkText(text);
+    if (chunks.length === 0) {
+        return [{ chunk: text.substring(0, 4000), score: 1 }];
+    }
+    const [queryEmbedding] = await embedStrings([query]);
+    const chunkEmbeddings = await embedStrings(chunks);
+    const similarities = chunkEmbeddings.map((chunkEmb, i) => ({
+        chunk: chunks[i],
+        score: cosineSimilarity(queryEmbedding, chunkEmb),
+    }));
+    similarities.sort((a, b) => b.score - a.score);
+    return similarities.slice(0, 5); // Return top 5
+}

package/dist/rag/schema.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export const RagLocalFilesArgsSchema = z.object({
+    query: z.string().describe("The search query to match file contents against"),
+    path: z
+        .string()
+        .optional()
+        .describe("Root directory to search (default: the server process's working directory). Must be within an allowed directory."),
+    file_pattern: z
+        .string()
+        .optional()
+        .describe("File pattern to include (e.g. '.ts', 'src/'). Default: all text files."),
+});
+export const RagWebContentArgsSchema = z.object({
+    url: z.string().describe("The URL to fetch"),
+    query: z.string().describe("The query to find relevant content for"),
+});

package/dist/read_document/handler.js

@@ -0,0 +1,61 @@
+// read_document/handler.ts — read content from PDF or DOCX files (MCP filesystem fork).
+//
+// Port of the Beledarian read_document tool (beledarians-lm-studio-tools
+// src/toolsProvider.ts). PDF via pdf-parse v2 class-based API
+// (new PDFParse({ data }) -> getText() / getInfo() / destroy()); DOCX via
+// mammoth extractRawText. The DOMMatrix polyfill is required by pdf-parse v2
+// (pdfjs) in a bare Node environment and is ported VERBATIM from the reference.
+import { readFile } from "fs/promises";
+import { validatePath } from "../helpers/path.js";
+// Polyfill DOMMatrix for pdf-parse v2 (required for node environment)
+function ensureDomMatrix() {
+    if (typeof global.DOMMatrix === "undefined") {
+        global.DOMMatrix = class DOMMatrix {
+            constructor(arg) {
+                this.a = 1;
+                this.b = 0;
+                this.c = 0;
+                this.d = 1;
+                this.e = 0;
+                this.f = 0;
+                if (Array.isArray(arg)) {
+                    this.a = arg[0];
+                    this.b = arg[1];
+                    this.c = arg[2];
+                    this.d = arg[3];
+                    this.e = arg[4];
+                    this.f = arg[5];
+                }
+            }
+        };
+    }
+}
+export async function handleReadDocument(filePath, allowedDirectories) {
+    const fpath = await validatePath(filePath, allowedDirectories);
+    const ext = fpath.split('.').pop()?.toLowerCase();
+    try {
+        if (ext === 'pdf') {
+            ensureDomMatrix();
+            // Dynamically import pdf-parse v2 (ESM equivalent of the reference's require)
+            const { PDFParse } = await import("pdf-parse");
+            const dataBuffer = await readFile(fpath);
+            // Use new class-based API
+            const parser = new PDFParse({ data: dataBuffer });
+            const textResult = await parser.getText();
+            const infoResult = await parser.getInfo(); // Optional: get metadata
+            await parser.destroy(); // Cleanup
+            return JSON.stringify({ content: textResult.text, metadata: infoResult.info });
+        }
+        else if (ext === 'docx') {
+            const mammoth = await import("mammoth");
+            const result = await mammoth.extractRawText({ path: fpath });
+            return JSON.stringify({ content: result.value, messages: result.messages });
+        }
+        else {
+            return JSON.stringify({ error: "Unsupported document format. Use read_file for text files." });
+        }
+    }
+    catch (e) {
+        return JSON.stringify({ error: `Failed to read document: ${e instanceof Error ? e.message : String(e)}` });
+    }
+}

package/dist/read_document/schema.js

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export const ReadDocumentArgsSchema = z.object({
+    file_path: z.string(),
+});

package/dist/run_javascript/handler.js

@@ -0,0 +1,124 @@
+// run_javascript/handler.ts — unrestricted JS/TS snippet execution (MCP filesystem fork).
+//
+// Runs a snippet on the Deno runtime with FULL permissions (no sandbox):
+// the script may read/write anywhere the server user can reach (drive letters
+// and UNC paths), use the network, read the environment, spawn processes, and
+// import arbitrary modules (node:*, npm:*, https:*). This is the "free"
+// counterpart to the other run_javascript tools, which confine snippets to a
+// working directory with net/env/sys/run/ffi denied.
+//
+// Engine resolution (first hit wins; result is cached):
+//   1. $DENO_PATH env var (absolute path to a deno binary)
+//   2. <ancestor>/.internal/utils/deno(.exe) walking up from the server CWD
+//      (LM Studio bundles deno at <home>/.internal/utils)
+//   3. <user home>/.lmstudio/.internal/utils/deno(.exe)
+//   4. deno on PATH
+//
+// Reuses the shell layer's spawn/capture machinery (runCaptured + caps).
+import fsp from "fs/promises";
+import fs from "fs";
+import nodePath from "path";
+import os from "os";
+import crypto from "crypto";
+import { RUN_JS_MAX_TIMEOUT_SEC } from "./schema.js";
+import { cap, CAP_OK, CAP_ERR, SHELL_JOBS_DIR, ensureJobsDir, resolveCwd, runCaptured, } from "../shell/handler.js";
+function denoName() {
+    return process.platform === "win32" ? "deno.exe" : "deno";
+}
+let cachedDenoPath;
+export function resolveDenoPath() {
+    if (cachedDenoPath !== undefined)
+        return cachedDenoPath;
+    let found = null;
+    // 1. explicit override
+    const env = process.env.DENO_PATH;
+    if (env && fs.existsSync(env))
+        found = env;
+    // 2. walk up from the server CWD: <dir>/.internal/utils/deno(.exe)
+    if (!found) {
+        let dir = process.cwd();
+        for (let i = 0; i < 8 && !found; i++) {
+            const candidate = nodePath.join(dir, ".internal", "utils", denoName());
+            if (fs.existsSync(candidate))
+                found = candidate;
+            const parent = nodePath.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    // 3. typical LM Studio user install: <home>/.lmstudio/.internal/utils/deno(.exe)
+    if (!found) {
+        const candidate = nodePath.join(os.homedir(), ".lmstudio", ".internal", "utils", denoName());
+        if (fs.existsSync(candidate))
+            found = candidate;
+    }
+    // 4. PATH lookup
+    if (!found) {
+        const dirs = (process.env.PATH ?? "").split(nodePath.delimiter).filter(Boolean);
+        for (const d of dirs) {
+            const candidate = nodePath.join(d, denoName());
+            if (fs.existsSync(candidate)) {
+                found = candidate;
+                break;
+            }
+        }
+    }
+    cachedDenoPath = found;
+    return found;
+}
+export async function handleRunJavascriptFree(javascript, timeoutSeconds, cwd) {
+    const deno = resolveDenoPath();
+    if (!deno) {
+        throw new Error("No Deno runtime found. Set the DENO_PATH environment variable to a deno binary, " +
+            "install deno on PATH, or run this server from inside an LM Studio installation " +
+            "(which bundles deno at <home>/.internal/utils/deno.exe).");
+    }
+    const abs = await resolveCwd(cwd);
+    await ensureJobsDir();
+    const file = nodePath.join(SHELL_JOBS_DIR, `js-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}.ts`);
+    await fsp.writeFile(file, javascript, "utf-8");
+    const timeout = Math.min(Math.max(timeoutSeconds ?? 5, 0.1), RUN_JS_MAX_TIMEOUT_SEC);
+    const started = Date.now();
+    try {
+        const r = await runCaptured(deno, [
+            "run",
+            "--no-prompt",
+            "--allow-read",
+            "--allow-write",
+            "--allow-net",
+            "--allow-env",
+            "--allow-sys",
+            "--allow-run",
+            "--allow-ffi",
+            "--allow-import",
+            file,
+        ], {
+            cwd: abs,
+            timeoutMs: timeout * 1000,
+            env: { ...process.env, NO_COLOR: "true" },
+        });
+        const durationMs = Date.now() - started;
+        if (r.spawnError) {
+            throw new Error(`Failed to launch deno: ${r.spawnError}`);
+        }
+        if (r.timedOut) {
+            throw new Error(`Process timed out after ${timeout}s.\nSTDOUT:\n${cap(r.stdout, CAP_ERR)}\nSTDERR:\n${cap(r.stderr, CAP_ERR)}`);
+        }
+        if (r.code !== 0) {
+            throw new Error(`Process exited with code ${r.code ?? "unknown"}.\nSTDOUT:\n${cap(r.stdout, CAP_ERR)}\nSTDERR:\n${cap(r.stderr, CAP_ERR)}`);
+        }
+        return JSON.stringify({
+            exitCode: 0,
+            stdout: cap(r.stdout, CAP_OK),
+            stderr: cap(r.stderr, CAP_OK),
+            timedOut: false,
+            duration_ms: durationMs,
+            cwd: abs,
+            deno,
+        });
+    }
+    finally {
+        await fsp.unlink(file).catch(() => undefined);
+    }
+}

package/dist/run_javascript/schema.js

@@ -0,0 +1,28 @@
+// run_javascript/schema.ts — argument schema for the unrestricted JS/TS execution tool.
+// (MCP filesystem fork: the "free" run_javascript — no working-directory sandbox.)
+import { z } from "zod";
+// Unlike the shell tools (28 s cap), this tool may run up to 60 s: the MCP
+// client request window was measured >63 s (a ~63 s in-harness tool call
+// survived, 2026-08-29), and 60 s matches the sibling run_javascript tools.
+export const RUN_JS_MAX_TIMEOUT_SEC = 60;
+// ---------------------------------------------------------------------------
+// Tool description (verbatim — pasted into server.ts ListTools entry):
+//
+// run_javascript_free:
+//   "Run a JavaScript/TypeScript code snippet on the Deno runtime with UNRESTRICTED permissions: full filesystem read/write (any drive or UNC path the server user can reach), network access, environment variables, child processes, and arbitrary imports (node:*, npm:*, https:*) — unlike the other run_javascript tools, there is no working-directory sandbox. The code is written to a temp .ts file and run; returns exit code, stdout, and stderr. Default 5 s timeout, max 60 s; optional cwd (defaults to the shell_cwd default). Non-zero exit or timeout returns an error that still includes the captured output. Requires a Deno binary: $DENO_PATH, <LM Studio home>/.internal/utils/deno(.exe) (found by walking up from the server CWD or the user home), or deno on PATH."
+// ---------------------------------------------------------------------------
+export const RunJavascriptFreeArgsSchema = z.object({
+    javascript: z
+        .string()
+        .describe("JavaScript (or TypeScript) code to execute. Runs as a Deno script: Deno.* APIs, console.log, and imports (node:*, npm:*, https:*) all work."),
+    timeout_seconds: z
+        .number()
+        .min(0.1)
+        .max(RUN_JS_MAX_TIMEOUT_SEC)
+        .optional()
+        .describe("Timeout in seconds (default: 5, max: 60)."),
+    cwd: z
+        .string()
+        .optional()
+        .describe("Working directory for the snippet (default: the shell_cwd default)."),
+});