Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

fix: a client that answers no roots/list can declare itself with OM_CALLER (#240) (#242)

Brenno Ferrarid13614abb6a5
diff --git a/.claude/scripts/lib/mcp-caller.ts b/.claude/scripts/lib/mcp-caller.ts
index b16ed74..5406020 100644
--- a/.claude/scripts/lib/mcp-caller.ts
+++ b/.claude/scripts/lib/mcp-caller.ts
@@ -3,9 +3,12 @@
*
* Identity comes from the MCP `roots/list` handshake — never from a tool
* argument, so a session cannot claim to be a project it is not. A client that
- * does not complete the handshake is anonymous and sees only `general`-scoped
- * memories; `health` reports that explicitly, since it otherwise looks like an
- * empty vault.
+ * completes no handshake may declare one in {@link CALLER_VAR} instead, which
+ * is set where the server is registered rather than chosen by the session and
+ * so sits on the same trust boundary as `roots`; that constant carries the
+ * whole argument. A client that does neither is anonymous and sees only
+ * `general`-scoped memories; `health` reports that explicitly, since it
+ * otherwise looks like an empty vault.
*/
import {
@@ -67,6 +70,52 @@ export function rootToPath(uri: unknown): string {
/** Where a repo may declare its own project name, overriding the folder name. */
export const PROJECT_MARKER = ".om-project";
+/**
+ * Where a client with no roots may declare an identity instead.
+ *
+ * **A real consumer arrived that cannot send roots.** Not every shipping MCP
+ * client implements the handshake: one answers `initialize` and leaves the
+ * server's `roots/list` request unanswered. It was not rootless for want of a
+ * directory, so {@link PROJECT_MARKER} cannot help it either, since nothing
+ * reads that file without a root to read it under. The consequence is not
+ * cosmetic: an identity-less caller is served **only** `general`-scoped
+ * memories, which is the narrowest slice of the vault there is.
+ *
+ * **Why this does not reopen the forgery hole the header refuses.** That rule
+ * is about a *tool argument*, which the model chooses mid-session and could
+ * therefore point at any project it liked. An environment variable is set by
+ * whoever registers and spawns this server, which is the same party that
+ * controls `roots` and could already declare any identity that way. Same trust
+ * boundary, no new surface. What stays refused is the session naming itself.
+ *
+ * **A fallback and never an override.** A client that sends roots is
+ * identifying itself, and second-guessing that with an environment left over
+ * from another context is how one repo starts answering as another.
+ */
+export const CALLER_VAR = "OM_CALLER";
+
+/** Reads one environment variable. Injected so the identity rules stay pure. */
+export type EnvLookup = (key: string) => string | undefined;
+
+const fromProcess: EnvLookup = (key) => process.env[key];
+
+/**
+ * The one shape an identity may take, wherever it was declared.
+ *
+ * Shared by the marker file and {@link CALLER_VAR} rather than spelled at each,
+ * because two copies of a validation rule are two chances for one of them to
+ * accept a path segment the scope comparison would then read oddly.
+ */
+function identityShape(raw: unknown): string | null {
+ const name = String(raw ?? "").trim().toLowerCase();
+ return name && /^[\w.-]+$/.test(name) ? name : null;
+}
+
+/** The identity declared in the environment, if it is one this may accept. */
+function declaredByEnv(env: EnvLookup): string | null {
+ return identityShape(env(CALLER_VAR));
+}
+
/**
* The calling repo's project identity.
*
@@ -76,25 +125,32 @@ export const PROJECT_MARKER = ".om-project";
* the other's memories. Declaring a distinct name in either repo separates
* them, and nothing changes for anyone who does not hit the collision.
*/
-export function callerProject(roots: readonly Root[]): string | null {
+export function callerProject(roots: readonly Root[], env: EnvLookup = fromProcess): string | null {
const first = roots[0];
- if (!first) return null;
+ if (!first) return declaredByEnv(env);
const root = rootToPath(first.uri).replace(/\/+$/, "");
const declared = readProjectMarker(root);
if (declared) return declared;
+ // A root carrying no usable path is the rootless case wearing a handshake, so
+ // it falls through to the environment rather than straight to anonymity.
const seg = root.split(/[\\/]/).filter(Boolean).pop();
- return seg ? seg.toLowerCase() : null;
+ return seg ? seg.toLowerCase() : declaredByEnv(env);
}
/** How the identity was decided, so `health` can explain itself. */
-export function callerProjectSource(roots: readonly Root[]): "declared" | "folder" | "none" {
+export function callerProjectSource(
+ roots: readonly Root[],
+ env: EnvLookup = fromProcess,
+): "declared" | "folder" | "env" | "none" {
const first = roots[0];
- if (!first) return "none";
- const root = rootToPath(first.uri).replace(/\/+$/, "");
- if (readProjectMarker(root)) return "declared";
- return root.split(/[\\/]/).filter(Boolean).length ? "folder" : "none";
+ if (first) {
+ const root = rootToPath(first.uri).replace(/\/+$/, "");
+ if (readProjectMarker(root)) return "declared";
+ if (root.split(/[\\/]/).filter(Boolean).length) return "folder";
+ }
+ return declaredByEnv(env) ? "env" : "none";
}
function readProjectMarker(root: string): string | null {
@@ -103,11 +159,9 @@ function readProjectMarker(root: string): string | null {
.split("\n")
.map((l) => l.trim())
.find((l) => l && !l.startsWith("#"));
- if (!raw) return null;
// Same shape as a folder name, so a declared identity cannot smuggle in a
// path segment or anything the scope rule would compare oddly.
- const name = raw.toLowerCase();
- return /^[\w.-]+$/.test(name) ? name : null;
+ return identityShape(raw);
} catch {
return null;
}
diff --git a/.claude/scripts/lib/mcp-server.ts b/.claude/scripts/lib/mcp-server.ts
index 49f2f6c..d5bfaa7 100644
--- a/.claude/scripts/lib/mcp-server.ts
+++ b/.claude/scripts/lib/mcp-server.ts
@@ -28,7 +28,7 @@ import {
} from "./mcp-exposure.ts";
import { expandNote } from "./mcp-graph.ts";
import { qmdProbe, qmdSearch, type QmdClient } from "./mcp-qmd-client.ts";
-import { callerProject, callerProjectSource, isVaultItself, PROJECT_MARKER, sumAuditField, sanitize } from "./mcp-caller.ts";
+import { callerProject, callerProjectSource, CALLER_VAR, isVaultItself, PROJECT_MARKER, sumAuditField, sanitize } from "./mcp-caller.ts";
import { callerPlatforms, digestsFrom, resolvableNames } from "./mcp-memory-bridge.ts";
import { captureNote, describeToolMarkup, toolMarkupRefusal } from "./mcp-capture.ts";
import { semanticMemoryOrder } from "./mcp-memory-bridge.ts";
@@ -60,6 +60,20 @@ import {
REASON_ACTION,
} from "./mcp-reason.ts";
+/**
+ * How `health` names each way an identity can be decided.
+ *
+ * A table rather than a ternary, because the ternary this replaced could only
+ * say "declared or folder" and would have reported a third source as the second
+ * the moment one existed. `satisfies` makes the compiler notice the next one.
+ */
+const IDENTITY_SOURCE = {
+ declared: `the ${PROJECT_MARKER} file`,
+ folder: "folder name",
+ env: `${CALLER_VAR} in this server's registration`,
+ none: "nowhere",
+} as const satisfies Record<ReturnType<typeof callerProjectSource>, string>;
+
const PROTOCOL_VERSION = "2025-11-25";
const SERVER_NAME = "om";
const SERVER_VERSION = "0.1.0";
@@ -741,7 +755,10 @@ export function createHandlers(deps: ServerDeps): Handlers {
" If that is not deliberate, unset it — everything below describes the OTHER vault.",
]
: []),
- `Caller: ${who.project ?? "ANONYMOUS (no MCP roots — only general-scope memories are visible)"}${who.project ? ` (from the ${callerProjectSource(session.roots) === "declared" ? PROJECT_MARKER + " file" : "folder name"})` : ""}`,
+ `Caller: ${who.project ?? `ANONYMOUS (no MCP roots and no ${CALLER_VAR} — only general-scope memories are visible)`}${who.project ? ` (from ${IDENTITY_SOURCE[callerProjectSource(session.roots)]})` : ""}`,
+ ...(who.project === null
+ ? [` A client that cannot send roots can still identify itself: set ${CALLER_VAR} where this server is registered.`]
+ : []),
...(who.project && callerProjectSource(session.roots) === "folder"
? [` Another repo with this folder name would share this identity. Write a distinct name into ${PROJECT_MARKER} to separate them.`]
: []),
diff --git a/.claude/scripts/tests/mcp-caller.test.ts b/.claude/scripts/tests/mcp-caller.test.ts
index 9cacfd2..d075b78 100644
--- a/.claude/scripts/tests/mcp-caller.test.ts
+++ b/.claude/scripts/tests/mcp-caller.test.ts
@@ -22,6 +22,7 @@ import {
rootToPath,
callerProject,
callerProjectSource,
+ CALLER_VAR,
PROJECT_MARKER,
isVaultItself,
sanitize,
@@ -86,12 +87,50 @@ describe("reading the caller's identity from roots", () => {
assert.equal(callerProject([root("file:///home/x/pocket")]), "pocket");
});
- test("no roots means NO identity — never a guess and never a default", () => {
+ test("no roots and no declared identity means NO identity — never a guess", () => {
// An anonymous caller must fall through to general-scoped material only.
// Inventing an identity here would hand it another project's memories.
- assert.equal(callerProject([]), null);
- assert.equal(callerProject([{}]), null);
- assert.equal(callerProject([root("")]), null);
+ const none = () => undefined;
+ assert.equal(callerProject([], none), null);
+ assert.equal(callerProject([{}], none), null);
+ assert.equal(callerProject([root("")], none), null);
+ assert.equal(callerProjectSource([], none), "none");
+ });
+
+ test("a rootless client may declare itself in the environment", () => {
+ // Not every shipping MCP client answers `roots/list`, and a
+ // caller with no identity is served only `general`. The variable is set
+ // where the server is registered, so it is the same trust boundary as
+ // roots rather than a session naming itself.
+ const env = (k: string) => (k === CALLER_VAR ? "workstation-a" : undefined);
+ assert.equal(callerProject([], env), "workstation-a");
+ assert.equal(callerProjectSource([], env), "env");
+
+ // A root that arrived carrying no usable path is the rootless case wearing
+ // a handshake, so it reaches the same fallback.
+ assert.equal(callerProject([{}], env), "workstation-a");
+ assert.equal(callerProject([root("")], env), "workstation-a");
+ });
+
+ test("the environment is a fallback and never an override", () => {
+ // A client that sent roots has identified itself. Letting an environment
+ // left over from another context win is how one repo answers as another.
+ const env = (k: string) => (k === CALLER_VAR ? "workstation-a" : undefined);
+ assert.equal(callerProject([root("file:///home/x/pocket")], env), "pocket");
+ assert.equal(callerProjectSource([root("file:///home/x/pocket")], env), "folder");
+ });
+
+ test("a declared identity from the environment obeys the same shape rule", () => {
+ // Same validation as the marker file, because two copies of one rule are
+ // two chances for one of them to accept a path segment.
+ for (const bad of ["../escape", "a/b", "with spaces", "", " "]) {
+ const env = (k: string) => (k === CALLER_VAR ? bad : undefined);
+ assert.equal(callerProject([], env), null, `rejected: ${JSON.stringify(bad)}`);
+ assert.equal(callerProjectSource([], env), "none");
+ }
+ // And it is lowercased and trimmed, the way a folder name is.
+ const shouty = (k: string) => (k === CALLER_VAR ? " Workstation-A " : undefined);
+ assert.equal(callerProject([], shouty), "workstation-a");
});
test("the first root wins when a session has several", () => {