filemayor-mcp 4.0.5 → 4.0.7

package/README.md

@@ -2,7 +2,7 @@
 
 **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)
+`v4.0.7` · Node ≥20 · [filemayor.com/mcp](https://filemayor.com/mcp)
 
 [![smithery badge](https://smithery.ai/badge/filemayor-mcp)](https://smithery.ai/server/filemayor-mcp)
 
@@ -29,10 +29,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
   "mcpServers": {
     "filemayor": {
       "command": "npx",
-      "args": ["-y", "filemayor-mcp"],
-      "env": {
-        "GEMINI_API_KEY": "your-key-here"
-      }
+      "args": ["-y", "filemayor-mcp"]
     }
   }
 }
@@ -40,6 +37,8 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 
 Restart Claude. You'll see the FileMayor tools in the 🔧 menu.
 
+> **No API key needed.** When Claude is the client, Claude IS the AI — it calls `filemayor_explain` to audit the folder, reasons about the moves, and passes them directly to `filemayor_apply`. The `filemayor_plan` tool (which calls an external AI) is only for non-Claude clients.
+
 ## 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.
@@ -51,7 +50,7 @@ Any client that speaks MCP over stdio works. Point it at `filemayor-mcp` and you
 | `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_plan` | For non-Claude clients: AI-generated plan using whichever key is set (`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `OPENAI_API_KEY`). When Claude is the client, skip this — Claude reasons directly. |
 | `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). |
@@ -104,26 +103,30 @@ Doesn't apply. FileMayor MCP is **Node.js**, not Python. Its single runtime depe
 
 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.
+- The whole server is one file: [`mcp/index.mjs`](https://github.com/Hrypopo/FileMayor/blob/main/mcp/index.mjs) — ~580 lines. Tool declarations and their `case` handlers sit side-by-side. You can read it end-to-end in about 15 minutes. (`--audit` prints the exact current line count under `verifyBy`, so the number can't drift out of date.)
 - `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.
+- The *only* off-machine egress path is the optional AI call inside `filemayor_plan`, gated by an AI provider key (`ANTHROPIC_API_KEY` → Claude, `GEMINI_API_KEY` → Gemini, or `OPENAI_API_KEY` → GPT-4o-mini). The first key present wins. Without any key, the tool returns an error and nothing is sent. With a key, only directory metadata (paths, sizes, extensions) is sent — no file contents. When Claude is the MCP client, `filemayor_plan` is not needed at all.
+- The GitHub repo is the canonical source.
 
 ### What `--audit` reports
 
 ```json
 {
   "package": "filemayor-mcp",
-  "version": "4.0.0",
+  "version": "4.0.7",
   "transport": { "type": "stdio", "networkListeners": false, "ports": [] },
   "outbound": {
     "defaultEgress": "none",
     "optionalEgress": {
       "enabled": false,
-      "destination": "https://generativelanguage.googleapis.com",
-      "trigger": "filemayor_plan tool only",
+      "destinations": [
+        "https://api.anthropic.com",
+        "https://generativelanguage.googleapis.com",
+        "https://api.openai.com"
+      ],
+      "trigger": "filemayor_plan tool only (not used when Claude is the MCP client)",
       "payload": "directory metadata only — no file contents",
-      "gatedBy": "GEMINI_API_KEY environment variable"
+      "gatedBy": "one of ANTHROPIC_API_KEY / GEMINI_API_KEY / OPENAI_API_KEY (none currently set)"
     }
   },
   "runtimeSafeguards": {
@@ -137,7 +140,7 @@ This is the supply-chain risk that applies to *every* MCP server in principle, o
   "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.",
+    "Read mcp/index.mjs end-to-end — the report prints the exact current line count here.",
     "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."
@@ -149,7 +152,7 @@ This is the supply-chain risk that applies to *every* MCP server in principle, o
 
 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.
+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 ~580 lines of source is the trustworthy path.
 
 ### Hardened-runtime safeguards (the engine, not just the MCP shell)
 
@@ -161,7 +164,7 @@ Every tool that touches disk runs through the same security layers the CLI and D
 | 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. |
+| No-telemetry | The MCP server makes no analytics calls. The only off-machine call is the documented, opt-in AI planner in `filemayor_plan` (not used when Claude is the client). |
 
 ## License
 

package/index.mjs

@@ -12,7 +12,17 @@
  *
  * 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.
+ * full rollback.
+ *
+ * When Claude is the MCP client, Claude IS the AI — no external API key
+ * is needed. filemayor_plan is available for non-Claude clients (Cursor,
+ * Zed, scripts) and picks up whichever key is set in the environment, in
+ * this priority order:
+ *   ANTHROPIC_API_KEY  → Claude (claude-haiku-4-5-20251001)
+ *   GEMINI_API_KEY     → Gemini (gemini-2.0-flash)
+ *   OPENAI_API_KEY     → GPT-4o-mini
+ * The key selects the provider; the core planner (cli/core/ai) dispatches
+ * the actual call. See detectAiProvider() below.
  * ═══════════════════════════════════════════════════════════════════
  */
 
@@ -75,6 +85,24 @@ function checkDir(p) {
     return { resolved: v.resolved };
 }
 
+// Pick the external AI provider for filemayor_plan from whichever key is
+// set, in priority order. The core planner (cli/core/ai) dispatches on
+// FM_AI_PROVIDER + FM_AI_API_KEY, so the keys below are the single source
+// of truth for what the tool actually supports. Returns null if no key.
+const AI_PROVIDERS = [
+    { env: 'ANTHROPIC_API_KEY', provider: 'anthropic', label: 'Claude (claude-haiku-4-5-20251001)' },
+    { env: 'GEMINI_API_KEY',    provider: 'gemini',    label: 'Gemini (gemini-2.0-flash)' },
+    { env: 'OPENAI_API_KEY',    provider: 'openai',    label: 'GPT-4o-mini' },
+];
+
+function detectAiProvider() {
+    for (const p of AI_PROVIDERS) {
+        const apiKey = process.env[p.env];
+        if (apiKey) return { ...p, apiKey };
+    }
+    return null;
+}
+
 // ─── Tool definitions ──────────────────────────────────────────────
 
 const TOOLS = [
@@ -115,7 +143,7 @@ const TOOLS = [
     },
     {
         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.',
+        description: 'For non-Claude MCP clients: generates a move plan from a natural-language prompt using an available AI provider (ANTHROPIC_API_KEY → Claude, GEMINI_API_KEY → Gemini, OPENAI_API_KEY → GPT-4o-mini). When Claude IS the client, skip this tool — instead call filemayor_explain to audit the folder, reason about the moves yourself, then pass them directly to filemayor_apply as the "moves" parameter.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -127,8 +155,24 @@ const TOOLS = [
     },
     {
         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: {} },
+        description: 'Execute a move plan and journal every operation for rollback. Two modes: (1) Claude-native — pass a "moves" array of {src, dst} objects that you generated yourself after calling filemayor_explain; (2) external-AI — call filemayor_plan first (Anthropic / Gemini / OpenAI, by key), then call this with no arguments to execute that plan. The journal is written to disk so filemayor_rollback can undo it.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                moves: {
+                    type: 'array',
+                    description: 'Optional. Array of move operations to execute. Each entry must have "src" (absolute source path) and "dst" (absolute destination path). When provided, skips filemayor_plan entirely — use this when Claude is generating the plan directly.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            src: { type: 'string', description: 'Absolute path of the file to move.' },
+                            dst: { type: 'string', description: 'Absolute destination path.' },
+                        },
+                        required: ['src', 'dst'],
+                    },
+                },
+            },
+        },
     },
     {
         name: 'filemayor_rollback',
@@ -253,17 +297,51 @@ async function handleTool(name, args) {
             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);
+            const ai = detectAiProvider();
+            if (!ai) {
+                return err(
+                    'filemayor_plan needs an AI provider key for non-Claude clients. Set one of:\n' +
+                    '  ANTHROPIC_API_KEY → Claude (claude-haiku-4-5-20251001)\n' +
+                    '  GEMINI_API_KEY    → Gemini (gemini-2.0-flash)\n' +
+                    '  OPENAI_API_KEY    → GPT-4o-mini\n\n' +
+                    'If Claude is your MCP client you do NOT need this tool — Claude is already the AI. ' +
+                    'Instead: call filemayor_explain to audit the folder, reason about the moves yourself, ' +
+                    'then pass them directly to filemayor_apply as the "moves" parameter.'
+                );
+            }
+            // Route the core planner to the selected provider. Restore the
+            // previous env afterwards so we never leak state between calls.
+            const prevProvider = process.env.FM_AI_PROVIDER;
+            const prevKey = process.env.FM_AI_API_KEY;
+            process.env.FM_AI_PROVIDER = ai.provider;
+            process.env.FM_AI_API_KEY = ai.apiKey;
+            try {
+                const engine = new CureEngine(c.resolved, ai.apiKey);
+                const plan = await engine.generatePlan(args.prompt);
+                activeCureEngine = engine;
+                return ok({ provider: ai.label, ...plan });
+            } finally {
+                if (prevProvider === undefined) delete process.env.FM_AI_PROVIDER;
+                else process.env.FM_AI_PROVIDER = prevProvider;
+                if (prevKey === undefined) delete process.env.FM_AI_API_KEY;
+                else process.env.FM_AI_API_KEY = prevKey;
+            }
         }
 
         case 'filemayor_apply': {
+            // Claude-native path: caller supplies explicit move list.
+            if (Array.isArray(args.moves) && args.moves.length > 0) {
+                const applyer = new ApplyEngine();
+                const plan = args.moves.map(m => ({ source: m.src, destination: m.dst }));
+                const results = await applyer.apply(plan);
+                return ok(results);
+            }
+            // External-planner path: filemayor_plan must have run first.
             if (!activeCureEngine || !activeCureEngine.plan) {
-                return err('No active plan. Call filemayor_plan first.');
+                return err(
+                    'No active plan. Either call filemayor_plan first, or pass a "moves" array directly ' +
+                    '(recommended when Claude is the client).'
+                );
             }
             const applyer = new ApplyEngine();
             const results = await applyer.apply(activeCureEngine.plan);
@@ -381,7 +459,11 @@ async function handleTool(name, args) {
                 node: process.version,
                 platform: `${process.platform} ${process.arch}`,
                 license: getLicenseInfo?.() ?? { tier: 'free', name: 'Free' },
-                geminiConfigured: !!process.env.GEMINI_API_KEY,
+                aiProviders: {
+                    anthropic: !!process.env.ANTHROPIC_API_KEY,
+                    gemini:    !!process.env.GEMINI_API_KEY,
+                    openai:    !!process.env.OPENAI_API_KEY,
+                },
             });
         }
 
