@imenam/refactoring-mcp 2.0.0

package/README.md

@@ -0,0 +1,72 @@
+# @imenam/refactoring-mcp
+
+An MCP (Model Context Protocol) server that lets AI agents copy or move blocks of code between files, with optional directory confinement for safety.
+
+## Tools
+
+### `move_or_copy_code`
+
+Copies or moves a range of lines from a source file to a destination file.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `sourceFile` | `string` | ✅ | Absolute path to the source file |
+| `startLine` | `number` | ✅ | Start line of the block (1-indexed) |
+| `endLine` | `number` | ✅ | End line of the block, inclusive (1-indexed) |
+| `operationType` | `"copy" \| "cut"` | ✅ | `copy` keeps the source intact, `cut` removes the lines |
+| `destinationFile` | `string` | ✅ | Absolute path to the destination file (created automatically if it doesn't exist) |
+| `destinationLine` | `number` | ❌ | Line at which to insert in the destination (appended at end by default) |
+
+### `get_file_outline`
+
+Returns the list of top-level symbols in a file (functions, classes, interfaces, types, constants, methods) with their start and end line numbers. Useful for identifying the exact coordinates of a code block before moving it.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `filePath` | `string` | ✅ | Absolute path to the file to analyse |
+
+## Configuration
+
+All file paths must be **absolute**. Relative paths are rejected.
+
+To restrict operations to a specific directory, set the `REFACTORING_ALLOWED_DIR` environment variable. Any attempt to access a file outside that directory will be blocked.
+
+```env
+# .env
+REFACTORING_ALLOWED_DIR=C:/Users/you/my-project
+```
+
+## Installation
+
+```bash
+npm install -g @imenam/refactoring-mcp
+```
+
+Or use it directly with `npx`:
+
+```json
+{
+  "refactoring-mcp": {
+    "command": "npx",
+    "args": ["-y", "@imenam/refactoring-mcp"]
+  }
+}
+```
+
+Or point to a local build:
+
+```json
+{
+  "refactoring-mcp": {
+    "command": "node",
+    "args": ["/absolute/path/to/refactoring-mcp/dist/index.js"],
+    "env": {
+      "REFACTORING_ALLOWED_DIR": "/absolute/path/to/your/project"
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,167 @@
+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 { z } from "zod";
+import { setupLogging } from "./logger.js";
+import { executeRefactor } from "./utils/files.js";
+import { getFileOutline } from "./utils/outline.js";
+setupLogging("MASTER");
+const server = new Server({ name: "refactoring-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
+const RefactorSchema = z.object({
+    sourceFile: z.string().describe("Chemin absolu complet du fichier d'origine"),
+    startLine: z
+        .number()
+        .int()
+        .positive()
+        .describe("Ligne de début du bloc de code (1-indexé)"),
+    endLine: z
+        .number()
+        .int()
+        .positive()
+        .describe("Ligne de fin du bloc de code incluse (1-indexé)"),
+    operationType: z
+        .enum(["copy", "cut"])
+        .describe("Type d'opération : copy (copie) ou cut (coupure/déplacement)"),
+    destinationFile: z
+        .string()
+        .describe("Chemin absolu complet du fichier de destination (créé automatiquement si inexistant)"),
+    destinationLine: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optionnel : ligne d'insertion dans le fichier de destination (1-indexé). Ajout en fin de fichier par défaut."),
+});
+const OutlineSchema = z.object({
+    filePath: z
+        .string()
+        .describe("Chemin absolu complet du fichier à analyser"),
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "move_or_copy_code",
+            description: "Copie ou déplace un bloc de lignes de code d'un fichier source vers un fichier de destination. " +
+                "Le fichier de destination (ainsi que ses dossiers parents) est créé automatiquement s'il n'existe pas. " +
+                "Tous les chemins doivent être absolus.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sourceFile: {
+                        type: "string",
+                        description: "Chemin absolu complet du fichier d'origine",
+                    },
+                    startLine: {
+                        type: "number",
+                        description: "Ligne de début du bloc de code (1-indexé)",
+                    },
+                    endLine: {
+                        type: "number",
+                        description: "Ligne de fin du bloc de code incluse (1-indexé)",
+                    },
+                    operationType: {
+                        type: "string",
+                        enum: ["copy", "cut"],
+                        description: "Type d'opération : copy ou cut",
+                    },
+                    destinationFile: {
+                        type: "string",
+                        description: "Chemin absolu complet du fichier de destination",
+                    },
+                    destinationLine: {
+                        type: "number",
+                        description: "Optionnel : ligne d'insertion dans la destination (ajout en fin de fichier par défaut)",
+                    },
+                },
+                required: [
+                    "sourceFile",
+                    "startLine",
+                    "endLine",
+                    "operationType",
+                    "destinationFile",
+                ],
+            },
+        },
+        {
+            name: "get_file_outline",
+            description: "Retourne la liste des symboles de premier niveau d'un fichier " +
+                "(fonctions, classes, interfaces, types, constantes, méthodes) avec leurs numéros de lignes de début et de fin. " +
+                "Utile pour identifier les coordonnées précises d'un bloc de code avant de le déplacer. " +
+                "Le chemin doit être absolu.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filePath: {
+                        type: "string",
+                        description: "Chemin absolu complet du fichier à analyser",
+                    },
+                },
+                required: ["filePath"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (name === "get_file_outline") {
+        try {
+            const { filePath } = OutlineSchema.parse(args);
+            const symbols = await getFileOutline(filePath);
+            return {
+                content: [{ type: "text", text: JSON.stringify(symbols, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Erreur : ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    if (name === "move_or_copy_code") {
+        try {
+            const validatedArgs = RefactorSchema.parse(args);
+            const result = await executeRefactor(validatedArgs);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Succès : opération "${result.operation}" effectuée.\n` +
+                            `- Lignes traitées : ${result.linesMoved}\n` +
+                            `- Fichier source : ${result.sourceLength} lignes après opération\n` +
+                            `- Fichier destination : ${result.destLength} lignes après opération`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Erreur : ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    return {
+        content: [{ type: "text", text: `Outil inconnu : ${name}` }],
+        isError: true,
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Serveur MCP Refactoring Helper démarré en stdio.");
+}
+main().catch((error) => {
+    console.error("Erreur critique au démarrage :", error);
+    process.exit(1);
+});

package/dist/logger.js

@@ -0,0 +1,37 @@
+import fs from "fs";
+import path from "path";
+const logDir = process.platform === "win32"
+    ? "C:\\var\\log\\refactoring-mcp"
+    : "/var/log/refactoring-mcp";
+const logFile = path.join(logDir, "server.log");
+export function setupLogging(prefix) {
+    if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+    }
+    const logToFile = (msg) => {
+        const timestamp = new Date().toISOString();
+        try {
+            fs.appendFileSync(logFile, `[${timestamp}] [PID ${process.pid}] [${prefix}] ${msg}\n`, "utf-8");
+        }
+        catch {
+            // Silently ignore log write failures to avoid crashing the server
+        }
+    };
+    // Rediriger console.log vers stderr pour protéger le flux JSON-RPC MCP
+    console.log = (...args) => {
+        const msg = args
+            .map((arg) => (typeof arg === "object" ? JSON.stringify(arg) : String(arg)))
+            .join(" ");
+        logToFile(`[INFO] ${msg}`);
+        process.stderr.write(msg + "\n");
+    };
+    // Surcharger console.error pour journalisation automatique
+    const originalError = console.error.bind(console);
+    console.error = (...args) => {
+        const msg = args
+            .map((arg) => (typeof arg === "object" ? JSON.stringify(arg) : String(arg)))
+            .join(" ");
+        logToFile(`[ERROR] ${msg}`);
+        originalError(msg);
+    };
+}

