@fenglimg/fabric-server 2.3.0-rc.16 → 2.3.0-rc.17

package/dist/index.d.ts

@@ -1173,7 +1173,33 @@ declare const AGENTS_MD_RESOURCE_URI = "fabric://bootstrap-readme";
 declare function formatPreexistingRootMessage(projectRoot: string): string | null;
 
 declare const FABRIC_SERVER_INSTRUCTIONS: string;
+declare function buildServerInstructions(projectRoot: string): string;
 declare function createFabricServer(tracker?: InFlightTracker): McpServer;
+/**
+ * The slice of the MCP `Server` the roots adoption consumes — injectable so
+ * tests can drive it without a live transport.
+ */
+interface McpRootsSource {
+    getClientCapabilities(): {
+        roots?: unknown;
+    } | undefined;
+    listRoots(): Promise<{
+        roots: Array<{
+            uri?: string;
+        }>;
+    }>;
+}
+/**
+ * ISS werewolf-minigame (rootless MCP spawn, KT-PIT-0046): fetch the client's
+ * workspace roots (when the client declares the `roots` capability) and record
+ * them as project-root candidates via `setMcpRootsHint`. Returns the accepted
+ * absolute paths ([] when the capability is absent or the fetch fails —
+ * best-effort, never sinks startup). Called from `oninitialized`; the
+ * env > CLAUDE_PROJECT_DIR > roots > cwd priority lives in
+ * `resolveProjectRoot`, which every tool call re-runs, so adoption heals
+ * subsequent calls without a restart.
+ */
+declare function adoptMcpClientRoots(source: McpRootsSource): Promise<string[]>;
 declare function startStdioServer(): Promise<void>;
 /**
  * Dependencies for the shutdown handler factory. Tests inject `exit` to assert
@@ -1199,4 +1225,4 @@ interface ShutdownHandlerDeps {
  */
 declare function createShutdownHandler(deps: ShutdownHandlerDeps): () => void;
 
