@imenam/simple-scraper 1.0.15 → 1.0.17

package/README.md

@@ -31,6 +31,23 @@ npm install -g @imenam/simple-scraper
 simple-scraper
 ```
 
+## MCP Configuration
+
+### Quick setup
+
+From the repo you want to scrape from, generate a ready-to-fill `.mcp.json` in the current directory:
+
+```bash
+npx @imenam/simple-scraper --claude-setup-mcp
+```
+
+It creates the `simple-scraper-mcp` entry with the proxy variables pre-filled from the current
+folder name (`PROXY_URL`, `APP_GROUP`, `PROXY_APP_NAME`, `PROXY_APP_PATH`) plus a 1920x1080
+viewport, and prints the remaining optional variables. An empty variable is simply inactive
+(no `PROXY_URL` = no GUI), so the generated config runs as-is. An existing `.mcp.json` is merged,
+other servers are preserved, and an existing `simple-scraper-mcp` entry is only replaced when
+`--force` is passed.
+
 ## Environment Variables
 
 | Variable | Required | Default | Description |
@@ -332,7 +349,7 @@ The capture area is resolved by precedence: `selector` → `clip` → `full_page
 | `full_page` | boolean | | Capture the full scrollable page height (default: false, ignored when `selector` or `clip` is provided) |
 | `format` | `png` \| `jpeg` | | Image format (default: `png`) |
 | `output` | `inline` \| `file` \| `both` | ✅ | `inline` embeds the image in the response, `file` saves to disk and returns the path, `both` does both |
-| `path` | string | | Absolute or relative path for the saved file. Defaults to `./screenshots/screenshot-<timestamp>.<format>` |
+| `path` | string | | **Absolute** path for the saved file — relative paths are rejected, since they would resolve against the server's working directory, which the client sets unpredictably. Missing parent directories are created. Defaults to `<server_root>/screenshots/screenshot-<timestamp>.<format>` |
 
 ---
 

package/dist/cli/setup-mcp.js

@@ -0,0 +1,103 @@
+import fs from 'fs';
+import path from 'path';
+const SERVER_NAME = 'simple-scraper-mcp';
+const PACKAGE_NAME = '@imenam/simple-scraper';
+/** "simple-scraper" -> "Simple-scraper" */
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/** "my_project-web" -> "My Project Web" */
+function toDisplayName(folder) {
+    return folder
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map(capitalize)
+        .join(' ');
+}
+/**
+ * Valeurs volontairement vides : chaque variable est inactive tant qu'elle n'est
+ * pas remplie (PROXY_URL vide = GUI désactivée), donc le fichier généré est
+ * utilisable tel quel, jamais à moitié cassé. Le viewport fait exception : un
+ * défaut 1920x1080 évite les layouts mobiles/tablette sur la plupart des sites.
+ */
+function buildServerEntry(codeRoot) {
+    // Le nom du dossier courant sert de base aux identifiants d'affichage côté proxy.
+    const folder = path.basename(codeRoot) || 'scraper';
+    return {
+        command: 'npx',
+        args: ['-y', PACKAGE_NAME],
+        env: {
+            PROXY_URL: 'http://localhost:',
+            APP_GROUP: capitalize(folder),
+            PROXY_APP_NAME: `Simple Scraper ${toDisplayName(folder)}`,
+            PROXY_APP_PATH: `/simple-scraper-${folder}`,
+            PUPPETEER_VIEWPORT_WIDTH: '1920',
+            PUPPETEER_VIEWPORT_HEIGHT: '1080',
+        },
+    };
+}
+const GENERATED_VARS = [
+    ['PROXY_URL', 'URL du proxy pour exposer la GUI (compléter le port)'],
+    ['APP_GROUP', 'groupe d\'affichage dans le dashboard du proxy'],
+    ['PROXY_APP_NAME', 'nom affiché de la GUI dans le dashboard du proxy'],
+    ['PROXY_APP_PATH', 'chemin de montage de la GUI derrière le proxy'],
+    ['PUPPETEER_VIEWPORT_WIDTH', 'largeur du viewport en pixels CSS'],
+    ['PUPPETEER_VIEWPORT_HEIGHT', 'hauteur du viewport en pixels CSS'],
+];
+const OPTIONAL_VARS = [
+    ['PUPPETEER_DEVICE_SCALE_FACTOR', 'pixels physiques par pixel CSS (2 = screenshots retina)'],
+    ['PUPPETEER_HEADLESS', 'false pour afficher la fenêtre Chromium'],
+    ['PUPPETEER_TIMEOUT', 'timeout de navigation en ms (défaut : 30000)'],
+    ['COOKIES_DIR', 'dossier de fichiers cookies au format Netscape (.txt)'],
+    ['MCP_LOG_DIR', 'répertoire des logs'],
+    ['SCRAPER_MAX_SESSIONS', 'nombre max de sessions interactives (défaut : 5)'],
+    ['SCRAPER_SESSION_TTL_MS', 'TTL d\'inactivité des sessions en ms (défaut : 600000)'],
+];
+export function runSetupMcp({ cwd, force }) {
+    const target = path.join(cwd, '.mcp.json');
+    let config = {};
+    const exists = fs.existsSync(target);
+    if (exists) {
+        const raw = fs.readFileSync(target, 'utf-8').trim();
+        if (raw !== '') {
+            try {
+                config = JSON.parse(raw);
+            }
+            catch (err) {
+                console.error(`Erreur : ${target} contient du JSON invalide (${err.message}).`);
+                console.error('Corrigez le fichier ou supprimez-le, puis relancez la commande.');
+                return 1;
+            }
+        }
+        if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+            console.error(`Erreur : ${target} ne contient pas un objet JSON.`);
+            return 1;
+        }
+    }
+    if (typeof config.mcpServers !== 'object' || config.mcpServers === null || Array.isArray(config.mcpServers)) {
+        config.mcpServers = {};
+    }
+    const alreadyPresent = Object.prototype.hasOwnProperty.call(config.mcpServers, SERVER_NAME);
+    if (alreadyPresent && !force) {
+        console.error(`Le serveur "${SERVER_NAME}" est déjà configuré dans ${target}.`);
+        console.error('Relancez avec --force pour écraser cette entrée (les autres serveurs sont préservés).');
+        return 1;
+    }
+    config.mcpServers[SERVER_NAME] = buildServerEntry(cwd);
+    fs.writeFileSync(target, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    const action = alreadyPresent ? 'remplacée' : exists ? 'ajoutée' : 'créée';
+    console.log(`Configuration ${SERVER_NAME} ${action} dans ${target}`);
+    console.log('');
+    console.log('À compléter dans le champ "env" :');
+    for (const [name, description] of GENERATED_VARS) {
+        console.log(`  ${name.padEnd(32)} ${description}`);
+    }
+    console.log('');
+    console.log('Variables optionnelles à ajouter au besoin :');
+    for (const [name, description] of OPTIONAL_VARS) {
+        console.log(`  ${name.padEnd(32)} ${description}`);
+    }
+    console.log('');
+    console.log('Une variable laissée vide est simplement inactive.');
+    return 0;
+}

