[release] Eager prefs probe in select_appwrite_project, slim get_auth_status, drop sessionProjectId

select_appwrite_project now resolves auth at select time instead of leaving
the override identity-only. Precedence:
  1. caller-supplied apiKey / sessionCookie
  2. YAML-inline real apiKey / sessionCookie
  3. cached prefsKey from ~/.appwrite/projects.json (probed for freshness)
  4. findWorkingSession(endpoint, projectId) — probe all prefs cookies
  5. none — selection still binds identity, response surfaces a warning

Response gains `authPinned: { method, source, prefsKey }` and a `warning`
field that names exactly what was tried when no auth was found. The
working prefsKey is persisted to the project registry so future
select-by-projectId calls short-circuit straight to the cached cookie.

get_auth_status default output collapses to nine slim keys (authenticated,
authMethod, endpoint, projectId, projectDir, configSource, source,
warnings, resolveError). The previous serverDefaults / cwdProject /
sessionOverride / effectiveConfigDir blocks lived at the top level and
created a false impression of two projects in play whenever the override
projectId differed from the cwd-config projectId. Pass
`includeDiagnostics: true` to reattach those blocks under a single
`diagnostics` field.

sessionProjectId removed from the YAML schema (appwrite-utils +
appwrite-utils-helpers) and from ConfigManager's session-loading branch.
Was a cache hint written back to user-checked-in YAML files — the role is
taken over by the projects.json registry, which is MCP-owned and never
touches user-tracked files. Existing YAMLs with the stray field still
load cleanly (Zod strips unknown keys) and writeYamlConfig no longer
emits the field on rewrite.

ProjectRegistryEntry and ProjectOverride gain optional prefsKey.
list_appwrite_projects.registeredProjects[] surfaces it.

Author: ZachHandley

packages/appwrite-utils-helpers/src/config/ConfigManager.ts

@@ -306,8 +306,13 @@ export class ConfigManager {
       // Session explicitly provided via options
       session = options.sessionOverride;
       logger.debug("Using session override from options", { prefix: "ConfigManager" });
-    } else if (options.useSession === true) {
-      // When session is explicitly requested, only accept a verified working session
+    } else {
+      // Probe prefs.json for a working session against this endpoint+project.
+      // Same call whether `useSession` was explicitly requested or not — we no
+      // longer write the resolved prefs key back to the YAML as a cache hint,
+      // so the only difference between modes used to be the cache-write path.
+      // Cross-run caching now lives in ~/.appwrite/projects.json (managed by
+      // the MCP's ProjectRegistry), not in user-checked-in config files.
       const workingSessionResult = await this.sessionService.findWorkingSession(
         config.appwriteEndpoint,
         config.appwriteProject
@@ -321,111 +326,6 @@ export class ConfigManager {
           `Found and tested working session from project ${workingSessionResult.prefsKey}`,
           { prefix: "ConfigManager", email: workingSessionResult.session.email }
         );
-
-        // Cache the working session key back to config file
-        config.sessionProjectId = workingSessionResult.prefsKey;
-
-        // Write the updated config back to file to cache the session key
-        const { writeYamlConfig } = await import('./yamlConfig.js');
-        try {
-          await writeYamlConfig(configPath, config);
-          logger.debug(`Cached session key ${workingSessionResult.prefsKey} to config file`, {
-            prefix: "ConfigManager"
-          });
-        } catch (error) {
-          logger.warn("Failed to cache session key to config file", {
-            prefix: "ConfigManager",
-            error: error instanceof Error ? error.message : String(error)
-          });
-        }
-      }
-    } else {
-      // First, try using cached sessionProjectId if available
-      if (config.sessionProjectId) {
-        logger.debug(`Attempting to use cached session key: ${config.sessionProjectId}`, {
-          prefix: "ConfigManager"
-        });
-
-        const prefs = await this.sessionService.loadSessionPrefs();
-        if (prefs && prefs[config.sessionProjectId]) {
-          const cachedSessionData = prefs[config.sessionProjectId];
-
-          // Verify the cached session still works
-          const sessionInfo: SessionAuthInfo = {
-            endpoint: cachedSessionData.endpoint,
-            projectId: config.appwriteProject,
-            cookie: cachedSessionData.cookie,
-            email: cachedSessionData.email,
-            expiresAt: cachedSessionData.expiresAt
-          };
-
-          const isValid = this.sessionService.isValidSession(sessionInfo);
-          const isWorking = isValid
-            ? await this.sessionService.isSessionWorking(
-                config.appwriteEndpoint,
-                config.appwriteProject,
-                cachedSessionData.cookie
-              )
-            : false;
-
-          if (isWorking) {
-            session = sessionInfo;
-            sessionPrefsKey = config.sessionProjectId;
-            logger.info(`Using cached session key: ${config.sessionProjectId}`, {
-              prefix: "ConfigManager",
-              email: cachedSessionData.email
-            });
-          } else {
-            logger.debug("Cached session is no longer valid, will search for new session", {
-              prefix: "ConfigManager"
-            });
-          }
-        } else {
-          logger.debug("Cached session key not found in prefs.json, will search for new session", {
-            prefix: "ConfigManager"
-          });
-        }
-      }
-
-      // If no cached session or it doesn't work, test all available sessions for this endpoint
-      if (!session) {
-        logger.debug("No direct session match, testing available sessions for endpoint", {
-          prefix: "ConfigManager",
-          endpoint: config.appwriteEndpoint,
-          projectId: config.appwriteProject
-        });
-
-        const workingSessionResult = await this.sessionService.findWorkingSession(
-          config.appwriteEndpoint,
-          config.appwriteProject
-        );
-
-        if (workingSessionResult) {
-          session = workingSessionResult.session;
-          sessionPrefsKey = workingSessionResult.prefsKey;
-
-          logger.info(
-            `Found and tested working session from project ${workingSessionResult.prefsKey}`,
-            { prefix: "ConfigManager", email: workingSessionResult.session.email }
-          );
-
-          // Cache the working session key back to config file
-          config.sessionProjectId = workingSessionResult.prefsKey;
-
-          // Write the updated config back to file to cache the session key
-          const { writeYamlConfig } = await import('./yamlConfig.js');
-          try {
-            await writeYamlConfig(configPath, config);
-            logger.debug(`Cached session key ${workingSessionResult.prefsKey} to config file`, {
-              prefix: "ConfigManager"
-            });
-          } catch (error) {
-            logger.warn("Failed to cache session key to config file", {
-              prefix: "ConfigManager",
-              error: error instanceof Error ? error.message : String(error)
-            });
-          }
-        }
       }
     }
 

