@danielblomma/cortex-mcp 2.0.4 → 2.0.6

package/bin/cortex.mjs

@@ -22,17 +22,20 @@ const PACKAGE_ROOT = path.resolve(__dirname, "..");
 const SCAFFOLD_ROOT = path.join(PACKAGE_ROOT, "scaffold");
 const PACKAGE_JSON_PATH = path.join(PACKAGE_ROOT, "package.json");
 
+// v2.0.5: project layout moved mcp/ under .context/mcp/, and the
+// gitignore policy flipped to "ignore everything in .context/, whitelist
+// only the three editable config files". Generated artifacts (db,
+// embeddings, cache, hooks, mcp/, govern.local.json) never land in git.
+const MCP_PROJECT_REL = path.join(".context", "mcp");
+
 const GITIGNORE_LINES = [
   "",
   "# Cortex local storage",
-  ".context/db/",
-  ".context/embeddings/",
-  ".context/cache/",
-  ".context/hooks/",
-  ".npm-cache/",
-  "mcp/.npm-cache/",
-  "mcp/dist/",
-  "mcp/node_modules/"
+  ".context/",
+  "!.context/config.yaml",
+  "!.context/rules.yaml",
+  "!.context/ontology.cypher",
+  ".npm-cache/"
 ];
 
 function printBanner(title) {
@@ -86,6 +89,13 @@ function printHelp() {
   console.log(helpRow("hooks [install|uninstall|status] [--project]", "Claude Code hooks"));
   console.log(helpRow("telemetry test", "Smoke-test the push pipeline"));
 
+  console.log(helpSection("HARNESS"));
+  console.log(helpRow("stage start --task-id <id> --description \"...\"", "Start a workflow run for a task"));
+  console.log(helpRow("stage status --task-id <id>", "Print run state JSON"));
+  console.log(helpRow("stage envelope --task-id <id> [--stage <name>]", "Compose stage prompt envelope"));
+  console.log(helpRow("stage advance --task-id <id> --stage <name> --body-file <path>", "Write artifact, advance run"));
+  console.log(helpRow("stage run --task-id <id> -- <command>", "Exec a command with CORTEX_ACTIVE_TASK_ID set"));
+
   console.log(helpSection("MISC"));
   console.log(helpRow("mcp", "Run the MCP stdio server for the current project"));
   console.log(helpRow("version", "Print CLI version"));
@@ -199,7 +209,6 @@ const INIT_SKIP_DIRECTORIES = new Set([
   ".cache",
   ".context",
   "scripts",
-  "mcp",
   ".githooks",
   "bin",
   "obj"
@@ -439,11 +448,26 @@ function mergeGitignore(targetDir) {
   fs.writeFileSync(gitignorePath, merged, "utf8");
 }
 
+function migrateLegacyMcpLocation(targetDir) {
+  const legacyMcp = path.join(targetDir, "mcp");
+  const newMcp = path.join(targetDir, MCP_PROJECT_REL);
+  if (!fs.existsSync(legacyMcp)) return;
+  if (fs.existsSync(newMcp)) return;
+  fs.mkdirSync(path.join(targetDir, ".context"), { recursive: true });
+  fs.renameSync(legacyMcp, newMcp);
+  console.log(
+    "[cortex] migrated legacy mcp/ → .context/mcp/ to keep project root clean. " +
+      "Re-run 'cortex connect' if Claude/Codex MCP registrations need to be refreshed.",
+  );
+}
+
 function installScaffold(targetDir, force) {
+  migrateLegacyMcpLocation(targetDir);
+
   const copyMap = [
     [path.join(SCAFFOLD_ROOT, ".context"), path.join(targetDir, ".context")],
     [path.join(SCAFFOLD_ROOT, "scripts"), path.join(targetDir, "scripts")],
-    [path.join(SCAFFOLD_ROOT, "mcp"), path.join(targetDir, "mcp")],
+    [path.join(SCAFFOLD_ROOT, "mcp"), path.join(targetDir, MCP_PROJECT_REL)],
     [path.join(SCAFFOLD_ROOT, ".githooks"), path.join(targetDir, ".githooks")]
   ];
 
@@ -633,7 +657,7 @@ async function connectClaude(targetDir) {
   }
 
   const serverName = "cortex";
-  const projectServerEntry = path.join("mcp", "dist", "server.js");
+  const projectServerEntry = path.join(MCP_PROJECT_REL, "dist", "server.js");
   await runCommandResult("claude", ["mcp", "remove", "-s", "project", serverName], targetDir, "ignore");
   await runCommand(
     "claude",
@@ -646,7 +670,7 @@ async function connectClaude(targetDir) {
 
 async function connectMcpClients(targetDir, options = {}) {
   const { skipBuild = false } = options;
-  const mcpDir = path.join(targetDir, "mcp");
+  const mcpDir = path.join(targetDir, MCP_PROJECT_REL);
   const packageJson = path.join(mcpDir, "package.json");
   const nodeModules = path.join(mcpDir, "node_modules");
   const serverEntry = path.join(mcpDir, "dist", "server.js");
@@ -662,7 +686,7 @@ async function connectMcpClients(targetDir, options = {}) {
       console.log(`[cortex] MCP build failed, continuing with existing dist output: ${toErrorMessage(error)}`);
     }
   } else if (!skipBuild) {
-    console.log("[cortex] mcp/node_modules not found, skipping build (run cortex bootstrap first)");
+    console.log("[cortex] .context/mcp/node_modules not found, skipping build (run cortex bootstrap first)");
   }
 
   if (!fs.existsSync(serverEntry)) {
@@ -716,7 +740,7 @@ async function maybeInstallGitHooks(targetDir) {
 }
 
 function ensureProjectInitialized(targetDir) {
-  const mcpPackageJson = path.join(targetDir, "mcp", "package.json");
+  const mcpPackageJson = path.join(targetDir, MCP_PROJECT_REL, "package.json");
   if (!fs.existsSync(mcpPackageJson)) {
     throw new Error(`Missing ${mcpPackageJson}. Run 'cortex init --bootstrap' first.`);
   }
@@ -731,7 +755,9 @@ function isTruthyEnv(value) {
 }
 
 function canAutoInitialize(targetDir) {
-  const scaffoldPaths = [".context", "scripts", "mcp", ".githooks"].map((entry) => path.join(targetDir, entry));
+  // Legacy mcp/ at root no longer counted — pre-v2.0.5 projects are migrated
+  // by installScaffold rather than blocking auto-init.
+  const scaffoldPaths = [".context", "scripts", ".githooks"].map((entry) => path.join(targetDir, entry));
   return scaffoldPaths.every((entryPath) => !fs.existsSync(entryPath));
 }
 
@@ -744,7 +770,12 @@ function isScaffoldOutOfDate(targetDir) {
   if (!fs.existsSync(doctorScript)) {
     return true;
   }
-  const mcpPackage = path.join(targetDir, "mcp", "package.json");
+  // Treat legacy mcp/ at project root as out-of-date so existing installs
+  // get migrated into .context/mcp/ on the next bootstrap.
+  if (fs.existsSync(path.join(targetDir, "mcp", "package.json"))) {
+    return true;
+  }
+  const mcpPackage = path.join(targetDir, MCP_PROJECT_REL, "package.json");
   if (!fs.existsSync(mcpPackage)) {
     return true;
   }
@@ -780,7 +811,8 @@ async function maybeMigrateScaffold(targetDir, command) {
 
   console.error(
     `[cortex] scaffold in ${targetDir} is out of date ` +
-      `(missing scripts/doctor.sh, mcp/package.json, or doctor subcommand in context.sh).`
+      `(missing scripts/doctor.sh, .context/mcp/package.json, doctor subcommand in context.sh, ` +
+      `or carries a legacy mcp/ directory at the project root).`
   );
 
   let proceed = autoYes;
@@ -808,8 +840,8 @@ async function maybeMigrateScaffold(targetDir, command) {
 }
 
 async function ensureProjectInitializedForMcp(targetDir) {
-  const mcpPackageJson = path.join(targetDir, "mcp", "package.json");
-  const serverEntry = path.join(targetDir, "mcp", "dist", "server.js");
+  const mcpPackageJson = path.join(targetDir, MCP_PROJECT_REL, "package.json");
+  const serverEntry = path.join(targetDir, MCP_PROJECT_REL, "dist", "server.js");
 
   if (fs.existsSync(mcpPackageJson) && fs.existsSync(serverEntry)) {
     return;
@@ -947,7 +979,7 @@ async function run() {
     process.env.CORTEX_PROJECT_ROOT = target;
     await ensureProjectInitializedForMcp(target);
     ensureProjectInitialized(target);
-    const serverEntry = path.join(target, "mcp", "dist", "server.js");
+    const serverEntry = path.join(target, MCP_PROJECT_REL, "dist", "server.js");
     if (!fs.existsSync(serverEntry)) {
       throw new Error(`Missing ${serverEntry}. Run 'cortex bootstrap' in ${target} first.`);
     }
@@ -980,6 +1012,10 @@ async function run() {
     return runRunCommand(rest);
   }
 
+  if (command === "stage") {
+    return runStageCommandShim(rest);
+  }
+
   const passthrough = new Set([
     "bootstrap",
     "update",
@@ -1038,12 +1074,12 @@ function isPidAlive(pid) {
 }
 
 function resolveProjectMcpDist() {
-  // v2.0.0: daemon/hooks/cli are built into the project's mcp/dist/
-  // (via 'cortex bootstrap'). PACKAGE_ROOT/scaffold/mcp/ is the source
-  // tree the scaffold is copied from. The actual built code lives in
-  // each project's <cwd>/mcp/dist/ after bootstrap.
+  // v2.0.5: project layout was moved from <cwd>/mcp/ to <cwd>/.context/mcp/.
+  // PACKAGE_ROOT/scaffold/mcp/ is still the source tree the scaffold is
+  // copied from; the actual built code lives in each project's
+  // <cwd>/.context/mcp/dist/ after bootstrap.
   const target = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
-  return path.join(target, "mcp", "dist");
+  return path.join(target, MCP_PROJECT_REL, "dist");
 }
 
 function resolveDaemonEntry() {
@@ -1502,6 +1538,19 @@ async function runRunCommand(args) {
   process.exit(exitCode);
 }
 
+async function runStageCommandShim(args) {
+  const target = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+  process.env.CORTEX_PROJECT_ROOT = path.resolve(target);
+  const entry = resolveCliEntry("stage");
+  if (!fs.existsSync(entry)) {
+    throw new Error(
+      `Build the project's MCP first (missing ${entry}). Run 'cortex bootstrap' in the project root.`,
+    );
+  }
+  const mod = await import(pathToFileURL(entry).href);
+  await mod.runStageCommand(args);
+}
+
 async function runTelemetryCommand(args) {
   const sub = args[0] || "help";
   if (sub === "test") {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",

package/scaffold/mcp/package-lock.json

@@ -10,6 +10,9 @@
       "dependencies": {
         "@huggingface/transformers": "^4.1.0",
         "@modelcontextprotocol/sdk": "^1.27.1",
+        "@types/js-yaml": "^4.0.9",
+        "js-yaml": "^4.1.1",
+        "minimatch": "^10.2.5",
         "ryugraph": "^25.9.1",
         "zod": "^3.24.1"
       },
@@ -842,12 +845,17 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/js-yaml": {
+      "version": "4.0.9",
+      "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
+      "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==",
+      "license": "MIT"
+    },
     "node_modules/@types/node": {
       "version": "22.19.13",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.13.tgz",
       "integrity": "sha512-akNQMv0wW5uyRpD2v2IEyRSZiR+BeGuoB6L310EgGObO44HSMNT8z1xzio28V8qOrgYaopIDNA18YgdXd+qTiw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -989,6 +997,21 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "license": "Python-2.0"
+    },
+    "node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
     "node_modules/body-parser": {
       "version": "2.2.2",
       "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz",
@@ -1020,6 +1043,18 @@
       "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
       "license": "MIT"
     },
+    "node_modules/brace-expansion": {
+      "version": "5.0.5",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
+      "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==",
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^4.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
     "node_modules/bytes": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
@@ -1760,7 +1795,6 @@
       "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.14.tgz",
       "integrity": "sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
@@ -1861,6 +1895,18 @@
         "url": "https://github.com/sponsors/panva"
       }
     },
+    "node_modules/js-yaml": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
     "node_modules/json-schema-traverse": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
@@ -1940,6 +1986,21 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/minimatch": {
+      "version": "10.2.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
+      "integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==",
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "brace-expansion": "^5.0.5"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/minimist": {
       "version": "1.2.8",
       "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
@@ -2611,7 +2672,6 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -2764,7 +2824,6 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
       "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

package/scaffold/mcp/package.json

@@ -12,8 +12,11 @@
     "test": "npm run build --silent && node --test tests/*.test.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
     "@huggingface/transformers": "^4.1.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@types/js-yaml": "^4.0.9",
+    "js-yaml": "^4.1.1",
+    "minimatch": "^10.2.5",
     "ryugraph": "^25.9.1",
     "zod": "^3.24.1"
   },