@cairnkeep/cli 2.8.0 → 2.11.0

package/mcp-memory-server/dist/eval-cli.js

@@ -7,6 +7,7 @@ import { isEvalEnabled, loadEvalPlan } from "./eval-plan.js";
 import { diagnoseEvalReport, readEvalReport, renderEvalReport, } from "./eval-report.js";
 import { buildAblationArms, runCapabilityAblation, runTwoPassExperiment, } from "./eval-runner.js";
 import { canonicalJson, EVAL_SCHEMA_VERSION } from "./eval-schema.js";
+import { privatePathIsSafe } from "./platform-security.js";
 process.stdout.on("error", (error) => {
     if (error.code === "EPIPE")
         process.exit(0);
@@ -126,7 +127,7 @@ async function evalRoot() {
             return null;
         throw error;
     }
-    if (info.isSymbolicLink() || !info.isDirectory() || (info.mode & 0o077) !== 0) {
+    if (info.isSymbolicLink() || !info.isDirectory() || !privatePathIsSafe(root)) {
         throw new Error("unsafe_eval_root");
     }
     const resolvedRoot = await realpath(root);
@@ -185,7 +186,7 @@ async function diagnoseProjectReports(projectRoot) {
         }
         if (info.isSymbolicLink() || !info.isDirectory() || await realpath(directory) !== directory)
             return "unsafe";
-        if (directory === root && (info.mode & 0o077) !== 0)
+        if (directory === root && !privatePathIsSafe(directory))
             return "unsafe";
     }
     const entries = await readdir(root, { withFileTypes: true });
@@ -201,7 +202,7 @@ async function diagnoseProjectReports(projectRoot) {
         if (!isContained(root, experimentPath) || experimentPath === root)
             return "unsafe";
         const experimentInfo = await lstat(experimentPath);
-        if (experimentInfo.isSymbolicLink() || !experimentInfo.isDirectory() || (experimentInfo.mode & 0o077) !== 0
+        if (experimentInfo.isSymbolicLink() || !experimentInfo.isDirectory() || !privatePathIsSafe(experimentPath)
             || await realpath(experimentPath) !== experimentPath) {
             return "unsafe";
         }
@@ -247,7 +248,7 @@ async function safeReportStore(experimentId) {
             throw new Error("eval_report_not_found");
         throw error;
     }
-    if (directory.isSymbolicLink() || !directory.isDirectory() || (directory.mode & 0o077) !== 0
+    if (directory.isSymbolicLink() || !directory.isDirectory() || !privatePathIsSafe(experimentPath)
         || await realpath(experimentPath) !== experimentPath) {
         throw new Error("unsafe_experiment_path");
     }
@@ -261,7 +262,7 @@ async function safeReportStore(experimentId) {
             throw new Error("eval_report_not_found");
         throw error;
     }
-    if (reportInfo.isSymbolicLink() || !reportInfo.isFile() || (reportInfo.mode & 0o077) !== 0
+    if (reportInfo.isSymbolicLink() || !reportInfo.isFile() || !privatePathIsSafe(reportPath)
         || reportInfo.size > DEFAULT_REPORT_BYTES) {
         throw new Error("unsafe_eval_report");
     }

package/mcp-memory-server/dist/eval-plan.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { constants } from "node:fs";
 import { accessSync, closeSync, existsSync, fstatSync, lstatSync, openSync, readFileSync, realpathSync, } from "node:fs";
-import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, delimiter, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CAPABILITY_IDS } from "./capability-schema.js";
 import { EVAL_SCHEMA_VERSION, canonicalDigest, canonicalJson, evalAdapterConfigSchema, evalTaskSetSchema, } from "./eval-schema.js";
@@ -16,6 +16,19 @@ function isContained(root, candidate) {
     const rel = relative(root, candidate);
     return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
 }
+function isExistingPathContained(root, candidate) {
+    const rootInfo = lstatSync(root);
+    let current = realpathSync(candidate);
+    for (;;) {
+        const currentInfo = lstatSync(current);
+        if (currentInfo.dev === rootInfo.dev && currentInfo.ino === rootInfo.ino)
+            return true;
+        const parent = dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
 function assertRealDirectory(path, label) {
     const info = lstatSync(path);
     if (info.isSymbolicLink() || !info.isDirectory())
@@ -68,12 +81,16 @@ function resolveExactCommit(repository, revision) {
     return resolved;
 }
 function parseCommittedTaskSet(taskSetPath) {
-    const manifestRepository = assertRealDirectory(git(dirname(taskSetPath), ["rev-parse", "--show-toplevel"], "Resolve task-set repository"), "Task-set repository");
-    if (!isContained(manifestRepository, taskSetPath))
+    const manifestDirectory = dirname(taskSetPath);
+    const manifestRepository = assertRealDirectory(git(manifestDirectory, ["rev-parse", "--show-toplevel"], "Resolve task-set repository"), "Task-set repository");
+    if (!isExistingPathContained(manifestRepository, taskSetPath)) {
         throw new Error("The task-set manifest must be contained by its Git repository.");
-    const manifestPath = relative(manifestRepository, taskSetPath).split(sep).join("/");
-    if (!manifestPath || manifestPath.startsWith("../"))
+    }
+    const manifestPrefix = git(manifestDirectory, ["rev-parse", "--show-prefix"], "Resolve task-set repository prefix");
+    const manifestPath = `${manifestPrefix}${basename(taskSetPath)}`.split("\\").join("/");
+    if (!manifestPath || manifestPath.startsWith("../") || isAbsolute(manifestPath)) {
         throw new Error("The task-set manifest path is invalid.");
+    }
     git(manifestRepository, ["ls-files", "--error-unmatch", "--", manifestPath], "Require a tracked evaluation task set");
     const dirty = git(manifestRepository, ["status", "--porcelain", "--untracked-files=all", "--", manifestPath], "Check evaluation task set status");
     if (dirty !== "")
@@ -111,15 +128,20 @@ function resolvePathProgram(program, base) {
 function resolveProgram(program, base) {
     if (isAbsolute(program) || program.includes("/") || program.includes("\\"))
         return resolvePathProgram(program, base);
+    const names = process.platform === "win32" && extname(program) === ""
+        ? [program, ...[".EXE", ".COM"].map((extension) => `${program}${extension}`)]
+        : [program];
     for (const directory of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
-        const candidate = join(directory, program);
-        try {
-            accessSync(candidate, constants.X_OK);
-            if (lstatSync(candidate).isFile() || lstatSync(candidate).isSymbolicLink())
-                return realpathSync(candidate);
-        }
-        catch {
-            // Continue through PATH without executing the candidate.
+        for (const name of names) {
+            const candidate = join(directory, name);
+            try {
+                accessSync(candidate, constants.X_OK);
+                if (lstatSync(candidate).isFile() || lstatSync(candidate).isSymbolicLink())
+                    return realpathSync(candidate);
+            }
+            catch {
+                // Continue through PATH without executing the candidate.
+            }
         }
     }
     throw new Error(`Evaluation program was not found on PATH: ${program}`);

package/mcp-memory-server/dist/eval-process.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { evalAdapterRequestSchema, evalAdapterResultSchema, } from "./eval-schema.js";
 export const EVAL_PROCESS_ERROR_CODES = [
     "spawn_error",
@@ -33,7 +33,7 @@ export class EvalProcessError extends Error {
 const DEFAULT_KILL_GRACE_MS = 1_000;
 const MAX_TIMER_MS = 2_147_483_647;
 function terminationScope() {
-    return process.platform === "win32" ? "child" : "process-group";
+    return process.platform === "win32" ? "process-tree" : "process-group";
 }
 function assertOptions(options) {
     if (!Number.isSafeInteger(options.timeout_ms) || options.timeout_ms <= 0 || options.timeout_ms > MAX_TIMER_MS) {
@@ -59,7 +59,9 @@ function signalChild(child, signal) {
             process.kill(-child.pid, signal);
             return true;
         }
-        return child.kill(signal);
+        const args = ["/PID", String(child.pid), "/T", ...(signal === "SIGKILL" ? ["/F"] : [])];
+        const result = spawnSync("taskkill.exe", args, { stdio: "ignore", windowsHide: true });
+        return result.status === 0 || child.kill(signal);
     }
     catch {
         try {
@@ -90,7 +92,12 @@ async function runCommandInternal(options) {
         let exitSignal = null;
         let graceTimer;
         let closeTimer;
-        const child = spawn(options.command.program, options.command.args, {
+        // A shebang does not make a JavaScript file directly executable on
+        // Windows. Adapter contracts may point at JS programs, so launch
+        // those through the current runtime while preserving the declared
+        // command for hashing and provenance.
+        const javascriptProgram = /\.(?:cjs|mjs|js)$/i.test(options.command.program);
+        const child = spawn(javascriptProgram ? process.execPath : options.command.program, [...(javascriptProgram ? [options.command.program] : []), ...options.command.args], {
             cwd: options.cwd,
             env: options.env,
             shell: false,

package/mcp-memory-server/dist/eval-report.js

@@ -1,9 +1,10 @@
 import { randomBytes } from "node:crypto";
 import { constants } from "node:fs";
-import { chmod, lstat, mkdir, open, readdir, realpath, rename, rm, } from "node:fs/promises";
+import { lstat, mkdir, open, readdir, realpath, rename, rm, } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { canonicalDigest, canonicalJson, evalAggregateSchema, evalReportSchema, } from "./eval-schema.js";
 import { computeDifferenceInDifferences, computePairedEstimate, } from "./eval-statistics.js";
+import { hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
 const DEFAULT_MAX_REPORT_BYTES = 16 * 1024 * 1024;
 const MAX_ALLOWED_REPORT_BYTES = 64 * 1024 * 1024;
 const DEFAULT_MAX_EXPERIMENTS = 10_000;
@@ -36,7 +37,7 @@ async function ensureSafeDirectory(path, privateMode = false) {
         if (info.isSymbolicLink() || !info.isDirectory())
             throw new Error("unsafe_report_directory");
         if (privateMode)
-            await chmod(path, 0o700);
+            hardenPrivatePath(path);
         return;
     }
     catch (error) {
@@ -48,7 +49,7 @@ async function ensureSafeDirectory(path, privateMode = false) {
         throw new Error("unsafe_report_directory");
     await ensureSafeDirectory(parent, false);
     await mkdir(path, { mode: 0o700 });
-    await chmod(path, 0o700);
+    hardenPrivatePath(path);
 }
 function assertLimits(maxReportBytes, maxExperiments) {
     if (!Number.isSafeInteger(maxReportBytes) || maxReportBytes < 1 || maxReportBytes > MAX_ALLOWED_REPORT_BYTES) {
@@ -206,8 +207,9 @@ export async function checkpointEvalReport(store, report, options = {}) {
             await handle.close();
             handle = undefined;
             injectFault(options, "after_close");
+            hardenPrivatePath(temporary);
             await rename(temporary, store.report_path);
-            await chmod(store.report_path, 0o600);
+            hardenPrivatePath(store.report_path);
             injectFault(options, "after_rename");
         }
         finally {
@@ -239,7 +241,7 @@ export async function diagnoseEvalReport(store) {
         });
         if (!info)
             return { state: "absent", code: "report_absent" };
-        if (info.isSymbolicLink() || !info.isFile() || (info.mode & 0o077) !== 0) {
+        if (info.isSymbolicLink() || !info.isFile() || !privatePathIsSafe(store.report_path)) {
             return { state: "unsafe", code: "report_unsafe" };
         }
         const report = await readEvalReport(store);
@@ -578,6 +580,7 @@ export function renderEvalReport(value) {
         `Cairn evaluation report: ${report.experiment_id}`,
         `status: ${report.status}`,
         `evidence: ${report.evidence.evidence_scope === "offline-framework" ? "framework-only" : "live-evaluation"}`,
+        `MCP tool profile digest: ${report.evidence.mcp_tool_profile_digest ?? "not-recorded"}`,
         "All effects are estimates; small samples, missing intervals, and intervals crossing zero are inconclusive.",
         "",
         "Aggregates",

package/mcp-memory-server/dist/eval-runner.js

@@ -10,6 +10,7 @@ import { canonicalDigest, evalReportSchema, evalReportRuntimeContractDigest, } f
 import { EvalProcessError, runBoundedCommand, runBoundedJsonAdapter, } from "./eval-process.js";
 import { checkpointEvalReport, createEvalReportStore, } from "./eval-report.js";
 import { applyEvalWorkspaceOverlay, cleanupEvalWorkspace, createEvalWorkspace, runTaskPreparation, runTaskVerifier, } from "./eval-workspace.js";
+import { resolveMcpToolProfile } from "./mcp-tool-profile.js";
 const moduleDirectory = dirname(fileURLToPath(import.meta.url));
 const publishedReportSchemaPath = resolve(moduleDirectory, "..", "..", "schemas", "eval-report.schema.json");
 let reportSchemaDigestsCache;
@@ -735,6 +736,7 @@ function initialReport(plan, experimentId, fallbackExperimentKind) {
             package_version: plan.source.kind === "bundled_fake" ? plan.source.package_version : "0.1.0",
             runtime_id: "node-local",
             task_set_digest: plan.task_set_digest,
+            mcp_tool_profile_digest: resolveMcpToolProfile({ projectRoot: process.cwd() }).profile_digest,
             report_digest: canonicalDigest({ experiment_id: experimentId, plan_digest: plan.plan_digest }),
             schema_digests: [...evalReportSchemaDigests()],
             note_snapshot_digests: [],

package/mcp-memory-server/dist/eval-schema.js

@@ -309,6 +309,7 @@ const evidenceProvenanceSchema = z.strictObject({
     package_version: z.string().min(1).max(128),
     runtime_id: identifierSchema,
     task_set_digest: digestSchema,
+    mcp_tool_profile_digest: digestSchema.optional(),
     report_digest: digestSchema,
     schema_digests: z.array(digestSchema).length(2),
     note_snapshot_digests: z.array(digestSchema).max(MAX_TASKS),

package/mcp-memory-server/dist/graph-cli.js

@@ -90,7 +90,13 @@ function graphifyEnvironment() {
     return environment;
 }
 function executeGraphify(projectRoot, args, timeout) {
-    const result = spawnSync("graphify", args, {
+    const configuredProgram = process.env.CAIRN_GRAPHIFY_BINARY?.trim();
+    const graphifyProgram = configuredProgram || "graphify";
+    const javascriptProgram = /\.(?:cjs|mjs|js)$/i.test(graphifyProgram);
+    const result = spawnSync(javascriptProgram ? process.execPath : graphifyProgram, [
+        ...(javascriptProgram ? [graphifyProgram] : []),
+        ...args,
+    ], {
         cwd: projectRoot,
         encoding: "utf8",
         shell: false,

package/mcp-memory-server/dist/index.js

@@ -17,6 +17,9 @@ import { EmbeddingCache, cosineSimilarity, embedTexts, getEmbeddingConfig, hashT
 import { computeRepoState, exploreCacheKey, normalizeExploreQuery, readExploreCache, writeExploreCache, } from "./explore-cache.js";
 import { canonicalTagsSchema, isTypedMemoryNodesEnabled, memoryImportEnvelopeSchema, noteNodeSchema, nodeTypeSchema, } from "./node-schema.js";
 import { attachNodeMetadata, applyReviewedTypedNode, commitMemoryImport, createTypedNode, deleteTypedNode, getTypedNode, invalidateReviewedTypedNode, listTypedHistory, planMemoryImport, supersedeTypedNode, } from "./node-store.js";
+import { contextPackHttpEnabled, contextPacksEnabled, listVisibleContext, readVisibleContext, searchVisibleContext } from "./context-pack.js";
+import { metadataForTool } from "./mcp-tool-catalog.js";
+import { profileAllowsTool, resolveMcpToolProfile } from "./mcp-tool-profile.js";
 const MINIMUM_NODE_MAJOR = 22;
 const nodeMajor = Number.parseInt(process.versions.node, 10);
 if (!Number.isInteger(nodeMajor) || nodeMajor < MINIMUM_NODE_MAJOR) {
@@ -758,7 +761,18 @@ async function runContextExplore(args) {
     }
     // --- Execution tier: return { ok: false, ... } (runtime problems, D-04) ---
     if (!evidence) {
-        const result = await runCommand(binaryPath, ["explore", "--query", query, "--repo-root", repoRoot], (timeoutSeconds ?? 120) * 1000, { ...process.env, NO_COLOR: "1" });
+        // Native Windows cannot execute a JavaScript file directly from a
+        // shebang. Treat JS helpers as Node programs while keeping compiled
+        // token_miser binaries byte-for-byte compatible on every platform.
+        const javascriptHelper = /\.(?:cjs|mjs|js)$/i.test(binaryPath);
+        const result = await runCommand(javascriptHelper ? process.execPath : binaryPath, [
+            ...(javascriptHelper ? [binaryPath] : []),
+            "explore",
+            "--query",
+            query,
+            "--repo-root",
+            repoRoot,
+        ], (timeoutSeconds ?? 120) * 1000, { ...process.env, NO_COLOR: "1" });
         if (result.timedOut || result.exitCode !== 0) {
             const payload = {
                 ok: false,
@@ -822,8 +836,18 @@ function gitToplevel(cwd) {
 // only allows one connected transport per server). All instances share the
 // module-level helpers + AgentFS below. Enables a single long-lived process to
 // serve many concurrent clients within one trusted server-side storage domain.
-function buildMemoryServer(context, capabilitySnapshot, withCapability) {
+function buildMemoryServer(context, capabilitySnapshot, withCapability, toolProfile = resolveMcpToolProfile({ projectRoot: process.cwd() })) {
     const server = new McpServer({ name: "cairn-memory", version: "0.1.0" });
+    const registerTool = (name, config, callback) => {
+        const metadata = metadataForTool(name);
+        if (!profileAllowsTool(toolProfile, name))
+            return;
+        server.registerTool(name, {
+            ...config,
+            title: metadata.title,
+            annotations: metadata.annotations,
+        }, callback);
+    };
     const capabilityEnabled = (id) => capabilitySnapshot?.capabilities.find((state) => state.id === id)?.enabled ?? true;
     const registerCapabilityTool = (id, name, config, callback) => {
         if (!capabilityEnabled(id))
@@ -840,15 +864,22 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
                 },
             }, callback)
             : callback;
-        server.registerTool(name, config, handler);
+        registerTool(name, config, handler);
     };
     const memoryConfig = () => context.memoryConfig ?? getMemoryConfig();
     const scopeOptions = { projectId: context.projectId };
     const typedNodesEnabled = isTypedMemoryNodesEnabled();
     const artifactToolsEnabled = isArtifactStoreEnabled() && (!context.remote || isArtifactHttpEnabled());
+    const contextPackToolsEnabled = contextPacksEnabled() && (!context.remote || contextPackHttpEnabled());
     if (artifactToolsEnabled && context.remote && !context.projectId) {
         throw new ClientContextError("Remote artifact access requires X-Cairn-Project.");
     }
+    if (contextPackToolsEnabled && context.remote && !context.projectId) {
+        throw new ClientContextError("Remote context pack access requires X-Cairn-Project.");
+    }
+    const contextPackProject = context.remote
+        ? { projectId: context.projectId }
+        : { projectRoot: process.cwd() };
     let fallbackArtifactSessionRef;
     const resolveArtifactSessionRef = (sessionRef) => {
         if (sessionRef)
@@ -892,7 +923,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
                 generatedFileInputContentSchema,
             ]),
         }).strict();
-        server.registerTool("artifact_write", {
+        registerTool("artifact_write", {
             description: "Write one bounded inline artifact to the immutable project artifact store.",
             inputSchema: artifactWriteToolSchema,
             annotations: {
@@ -920,7 +951,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
                 structuredContent: payload,
             };
         });
-        server.registerTool("artifact_read", {
+        registerTool("artifact_read", {
             description: "Read one artifact by exact ID or an unambiguous ID prefix.",
             inputSchema: z.object({ artifact_id: artifactIdentifierSchema }).strict(),
             annotations: {
@@ -936,7 +967,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
                 structuredContent: payload,
             };
         });
-        server.registerTool("artifact_list", {
+        registerTool("artifact_list", {
             description: "List artifact metadata newest first with exact filters and opaque pagination.",
             inputSchema: z.object({
                 session_ref: artifactSessionRefSchema.optional(),
@@ -976,7 +1007,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
                 structuredContent: payload,
             };
         });
-        server.registerTool("artifact_delete", {
+        registerTool("artifact_delete", {
             description: "Hard-delete one artifact by exact ID or an unambiguous ID prefix.",
             inputSchema: z.object({ artifact_id: artifactIdentifierSchema }).strict(),
             annotations: {
@@ -1013,7 +1044,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             };
         });
     }
-    server.registerTool("memory_read", {
+    registerTool("memory_read", {
         description: "Read an exact key or search memory entries across AgentFS scopes.",
         // Plain object schema — a .refine() wrapper (ZodEffects) makes the SDK
         // publish an empty JSON Schema, hiding the parameters from clients.
@@ -1151,7 +1182,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             structuredContent: payload,
         };
     });
-    server.registerTool("memory_list", {
+    registerTool("memory_list", {
         description: "List keys from a scoped AgentFS database.",
         inputSchema: z.object({
             scope: z.string(),
@@ -1189,7 +1220,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             structuredContent: typedNodesEnabled ? { keys, nodes } : { keys },
         };
     });
-    server.registerTool("memory_delete", {
+    registerTool("memory_delete", {
         description: "Delete a key from a scoped AgentFS database.",
         inputSchema: z.object({
             scope: z.string(),
@@ -1273,7 +1304,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             structuredContent: payload,
         };
     });
-    server.registerTool("memory_extract", {
+    registerTool("memory_extract", {
         description: "Extract durable memory candidates from a session summary or selected text. Review the returned candidates before writing them.",
         inputSchema: z.object({
             scope: z.string(),
@@ -1294,7 +1325,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             structuredContent: payload,
         };
     });
-    server.registerTool("memory_supersede", {
+    registerTool("memory_supersede", {
         description: "Preserve the current value of a memory entry in hidden history, then write a new live value to the base key.",
         inputSchema: z.object({
             scope: z.string(),
@@ -1380,7 +1411,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             await agent.close();
         }
     });
-    server.registerTool("memory_apply_reviewed", {
+    registerTool("memory_apply_reviewed", {
         description: "Idempotently apply a human-reviewed memory revision with durable provenance.",
         inputSchema: z.object({
             scope: z.string(),
@@ -1484,7 +1515,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             await agent.close();
         }
     });
-    server.registerTool("memory_invalidate_reviewed", {
+    registerTool("memory_invalidate_reviewed", {
         description: "Invalidate a reviewed revision, removing it only when the live value still matches.",
         inputSchema: z.object({
             scope: z.string(),
@@ -1609,7 +1640,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             await agent.close();
         }
     });
-    server.registerTool("memory_history", {
+    registerTool("memory_history", {
         description: "Read prior versions of a memory entry from the hidden history namespace.",
         inputSchema: z.object({
             scope: z.string(),
@@ -1678,7 +1709,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
         };
     });
     if (typedNodesEnabled) {
-        server.registerTool("memory_import", {
+        registerTool("memory_import", {
             description: "Validate, plan, and atomically import a bounded batch of typed memory nodes.",
             inputSchema: memoryImportEnvelopeSchema,
             annotations: {
@@ -1698,30 +1729,18 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             }
             // Resolve containment before any database is opened or directory is created.
             const scopePath = resolveScopePath(envelope.scope, scopeOptions);
-            const existing = await openScope(envelope.scope, false, scopeOptions);
-            let plan;
-            try {
-                plan = await planMemoryImport(existing, envelope);
-            }
-            finally {
-                await existing?.close();
-            }
-            if (envelope.dry_run) {
-                const payload = await commitMemoryImport(null, plan);
-                return {
-                    content: [{ type: "text", text: asToolText(payload) }],
-                    structuredContent: payload,
-                };
-            }
             const payload = await serializeScopeMutation(scopePath, async () => {
-                const agent = await openScope(envelope.scope, true, scopeOptions);
-                if (!agent)
-                    throw new Error(`Unable to open scope ${envelope.scope}.`);
+                const agent = await openScope(envelope.scope, !envelope.dry_run, scopeOptions);
                 try {
+                    const plan = await planMemoryImport(agent, envelope);
+                    if (envelope.dry_run)
+                        return commitMemoryImport(null, plan);
+                    if (!agent)
+                        throw new Error(`Unable to open scope ${envelope.scope}.`);
                     return await commitMemoryImport(agent, plan);
                 }
                 finally {
-                    await agent.close();
+                    await agent?.close();
                 }
             });
             return {
@@ -1730,7 +1749,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             };
         });
     }
-    server.registerTool("domain_knowledge_query", {
+    registerTool("domain_knowledge_query", {
         description: "Query an AnythingLLM workspace in query mode for domain knowledge.",
         inputSchema: z.object({
             workspace: z.string().min(1).optional(),
@@ -1750,7 +1769,7 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
             structuredContent: { workspace: workspaceSlug, answer },
         };
     });
-    server.registerTool("domain_knowledge_sync", {
+    registerTool("domain_knowledge_sync", {
         description: "Upload and embed configured project documentation into an AnythingLLM workspace. Uses anythingllm-projects.json so include/exclude rules are honored. Use mode='replace' with confirm_replace=true when stale workspace docs must be removed before re-embedding.",
         inputSchema: z.object({
             workspace: z.string().min(1).optional(),
@@ -1879,6 +1898,37 @@ function buildMemoryServer(context, capabilitySnapshot, withCapability) {
         const payload = { ok: true, status: body.status, cluster_healthy: body.cluster_healthy ?? null };
         return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
     });
+    if (contextPackToolsEnabled) {
+        registerTool("context_pack_list", {
+            description: "List documents and explicitly approved skills from context packs enabled for this project.",
+            inputSchema: z.object({}).strict(),
+        }, async () => {
+            const payload = await listVisibleContext(contextPackProject);
+            return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
+        });
+        registerTool("context_pack_search", {
+            description: "Search documents and explicitly approved skills in context packs enabled for this project.",
+            inputSchema: z.object({
+                query: z.string().min(1).max(4096),
+                limit: z.number().int().min(1).max(100).optional(),
+            }).strict(),
+        }, async ({ query, limit }) => {
+            const payload = await searchVisibleContext(query, { ...contextPackProject, limit });
+            return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
+        });
+        registerTool("context_pack_read", {
+            description: "Read a bounded UTF-8 range from one enabled context-pack document or approved skill.",
+            inputSchema: z.object({
+                pack: z.string().min(1).max(128),
+                path: z.string().min(1).max(512),
+                offset: z.number().int().min(0).optional(),
+                max_bytes: z.number().int().min(1).max(8192).optional(),
+            }).strict(),
+        }, async ({ pack, path, offset, max_bytes }) => {
+            const payload = await readVisibleContext(pack, path, { ...contextPackProject, offset, maxBytes: max_bytes });
+            return { content: [{ type: "text", text: asToolText(payload) }], structuredContent: payload };
+        });
+    }
     return server;
 }
 function createMemoryServer(context = {}) {

package/mcp-memory-server/dist/mcp-tool-catalog.js

@@ -0,0 +1,47 @@
+const observation = (title, openWorldHint = false) => ({
+    title,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint },
+});
+const additive = (title, openWorldHint = false) => ({
+    title,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint },
+});
+const mutation = (title, openWorldHint = false) => ({
+    title,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint },
+});
+// This is the authoritative MCP catalog. Adding a registered tool without an
+// entry is a startup error, so clients can safely classify every Cairnkeep tool.
+export const MCP_TOOL_CATALOG = {
+    artifact_write: additive("Write artifact"),
+    artifact_read: observation("Read artifact"),
+    artifact_list: observation("List artifacts"),
+    artifact_delete: mutation("Delete artifact"),
+    memory_read: observation("Read memory"),
+    memory_write: mutation("Write memory"),
+    memory_list: observation("List memory"),
+    memory_delete: mutation("Delete memory"),
+    memory_search: observation("Search memory"),
+    memory_extract: observation("Extract memory candidates", true),
+    memory_supersede: mutation("Supersede memory"),
+    memory_apply_reviewed: mutation("Apply reviewed memory"),
+    memory_invalidate_reviewed: mutation("Invalidate reviewed memory"),
+    memory_history: observation("Read memory history"),
+    memory_import: mutation("Import memory"),
+    domain_knowledge_query: observation("Query domain knowledge", true),
+    domain_knowledge_sync: mutation("Synchronize domain knowledge", true),
+    context_explore: observation("Explore repository context", true),
+    route_check: observation("Check route", true),
+    context_pack_list: observation("List context packs"),
+    context_pack_search: observation("Search context packs"),
+    context_pack_read: observation("Read context pack file"),
+};
+export const MCP_TOOL_NAMES = Object.freeze(Object.keys(MCP_TOOL_CATALOG));
+export function isCairnToolName(value) {
+    return Object.hasOwn(MCP_TOOL_CATALOG, value);
+}
+export function metadataForTool(name) {
+    if (!isCairnToolName(name))
+        throw new Error(`MCP tool ${name} has no annotation contract.`);
+    return MCP_TOOL_CATALOG[name];
+}