aiquila-mcp 0.3.11 → 0.3.12

package/dist/auth/store.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 import { randomUUID } from 'node:crypto';
 import { readFileSync, writeFileSync, mkdirSync, renameSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { logger } from '../logger.js';
 const CODE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const REFRESH_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
@@ -9,6 +9,39 @@ const DEFAULT_STATE_DIR = '/app/state';
 function stateDir() {
     return (process.env.MCP_AUTH_STATE_DIR ?? DEFAULT_STATE_DIR).replace(/\/+$/, '');
 }
+// True once we've emitted the loud "state dir not writable" warning, so the
+// startup probe and the first failed persist warn at most once between them —
+// subsequent persist failures drop to debug to avoid flooding the logs.
+let warnedUnwritable = false;
+/**
+ * Operator-facing remediation for an unwritable state directory. The fix is to
+ * recreate the (root-owned) Docker named volume so a fresh one inherits the
+ * image's node ownership — `docker compose exec ... chown` cannot be used here
+ * because the container would otherwise be in a crash loop. See discussion #342.
+ */
+export function stateUnwritableMessage(dir, code) {
+    return (`State directory ${dir} is not writable${code ? ` (${code})` : ''} — ` +
+        `OAuth tokens will NOT persist; clients must re-authenticate after every restart. ` +
+        `To restore persistence, recreate the state volume (this clears existing tokens; ` +
+        `clients re-authenticate once):\n` +
+        `  docker compose down mcp && docker volume rm <project>_mcp_state && docker compose up -d mcp\n` +
+        `See https://github.com/elgorro/aiquila/discussions/342`);
+}
+/**
+ * Marks the unwritable-state warning as already emitted (called by the startup
+ * probe in the HTTP transport) so the first failed persist does not warn twice.
+ */
+export function markStateUnwritableWarned() {
+    warnedUnwritable = true;
+}
+function warnPersistFailed(dir, code, err) {
+    if (warnedUnwritable) {
+        logger.debug({ dir, code, err }, '[state] persist failed — state dir not writable');
+        return;
+    }
+    warnedUnwritable = true;
+    logger.warn({ dir, code }, stateUnwritableMessage(dir, code));
+}
 function ensureDir(dir) {
     try {
         mkdirSync(dir, { recursive: true });
@@ -49,7 +82,10 @@ function saveJson(filePath, data) {
         catch {
             // ignore cleanup failure
         }
-        throw err;
+        // Graceful degradation: a persist failure must never crash a request or the
+        // process. The server keeps running with in-memory state (tokens just won't
+        // survive a restart) and warns the operator how to fix it. See discussion #342.
+        warnPersistFailed(dirname(filePath), err.code, err);
     }
 }
 export class StateDirNotWritableError extends Error {

package/dist/transports/http.js

@@ -7,7 +7,7 @@ import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
 import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
 import { createServer, SERVER_VERSION } from '../server.js';
 import { NextcloudOAuthProvider } from '../auth/provider.js';
-import { probeStateDir, StateDirNotWritableError } from '../auth/store.js';
+import { probeStateDir, StateDirNotWritableError, stateUnwritableMessage, markStateUnwritableWarned, } from '../auth/store.js';
 import { loginHandler } from '../auth/login.js';
 import { logger } from '../logger.js';
 import { fetchStatus } from '../client/ocs.js';
@@ -182,11 +182,16 @@ export async function startHttp() {
         }
         catch (err) {
             if (err instanceof StateDirNotWritableError) {
-                logger.fatal({ dir: err.dir, code: err.cause.code }, `[startup] State directory is not writable — refresh tokens cannot be persisted. ` +
-                    `Fix volume ownership and restart:\n  docker compose exec -u 0 mcp chown -R node:node ${err.dir}\n  docker compose restart mcp`);
-                process.exit(1);
+                // Degrade gracefully rather than crash-loop: the server still serves
+                // requests, it just can't persist OAuth tokens until the operator fixes
+                // the volume. Crashing here was un-fixable under `restart: unless-stopped`
+                // because `docker compose exec` needs a running container (discussion #342).
+                logger.warn({ dir: err.dir, code: err.cause.code }, stateUnwritableMessage(err.dir, err.cause.code));
+                markStateUnwritableWarned();
+            }
+            else {
+                throw err;
             }
-            throw err;
         }
         const provider = new NextcloudOAuthProvider();
         // When gated dynamic registration is desired, require a bearer token on POST /register.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiquila-mcp",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "AIquila - MCP server for Nextcloud integration",
   "type": "module",
   "main": "dist/index.js",