@imenam/mcp-documentor 1.0.67 → 1.0.69

package/README.md

@@ -37,6 +37,21 @@ Global install exposes:
 
 ## MCP Configuration
 
+### Quick setup
+
+From the repo you want to document, generate a ready-to-fill `.mcp.json` in the current directory:
+
+```bash
+npx @imenam/mcp-documentor --claude-setup-mcp
+```
+
+It creates the `mcp-documentor` entry with the usual environment variables as empty placeholders —
+an empty variable is simply inactive, so the generated config runs as-is and you only fill in what
+you need. An existing `.mcp.json` is merged, other servers are preserved, and an existing
+`mcp-documentor` entry is only replaced when `--force` is passed.
+
+### Manual setup
+
 Add to your MCP client config (e.g. Cursor `mcp.json`):
 
 ```json
@@ -62,6 +77,7 @@ Add to your MCP client config (e.g. Cursor `mcp.json`):
 | `PROXY_URL` | No | URL of the proxy server to register and launch the GUI |
 | `APP_GROUP` | No | Groups the app under a collapsible section (folded by default) in the proxy dashboard. Apps sharing the same value appear together; if unset, the app lands in the default "ungrouped" section |
 | `MCP_DATA_DIR` | No | Overrides the default data directory (see Data storage) |
+| `MCP_LOG_DIR` | No | Overrides the log directory of both the server and the GUI worker (default: `<package>/.docs-data/logs`). Must be set in the MCP client config — the package `.env` is loaded after the logger starts |
 | `MCP_DOCUMENTOR_CODE_ROOT` | No | Base directory that tracked-file paths are stored relative to, keeping docs portable across machines (see [Portable tracked-file paths](#portable-tracked-file-paths)) |
 | `MCP_DOCUMENTOR_CODE_ROOTS` | No | JSON map of per-project code-root overrides, e.g. `{"my-proj":"/srv/my-proj"}` |
 | `READ_ONLY` | No | When set to `1`/`true`/`yes`, disables all create/update/delete tools and GUI write actions (read-only mode) |

package/dist/src/cli/setup-mcp.d.ts

@@ -0,0 +1,5 @@
+export interface SetupMcpOptions {
+    cwd: string;
+    force: boolean;
+}
+export declare function runSetupMcp({ cwd, force }: SetupMcpOptions): number;

package/dist/src/cli/setup-mcp.js

@@ -0,0 +1,98 @@
+import fs from "fs";
+import path from "path";
+const SERVER_NAME = "mcp-documentor";
+const PACKAGE_NAME = "@imenam/mcp-documentor";
+/**
+ * Valeurs volontairement vides : chaque variable est inactive tant qu'elle n'est
+ * pas remplie (PROXY_URL vide = GUI désactivée, clé vide = pas d'embeddings),
+ * donc le fichier généré est utilisable tel quel, jamais à moitié cassé.
+ */
+/** Slashes POSIX : évite les backslashes échappés dans le JSON, et Node les accepte sous Windows. */
+function toPosixPath(dir) {
+    return dir.replace(/\\/g, "/");
+}
+function buildServerEntry(codeRoot) {
+    return {
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+        env: {
+            PROXY_URL: "",
+            APP_GROUP: "",
+            APP_PATH: "",
+            MCP_DATA_DIR: "",
+            MCP_LOG_DIR: "",
+            MCP_DOCUMENTOR_CODE_ROOT: toPosixPath(codeRoot),
+            MCP_DOCUMENTOR_OPENAI_API_KEY: "",
+            MCP_DOCUMENTOR_OPENAI_MODEL: "text-embedding-3-small",
+            MCP_DOCUMENTOR_SYNC_REMOTE: "",
+            MCP_DOCUMENTOR_SYNC_BRANCH: "",
+            MCP_DOCUMENTOR_SYNC_TOKEN: "",
+        },
+    };
+}
+const GENERATED_VARS = [
+    ["PROXY_URL", "URL du proxy pour exposer la GUI"],
+    ["APP_GROUP", "groupe d'affichage dans le dashboard du proxy"],
+    ["APP_PATH", "chemin de montage de la GUI derrière le proxy"],
+    ["MCP_DATA_DIR", "répertoire de données (défaut : celui du package)"],
+    ["MCP_LOG_DIR", "répertoire des logs"],
+    ["MCP_DOCUMENTOR_CODE_ROOT", "racine du code (pré-remplie avec le répertoire courant)"],
+    ["MCP_DOCUMENTOR_OPENAI_API_KEY", "clé OpenAI (active search_docs)"],
+    ["MCP_DOCUMENTOR_OPENAI_MODEL", "modèle d'embedding"],
+    ["MCP_DOCUMENTOR_SYNC_REMOTE", "URL HTTPS du repo privé de sync GitHub"],
+    ["MCP_DOCUMENTOR_SYNC_BRANCH", "branche de sync (défaut : main)"],
+    ["MCP_DOCUMENTOR_SYNC_TOKEN", "PAT GitHub fine-grained pour la sync"],
+];
+const OPTIONAL_VARS = [
+    ["MCP_DOCUMENTOR_CODE_ROOTS", 'code roots par projet, ex: {"my-proj":"/srv/my-proj"}'],
+    ["READ_ONLY", "1/true pour désactiver toutes les écritures"],
+    ["SYNC_PULL_ON_START", "false pour désactiver le pull au démarrage"],
+];
+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(30)} ${description}`);
+    }
+    console.log("");
+    console.log("Variables optionnelles à ajouter au besoin :");
+    for (const [name, description] of OPTIONAL_VARS) {
+        console.log(`  ${name.padEnd(30)} ${description}`);
+    }
+    console.log("");
+    console.log("Une variable laissée vide est simplement inactive.");
+    return 0;
+}

