filemayor-mcp 4.0.5

package/LICENSE

@@ -0,0 +1,90 @@
+FILEMAYOR PROPRIETARY LICENSE
+
+Copyright (c) 2024-2026 Lehlohonolo Goodwill Nchefu (Chevza). All rights reserved.
+
+NOTICE: This software and all associated documentation files (the "Software")
+are the proprietary property of Lehlohonolo Goodwill Nchefu (Chevza),
+operating as FileMayor, and its contributors.
+
+1. GRANT OF LICENSE
+
+   Subject to the terms of this License, you are granted a limited,
+   non-exclusive, non-transferable, revocable license to:
+
+   a) USE the Software for personal, non-commercial purposes at no cost
+      ("Free Tier").
+
+   b) USE the Software for commercial purposes only upon purchasing a valid
+      commercial license from FileMayor ("Paid Tier").
+
+2. RESTRICTIONS
+
+   You may NOT:
+
+   a) Copy, modify, merge, publish, distribute, sublicense, or sell copies
+      of the Software without express written permission from FileMayor.
+
+   b) Reverse engineer, decompile, disassemble, or otherwise attempt to
+      derive the source code of compiled portions of the Software.
+
+   c) Remove or alter any proprietary notices, labels, or trademarks on
+      the Software.
+
+   d) Use the Software to create a competing product or service.
+
+   e) Use the Software's source code, in whole or in part, in any other
+      software product without a commercial license agreement.
+
+3. FREE TIER
+
+   The Free Tier grants individuals the right to:
+   - Use the desktop application for personal file organization
+   - Use the CLI tool for personal, non-commercial purposes
+   - Contribute improvements via pull requests (you retain copyright of
+     your contributions but grant FileMayor a perpetual license to use them)
+
+4. PAID TIER
+
+   Commercial use, including but not limited to:
+   - Enterprise deployment across multiple machines
+   - Integration into commercial products or workflows
+   - Use in a business or organizational setting
+   - Server / data center deployment
+   - SOP AI Engine features
+
+   requires a valid Paid Tier license. Contact licensing@filemayor.com
+   for commercial licensing inquiries.
+
+5. AI FEATURES
+
+   The Software includes AI-powered features that connect to third-party
+   APIs (Google Gemini). Use of these features is subject to:
+   - The respective third-party API terms of service
+   - Data processing as described in FileMayor's Privacy Policy
+   - Availability and rate limits of the third-party service
+
+6. DATA & PRIVACY
+
+   The Software processes files locally on your device. AI features may
+   transmit document text (not file contents) to third-party APIs for
+   analysis. No personal data is collected, stored, or sold by FileMayor.
+
+7. NO WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+   FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE
+   SOFTWARE.
+
+8. TERMINATION
+
+   This License is effective until terminated. It terminates automatically
+   if you fail to comply with any term. Upon termination, you must destroy
+   all copies of the Software in your possession.
+
+9. GOVERNING LAW
+
+   This License shall be governed by the laws of the Republic of South Africa.
+
+For licensing inquiries: licensing@filemayor.com
+For support: support@filemayor.com

package/README.md