package/dist/utils/config.js

@@ -0,0 +1,11 @@
+import path from "path";
+import { fileURLToPath } from "url";
+import dotenv from "dotenv";
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const envPath = path.join(rootDir, ".env");
+export function getConfig() {
+    dotenv.config({ path: envPath, override: true });
+    const rawDir = process.env.REFACTORING_ALLOWED_DIR;
+    const allowedDir = rawDir ? path.resolve(rawDir) : null;
+    return { allowedDir };
+}

package/dist/utils/files.js

@@ -0,0 +1,96 @@
+import fs from "fs/promises";
+import path from "path";
+import { getConfig } from "./config.js";
+const MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024; // 10 MB
+export async function validateAndResolvePath(filePath) {
+    if (!path.isAbsolute(filePath)) {
+        throw new Error(`Le chemin doit être absolu : "${filePath}"`);
+    }
+    const resolved = path.resolve(filePath);
+    // Résoudre les symlinks pour éviter les contournements de confinement
+    // Si le fichier n'existe pas encore (destination), on résout le dossier parent
+    let realResolved;
+    try {
+        realResolved = await fs.realpath(resolved);
+    }
+    catch {
+        const parent = path.dirname(resolved);
+        try {
+            const realParent = await fs.realpath(parent);
+            realResolved = path.join(realParent, path.basename(resolved));
+        }
+        catch {
+            // Le dossier parent n'existe pas non plus — on conserve le chemin résolu
+            realResolved = resolved;
+        }
+    }
+    const { allowedDir } = getConfig();
+    if (allowedDir) {
+        // Normaliser avec séparateur pour éviter les faux positifs (ex: /foo vs /foobar)
+        const normalizedResolved = realResolved.endsWith(path.sep)
+            ? realResolved
+            : realResolved + path.sep;
+        const normalizedAllowed = allowedDir.endsWith(path.sep)
+            ? allowedDir
+            : allowedDir + path.sep;
+        if (!normalizedResolved.startsWith(normalizedAllowed) &&
+            realResolved !== allowedDir) {
+            throw new Error(`Accès interdit : le chemin "${realResolved}" n'est pas confiné dans le dossier autorisé "${allowedDir}"`);
+        }
+    }
+    return realResolved;
+}
+export async function checkFileSize(filePath) {
+    const stats = await fs.stat(filePath);
+    if (stats.size > MAX_FILE_SIZE_BYTES) {
+        throw new Error(`Fichier trop volumineux : ${Math.round(stats.size / 1024 / 1024)} MB (maximum ${MAX_FILE_SIZE_BYTES / 1024 / 1024} MB)`);
+    }
+}
+export async function executeRefactor(params) {
+    const sourcePath = await validateAndResolvePath(params.sourceFile);
+    const destPath = await validateAndResolvePath(params.destinationFile);
+    // Vérifier la taille du fichier source avant lecture
+    await checkFileSize(sourcePath);
+    // Lire le fichier source
+    const sourceContent = await fs.readFile(sourcePath, "utf-8");
+    const sourceLines = sourceContent.split(/\r?\n/);
+    const { startLine, endLine } = params;
+    if (startLine < 1 || endLine > sourceLines.length || startLine > endLine) {
+        throw new Error(`Lignes source invalides (demandées: ${startLine}-${endLine}, fichier source de ${sourceLines.length} lignes)`);
+    }
+    // Extraire le segment
+    const segment = sourceLines.slice(startLine - 1, endLine);
+    // Si coupure, supprimer les lignes du fichier source
+    if (params.operationType === "cut") {
+        sourceLines.splice(startLine - 1, endLine - startLine + 1);
+        await fs.writeFile(sourcePath, sourceLines.join("\n"), "utf-8");
+    }
+    // Préparer le fichier de destination (création automatique si inexistant)
+    const destDir = path.dirname(destPath);
+    await fs.mkdir(destDir, { recursive: true });
+    let destLines = [];
+    try {
+        const destContent = await fs.readFile(destPath, "utf-8");
+        destLines = destContent.split(/\r?\n/);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        // Fichier inexistant : on part d'un tableau vide
+    }
+    // Insérer le segment dans la destination
+    if (params.destinationLine !== undefined && params.destinationLine > 0) {
+        const insertIndex = Math.max(0, Math.min(destLines.length, params.destinationLine - 1));
+        destLines.splice(insertIndex, 0, ...segment);
+    }
+    else {
+        destLines.push(...segment);
+    }
+    await fs.writeFile(destPath, destLines.join("\n"), "utf-8");
+    return {
+        linesMoved: segment.length,
+        operation: params.operationType,
+        sourceLength: sourceLines.length,
+        destLength: destLines.length,
+    };
+}