package/dist/index.js

@@ -15,6 +15,12 @@ import { registerSessionRpc } from './session-rpc.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDir = path.resolve(__dirname, '..');
 const envPath = path.join(rootDir, '.env');
+// Les flags CLI sont traités avant toute initialisation (dotenv, logs, GUI) :
+// ils s'exécutent dans le répertoire de l'utilisateur, pas dans un serveur MCP.
+if (process.argv.slice(2).includes('--claude-setup-mcp')) {
+    const { runSetupMcp } = await import('./cli/setup-mcp.js');
+    process.exit(runSetupMcp({ cwd: process.cwd(), force: process.argv.slice(2).includes('--force') }));
+}
 dotenv.config({ path: envPath, override: true });
 setupLogging('MASTER');
 const launcher = new GuiLauncher({
@@ -592,7 +598,13 @@ server.tool('screenshot', 'Take a screenshot of a page. Provide either session_i
     full_page: z.boolean().optional().describe('Capture the full scrollable page height (default: false, ignored when selector or clip is provided)'),
     format: z.enum(['png', 'jpeg']).optional().describe('Image format (default: png)'),
     output: z.enum(['inline', 'file', 'both']).describe('Return format: "inline" embeds the image in the response, "file" saves to disk and returns the path, "both" does both'),
-    path: z.string().optional().describe('Absolute or relative file path for the saved image (used when output is "file" or "both"). Relative paths are resolved from the MCP server\'s working directory. Defaults to <server_root>/screenshots/<timestamp>.<format>'),
+    path: z
+        .string()
+        .refine(p => path.isAbsolute(p), {
+        message: 'path must be absolute — a relative path would resolve against the MCP server\'s working directory, which is set by the client and not predictable.',
+    })
+        .optional()
+        .describe('Absolute file path for the saved image (used when output is "file" or "both"). Must be absolute; missing parent directories are created. Defaults to <server_root>/screenshots/screenshot-<timestamp>.<format>'),
 }, async ({ session_id, url, wait_for, timeout, selector, clip, viewport, full_page, format, output, path: filePath }) => {
     const effectiveTimeout = timeout ?? getDefaultTimeout();
     const fmt = format ?? 'png';
@@ -646,7 +658,8 @@ server.tool('screenshot', 'Take a screenshot of a page. Provide either session_i
             imageBuffer = Buffer.from(await page.screenshot({ type: fmt, fullPage: full_page ?? false }));
         }
         const base64 = imageBuffer.toString('base64');
-        // Resolve file path
+        // Resolve file path. filePath is guaranteed absolute by the schema; resolve()
+        // is kept only to normalise separators and any ".." segments.
         const resolvedPath = (() => {
             if (filePath)
                 return path.resolve(filePath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/simple-scraper",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "MCP server for web scraping and JavaScript execution using Puppeteer",
   "type": "module",
   "main": "dist/index.js",