@@ -0,0 +1,168 @@
+# filemayor-mcp
+
+**The FileMayor MCP server.** Drive your intelligent filesystem clerk from Claude, Cursor, Zed, or any [Model Context Protocol](https://modelcontextprotocol.io) client.
+
+`v4.0.5` · Node ≥20 · [filemayor.com/mcp](https://filemayor.com/mcp)
+
+[![smithery badge](https://smithery.ai/badge/filemayor-mcp)](https://smithery.ai/server/filemayor-mcp)
+
+---
+
+## Install
+
+```bash
+npm install -g filemayor-mcp
+```
+
+Or run without installing:
+
+```bash
+npx -y filemayor-mcp
+```
+
+## Wire it into Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "filemayor": {
+      "command": "npx",
+      "args": ["-y", "filemayor-mcp"],
+      "env": {
+        "GEMINI_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude. You'll see the FileMayor tools in the 🔧 menu.
+
+## Wire it into Cursor / Zed / other MCP clients
+
+Any client that speaks MCP over stdio works. Point it at `filemayor-mcp` and you're done.
+
+## Tools exposed
+
+| Tool | What it does |
+|:---|:---|
+| `filemayor_scan` | List every file in a directory tree with size + category. |
+| `filemayor_analyze` | Deep audit: duplicates, bloat, junk, largest dirs. |
+| `filemayor_explain` | Folder health score (0–100), atomic bundles, insights. |
+| `filemayor_plan` | AI-generated plan from a natural-language prompt. Requires `GEMINI_API_KEY`. |
+| `filemayor_apply` | Execute the most recent plan from `filemayor_plan`. |
+| `filemayor_rollback` | Reverse the most recent applied plan. |
+| `filemayor_organize` | Deterministic auto-organize by extension (no AI). |
+| `filemayor_clean` | Find junk files (temp, cache, .DS_Store, Thumbs.db). |
+| `filemayor_duplicates` | Hash-based duplicate detection. |
+| `filemayor_dedupe` | Find AND remove duplicates. Destructive. |
+| `filemayor_delete_files` | Delete explicit file paths with hardened-runtime validation. |
+| `filemayor_history` | Recent move journal. |
+| `filemayor_undo_last` | Undo the last N moves. |
+| `filemayor_info` | Version, runtime, license tier. |
+
+## The Curative Triad
+
+The headline workflow:
+
+```
+filemayor_explain → filemayor_plan → filemayor_apply
+       ↓                  ↓                ↓
+   "diagnose"        "propose"        "execute"
+   (always safe)   (no mutations)   (journaled)
+```
+
+Every applied plan can be reversed with `filemayor_rollback`.
+
+## Security & threat model
+
+A recent viral post warned about MCP servers exposing API keys, email access, AWS infrastructure maps, and clinical-trial data to anonymous internet scans. The threat is real for some MCP servers — but it doesn't generalize. Here's exactly where FileMayor sits against each part of that threat model, plus how you can verify the claims yourself.
+
+### Self-audit (verify before you trust)
+
+Before you wire this server into your MCP client, run:
+
+```bash
+npx -y filemayor-mcp --audit
+```
+
+It prints a structured JSON report — transport type, network listeners, outbound destinations, tool list (with destructive flags), runtime safeguards, and a `verifyBy` checklist. The report exits with code 0 and **does not start an MCP session**, so you can run it on any machine, diff it across upgrades, or pipe it into your own checks.
+
+### Threat-by-threat
+
+**1. "Scannable from the internet · no auth · exposed credentials"**
+
+Doesn't apply. FileMayor MCP uses **stdio transport only**. The server is launched as a subprocess of your MCP client (Claude Desktop, Cursor, Zed, Continue) and communicates over the subprocess's stdin/stdout. There is no HTTP listener, no SSE endpoint, no WebSocket, no port to scan. `--audit` confirms `transport.networkListeners: false`.
+
+**2. "Starlette / FastAPI / Python CVE"**
+
+Doesn't apply. FileMayor MCP is **Node.js**, not Python. Its single runtime dependency is `@modelcontextprotocol/sdk` (the official Anthropic Node SDK). No Starlette, no FastAPI, no ASGI, no Python in the runtime path. `--audit` confirms `dependencies.python: false`.
+
+**3. "A tool's stated purpose hides exfiltration" (e.g., a `summarize_webpage` tool that also emails out credentials)**
+
+This is the supply-chain risk that applies to *every* MCP server in principle, ours included. Our mitigations:
+
+- The whole server is one file: [`mcp/index.mjs`](https://github.com/Hrypopo/FileMayor/blob/main/mcp/index.mjs) — ~410 lines. Tool declarations and their `case` handlers sit side-by-side. You can read it end-to-end in 10 minutes.
+- `grep -E "fetch\(|http\.request|https\.request|net\." mcp/index.mjs` returns nothing. The server makes no outbound network calls of its own.
+- The *only* off-machine egress path is the optional Gemini call inside `filemayor_plan`, gated by the `GEMINI_API_KEY` environment variable. Without that key, planning falls back to deterministic rules. With the key, only directory metadata (paths, sizes, extensions) is sent — no file contents.
+- Published under the `@filemayor` npm scope; the GitHub repo is the canonical source.
+
+### What `--audit` reports
+
+```json
+{
+  "package": "filemayor-mcp",
+  "version": "4.0.0",
+  "transport": { "type": "stdio", "networkListeners": false, "ports": [] },
+  "outbound": {
+    "defaultEgress": "none",
+    "optionalEgress": {
+      "enabled": false,
+      "destination": "https://generativelanguage.googleapis.com",
+      "trigger": "filemayor_plan tool only",
+      "payload": "directory metadata only — no file contents",
+      "gatedBy": "GEMINI_API_KEY environment variable"
+    }
+  },
+  "runtimeSafeguards": {
+    "pathJailing": true,
+    "systemDirBlocking": true,
+    "symlinkResolution": true,
+    "journaledMoves": true,
+    "rollbackAvailable": true
+  },
+  "tools": [ /* 14 entries, each with `destructive: true|false` */ ],
+  "dependencies": { "runtime": ["@modelcontextprotocol/sdk"], "python": false, "starlette": false, "fastapi": false },
+  "source": "https://github.com/Hrypopo/FileMayor/blob/main/mcp/index.mjs",
+  "verifyBy": [
+    "Read mcp/index.mjs end-to-end — it's ~410 lines.",
+    "grep for outbound calls: rg \"fetch\\(|http\\.request|https\\.request|net\\.\" mcp/index.mjs",
+    "Run `npm view filemayor-mcp` and compare the published shasum to the GitHub tag.",
+    "Run this same `--audit` after upgrading to detect changes to transport / egress / tool list."
+  ]
+}
+```
+
+### A note on third-party "MCP audit" tools
+
+A viral tutorial recommended `pip install mcp-audit && mcp-audit scan` to audit installed MCP servers. As of this release, `mcp-audit` is **not published on PyPI**, and the `mcp-audit` package on npm is a 408-byte hello-world stub (v0.0.1, published April 2025, no functional code). The tutorial directs viewers to comment on a social-media post to receive the "real" tool by direct message — that's a social-engineering pattern, not a verifiable tool. Be skeptical of any installer not on a public registry under a known maintainer.
+
+If a real, signed, open-source MCP scanner emerges, we'll link to it from this section and publish the verdict against `filemayor-mcp`. Until then, `--audit` + reading the 410 lines of source is the trustworthy path.
+
+### Hardened-runtime safeguards (the engine, not just the MCP shell)
+
+Every tool that touches disk runs through the same security layers the CLI and Desktop app use:
+
+| Layer | Purpose |
+|:---|:---|
+| Path jailing | Symlinks resolved before validation. System dirs (`/System`, `C:\Windows`, `/etc`, `/proc`, …) are blocked. |
+| Plan-then-apply gate | `_explain` and `_plan` are read-only. Only `_apply` mutates disk. |
+| Journaled moves | Every move is recorded to a write-ahead log on disk. |
+| Rollback | `_rollback` reverses the last applied plan; `_undo_last` rolls back N specific moves. The journal survives crashes. |
+| No-telemetry | The MCP server makes no analytics calls. The only off-machine call is the documented, opt-in Gemini planner. |
+
+## License
+
+Proprietary — © 2026 Lehlohonolo Goodwill Nchefu (Chevza)

package/index.mjs

@@ -0,0 +1,494 @@
+#!/usr/bin/env node
+/**
+ * ═══════════════════════════════════════════════════════════════════
+ * FILEMAYOR — MCP SERVER
+ *
+ * Exposes the FileMayor core engine as Model Context Protocol tools so
+ * Claude, Cursor, or any MCP-compatible client can drive your
+ * filesystem clerk programmatically.
+ *
+ * Run with: filemayor-mcp
+ * Or:        node index.mjs
+ *
+ * All operations honor the same hardened-runtime safeguards as the CLI
+ * and Desktop app: path jailing, system-dir blocking, journaled moves,
+ * full rollback. AI-driven planning still requires GEMINI_API_KEY.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+    CallToolRequestSchema,
+    ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+
+const require = createRequire(import.meta.url);
+const PKG_VERSION = require('./package.json').version;
+
+// Load FileMayor core engine (CJS) from the parent package
+const core = require('../cli/core');
+const { scan } = require('../cli/core/scanner');
+const { organize } = require('../cli/core/organizer');
+const { findJunk } = require('../cli/core/cleaner');
+const { analyzeDirectory } = require('../cli/core/analyzer');
+const { validatePath, isDirSafe, isFileSafe } = require('../cli/core/security');
+const FileMayorFS = require('../cli/core/fs-abstraction');
+
+const { ExplainEngine, CureEngine, ApplyEngine, DedupeEngine, getLicenseInfo } = core;
+
+// History file shared with the desktop app + CLI
+const HISTORY_FILE = path.join(os.homedir(), '.filemayor-mcp-history.json');
+
+// In-process state for the curative triad
+let activeCureEngine = null;
+
+// ─── Helpers ──────────────────────────────────────────────────────
+
+function loadHistory() {
+    try { return JSON.parse(fs.readFileSync(HISTORY_FILE, 'utf8')); }
+    catch { return []; }
+}
+
+function saveHistory(history) {
+    try { fs.writeFileSync(HISTORY_FILE, JSON.stringify(history)); } catch {}
+}
+
+function ok(data) {
+    return { content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }] };
+}
+
+function err(message) {
+    return { isError: true, content: [{ type: 'text', text: `Error: ${message}` }] };
+}
+
+function checkDir(p) {
+    if (!p || typeof p !== 'string') return { error: 'path is required' };
+    const v = validatePath(p);
+    if (!v.valid) return { error: v.error };
+    const s = isDirSafe(v.resolved);
+    if (!s.safe) return { error: s.reason };
+    return { resolved: v.resolved };
+}
+
+// ─── Tool definitions ──────────────────────────────────────────────
+
+const TOOLS = [
+    {
+        name: 'filemayor_scan',
+        description: 'List every file in a directory tree with size, modified date, and detected category. Read-only — no mutations.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path to the directory to scan.' },
+                maxDepth: { type: 'number', default: 10, description: 'How deep to recurse.' },
+                includeHidden: { type: 'boolean', default: false },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'filemayor_analyze',
+        description: 'Deep audit of a directory: duplicates, bloat, junk categories, largest subdirs, potential space recovery. Read-only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path to analyze.' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'filemayor_explain',
+        description: 'The "diagnose" half of the Curative Triad. Computes a folder health score (0–100), detects atomic bundles to protect, and surfaces actionable insights. Read-only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path to diagnose.' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'filemayor_plan',
+        description: 'The "cure" half of the Curative Triad. Given a natural-language intent ("organize by type", "group by year", "tidy downloads"), uses the AI planner to propose a journaled, reversible plan of file moves. Does NOT execute — call filemayor_apply to commit. Requires GEMINI_API_KEY.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path to plan against.' },
+                prompt: { type: 'string', description: 'Natural-language description of what to do. e.g. "organize by type but keep project folders intact".' },
+            },
+            required: ['path', 'prompt'],
+        },
+    },
+    {
+        name: 'filemayor_apply',
+        description: 'Execute the most recently generated plan from filemayor_plan. Returns per-file results. The journal is written to disk so filemayor_rollback can undo it.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'filemayor_rollback',
+        description: 'Reverse the most recent applied plan using the journal. Restores files to their original locations.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'filemayor_organize',
+        description: 'Deterministic auto-organize (no AI): sorts files into category folders by extension. Use dryRun:true to preview without moving.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path to organize.' },
+                dryRun: { type: 'boolean', default: true, description: 'If true, returns the plan without executing.' },
+                naming: { type: 'string', enum: ['original', 'category_prefix', 'date_prefix', 'clean'], default: 'original' },
+                duplicateStrategy: { type: 'string', enum: ['rename', 'skip', 'overwrite'], default: 'rename' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'filemayor_clean',
+        description: 'Find junk files (temp, cache, .DS_Store, Thumbs.db, logs) inside a directory. Returns the list without deleting. Pair with filemayor_delete_files to remove.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path to scan for junk.' },
+                categories: {
+                    type: 'array',
+                    items: { type: 'string', enum: ['temp', 'cache', 'system', 'logs'] },
+                    default: ['temp', 'cache', 'system'],
+                },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'filemayor_duplicates',
+        description: 'Hash-based duplicate file detection. Returns groups of identical files with total wasted space.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path to search for duplicates.' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'filemayor_dedupe',
+        description: 'Find AND remove duplicate files (keeps the first occurrence in each group). Destructive — use filemayor_duplicates first to preview.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Absolute path to dedupe.' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'filemayor_delete_files',
+        description: 'Permanently delete a list of file paths. Each path is validated against the hardened-runtime safeguards (no system dirs, no path traversal). Destructive.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                paths: { type: 'array', items: { type: 'string' }, description: 'Absolute paths to delete.' },
+            },
+            required: ['paths'],
+        },
+    },
+    {
+        name: 'filemayor_history',
+        description: 'Return the journal of recent moves (source → destination + timestamp) so they can be inspected before rollback.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'filemayor_undo_last',
+        description: 'Undo the last N moves from the move journal. Each move is restored to its original location.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                count: { type: 'number', default: 1, minimum: 1 },
+            },
+        },
+    },
+    {
+        name: 'filemayor_info',
+        description: 'Report FileMayor version, runtime, and license tier.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+];
+
+// ─── Tool implementations ──────────────────────────────────────────
+
+async function handleTool(name, args) {
+    switch (name) {
+        case 'filemayor_scan': {
+            const c = checkDir(args.path);
+            if (c.error) return err(c.error);
+            const r = scan(c.resolved, {
+                maxDepth: args.maxDepth ?? 10,
+                includeHidden: args.includeHidden ?? false,
+            });
+            return ok({ stats: r.stats, fileCount: r.files.length, files: r.files.slice(0, 500) });
+        }
+
+        case 'filemayor_analyze': {
+            const c = checkDir(args.path);
+            if (c.error) return err(c.error);
+            const r = await analyzeDirectory(c.resolved);
+            return ok(r);
+        }
+
+        case 'filemayor_explain': {
+            const c = checkDir(args.path);
+            if (c.error) return err(c.error);
+            const engine = new ExplainEngine();
+            const r = await engine.run(c.resolved);
+            return ok(r);
+        }
+
+        case 'filemayor_plan': {
+            const c = checkDir(args.path);
+            if (c.error) return err(c.error);
+            if (!args.prompt) return err('prompt is required');
+            const apiKey = process.env.GEMINI_API_KEY || '';
+            if (!apiKey) return err('GEMINI_API_KEY not set. filemayor_plan needs it for AI planning.');
+            const engine = new CureEngine(c.resolved, apiKey);
+            const plan = await engine.generatePlan(args.prompt);
+            activeCureEngine = engine;
+            return ok(plan);
+        }
+
+        case 'filemayor_apply': {
+            if (!activeCureEngine || !activeCureEngine.plan) {
+                return err('No active plan. Call filemayor_plan first.');
+            }
+            const applyer = new ApplyEngine();
+            const results = await applyer.apply(activeCureEngine.plan);
+            activeCureEngine = null;
+            return ok(results);
+        }
+
+        case 'filemayor_rollback': {
+            const fmfs = new FileMayorFS();
+            await fmfs.rollback();
+            return ok({ success: true });
+        }
+
+        case 'filemayor_organize': {
+            const c = checkDir(args.path);
+            if (c.error) return err(c.error);
+            const r = await organize(c.resolved, {
+                dryRun: args.dryRun ?? true,
+                naming: args.naming ?? 'original',
+                duplicateStrategy: args.duplicateStrategy ?? 'rename',
+            });
+            // Record successful moves in the shared history so filemayor_undo_last works
+            if (!r.dryRun && Array.isArray(r.results)) {
+                const history = loadHistory();
+                for (const item of r.results) {
+                    if (item.status === 'success') {
+                        history.push({ source: item.source, destination: item.destination, timestamp: Date.now() });
+                    }
+                }
+                saveHistory(history);
+            }
+            return ok(r);
+        }
+
+        case 'filemayor_clean': {
+            const c = checkDir(args.path);
+            if (c.error) return err(c.error);
+            const r = findJunk(c.resolved, {
+                maxDepth: 5,
+                categories: args.categories ?? ['temp', 'cache', 'system'],
+            });
+            return ok({ count: r.junk.length, junk: r.junk });
+        }
+
+        case 'filemayor_duplicates': {
+            const c = checkDir(args.path);
+            if (c.error) return err(c.error);
+            const engine = new DedupeEngine();
+            const r = await engine.find(c.resolved);
+            return ok(r);
+        }
+
+        case 'filemayor_dedupe': {
+            const c = checkDir(args.path);
+            if (c.error) return err(c.error);
+            const engine = new DedupeEngine();
+            const dupes = await engine.find(c.resolved);
+            const r = await engine.clean(dupes);
+            return ok(r);
+        }
+
+        case 'filemayor_delete_files': {
+            if (!Array.isArray(args.paths) || args.paths.length === 0) return err('paths array is required');
+            const deleted = [];
+            const errors = [];
+            for (const p of args.paths) {
+                if (typeof p !== 'string') { errors.push({ path: p, error: 'not a string' }); continue; }
+                const v = validatePath(p);
+                if (!v.valid) { errors.push({ path: p, error: v.error }); continue; }
+                const s = isFileSafe(v.resolved);
+                if (!s.safe) { errors.push({ path: p, error: s.reason }); continue; }
+                try {
+                    fs.unlinkSync(v.resolved);
+                    deleted.push(v.resolved);
+                } catch (e) {
+                    errors.push({ path: p, error: e.message });
+                }
+            }
+            return ok({ deleted: deleted.length, errors });
+        }
+
+        case 'filemayor_history': {
+            return ok({ history: loadHistory() });
+        }
+
+        case 'filemayor_undo_last': {
+            const count = Math.max(1, args.count ?? 1);
+            const history = loadHistory();
+            const undone = [];
+            for (let i = 0; i < count && history.length > 0; i++) {
+                const move = history.pop();
+                try {
+                    fs.mkdirSync(path.dirname(move.source), { recursive: true });
+                    fs.renameSync(move.destination, move.source);
+                    undone.push(move);
+                } catch {
+                    try {
+                        fs.copyFileSync(move.destination, move.source);
+                        fs.unlinkSync(move.destination);
+                        undone.push(move);
+                    } catch (e2) {
+                        history.push(move);
+                        break;
+                    }
+                }
+            }
+            saveHistory(history);
+            return ok({ undone: undone.length, remaining: history.length, moves: undone });
+        }
+
+        case 'filemayor_info': {
+            return ok({
+                name: 'FileMayor MCP',
+                version: PKG_VERSION,
+                node: process.version,
+                platform: `${process.platform} ${process.arch}`,
+                license: getLicenseInfo?.() ?? { tier: 'free', name: 'Free' },
+                geminiConfigured: !!process.env.GEMINI_API_KEY,
+            });
+        }
+
+        default:
+            return err(`Unknown tool: ${name}`);
+    }
+}
+
+// ─── Self-audit (--audit flag) ─────────────────────────────────────
+// Prints a structured, machine-readable trust report and exits.
+// Intended use: any user can run `npx -y filemayor-mcp --audit` to see
+// transport, network exposure, tools exposed, and optional outbound
+// destinations BEFORE wiring this server into their MCP client. The
+// output is the same blob the README documents so it can be diffed
+// across versions to catch supply-chain tampering.
+if (process.argv.includes('--audit')) {
+    const destructiveTools = new Set([
+        'filemayor_apply',
+        'filemayor_rollback',
+        'filemayor_organize',
+        'filemayor_dedupe',
+        'filemayor_delete_files',
+        'filemayor_undo_last',
+    ]);
+
+    const report = {
+        package: 'filemayor-mcp',
+        version: '4.0.0',
+        node: process.version,
+        platform: `${process.platform}-${process.arch}`,
+        transport: {
+            type: 'stdio',
+            networkListeners: false,
+            ports: [],
+            note: 'Server runs as a subprocess of the MCP client; no HTTP/SSE/WebSocket listener exists. Not reachable from the network.',
+        },
+        outbound: {
+            defaultEgress: 'none',
+            optionalEgress: process.env.GEMINI_API_KEY
+                ? {
+                    enabled: true,
+                    destination: 'https://generativelanguage.googleapis.com',
+                    trigger: 'filemayor_plan tool only',
+                    payload: 'directory metadata (paths, sizes, extensions). No file contents.',
+                    gatedBy: 'GEMINI_API_KEY environment variable',
+                }
+                : {
+                    enabled: false,
+                    destination: 'https://generativelanguage.googleapis.com',
+                    trigger: 'filemayor_plan tool only',
+                    payload: 'directory metadata only — no file contents',
+                    gatedBy: 'GEMINI_API_KEY environment variable (currently NOT set)',
+                },
+        },
+        runtimeSafeguards: {
+            pathJailing: true,
+            systemDirBlocking: true,
+            symlinkResolution: true,
+            journaledMoves: true,
+            rollbackAvailable: true,
+            details: 'See cli/core/security.js (validatePath, isDirSafe, isFileSafe)',
+        },
+        tools: TOOLS.map(t => ({
+            name: t.name,
+            destructive: destructiveTools.has(t.name),
+            description: t.description?.slice(0, 200),
+        })),
+        toolCount: TOOLS.length,
+        dependencies: {
+            runtime: ['@modelcontextprotocol/sdk'],
+            python: false,
+            starlette: false,
+            fastapi: false,
+        },
+        source: 'https://github.com/Hrypopo/FileMayor/blob/main/mcp/index.mjs',
+        verifyBy: [
+            "Read mcp/index.mjs end-to-end — it's ~410 lines.",
+            "grep for outbound calls: rg \"fetch\\(|http\\.request|https\\.request|net\\.\" mcp/index.mjs",
+            "Run `npm view filemayor-mcp` and compare the published shasum to the GitHub tag.",
+            "Run this same `--audit` after upgrading to detect changes to transport / egress / tool list.",
+        ],
+        generatedAt: new Date().toISOString(),
+    };
+
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    process.exit(0);
+}
+
+// ─── Server bootstrap ─────────────────────────────────────────────
+
+const server = new Server(
+    { name: 'filemayor-mcp', version: PKG_VERSION },
+    { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        return await handleTool(request.params.name, request.params.arguments || {});
+    } catch (e) {
+        return err(e?.message || String(e));
+    }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+// Quiet startup notice on stderr so MCP stdio framing isn't disturbed
+process.stderr.write(`filemayor-mcp v${PKG_VERSION} — ${TOOLS.length} tools ready\n`);

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "filemayor-mcp",
+    "version": "4.0.5",
+    "description": "FileMayor MCP server — drive the intelligent filesystem clerk from Claude, Cursor, or any MCP client.",
+    "type": "module",
+    "main": "index.mjs",
+    "bin": {
+        "filemayor-mcp": "./index.mjs"
+    },
+    "files": [
+        "index.mjs",
+        "README.md",
+        "LICENSE"
+    ],
+    "engines": {
+        "node": ">=20.20.0"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "filemayor",
+        "filesystem",
+        "file-organization",
+        "file-manager",
+        "local-first",
+        "reversible",
+        "claude",
+        "cursor",
+        "zed",
+        "anthropic",
+        "ai",
+        "llm",
+        "agent"
+    ],
+    "mcp": {
+        "startCommand": "npx -y filemayor-mcp",
+        "transport": "stdio",
+        "auditCommand": "npx -y filemayor-mcp --audit"
+    },
+    "author": {
+        "name": "Lehlohonolo Goodwill Nchefu (Chevza)",
+        "email": "hloninchefu@gmail.com"
+    },
+    "license": "PROPRIETARY",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Hrypopo/FileMayor.git",
+        "directory": "mcp"
+    },
+    "homepage": "https://filemayor.com",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.4"
+    }
+}