@cairnkeep/cli 2.7.0 → 2.9.0

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

@@ -186,7 +186,7 @@ function validateBundledBinding(taskSetPath, taskSet, taskSetBytes) {
         binding_path: realpathSync(bindingPath),
     };
 }
-function validateArms(arms) {
+function validateArms(arms, experimentKind) {
     if (arms.length < 1 || arms.length > 2)
         throw new Error("Evaluation requires one or two arms.");
     const seen = new Set();
@@ -201,8 +201,12 @@ function validateArms(arms) {
         }
         if (arm.id === "baseline" && arm.disabled_capability !== null)
             throw new Error("Baseline cannot disable a capability.");
-        if (arm.id === "treatment" && arm.disabled_capability === null)
-            throw new Error("Treatment must disable exactly one capability.");
+        if (arm.id === "treatment" && experimentKind === "ablation" && arm.disabled_capability === null) {
+            throw new Error("Ablation treatment must disable exactly one capability.");
+        }
+        if (experimentKind === "skill_candidate" && arm.disabled_capability !== null) {
+            throw new Error("Skill-candidate arms cannot disable capabilities.");
+        }
         return { id: arm.id, disabled_capability: arm.disabled_capability };
     });
 }
@@ -214,7 +218,10 @@ export function isEvalEnabled(value = process.env.CAIRN_EVAL) {
 }
 export function buildEvalSchedule(options) {
     const taskSet = evalTaskSetSchema.parse(options.taskSet);
-    const arms = validateArms(options.arms);
+    const inferredKind = options.arms.length === 1 ? "two_pass" : options.arms.some(({ disabled_capability }) => disabled_capability !== null)
+        ? "ablation"
+        : "skill_candidate";
+    const arms = validateArms(options.arms, inferredKind);
     if (!Number.isSafeInteger(options.repetitions) || options.repetitions < 1 || options.repetitions > MAX_REPETITIONS) {
         throw new Error(`Evaluation repetitions must be an integer from 1 to ${MAX_REPETITIONS}.`);
     }
@@ -282,7 +289,15 @@ export function validateEvalInputs(options) {
     }
     const repetitions = options.repetitions ?? 1;
     const seed = options.seed ?? "cairn-eval-v1";
-    const arms = validateArms(options.arms ?? [{ id: "baseline", disabled_capability: null }]);
+    const suppliedArms = options.arms ?? [{ id: "baseline", disabled_capability: null }];
+    const experimentKind = options.experimentKind
+        ?? (suppliedArms.length === 1 ? "two_pass" : "ablation");
+    if (experimentKind === "two_pass" && suppliedArms.length !== 1)
+        throw new Error("Two-pass evaluation requires one arm.");
+    if ((experimentKind === "ablation" || experimentKind === "skill_candidate") && suppliedArms.length !== 2) {
+        throw new Error(`${experimentKind} evaluation requires two arms.`);
+    }
+    const arms = validateArms(suppliedArms, experimentKind);
     const passes = ["run1", "run2"];
     const schedule = buildEvalSchedule({ taskSet, arms, repetitions, passes, seed });
     const adapterBase = dirname(adapterInput.path);
@@ -304,6 +319,7 @@ export function validateEvalInputs(options) {
         repetitions,
         seed,
         arms,
+        experiment_kind: experimentKind,
         passes,
         concurrency: 1,
         task_set_commit: taskSetCommit,
@@ -320,6 +336,7 @@ export function validateEvalInputs(options) {
         repetitions,
         seed,
         arms,
+        experiment_kind: experimentKind,
         passes: ["run1", "run2"],
         concurrency: 1,
         invocation_count: schedule.invocation_count,

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

@@ -246,6 +246,37 @@ function hasTrailingJsonDocument(value) {
     }
     return false;
 }
+export async function runBoundedJsonProcess(options) {
+    const request = options.request_schema.safeParse(options.request);
+    if (!request.success)
+        throw new EvalProcessError("invalid_request");
+    const commandResult = await runCommandInternal({
+        command: options.command,
+        cwd: options.cwd,
+        env: options.env,
+        timeout_ms: options.timeout_ms,
+        max_stdout_bytes: options.max_stdout_bytes,
+        kill_grace_ms: options.kill_grace_ms,
+        signal: options.signal,
+        stdout_mode: "raw",
+        stdin_document: Buffer.from(JSON.stringify(request.data), "utf8"),
+    });
+    if (commandResult.exit_code !== 0 || commandResult.signal !== null || commandResult.cleanup !== "closed") {
+        throw new EvalProcessError("adapter_error", commandResult);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(commandResult.stdout ?? "");
+    }
+    catch {
+        throw new EvalProcessError(hasTrailingJsonDocument(commandResult.stdout ?? "") ? "multiple_json" : "invalid_json", commandResult);
+    }
+    const result = options.result_schema.safeParse(parsed);
+    if (!result.success)
+        throw new EvalProcessError("invalid_result", commandResult);
+    const { stdout: _stdout, ...processResult } = commandResult;
+    return { ...processResult, result: result.data };
+}
 export async function runBoundedJsonAdapter(options) {
     const request = evalAdapterRequestSchema.safeParse(options.request);
     if (!request.success)

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

@@ -578,6 +578,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

@@ -9,7 +9,8 @@ import { CAPABILITY_IDS, capabilityStatusSchema, } from "./capability-schema.js"
 import { canonicalDigest, evalReportSchema, evalReportRuntimeContractDigest, } from "./eval-schema.js";
 import { EvalProcessError, runBoundedCommand, runBoundedJsonAdapter, } from "./eval-process.js";
 import { checkpointEvalReport, createEvalReportStore, } from "./eval-report.js";
-import { cleanupEvalWorkspace, createEvalWorkspace, runTaskPreparation, runTaskVerifier, } from "./eval-workspace.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;
@@ -557,6 +558,8 @@ export async function runEvalObservation(options) {
             observation.missing_reasons.push("preparation_failed");
         }
         else {
+            if (options.workspace_overlay)
+                await applyEvalWorkspaceOverlay(workspace, options.workspace_overlay);
             const request = {
                 schema_version: 1,
                 experiment_id: options.report.experiment_id,
@@ -698,7 +701,7 @@ export async function runEvalObservation(options) {
     await checkpoint(options.report_store, options.report);
     return { observation, snapshot: distilledSnapshot, cancelled: observation.terminal_state === "cancelled" };
 }
-function initialReport(plan, experimentId) {
+function initialReport(plan, experimentId, fallbackExperimentKind) {
     const now = new Date().toISOString();
     const sourceCommit = plan.task_set_commit ?? (plan.source.kind === "git" ? plan.source.revision : plan.task_set_digest);
     const missingness = { count: 0, reasons: [] };
@@ -706,7 +709,7 @@ function initialReport(plan, experimentId) {
         schema_version: 1,
         experiment_id: experimentId,
         status: "partial",
-        experiment_kind: plan.arms.length === 1 ? "two_pass" : "ablation",
+        experiment_kind: plan.experiment_kind ?? fallbackExperimentKind,
         task_set_digest: plan.task_set_digest,
         adapter_config_digest: plan.adapter_config_digest,
         source_revision: plan.source.kind === "git" ? plan.source.revision : plan.task_set_digest,
@@ -733,6 +736,7 @@ function initialReport(plan, experimentId) {
             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: [],
@@ -750,7 +754,7 @@ async function runExperiment(options, capabilityArms) {
     });
     if (reportStore.experiment_id !== experimentId)
         throw new Error("report_experiment_mismatch");
-    const report = initialReport(options.plan, experimentId);
+    const report = initialReport(options.plan, experimentId, capabilityArms ? "ablation" : "two_pass");
     const snapshotsByTask = new Map();
     const notesByTask = new Map();
     const snapshots = [];
@@ -782,6 +786,7 @@ async function runExperiment(options, capabilityArms) {
                 distill_command: options.distill_command,
                 distill_timeout_ms: options.distill_timeout_ms,
                 capability_runtime: capabilityRuntime,
+                workspace_overlay: options.workspace_overlays?.[row.arm],
             });
             executed.push(row.observation_id);
             if (result.snapshot) {
@@ -813,6 +818,9 @@ export async function runTwoPassExperiment(options) {
     return runExperiment(options);
 }
 export async function runCapabilityAblation(options) {
+    if (options.plan.experiment_kind !== undefined && options.plan.experiment_kind !== "ablation") {
+        throw new Error("ablation_experiment_kind_required");
+    }
     const arms = buildAblationArms(options.disabled_capability);
     const intended = arms.map(({ id, disabled_capability }) => ({ id, disabled_capability }));
     if (canonicalDigest(options.plan.arms) !== canonicalDigest(intended))

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

@@ -13,7 +13,7 @@ export const EVAL_OBSERVATION_TERMINAL_STATES = [
     "invalid_result",
 ];
 export const EVAL_PASS_STATES = ["passed", "failed", "unknown"];
-export const EVAL_EXPERIMENT_KINDS = ["two_pass", "ablation"];
+export const EVAL_EXPERIMENT_KINDS = ["two_pass", "ablation", "skill_candidate"];
 const MAX_TEXT_BYTES = 1024 * 1024;
 const MAX_COMMAND_ARGS = 256;
 const MAX_TASKS = 10_000;
@@ -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/eval-workspace.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { constants, existsSync } from "node:fs";
 import { chmod, lstat, mkdir, mkdtemp, open, readFile, realpath, writeFile, } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -155,7 +156,7 @@ export async function createEvalWorkspace(options) {
     };
     try {
         if (options.plan.source.kind === "git") {
-            const added = await gitCommand(options.plan.source.repository_root, ["worktree", "add", "--detach", workspace.source_path, options.plan.source.revision], "exit-only");
+            const added = await gitCommand(options.plan.source.repository_root, ["worktree", "add", "--quiet", "--detach", workspace.source_path, options.plan.source.revision], "exit-only");
             requireSuccessfulCommand(added, "workspace_add_failed");
             workspace.worktree_registered = true;
             await verifyGitWorkspace(workspace);
@@ -192,6 +193,54 @@ export async function runTaskPreparation(workspace, options = {}) {
         signal: options.signal,
     });
 }
+export async function applyEvalWorkspaceOverlay(workspace, overlay) {
+    const segments = overlay.relative_path.split("/");
+    if (overlay.relative_path.startsWith("/") || overlay.relative_path.endsWith("/")
+        || overlay.relative_path.includes("\\") || segments.some((segment) => segment === "" || segment === "." || segment === "..")
+        || /[\u0000-\u001f\u007f]/.test(overlay.relative_path)) {
+        throw new Error("workspace_overlay_path_invalid");
+    }
+    const target = resolve(workspace.source_path, overlay.relative_path);
+    if (!isContained(workspace.source_path, target) || target === workspace.source_path) {
+        throw new Error("workspace_overlay_path_escape");
+    }
+    let cursor = workspace.source_path;
+    for (const segment of segments.slice(0, -1)) {
+        cursor = join(cursor, segment);
+        try {
+            const info = await lstat(cursor);
+            if (info.isSymbolicLink() || !info.isDirectory())
+                throw new Error("workspace_overlay_parent_unsafe");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await mkdir(cursor, { mode: 0o700 });
+        }
+    }
+    try {
+        const info = await lstat(target);
+        if (info.isSymbolicLink() || !info.isFile())
+            throw new Error("workspace_overlay_target_unsafe");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const parent = await realpath(dirname(target));
+    const source = await realpath(workspace.source_path);
+    if (!isContained(source, parent))
+        throw new Error("workspace_overlay_parent_escape");
+    const bytes = Buffer.from(overlay.content, "utf8");
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== overlay.digest)
+        throw new Error("workspace_overlay_digest_mismatch");
+    await writeFile(target, bytes, { mode: 0o600 });
+    await chmod(target, 0o600);
+    const storedDigest = createHash("sha256").update(await readFile(target)).digest("hex");
+    if (storedDigest !== overlay.digest)
+        throw new Error("workspace_overlay_write_mismatch");
+}
 function verifierReason(code) {
     return `verifier_${code}`;
 }

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) {
@@ -822,8 +825,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 +853,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 +912,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 +940,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 +956,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 +996,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 +1033,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 +1171,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 +1209,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 +1293,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 +1314,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 +1400,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 +1504,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 +1629,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 +1698,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: {
@@ -1730,7 +1750,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 +1770,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 +1899,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];
+}

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

@@ -0,0 +1,85 @@
+import { MCP_TOOL_CATALOG, MCP_TOOL_NAMES } from "./mcp-tool-catalog.js";
+import { resetMcpToolProfile, resolveMcpToolProfile, setMcpToolProfile } from "./mcp-tool-profile.js";
+function usage() {
+    process.stderr.write("Usage: cairn mcp-tools list [--json] | status [--project PATH] [--json] | set full|read-only [--project PATH] | set custom --tool NAME... [--project PATH] | reset [--project PATH]\n");
+    process.exit(2);
+}
+function option(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--"))
+        usage();
+    args.splice(index, 2);
+    return value;
+}
+function flags(args, name) {
+    const values = [];
+    for (let index = 0; index < args.length;) {
+        if (args[index] !== name) {
+            index += 1;
+            continue;
+        }
+        args.splice(index, 1);
+        let consumed = 0;
+        while (index < args.length && !args[index].startsWith("--")) {
+            values.push(args[index]);
+            args.splice(index, 1);
+            consumed += 1;
+        }
+        if (consumed === 0)
+            usage();
+    }
+    return values;
+}
+function output(value, json, human) {
+    process.stdout.write(`${json ? JSON.stringify(value) : human}\n`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args.shift();
+    const jsonIndex = args.indexOf("--json");
+    const json = jsonIndex >= 0;
+    if (json)
+        args.splice(jsonIndex, 1);
+    const projectRoot = option(args, "--project") ?? process.cwd();
+    if (command === "list") {
+        if (args.length)
+            usage();
+        const tools = MCP_TOOL_NAMES.map((name) => ({ name, title: MCP_TOOL_CATALOG[name].title, annotations: MCP_TOOL_CATALOG[name].annotations }));
+        output({ schema_version: 1, tools }, json, tools.map(({ name, annotations }) => `${name}\t${annotations.readOnlyHint ? "read-only" : "mutation"}`).join("\n"));
+        return;
+    }
+    if (command === "status") {
+        if (args.length)
+            usage();
+        const status = resolveMcpToolProfile({ projectRoot });
+        output(status, json, `Profile: ${status.mode}\nSource: ${status.source}\nDigest: ${status.profile_digest}\nTools: ${status.allowed_tools.join(", ")}`);
+        return;
+    }
+    if (command === "set") {
+        const mode = args.shift();
+        if (!mode || !["full", "read-only", "custom"].includes(mode))
+            usage();
+        const allowedTools = flags(args, "--tool");
+        if (args.length || (mode === "custom" && allowedTools.length === 0) || (mode !== "custom" && allowedTools.length > 0))
+            usage();
+        const status = await setMcpToolProfile({ projectRoot, mode, allowedTools });
+        output(status, json, `MCP tool profile set to ${mode} (${status.profile_digest}).`);
+        return;
+    }
+    if (command === "reset") {
+        if (args.length)
+            usage();
+        await resetMcpToolProfile(projectRoot);
+        const status = resolveMcpToolProfile({ projectRoot });
+        output(status, json, `Project MCP tool profile reset; effective profile is ${status.mode} from ${status.source}.`);
+        return;
+    }
+    usage();
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});