packages/appwrite-utils-helpers/src/config/yamlConfig.ts

@@ -19,7 +19,6 @@ const YamlConfigSchema = z.object({
       email: z.string().optional(),
       expiresAt: z.string().optional(),
     }).optional(),
-    sessionProjectId: z.string().optional(),
   }),
   logging: z
     .object({
@@ -199,7 +198,6 @@ export const convertYamlToAppwriteConfig = (yamlConfig: YamlConfig): AppwriteCon
     sessionCookie: yamlConfig.appwrite.sessionCookie,
     authMethod: yamlConfig.appwrite.authMethod || "auto",
     sessionMetadata: yamlConfig.appwrite.sessionMetadata,
-    sessionProjectId: yamlConfig.appwrite.sessionProjectId,
     apiMode: "auto", // Default to auto-detect for dual API support
     appwriteClient: null,
     logging: {
@@ -567,7 +565,6 @@ export const writeYamlConfig = async (configPath: string, config: AppwriteConfig
         sessionCookie: config.sessionCookie,
         authMethod: config.authMethod || "auto",
         sessionMetadata: config.sessionMetadata,
-        sessionProjectId: config.sessionProjectId,
       },
       logging: {
         enabled: config.logging?.enabled || false,

packages/appwrite-utils-helpers/tests/sessionProjectIdHygiene.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import yaml from "js-yaml";
+
+import { loadYamlConfig, writeYamlConfig } from "../src/config/yamlConfig.js";
+
+/**
+ * Regression coverage for the `sessionProjectId` removal:
+ *
+ *  - existing user YAMLs that still carry a `sessionProjectId` field (written
+ *    by an older release of this package) must still parse cleanly — Zod
+ *    strips unknown keys by default, so loading just silently drops it
+ *  - `writeYamlConfig` MUST NOT re-emit the field even if it survived round-trip
+ *    via some other path (we want it gone next time the file is written)
+ */
+
+let scratch: string;
+
+beforeEach(async () => {
+  scratch = await mkdtemp(join(tmpdir(), "appwrite-mcp-sessionhygiene-"));
+});
+
+afterEach(async () => {
+  await rm(scratch, { recursive: true, force: true });
+});
+
+const yamlWithStraySessionProjectId = `
+appwrite:
+  endpoint: https://x.test/v1
+  project: real-project-id
+  key: standard_realkey
+  authMethod: auto
+  sessionProjectId: stale-prefs-key
+logging:
+  enabled: false
+  level: info
+backups:
+  enabled: true
+  interval: 3600
+  retention: 30
+  cleanup: true
+data:
+  enableMockData: false
+  documentBucketId: documents
+  usersCollectionName: Members
+  importDirectory: importData
+appwriteCollections: []
+appwriteTables: []
+functions: []
+sites: []
+buckets: []
+teams: []
+extension:
+  enabled: false
+`;
+
+describe("sessionProjectId hygiene", () => {
+  test("loadYamlConfig tolerates a stray sessionProjectId without crashing", async () => {
+    const path = join(scratch, "appwrite-config.yaml");
+    await writeFile(path, yamlWithStraySessionProjectId, "utf-8");
+
+    const config = await loadYamlConfig(path);
+    expect(config).not.toBeNull();
+    expect(config!.appwriteProject).toBe("real-project-id");
+    // Zod-stripped — the field never makes it onto the loaded config.
+    expect((config as any).sessionProjectId).toBeUndefined();
+  });
+
+  test("writeYamlConfig does NOT emit sessionProjectId even when injected onto the config object", async () => {
+    const path = join(scratch, "appwrite-config.yaml");
+    await writeFile(path, yamlWithStraySessionProjectId, "utf-8");
+
+    const config = await loadYamlConfig(path);
+    expect(config).not.toBeNull();
+
+    // Simulate an older code path that sneaks the field back in.
+    (config as any).sessionProjectId = "should-never-be-written";
+
+    await writeYamlConfig(path, config!);
+    const raw = await readFile(path, "utf-8");
+    const parsed = yaml.load(raw) as { appwrite?: Record<string, unknown> };
+    expect(parsed.appwrite).toBeDefined();
+    expect("sessionProjectId" in (parsed.appwrite ?? {})).toBe(false);
+  });
+});

packages/appwrite-utils-mcp/src/auth/AuthResolver.ts

@@ -98,6 +98,13 @@ export interface ProjectOverride {
    * trees without restarting from a different working directory.
    */
   projectDir?: string;
+  /**
+   * Cache hint: which key in `~/.appwrite/prefs.json` last passed a live
+   * probe for this project (via `select_appwrite_project`'s eager probe).
+   * Surfaced for diagnostics; the override's `sessionCookie` is the actual
+   * auth payload.
+   */
+  prefsKey?: string;
 }
 
 /**

packages/appwrite-utils-mcp/src/state/ProjectRegistry.ts

@@ -30,6 +30,14 @@ import { randomBytes } from "node:crypto";
 export interface ProjectRegistryEntry {
   projectDir: string;
   endpoint?: string;
+  /**
+   * Key into `~/.appwrite/prefs.json` whose cookie last passed a live probe
+   * for this project (via `SessionAuthService.findWorkingSession`). Used as a
+   * cache hint on subsequent selections so the resolver can skip re-probing
+   * every cookie. Stale entries are detected at use time and quietly
+   * superseded — losing freshness here is never fatal.
+   */
+  prefsKey?: string;
   lastSelectedAt: string;
 }
 
@@ -111,6 +119,7 @@ export class ProjectRegistry {
     const next: ProjectRegistryEntry = {
       projectDir: entry.projectDir,
       endpoint: entry.endpoint,
+      prefsKey: entry.prefsKey,
       lastSelectedAt: entry.lastSelectedAt ?? new Date().toISOString(),
     };
     snapshot[projectId] = next;
@@ -180,13 +189,16 @@ function normalize(parsed: unknown): ProjectRegistrySnapshot {
     const entry = raw as {
       projectDir?: unknown;
       endpoint?: unknown;
+      prefsKey?: unknown;
       lastSelectedAt?: unknown;
     };
     if (typeof entry.projectDir !== "string" || !entry.projectDir) continue;
     out[pid] = {
       projectDir: entry.projectDir,
       endpoint:
         typeof entry.endpoint === "string" && entry.endpoint ? entry.endpoint : undefined,
+      prefsKey:
+        typeof entry.prefsKey === "string" && entry.prefsKey ? entry.prefsKey : undefined,
       lastSelectedAt:
         typeof entry.lastSelectedAt === "string" && entry.lastSelectedAt
           ? entry.lastSelectedAt