-export { AGENTS_MD_RESOURCE_URI, type AlwaysActiveBody, type ArchiveHistoryEntry, type ArchiveHistoryReport, type BacklogAgeMetric, COLD_EVAL_RUBRIC, type CiteCoverageReport, type ColdEvalBatch, type ColdEvalCandidate, type ColdEvalVerdict, type ConflictEntry, type ConflictJudge, type ConflictLintReport, type ConflictPair, type ConflictVerdict, type ConsumptionEntry, type ConsumptionInspection, type ConsumptionLintConfig, DEFAULT_CONFLICT_SIMILARITY_THRESHOLD, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type EnrichDescriptionsCandidate, type EnrichDescriptionsMode, type EnrichDescriptionsReport, FABRIC_SERVER_INSTRUCTIONS, type HistoryAllReport, type HistoryDayRow, type InFlightTracker, type KnowledgeCensus, LEDGER_PATH, LEGACY_LEDGER_PATH, METRICS_LEDGER_PATH, METRIC_COUNTER_NAMES, type MetricCounterName, type MetricsRow, OPTIONAL_EMBED_PACKAGE, type PlanContextInput, type PlanContextResult, type PrecheckResult, RETIRED_TOKENS, type RecallInput, type RecallResult, type RelatedBrokenLink, type RelatedGraphInspection, type RelatedGraphNode, type RelatedHubEntry, type RequirementProfile, type RetiredReferenceHit, type RetiredReferenceInspection, type RetiredToken, type SelectionTokenState, type ShutdownHandlerDeps, type StoreCanonicalEntry, type StoreReachability, type SurfaceVerdict, type UnboundProjectViolation, type WhyNotSurfacedResult, aggregateConsumption, appendEventLedgerEvent, buildAlwaysActiveBodies, buildColdEvalBatch, buildKnowledgeCensus, buildRelatedGraph, bumpCounter, checkBacklogAge, clearPrecheckCache, collectStoreCanonicalEntries, computeReadSetRevision, contextCache, createFabricServer, createInFlightTracker, createShutdownHandler, defaultEmbedCacheDir, detectUnboundProject, drainCounters, enrichDescriptions, evaluateStoreDir, explainWhyNotSurfaced, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, inspectConsumption, inspectRelatedGraph, inspectRetiredReferences, isEmbedderResolvable, lintConflicts, loadConflictEntries, loadEmbedder, pairSimilarity, planContext, precheckStoreReachability, readEmbedConfig, readEventLedger, readFusion, readLedger, readMetrics, readSelectionToken, recall, rehydrateAgentsMetaAt, renderBacklogAgeLine, resolveLedgerPaths, reviewKnowledge, reviewPending, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorConflictLint, runDoctorFix, runDoctorHistoryAll, runDoctorReport, startMetricsFlush, startRotationTick, startStdioServer, stopMetricsFlush, stopRotationTick };
+export { AGENTS_MD_RESOURCE_URI, type AlwaysActiveBody, type ArchiveHistoryEntry, type ArchiveHistoryReport, type BacklogAgeMetric, COLD_EVAL_RUBRIC, type CiteCoverageReport, type ColdEvalBatch, type ColdEvalCandidate, type ColdEvalVerdict, type ConflictEntry, type ConflictJudge, type ConflictLintReport, type ConflictPair, type ConflictVerdict, type ConsumptionEntry, type ConsumptionInspection, type ConsumptionLintConfig, DEFAULT_CONFLICT_SIMILARITY_THRESHOLD, type DoctorApplyLintMutation, type DoctorApplyLintMutationKind, type DoctorApplyLintReport, type DoctorFixReport, type DoctorIssue, type DoctorReport, EVENT_LEDGER_PATH, type EnrichDescriptionsCandidate, type EnrichDescriptionsMode, type EnrichDescriptionsReport, FABRIC_SERVER_INSTRUCTIONS, type HistoryAllReport, type HistoryDayRow, type InFlightTracker, type KnowledgeCensus, LEDGER_PATH, LEGACY_LEDGER_PATH, METRICS_LEDGER_PATH, METRIC_COUNTER_NAMES, type McpRootsSource, type MetricCounterName, type MetricsRow, OPTIONAL_EMBED_PACKAGE, type PlanContextInput, type PlanContextResult, type PrecheckResult, RETIRED_TOKENS, type RecallInput, type RecallResult, type RelatedBrokenLink, type RelatedGraphInspection, type RelatedGraphNode, type RelatedHubEntry, type RequirementProfile, type RetiredReferenceHit, type RetiredReferenceInspection, type RetiredToken, type SelectionTokenState, type ShutdownHandlerDeps, type StoreCanonicalEntry, type StoreReachability, type SurfaceVerdict, type UnboundProjectViolation, type WhyNotSurfacedResult, adoptMcpClientRoots, aggregateConsumption, appendEventLedgerEvent, buildAlwaysActiveBodies, buildColdEvalBatch, buildKnowledgeCensus, buildRelatedGraph, buildServerInstructions, bumpCounter, checkBacklogAge, clearPrecheckCache, collectStoreCanonicalEntries, computeReadSetRevision, contextCache, createFabricServer, createInFlightTracker, createShutdownHandler, defaultEmbedCacheDir, detectUnboundProject, drainCounters, enrichDescriptions, evaluateStoreDir, explainWhyNotSurfaced, extractKnowledge, findConflictCandidates, flushAndSyncEventLedger, flushMetrics, formatPreexistingRootMessage, getEventLedgerPath, getLedgerPath, getLegacyLedgerPath, getMetricsLedgerPath, inspectConsumption, inspectRelatedGraph, inspectRetiredReferences, isEmbedderResolvable, lintConflicts, loadConflictEntries, loadEmbedder, pairSimilarity, planContext, precheckStoreReachability, readEmbedConfig, readEventLedger, readFusion, readLedger, readMetrics, readSelectionToken, recall, rehydrateAgentsMetaAt, renderBacklogAgeLine, resolveLedgerPaths, reviewKnowledge, reviewPending, runDoctorApplyLint, runDoctorArchiveHistory, runDoctorCiteCoverage, runDoctorConflictLint, runDoctorFix, runDoctorHistoryAll, runDoctorReport, startMetricsFlush, startRotationTick, startStdioServer, stopMetricsFlush, stopRotationTick };