@@ -407,9 +489,16 @@ if (process.argv.includes('--audit')) {
         'filemayor_undo_last',
     ]);
 
+    const activeProvider = detectAiProvider();
+    const PROVIDER_ENDPOINTS = {
+        anthropic: 'https://api.anthropic.com',
+        gemini: 'https://generativelanguage.googleapis.com',
+        openai: 'https://api.openai.com',
+    };
+
     const report = {
         package: 'filemayor-mcp',
-        version: '4.0.0',
+        version: PKG_VERSION,
         node: process.version,
         platform: `${process.platform}-${process.arch}`,
         transport: {
@@ -420,20 +509,21 @@ if (process.argv.includes('--audit')) {
         },
         outbound: {
             defaultEgress: 'none',
-            optionalEgress: process.env.GEMINI_API_KEY
+            optionalEgress: activeProvider
                 ? {
                     enabled: true,
-                    destination: 'https://generativelanguage.googleapis.com',
+                    destination: PROVIDER_ENDPOINTS[activeProvider.provider],
+                    provider: activeProvider.label,
                     trigger: 'filemayor_plan tool only',
                     payload: 'directory metadata (paths, sizes, extensions). No file contents.',
-                    gatedBy: 'GEMINI_API_KEY environment variable',
+                    gatedBy: `${activeProvider.env} environment variable`,
                 }
                 : {
                     enabled: false,
-                    destination: 'https://generativelanguage.googleapis.com',
+                    destinations: Object.values(PROVIDER_ENDPOINTS),
                     trigger: 'filemayor_plan tool only',
                     payload: 'directory metadata only — no file contents',
-                    gatedBy: 'GEMINI_API_KEY environment variable (currently NOT set)',
+                    gatedBy: 'one of ANTHROPIC_API_KEY / GEMINI_API_KEY / OPENAI_API_KEY (none currently set)',
                 },
         },
         runtimeSafeguards: {
@@ -458,7 +548,7 @@ if (process.argv.includes('--audit')) {
         },
         source: 'https://github.com/Hrypopo/FileMayor/blob/main/mcp/index.mjs',
         verifyBy: [
-            "Read mcp/index.mjs end-to-end — it's ~410 lines.",
+            `Read mcp/index.mjs end-to-end — it's ${(() => { try { return fs.readFileSync(new URL(import.meta.url)).toString().split('\n').length; } catch { return 'a few hundred'; } })()} 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.",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "filemayor-mcp",
-    "version": "4.0.5",
+    "version": "4.0.7",
     "description": "FileMayor MCP server — drive the intelligent filesystem clerk from Claude, Cursor, or any MCP client.",
     "type": "module",
     "main": "index.mjs",