@imenam/mcp-documentor 1.0.72 → 1.0.76

package/dist/src/gui-worker.js

@@ -32,6 +32,22 @@ 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";
+function resolveGuiMode() {
+    const proxyUrl = process.env.PROXY_URL?.trim();
+    if (proxyUrl)
+        return { kind: "proxy", proxyUrl };
+    const rawPort = process.env.APP_PORT?.trim();
+    if (!rawPort) {
+        return { kind: "disabled", reason: "PROXY_URL et APP_PORT non définis" };
+    }
+    const port = Number(rawPort);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return { kind: "disabled", reason: `APP_PORT invalide (${rawPort}) — attendu : entier entre 1 et 65535` };
+    }
+    return { kind: "standalone", port };
+}
+const guiMode = resolveGuiMode();
+const isStandalone = guiMode.kind === "standalone";
 setupLogging({ processLabel: "mcp-documentor:GUI", logDir: resolveLogDir(rootDir) });
 const logger = createLogger("mcp-documentor:GUI");
 process.on("uncaughtException", (err) => {
@@ -208,7 +224,7 @@ app.get("/proxy/health", (c) => {
     const memory = process.memoryUsage();
     return c.json({
         status: "ok",
-        proxy: proxyClient ? proxyClient.getStatus() : process.env.PROXY_URL ? "error" : "standalone",
+        proxy: proxyClient ? proxyClient.getStatus() : isStandalone ? "standalone" : "error",
         uptime: process.uptime(),
         memory: { rss: memory.rss, heapUsed: memory.heapUsed },
         ipc: process.connected ? "connected" : "disconnected",
@@ -343,22 +359,29 @@ app.get("/api/projects", async (c) => {
 });
 app.get("/api/folders", async (c) => {
     const project = c.req.query("project");
-    const result = await ipcRequest("LIST_FOLDERS", project ? { project } : {});
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
+    const result = await ipcRequest("LIST_FOLDERS", { project });
     if (result.error)
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
 });
-app.put("/api/project", async (c) => {
+// Creates an empty project. Selecting a project is a client-side concern:
+// the server holds no active project.
+app.post("/api/projects", async (c) => {
     const { project } = await c.req.json();
     if (!project)
         return c.json({ error: "project is required" }, 400);
-    const result = await ipcRequest("UPDATE_PROJECT", { project });
+    const result = await ipcRequest("CREATE_PROJECT", { project });
     if (result.error)
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
 });
 app.get("/api/docs", async (c) => {
-    const result = await ipcRequest("LIST_DOCS");
+    const project = c.req.query("project");
+    if (!project)
+        return c.json({ error: "project query param is required" }, 400);
+    const result = await ipcRequest("LIST_DOCS", { project });
     if (result.error)
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
@@ -475,10 +498,13 @@ app.get("/api/history-version/*", async (c) => {
     return c.json(result.data);
 });
 app.post("/api/search", async (c) => {
-    const { query, top_k, all_projects } = await c.req.json();
+    const { query, top_k, all_projects, project } = await c.req.json();
     if (!query)
         return c.json({ error: "query is required" }, 400);
-    const result = await ipcRequest("SEARCH_DOCS", { query, top_k: top_k || 5, all_projects: !!all_projects });
+    if (!all_projects && !project) {
+        return c.json({ error: "project is required unless all_projects is set" }, 400);
+    }
+    const result = await ipcRequest("SEARCH_DOCS", { query, top_k: top_k || 5, all_projects: !!all_projects, project });
     if (result.error)
         return c.json({ error: result.error }, 500);
     return c.json(result.data);
@@ -522,14 +548,9 @@ app.get("/api/export-zip/:id", async (c) => {
     const bundle = bundles.find((b) => b.id === id);
     if (!bundle)
         return c.json({ error: "Bundle not found" }, 404);
-    let currentProject = "default";
-    try {
-        const configPath = path.join(dataDir, "config.json");
-        if (fs.existsSync(configPath)) {
-            currentProject = JSON.parse(fs.readFileSync(configPath, "utf-8")).currentProject ?? "default";
-        }
-    }
-    catch { /* use default */ }
+    // Legacy bundles may hold bare doc ids; they are resolved against the project
+    // the caller is viewing. Fully qualified "project:doc-id" refs ignore it.
+    const fallbackProject = c.req.query("project");
     const flat = c.req.query('flat') === '1';
     const includeHeaders = c.req.query('headers') === '1';
     const zip = new JSZip();
@@ -541,10 +562,15 @@ app.get("/api/export-zip/:id", async (c) => {
             project = ref.slice(0, colonIdx);
             docId = ref.slice(colonIdx + 1);
         }
-        else {
-            project = currentProject;
+        else if (fallbackProject) {
+            project = fallbackProject;
             docId = ref;
         }
+        else {
+            zip.file(`${ref}.md`, `# [Unqualified doc reference: ${ref} — no project given]
+`);
+            continue;
+        }
         const docFilePath = path.join(dataDir, "projects", project, ...docId.split("/")) + ".md";
         let content;
         if (!fs.existsSync(docFilePath)) {
@@ -704,8 +730,9 @@ app.get("/*", (c, next) => {
         const indexPath = path.join(absoluteStaticRoot, "index.html");
         if (fs.existsSync(indexPath)) {
             // ?__pdf=1 : accès direct depuis Puppeteer — pas de préfixe proxy dans <base href>
+            // En mode standalone la GUI est déjà servie à la racine : même règle.
             const isPdfRender = c.req.query('__pdf') === '1';
-            const baseHref = isPdfRender ? '/' : getHtmlBaseHref(configuredAppPath);
+            const baseHref = isStandalone || isPdfRender ? '/' : getHtmlBaseHref(configuredAppPath);
             const html = fs
                 .readFileSync(indexPath, "utf8")
                 .replace("<head>", `<head>\n    <base href="${baseHref}" />`);
@@ -717,12 +744,54 @@ app.get("/*", (c, next) => {
         return next();
     }
 });
+/**
+ * Lance Hono sur `port` et prévient le master. `publicUrl` est l'URL que
+ * l'utilisateur doit ouvrir : via le proxy, ou directement en localhost.
+ */
+function listen(port, publicUrl, isProxied) {
+    logger.info(`Starting Hono server on port ${port}...`);
+    const serverInstance = serve({ fetch: app.fetch, port, hostname: "0.0.0.0" }, (info) => {
+        logger.info(`Dashboard server listening on port ${info.port}`);
+        safeSend(IPCMessageSchema.parse({
+            type: "READY",
+            data: { port: info.port, isProxied, url: publicUrl },
+            timestamp: new Date().toISOString(),
+        }));
+    });
+    serverInstance.on("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+            // Sortie propre (code 0) : le master ne doit pas relancer un worker de plus.
+            logger.error(`Port ${port} already in use — another GUI instance is running.`);
+            safeSend(IPCMessageSchema.parse({
+                type: "ALREADY_RUNNING",
+                data: { url: publicUrl },
+                timestamp: new Date().toISOString(),
+            }));
+            process.exit(0);
+        }
+        logger.error(`Server error: ${err.message}`);
+        process.exit(1);
+    });
+}
+/** Sans proxy : la GUI écoute sur APP_PORT et est servie à la racine. */
+function startStandalone(port) {
+    const publicUrl = `http://localhost:${port}`;
+    logger.info(`Standalone mode (no PROXY_URL): serving GUI on ${publicUrl}`);
+    localPort = port;
+    guiPublicUrl = publicUrl;
+    setupIpcErrorHandlers();
+    listen(port, publicUrl, false);
+}
 async function startServer() {
-    if (!process.env.PROXY_URL) {
-        process.stderr.write('[GUI] PROXY_URL non défini — arrêt.\n');
+    if (guiMode.kind === "disabled") {
+        process.stderr.write(`[GUI] ${guiMode.reason} — arrêt.\n`);
         process.exit(0);
     }
-    const proxyUrl = process.env.PROXY_URL;
+    if (guiMode.kind === "standalone") {
+        startStandalone(guiMode.port);
+        return;
+    }
+    const proxyUrl = guiMode.proxyUrl;
     const appPath = configuredAppPath;
     const appName = process.env.APP_NAME || "MCP Documentor GUI";
     logger.info(`Starting server with proxyUrl=${proxyUrl}`);
@@ -769,19 +838,7 @@ async function startServer() {
     process.on("SIGTERM", cleanupProxy);
     process.on("SIGINT", cleanupProxy);
     setupIpcErrorHandlers();
-    logger.info(`Starting Hono server on port ${finalPort}...`);
-    const serverInstance = serve({ fetch: app.fetch, port: finalPort, hostname: "0.0.0.0" }, (info) => {
-        logger.info(`Dashboard server listening on port ${info.port}`);
-        safeSend(IPCMessageSchema.parse({
-            type: "READY",
-            data: { port: info.port, isProxied: true, url: publicUrl },
-            timestamp: new Date().toISOString(),
-        }));
-    });
-    serverInstance.on("error", (err) => {
-        logger.error(`Server error: ${err.message}`);
-        process.exit(1);
-    });
+    listen(finalPort, publicUrl, true);
 }
 startServer().catch((err) => {
     logger.error(`Failed to start GUI Worker: ${err.message}`);

package/dist/src/index.js

@@ -20,7 +20,6 @@ import { searchDocs } from "./tools/search-docs.js";
 import { checkFreshness, computeFreshness } from "./tools/check-freshness.js";
 import { findAndHashSection } from "./core/section-tracker.js";
 import { toAbsolutePath } from "./core/path-resolver.js";
-import { setProject } from "./tools/set-project.js";
 import { listProjects } from "./tools/list-projects.js";
 import { refreshFileSnapshot } from "./tools/refresh-file-snapshot.js";
 import { getDocMetadata } from "./tools/get-doc-metadata.js";
@@ -50,8 +49,14 @@ 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") }));
+    const argv = process.argv.slice(2);
+    const { runSetupMcp, parseGuiExposure } = await import("./cli/setup-mcp.js");
+    const parsed = parseGuiExposure(argv);
+    if ("error" in parsed) {
+        console.error(`Erreur : ${parsed.error}`);
+        process.exit(1);
+    }
+    process.exit(runSetupMcp({ cwd: process.cwd(), force: argv.includes("--force"), exposure: parsed.exposure }));
 }
 function findProjectRoot(startDir) {
     let current = startDir;
@@ -73,6 +78,7 @@ function getConfig() {
     }
     return {
         proxyUrl: process.env.PROXY_URL,
+        appPort: process.env.APP_PORT,
         version: APP_VERSION,
     };
 }
@@ -80,7 +86,9 @@ getConfig();
 const storageEngine = new StorageEngine(rootDir);
 const embeddingStore = new EmbeddingStore();
 const embeddingEngine = new EmbeddingEngine(embeddingStore);
-storageEngine.ensureProject(storageEngine.getConfig().currentProject);
+for (const project of storageEngine.getConfig().projects) {
+    storageEngine.ensureProject(project);
+}
 const openaiModel = process.env.MCP_DOCUMENTOR_OPENAI_MODEL || "text-embedding-3-small";
 embeddingStore.init(storageEngine.getDataDir(), openaiModel);
 const historyStore = new HistoryStore();
@@ -123,8 +131,8 @@ function handleIPCMessage(msg) {
     else if (msg.type === "GET_CONFIG") {
         handleGetConfig(msg);
     }
-    else if (msg.type === "UPDATE_PROJECT") {
-        handleUpdateProject(msg);
+    else if (msg.type === "CREATE_PROJECT") {
+        handleCreateProject(msg);
     }
     else if (msg.type === "LIST_PROJECTS") {
         handleListProjects(msg);
@@ -188,25 +196,45 @@ function requireProjectFromIPC(msg) {
         throw new Error("project is required for this operation");
     return project;
 }
+/** Loads one project's summaries and flags each entry as stale/broken. */
+async function listDocsWithFreshness(project) {
+    const docs = await storageEngine.listDocs(project);
+    for (const doc of docs) {
+        const full = await storageEngine.getDoc(doc.id, project);
+        if (full && full.tracked_files.length > 0) {
+            const report = computeFreshness(full.tracked_files, project);
+            doc.isStale = report.status === "stale" || report.status === "broken";
+            doc.isBroken = report.status === "broken";
+        }
+    }
+    return docs;
+}
+/**
+ * Tells every connected GUI that one project's docs changed. Clients showing
+ * that project refetch; the others ignore it. Broadcasting a full INITIAL_STATE
+ * here used to drag every client onto the writer's project.
+ */
+function broadcastDocsChanged(project) {
+    broadcastToGUI({
+        type: "DOCS_CHANGED",
+        data: { project },
+        timestamp: new Date().toISOString(),
+    });
+}
+/**
+ * Server-side state only: the project list and server capabilities. Which
+ * project a client displays is that client's own business (URL + local
+ * preference), so no docs and no active project are pushed here.
+ */
 async function handleGetInitialState(msg) {
     try {
         const config = storageEngine.getConfig();
-        const docs = await storageEngine.listDocs();
-        for (const doc of docs) {
-            const full = await storageEngine.getDoc(doc.id); // doc.id is now the full path
-            if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files, config.currentProject);
-                doc.isStale = report.status === "stale" || report.status === "broken";
-                doc.isBroken = report.status === "broken";
-            }
-        }
         const bundles = storageEngine.getBundles();
         broadcastToGUI({
             type: "INITIAL_STATE",
             correlationId: msg.correlationId,
             data: {
                 config,
-                docs,
                 projects: config.projects,
                 bundles,
                 readOnly: isReadOnly(),
@@ -228,39 +256,31 @@ async function handleGetConfig(msg) {
         timestamp: new Date().toISOString(),
     });
 }
-async function handleUpdateProject(msg) {
+/**
+ * Creates an empty project. It does NOT change any server-side "active"
+ * project — there is none: the selector in the GUI is a per-client view.
+ */
+async function handleCreateProject(msg) {
     try {
         const project = path.basename(msg.data.project);
         if (!project || project === "..")
             throw new Error("Invalid project name");
         storageEngine.ensureProject(project);
-        const config = storageEngine.getConfig();
-        config.currentProject = project;
-        storageEngine.saveConfig(config);
-        const docs = await storageEngine.listDocs();
-        for (const doc of docs) {
-            const full = await storageEngine.getDoc(doc.id);
-            if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files, project);
-                doc.isStale = report.status === "stale" || report.status === "broken";
-                doc.isBroken = report.status === "broken";
-            }
-        }
         broadcastToGUI({
-            type: "UPDATE_PROJECT_RESPONSE",
+            type: "CREATE_PROJECT_RESPONSE",
             correlationId: msg.correlationId,
-            data: { success: true, currentProject: project },
+            data: { success: true, project, projects: storageEngine.getConfig().projects },
             timestamp: new Date().toISOString(),
         });
         broadcastToGUI({
-            type: "INITIAL_STATE",
-            data: { config: storageEngine.getConfig(), docs, projects: storageEngine.getConfig().projects },
+            type: "PROJECTS_CHANGED",
+            data: { projects: storageEngine.getConfig().projects },
             timestamp: new Date().toISOString(),
         });
     }
     catch (err) {
         broadcastToGUI({
-            type: "UPDATE_PROJECT_RESPONSE",
+            type: "CREATE_PROJECT_RESPONSE",
             correlationId: msg.correlationId,
             error: err.message,
             timestamp: new Date().toISOString(),
@@ -278,16 +298,7 @@ async function handleListProjects(msg) {
 }
 async function handleListDocs(msg) {
     try {
-        const currentProject = storageEngine.getConfig().currentProject;
-        const docs = await storageEngine.listDocs();
-        for (const doc of docs) {
-            const full = await storageEngine.getDoc(doc.id);
-            if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files, currentProject);
-                doc.isStale = report.status === "stale" || report.status === "broken";
-                doc.isBroken = report.status === "broken";
-            }
-        }
+        const docs = await listDocsWithFreshness(requireProjectFromIPC(msg));
         broadcastToGUI({
             type: "LIST_DOCS_RESPONSE",
             correlationId: msg.correlationId,
@@ -327,8 +338,7 @@ async function handleGetDoc(msg) {
 }
 async function handleListFoldersIPC(msg) {
     try {
-        const project = msg.data?.project;
-        const docs = await storageEngine.listDocs(project);
+        const docs = await storageEngine.listDocs(requireProjectFromIPC(msg));
         const folders = new Set();
         for (const doc of docs) {
             if (doc.folder) {
@@ -394,21 +404,7 @@ async function handleCreateDocIPC(msg) {
             data: { success: true, id },
             timestamp: new Date().toISOString(),
         });
-        const config = storageEngine.getConfig();
-        const docs = await storageEngine.listDocs();
-        for (const doc of docs) {
-            const full = await storageEngine.getDoc(doc.id);
-            if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files, config.currentProject);
-                doc.isStale = report.status === "stale" || report.status === "broken";
-                doc.isBroken = report.status === "broken";
-            }
-        }
-        broadcastToGUI({
-            type: "INITIAL_STATE",
-            data: { config, docs, projects: config.projects },
-            timestamp: new Date().toISOString(),
-        });
+        broadcastDocsChanged(project);
     }
     catch (err) {
         broadcastToGUI({
@@ -430,9 +426,10 @@ async function handleUpdateDocIPC(msg) {
         return;
     }
     try {
+        const project = requireProjectFromIPC(msg);
         const result = await updateDoc(storageEngine, embeddingEngine, {
             path: msg.data.id,
-            project: requireProjectFromIPC(msg),
+            project,
             content: msg.data.content,
             ...(msg.data.title !== undefined && { title: msg.data.title }),
         });
@@ -453,6 +450,7 @@ async function handleUpdateDocIPC(msg) {
             data: { success: true, message },
             timestamp: new Date().toISOString(),
         });
+        broadcastDocsChanged(project);
     }
     catch (err) {
         broadcastToGUI({
@@ -493,21 +491,7 @@ async function handleDeleteDocIPC(msg) {
             data: { success: true, message },
             timestamp: new Date().toISOString(),
         });
-        const config = storageEngine.getConfig();
-        const docs = await storageEngine.listDocs();
-        for (const doc of docs) {
-            const full = await storageEngine.getDoc(doc.id);
-            if (full && full.tracked_files.length > 0) {
-                const report = computeFreshness(full.tracked_files, config.currentProject);
-                doc.isStale = report.status === "stale" || report.status === "broken";
-                doc.isBroken = report.status === "broken";
-            }
-        }
-        broadcastToGUI({
-            type: "INITIAL_STATE",
-            data: { config, docs, projects: config.projects },
-            timestamp: new Date().toISOString(),
-        });
+        broadcastDocsChanged(project);
     }
     catch (err) {
         broadcastToGUI({
@@ -603,9 +587,9 @@ async function handleSearchDocs(msg) {
             });
         }
         else {
-            const currentProject = storageEngine.getConfig().currentProject;
-            results = await embeddingEngine.search(query, currentProject, top_k || 5, async (docPath) => {
-                const doc = await storageEngine.getDoc(docPath);
+            const project = requireProjectFromIPC(msg);
+            results = await embeddingEngine.search(query, project, top_k || 5, async (docPath) => {
+                const doc = await storageEngine.getDoc(docPath, project);
                 if (!doc)
                     return null;
                 return { title: doc.title, content: doc.content };
@@ -832,9 +816,13 @@ function startGuiWorker() {
     });
     return child;
 }
+/** La GUI a besoin soit d'un proxy, soit d'un port local (mode standalone). */
+function guiIsConfigured() {
+    return !!(process.env.PROXY_URL?.trim() || process.env.APP_PORT?.trim());
+}
 function launchGUI() {
-    if (!process.env.PROXY_URL) {
-        logger.info('[MASTER] PROXY_URL non défini — GUI désactivée.');
+    if (!guiIsConfigured()) {
+        logger.info('[MASTER] Ni PROXY_URL ni APP_PORT défini — GUI désactivée.');
         guiStatus = "disabled";
         return;
     }
@@ -842,10 +830,10 @@ function launchGUI() {
     startGuiWorker();
 }
 async function reconnectGui(args) {
-    getConfig(); // relit le .env au cas où PROXY_URL aurait été ajouté après le démarrage
-    if (!process.env.PROXY_URL) {
+    getConfig(); // relit le .env au cas où PROXY_URL/APP_PORT aurait été ajouté après le démarrage
+    if (!guiIsConfigured()) {
         return {
-            content: [{ type: "text", text: "Error: PROXY_URL is not set — the GUI is disabled. Add PROXY_URL to the .env file, then call reconnect_gui again." }],
+            content: [{ type: "text", text: "Error: neither PROXY_URL nor APP_PORT is set — the GUI is disabled. Add PROXY_URL (to expose the GUI through the proxy) or APP_PORT (to serve it directly on localhost) to the .env file, then call reconnect_gui again." }],
             isError: true,
         };
     }
@@ -854,9 +842,9 @@ async function reconnectGui(args) {
     const force = args?.force === true;
     if (alive && !force) {
         if (guiStatus === "starting") {
-            return { content: [{ type: "text", text: "GUI worker is already starting (proxy registration in progress). Wait a few seconds, then call reconnect_gui again if needed." }] };
+            return { content: [{ type: "text", text: "GUI worker is already starting. Wait a few seconds, then call reconnect_gui again if needed." }] };
         }
-        return { content: [{ type: "text", text: `GUI is already registered with the proxy${guiUrl ? ` at ${guiUrl}` : ""}. Nothing to do (use force=true to restart it anyway).` }] };
+        return { content: [{ type: "text", text: `GUI is already running${guiUrl ? ` at ${guiUrl}` : ""}. Nothing to do (use force=true to restart it anyway).` }] };
     }
     logger.info(`[MASTER] reconnect_gui: ${alive ? "restarting (force)" : "relaunching"} GUI worker...`);
     const result = await new Promise((resolve) => {
@@ -867,20 +855,24 @@ async function reconnectGui(args) {
         guiStartWaiter = (r) => { cleanup(); resolve(r); };
         newChild.on("exit", onExit);
     });
+    const proxyUrl = process.env.PROXY_URL?.trim();
     if (result.outcome === "ready") {
-        return { content: [{ type: "text", text: `GUI reconnected and registered with the proxy. URL: ${result.url}` }] };
+        return { content: [{ type: "text", text: `GUI reconnected. URL: ${result.url}` }] };
     }
     if (result.outcome === "already_running") {
-        return { content: [{ type: "text", text: `GUI is already registered by another MCP instance. URL: ${result.url ?? "unknown"}` }] };
+        return { content: [{ type: "text", text: `GUI is already served by another MCP instance. URL: ${result.url ?? "unknown"}` }] };
     }
     if (result.outcome === "exited") {
+        const hint = proxyUrl
+            ? `The proxy server is probably still unreachable at ${proxyUrl}. Start the proxy server, then call reconnect_gui again.`
+            : `Port ${process.env.APP_PORT} is probably already taken by another process. Free it or set another APP_PORT, then call reconnect_gui again.`;
         return {
-            content: [{ type: "text", text: `GUI worker exited before completing registration (code=${result.code}). The proxy server is probably still unreachable at ${process.env.PROXY_URL}. Start the proxy server, then call reconnect_gui again.` }],
+            content: [{ type: "text", text: `GUI worker exited before it was ready (code=${result.code}). ${hint}` }],
             isError: true,
         };
     }
     return {
-        content: [{ type: "text", text: `GUI worker started but did not confirm proxy registration within 15s. Check the logs (${resolveLogDir(rootDir)}), then retry.` }],
+        content: [{ type: "text", text: `GUI worker started but did not confirm it was ready within 15s. Check the logs (${resolveLogDir(rootDir)}), then retry.` }],
         isError: true,
     };
 }
@@ -1059,20 +1051,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 required: [],
             },
         },
-        {
-            name: "set_project",
-            description: "Switch the active project and update it as the default for all subsequent MCP tool operations. If the project name does not exist yet, it is created automatically. Also controls what the GUI displays.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    project: { type: "string", description: "Project name to switch to (created if it does not exist)" },
-                },
-                required: ["project"],
-            },
-        },
         {
             name: "list_projects",
-            description: "List all available documentation projects and show which one is currently active.",
+            description: "List all available documentation projects. There is no active project: every tool call names the project it targets.",
             inputSchema: {
                 type: "object",
                 properties: {},
@@ -1154,9 +1135,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             inputSchema: {
                 type: "object",
                 properties: {
-                    project: { type: "string", description: "Project to check (defaults to current project)" },
+                    project: { type: "string", description: "Project whose entries are checked. Required — never defaulted to a current project." },
                 },
-                required: [],
+                required: ["project"],
             },
         },
         {
@@ -1362,7 +1343,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                             type: "object",
                             properties: {
                                 hunk: { type: "number", description: "Hunk number from get_conflict_hunks" },
-                                take: { type: "string", enum: ["local", "remote", "both", "none", "custom"], description: "'local' this machine, 'remote' the other machine, 'both' concatenates local then remote, 'none' drops the passage, 'custom' uses the provided content" },
+                                take: { type: "string", enum: ["local", "remote", "both", "none", "custom"], description: "'local' this machine, 'remote' the other machine, 'both' concatenates local then remote, 'none' drops the passage, 'custom' uses the provided content. 'both' is refused on frontmatter hunks, where it would duplicate a YAML key." },
                                 content: { type: "string", description: "Replacement text, required when take is 'custom'" },
                             },
                             required: ["hunk", "take"],
@@ -1410,7 +1391,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "check_freshness":
                 return await checkFreshness(storageEngine, args);
             case "set_project":
-                return await setProject(storageEngine, args);
+                // Removed: there is no server-side active project any more. Kept as an
+                // explicit answer for agents that still remember the old tool.
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: "set_project no longer exists: there is no active project. " +
+                                "Pass the project explicitly to every tool call (use list_projects to see them). " +
+                                "A project is created on demand by create_doc.",
+                        },
+                    ],
+                };
             case "list_projects":
                 return await listProjects(storageEngine);
             case "refresh_file_snapshot":
@@ -1505,9 +1498,6 @@ async function syncPullOnStartup() {
                 await reindexEmbeddings(storageEngine, embeddingEngine, embeddingStore, {});
             }
         }
-        else if (res.status === "diverged") {
-            logger.warn(`Startup sync: local history diverged (ahead ${res.ahead}, behind ${res.behind}). Started on local data — run sync_status / sync_docs to reconcile.`);
-        }
         else if (res.status === "conflict") {
             logger.warn(`Startup sync: merge conflict in ${res.conflicted.length} file(s). Started on local data — resolve with resolve_sync_conflict.`);
         }

package/dist/src/tools/check-links.js

@@ -38,7 +38,7 @@ export async function checkLinks(storageEngine, args) {
     try {
         const validated = CheckLinksArgsSchema.parse(args);
         const config = storageEngine.getConfig();
-        const project = validated.project ?? config.currentProject;
+        const project = validated.project;
         const knownProjects = new Set(config.projects);
         const docs = await storageEngine.listDocs(project);
         const validIds = new Set(docs.map((d) => d.id));