package/dist/index.js

@@ -112,6 +112,31 @@ function normalizeTrustedRootOverride(raw) {
     return null;
   }
 }
+function climbToAnchor(start) {
+  let dir = start;
+  let firstFabric = null;
+  for (let i = 0; i < 64; i++) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    if (firstFabric === null && existsSync(join(dir, ".fabric"))) firstFabric = dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return firstFabric;
+}
+var mcpRootsHint = [];
+function setMcpRootsHint(paths) {
+  const accepted = [];
+  for (const path of paths) {
+    const normalized = normalizeTrustedRootOverride(path);
+    if (normalized !== null && existsSync(normalized)) accepted.push(normalized);
+  }
+  mcpRootsHint = accepted;
+  return accepted.slice();
+}
+function isProjectRootConfigured(projectRoot) {
+  return existsSync(join(projectRoot, ".fabric", "fabric-config.json"));
+}
 function resolveProjectRoot(startCwd) {
   const envOverride = process.env.FABRIC_PROJECT_ROOT;
   if (typeof envOverride === "string" && envOverride.length > 0) {
@@ -123,17 +148,30 @@ function resolveProjectRoot(startCwd) {
     const normalized = normalizeTrustedRootOverride(claudeRoot);
     if (normalized !== null) return normalized;
   }
-  const start = typeof startCwd === "string" && startCwd.length > 0 ? startCwd : process.cwd();
-  let dir = start;
-  let firstFabric = null;
-  for (let i = 0; i < 64; i++) {
-    if (existsSync(join(dir, ".git"))) return dir;
-    if (firstFabric === null && existsSync(join(dir, ".fabric"))) firstFabric = dir;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
+  for (const rootHint of mcpRootsHint) {
+    const anchored2 = climbToAnchor(rootHint);
+    if (anchored2 !== null) return anchored2;
   }
-  return firstFabric ?? start;
+  const start = typeof startCwd === "string" && startCwd.length > 0 ? startCwd : process.cwd();
+  const anchored = climbToAnchor(start);
+  if (anchored !== null) return anchored;
+  return mcpRootsHint[0] ?? start;
+}
+
+// src/services/project-root-warning.ts
+var PROJECT_ROOT_UNRESOLVED_CODE = "project_root_unresolved";
+function projectRootUnresolvedMessage(projectRoot) {
+  return `project root unresolved \u2014 serving personal store only (resolved "${projectRoot}", no .fabric/fabric-config.json found; team stores are NOT loaded)`;
+}
+var PROJECT_ROOT_ACTION_HINT = "Set FABRIC_PROJECT_ROOT (or CLAUDE_PROJECT_DIR) in the MCP server env, launch the server from inside the project, or use an MCP client that exposes workspace roots (adopted automatically after initialize). Run `fabric doctor` in the project to verify.";
+function projectRootWarning(projectRoot) {
+  if (isProjectRootConfigured(projectRoot)) return null;
+  return {
+    code: PROJECT_ROOT_UNRESOLVED_CODE,
+    file: "<server>",
+    message: projectRootUnresolvedMessage(projectRoot),
+    action_hint: PROJECT_ROOT_ACTION_HINT
+  };
 }
 
 // src/services/event-ledger.ts
@@ -2881,6 +2919,10 @@ function registerExtractKnowledge(server, tracker) {
         if (gateWarn) {
           response.warnings = [gateWarn];
         }
+        const rootWarn = projectRootWarning(projectRoot);
+        if (rootWarn) {
+          response.warnings = [...response.warnings ?? [], rootWarn];
+        }
         const scopeWarn = unsealedProjectScopeWarning(projectRoot);
         if (scopeWarn) {
           response.warnings = [...response.warnings ?? [], scopeWarn];
@@ -4518,6 +4560,7 @@ function registerRecall(server, tracker) {
         const gateResult = await awaitFirstReconcileGate();
         const gateWarn = gateWarning(gateResult);
         const projectRoot = resolveProjectRoot();
+        const rootWarn = projectRootWarning(projectRoot);
         const input = {
           paths,
           intent,
@@ -4538,7 +4581,8 @@ function registerRecall(server, tracker) {
         const response = {
           ...result,
           warnings: [
-            ...gateWarn ? [gateWarn] : []
+            ...gateWarn ? [gateWarn] : [],
+            ...rootWarn ? [rootWarn] : []
           ]
         };
         const payloadLimits = readPayloadLimits(projectRoot);
@@ -4714,6 +4758,10 @@ function registerArchiveScan(server, tracker) {
           correlation_id,
           session_id
         });
+        const rootWarn = projectRootWarning(projectRoot);
+        if (rootWarn) {
+          result.warnings = [...result.warnings ?? [], rootWarn];
+        }
         const payloadLimits = readPayloadLimits(projectRoot);
         const serialized = JSON.stringify(result);
         const guardResult = enforcePayloadLimit3(serialized, payloadLimits);
@@ -6301,6 +6349,10 @@ function registerReview(server, tracker) {
         if (gateWarn) {
           response.warnings = [gateWarn];
         }
+        const rootWarn = projectRootWarning(projectRoot);
+        if (rootWarn) {
+          response.warnings = [...response.warnings ?? [], rootWarn];
+        }
         if (narrowed.action !== "retire") {
           const scopeWarn = unsealedProjectScopeWarning(projectRoot);
           if (scopeWarn) {
@@ -6368,6 +6420,10 @@ function registerPending(server, tracker) {
         if (gateWarn) {
           response.warnings = [gateWarn];
         }
+        const rootWarn = projectRootWarning(projectRoot);
+        if (rootWarn) {
+          response.warnings = [...response.warnings ?? [], rootWarn];
+        }
         const payloadLimits = readPayloadLimits(projectRoot);
         const serialized = JSON.stringify(response);
         const guardResult = enforcePayloadLimit5(serialized, payloadLimits);
@@ -12952,14 +13008,23 @@ var FABRIC_SERVER_INSTRUCTIONS = [
   "- Pass the client `session_id` to `fab_recall` so cross-session knowledge-debt tracking stays accurate.",
   "- Cite the KB id you applied or dismissed before edits, per the project's cite policy."
 ].join("\n");
+function buildServerInstructions(projectRoot) {
+  if (isProjectRootConfigured(projectRoot)) return FABRIC_SERVER_INSTRUCTIONS;
+  return [
+    `\u26A0\uFE0F WARNING: ${projectRootUnresolvedMessage(projectRoot)}`,
+    "If this client exposes MCP workspace roots, the server adopts them right after initialize and team stores load on the next tool call \u2014 otherwise set FABRIC_PROJECT_ROOT (or CLAUDE_PROJECT_DIR) in the MCP server env, or launch the server from inside the project. Tool responses carry a `project_root_unresolved` warning until resolved.",
+    "",
+    FABRIC_SERVER_INSTRUCTIONS
+  ].join("\n");
+}
 function createFabricServer(tracker) {
   const server = new McpServer(
     {
       name: "fabric-knowledge-server",
-      version: "2.3.0-rc.16"
+      version: "2.3.0-rc.17"
     },
     {
-      instructions: FABRIC_SERVER_INSTRUCTIONS
+      instructions: buildServerInstructions(resolveProjectRoot())
     }
   );
   registerRecall(server, tracker);
@@ -12994,16 +13059,70 @@ function createFabricServer(tracker) {
   );
   return server;
 }
+async function adoptMcpClientRoots(source) {
+  try {
+    if (source.getClientCapabilities()?.roots === void 0) return [];
+    const { roots } = await source.listRoots();
+    const paths = [];
+    for (const root of roots) {
+      if (typeof root.uri !== "string" || !root.uri.startsWith("file:")) continue;
+      try {
+        paths.push(fileURLToPath(root.uri));
+      } catch {
+      }
+    }
+    return setMcpRootsHint(paths);
+  } catch {
+    return [];
+  }
+}
 async function startStdioServer() {
   const tracker = createInFlightTracker();
-  const projectRoot = resolveProjectRoot();
+  let projectRoot = resolveProjectRoot();
   const rootMsg = formatPreexistingRootMessage(projectRoot);
   if (rootMsg !== null) {
     process.stderr.write(`${rootMsg}
 `);
   }
+  if (!isProjectRootConfigured(projectRoot)) {
+    process.stderr.write(
+      `[startup] warning: ${projectRootUnresolvedMessage(projectRoot)}. Waiting for MCP client roots after initialize; set FABRIC_PROJECT_ROOT to pin explicitly.
+`
+    );
+  }
   const server = createFabricServer(tracker);
   const transport = new StdioServerTransport();
+  server.server.oninitialized = () => {
+    void (async () => {
+      const adopted = await adoptMcpClientRoots(server.server);
+      if (adopted.length === 0) {
+        if (!isProjectRootConfigured(projectRoot)) {
+          process.stderr.write(
+            "[roots] client exposed no usable MCP roots \u2014 project root stays unresolved; serving personal store only.\n"
+          );
+        }
+        return;
+      }
+      const newRoot = resolveProjectRoot();
+      if (newRoot !== projectRoot) {
+        process.stderr.write(
+          `[roots] project root re-resolved via MCP client roots: "${projectRoot}" \u2192 "${newRoot}"
+`
+        );
+        stopMetricsFlush(projectRoot);
+        stopRotationTick(projectRoot);
+        startMetricsFlush(newRoot);
+        startRotationTick(newRoot);
+        projectRoot = newRoot;
+      }
+      if (!isProjectRootConfigured(projectRoot)) {
+        process.stderr.write(
+          `[roots] warning: ${projectRootUnresolvedMessage(projectRoot)}
+`
+        );
+      }
+    })();
+  };
   setFirstReconcile(Promise.resolve());
   await server.connect(transport);
   startMetricsFlush(projectRoot);
@@ -13011,18 +13130,17 @@ async function startStdioServer() {
   const closeServer = async () => {
     await server.close();
   };
-  process.on(
-    "SIGINT",
-    createShutdownHandler({ signal: "SIGINT", tracker, projectRoot, closeServer })
-  );
-  process.on(
-    "SIGTERM",
-    createShutdownHandler({ signal: "SIGTERM", tracker, projectRoot, closeServer })
-  );
-  process.on(
-    "SIGHUP",
-    createShutdownHandler({ signal: "SIGHUP", tracker, projectRoot, closeServer })
-  );
+  const shutdownDeps = (signal) => ({
+    signal,
+    tracker,
+    get projectRoot() {
+      return projectRoot;
+    },
+    closeServer
+  });
+  process.on("SIGINT", createShutdownHandler(shutdownDeps("SIGINT")));
+  process.on("SIGTERM", createShutdownHandler(shutdownDeps("SIGTERM")));
+  process.on("SIGHUP", createShutdownHandler(shutdownDeps("SIGHUP")));
 }
 function createShutdownHandler(deps3) {
   const exit = deps3.exit ?? ((code) => process.exit(code));
@@ -13080,12 +13198,14 @@ export {
   METRIC_COUNTER_NAMES,
   OPTIONAL_EMBED_PACKAGE,
   RETIRED_TOKENS,
+  adoptMcpClientRoots,
   aggregateConsumption,
   appendEventLedgerEvent,
   buildAlwaysActiveBodies,
   buildColdEvalBatch,
   buildKnowledgeCensus,
   buildRelatedGraph,
+  buildServerInstructions,
   bumpCounter,
   checkBacklogAge,
   clearPrecheckCache,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fenglimg/fabric-server",
-  "version": "2.3.0-rc.16",
+  "version": "2.3.0-rc.17",
   "description": "Fabric MCP knowledge server — stdio transport for Claude Code / Codex CLI, manages .fabric/ knowledge base + agents.meta.json + event ledger.",
   "license": "MIT",
   "author": "wangzhichao <fenglimg90@gmail.com>",
@@ -37,7 +37,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "minimatch": "^10.0.1",
     "zod": "^3.25.0",
-    "@fenglimg/fabric-shared": "2.3.0-rc.16"
+    "@fenglimg/fabric-shared": "2.3.0-rc.17"
   },
   "optionalDependencies": {
     "fastembed": "^2.0.0"