package/dist/src/core/log-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Répertoire des logs : MCP_LOG_DIR s'il est renseigné, sinon <racine>/.docs-data/logs.
+ * Lu depuis process.env uniquement (le .env du package est chargé après l'init du
+ * logger), donc la variable doit venir de la config du client MCP.
+ */
+export declare function resolveLogDir(rootDir: string): string;

package/dist/src/core/log-dir.js

@@ -0,0 +1,12 @@
+import path from "path";
+/**
+ * Répertoire des logs : MCP_LOG_DIR s'il est renseigné, sinon <racine>/.docs-data/logs.
+ * Lu depuis process.env uniquement (le .env du package est chargé après l'init du
+ * logger), donc la variable doit venir de la config du client MCP.
+ */
+export function resolveLogDir(rootDir) {
+    const configured = process.env.MCP_LOG_DIR?.trim();
+    if (configured)
+        return path.resolve(configured);
+    return path.join(rootDir, ".docs-data", "logs");
+}

package/dist/src/gui-worker.js

@@ -12,6 +12,7 @@ import { promisify } from "util";
 const execFileAsync = promisify(execFile);
 import { fileURLToPath } from "url";
 import { createLogger, setupLogging } from "@imenam/mcp-gui-interface";
+import { resolveLogDir } from "./core/log-dir.js";
 import matter from "gray-matter";
 import JSZip from "jszip";
 import puppeteer from "puppeteer-core";
@@ -31,7 +32,7 @@ const dataDir = process.env.MCP_DATA_DIR?.trim() || path.join(rootDir, ".docs-da
 const staticRoot = path.join(rootDir, "gui/dist");
 const absoluteStaticRoot = path.resolve(staticRoot);
 const configuredAppPath = process.env.APP_PATH || "/documentor-gui";
-setupLogging({ processLabel: "mcp-documentor:GUI", logDir: path.join(rootDir, ".docs-data", "logs") });
+setupLogging({ processLabel: "mcp-documentor:GUI", logDir: resolveLogDir(rootDir) });
 const logger = createLogger("mcp-documentor:GUI");
 process.on("uncaughtException", (err) => {
     logger.error(`Uncaught Exception: ${err.message}`);

package/dist/src/index.js

@@ -8,6 +8,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { APP_VERSION } from "./version.js";
 import { GuiLauncher, createLogger, setupLogging } from "@imenam/mcp-gui-interface";
+import { resolveLogDir } from "./core/log-dir.js";
 import { StorageEngine } from "./core/storage-engine.js";
 import { EmbeddingStore } from "./core/embedding-store.js";
 import { EmbeddingEngine } from "./core/embedding-engine.js";
@@ -45,6 +46,12 @@ import { syncStatus, pullDocs, pushDocs, syncDocs, resolveSyncConflict } from ".
 import { isReadOnly, WRITE_TOOLS } from "../shared/read-only.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+// Les flags CLI sont traités avant toute initialisation (storage, sqlite, logs) :
+// 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") }));
+}
 function findProjectRoot(startDir) {
     let current = startDir;
     while (current !== path.dirname(current)) {
@@ -57,7 +64,7 @@ function findProjectRoot(startDir) {
 }
 const rootDir = findProjectRoot(__dirname);
 const packageEnvPath = path.join(rootDir, ".env");
-setupLogging({ processLabel: "mcp-documentor", logDir: path.join(rootDir, ".docs-data", "logs") });
+setupLogging({ processLabel: "mcp-documentor", logDir: resolveLogDir(rootDir) });
 const logger = createLogger("mcp-documentor");
 function getConfig() {
     if (fs.existsSync(packageEnvPath)) {
@@ -784,7 +791,7 @@ async function reconnectGui(args) {
         };
     }
     return {
-        content: [{ type: "text", text: "GUI worker started but did not confirm proxy registration within 15s. Check the logs (.docs-data/logs), then retry." }],
+        content: [{ type: "text", text: `GUI worker started but did not confirm proxy registration within 15s. Check the logs (${resolveLogDir(rootDir)}), then retry.` }],
         isError: true,
     };
 }

package/dist/src/version.d.ts

@@ -1 +1 @@
-export declare const APP_VERSION = "1.0.67";
+export declare const APP_VERSION = "1.0.69";

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated version file - do not edit manually
-export const APP_VERSION = '1.0.67';
+export const APP_VERSION = '1.0.69';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imenam/mcp-documentor",
-  "version": "1.0.67",
+  "version": "1.0.69",
   "main": "dist/src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",