package/dist/utils/outline.js

@@ -0,0 +1,55 @@
+import fs from "fs/promises";
+import { validateAndResolvePath, checkFileSize } from "./files.js";
+const SYMBOL_PATTERNS = [
+    {
+        regex: /^(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+(\w+)/,
+        type: "function",
+    },
+    {
+        regex: /^(?:export\s+)?(?:abstract\s+)?class\s+(\w+)/,
+        type: "class",
+    },
+    {
+        regex: /^(?:export\s+)?interface\s+(\w+)/,
+        type: "interface",
+    },
+    {
+        regex: /^(?:export\s+)?type\s+(\w+)\s*[=<]/,
+        type: "type",
+    },
+    {
+        regex: /^(?:export\s+)?(?:const|let|var)\s+(\w+)\s*[=:]/,
+        type: "const",
+    },
+    // Méthodes dans une classe (indentées d'au moins 2 espaces/tab)
+    // On exclut les mots-clés JS/TS pour éviter les faux positifs (if, for, while, switch, catch, return...)
+    {
+        regex: /^[ \t]{2,}(?:(?:public|private|protected|static|async|override)\s+)*(?!(if|for|while|switch|catch|return|throw|new|typeof|instanceof|await|yield|delete|void|case|else|do)\b)(\w+)\s*[(<]/,
+        type: "method",
+    },
+];
+export async function getFileOutline(filePath) {
+    const resolved = await validateAndResolvePath(filePath);
+    await checkFileSize(resolved);
+    const content = await fs.readFile(resolved, "utf-8");
+    const lines = content.split(/\r?\n/);
+    const symbols = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        for (const { regex, type } of SYMBOL_PATTERNS) {
+            const match = line.match(regex);
+            if (match && match[1]) {
+                // Pour le pattern "method", le groupe capturant est match[2] car match[1] est le lookahead
+                const name = match[2] ?? match[1];
+                symbols.push({ name, type, startLine: i + 1, endLine: 0 });
+                break;
+            }
+        }
+    }
+    // Calculer les lignes de fin : fin du symbole = début du suivant - 1 (ou fin du fichier)
+    for (let i = 0; i < symbols.length; i++) {
+        symbols[i].endLine =
+            i + 1 < symbols.length ? symbols[i + 1].startLine - 1 : lines.length;
+    }
+    return symbols;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@imenam/refactoring-mcp",
+  "version": "2.0.0",
+  "description": "MCP server to copy or move code blocks between files, with optional directory confinement.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "refactoring-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "release:patch": "npm version patch && npm publish --access public && git push origin main --follow-tags",
+    "release:minor": "npm version minor && npm publish --access public && git push origin main --follow-tags",
+    "release:major": "npm version major && npm publish --access public && git push origin main --follow-tags"
+  },
+  "keywords": [
+    "mcp",
+    "refactoring",
+    "code",
+    "move",
+    "copy",
+    "model-context-protocol"
+  ],
+  "author": "imenam",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Matthieu-Pesnot-Pin/refactoring-mcp.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3"
+  }
+}