filemayor-mcp 4.0.5 → 4.0.6

package/README.md

@@ -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). |
@@ -106,8 +105,8 @@ This is the supply-chain risk that applies to *every* MCP server in principle, o
 
 - 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.
+- The *only* off-machine egress path is the optional AI call inside `filemayor_plan`, gated by an AI provider key (`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `OPENAI_API_KEY`). 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
 
@@ -120,10 +119,10 @@ This is the supply-chain risk that applies to *every* MCP server in principle, o
     "defaultEgress": "none",
     "optionalEgress": {
       "enabled": false,
-      "destination": "https://generativelanguage.googleapis.com",
-      "trigger": "filemayor_plan tool only",
+      "destination": "ai provider API (Anthropic / Google / OpenAI — whichever key is set)",
+      "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": "ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENAI_API_KEY environment variable"
     }
   },
   "runtimeSafeguards": {
@@ -161,7 +160,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,14 @@
  *
  * 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:
+ *   ANTHROPIC_API_KEY  → Claude claude-haiku-4-5-20251001
+ *   GEMINI_API_KEY     → Gemini Flash
+ *   OPENAI_API_KEY     → GPT-4o-mini
  * ═══════════════════════════════════════════════════════════════════
  */
 
@@ -115,7 +122,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 +134,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) Gemini/external — call filemayor_plan first, 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',
@@ -254,7 +277,14 @@ async function handleTool(name, args) {
             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.');
+            if (!apiKey) {
+                return err(
+                    'filemayor_plan requires GEMINI_API_KEY (the underlying planner uses the Gemini API).\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.'
+                );
+            }
             const engine = new CureEngine(c.resolved, apiKey);
             const plan = await engine.generatePlan(args.prompt);
             activeCureEngine = engine;
@@ -262,8 +292,19 @@ async function handleTool(name, args) {
         }
 
         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 +422,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,
+                },
             });
         }
 

package/package.json

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