The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: install native Cursor hook and MCP config (#1543)
Affaan Mustafa92e0c7e9ff92
diff --git a/.cursor/hooks.json b/.cursor/hooks.jsonindex cbe4d3460..573e647f4 100644--- a/.cursor/hooks.json+++ b/.cursor/hooks.json@@ -1,4 +1,5 @@{+ "version": 1,"hooks": {"sessionStart": [{diff --git a/scripts/hooks/mcp-health-check.js b/scripts/hooks/mcp-health-check.jsindex 4c40e1148..c47d3880e 100644--- a/scripts/hooks/mcp-health-check.js+++ b/scripts/hooks/mcp-health-check.js@@ -308,10 +308,15 @@ function probeCommandServer(serverName, config) {let stderr = '';let done = false;+ let timer = null;function finish(result) {if (done) return;done = true;+ if (timer) {+ clearTimeout(timer);+ timer = null;+ }resolve(result);}@@ -354,7 +359,19 @@ function probeCommandServer(serverName, config) {});});- const timer = setTimeout(() => {+ timer = setTimeout(() => {+ // A fast-crashing stdio server can finish before the timer callback runs+ // on a loaded machine. Check the process state again before classifying it+ // as healthy on timeout.+ if (child.exitCode !== null || child.signalCode !== null) {+ finish({+ ok: false,+ statusCode: child.exitCode,+ reason: stderr.trim() || `process exited before handshake (${child.signalCode || child.exitCode || 'unknown'})`+ });+ return;+ }+try {child.kill('SIGTERM');} catch {diff --git a/scripts/lib/install-executor.js b/scripts/lib/install-executor.jsindex 7ad7a4086..d6676c56f 100644--- a/scripts/lib/install-executor.js+++ b/scripts/lib/install-executor.js@@ -184,6 +184,41 @@ function addFileCopyOperation(operations, options) {return true;}+function readJsonObject(filePath, label) {+ let parsed;+ try {+ parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));+ } catch (error) {+ throw new Error(`Failed to parse ${label} at ${filePath}: ${error.message}`);+ }++ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {+ throw new Error(`Invalid ${label} at ${filePath}: expected a JSON object`);+ }++ return parsed;+}++function addJsonMergeOperation(operations, options) {+ const sourcePath = path.join(options.sourceRoot, options.sourceRelativePath);+ if (!fs.existsSync(sourcePath)) {+ return false;+ }++ operations.push({+ kind: 'merge-json',+ moduleId: options.moduleId,+ sourceRelativePath: options.sourceRelativePath,+ destinationPath: options.destinationPath,+ strategy: 'merge-json',+ ownership: 'managed',+ scaffoldOnly: false,+ mergePayload: readJsonObject(sourcePath, options.sourceRelativePath),+ });++ return true;+}+function addMatchingRuleOperations(operations, options) {const sourceDir = path.join(options.sourceRoot, options.sourceRelativeDir);if (!fs.existsSync(sourceDir)) {@@ -342,10 +377,10 @@ function planCursorLegacyInstall(context) {sourceRelativePath: path.join('.cursor', 'hooks.json'),destinationPath: path.join(targetRoot, 'hooks.json'),});- addFileCopyOperation(operations, {+ addJsonMergeOperation(operations, {moduleId: 'legacy-cursor-install',sourceRoot: context.sourceRoot,- sourceRelativePath: path.join('.cursor', 'mcp.json'),+ sourceRelativePath: '.mcp.json',destinationPath: path.join(targetRoot, 'mcp.json'),});@@ -540,6 +575,22 @@ function createLegacyCompatInstallPlan(options = {}) {}function materializeScaffoldOperation(sourceRoot, operation) {+ if (operation.kind === 'merge-json') {+ return [{+ kind: 'merge-json',+ moduleId: operation.moduleId,+ sourceRelativePath: operation.sourceRelativePath,+ destinationPath: operation.destinationPath,+ strategy: operation.strategy || 'merge-json',+ ownership: operation.ownership || 'managed',+ scaffoldOnly: Object.hasOwn(operation, 'scaffoldOnly') ? operation.scaffoldOnly : false,+ mergePayload: readJsonObject(+ path.join(sourceRoot, operation.sourceRelativePath),+ operation.sourceRelativePath+ ),+ }];+ }+const sourcePath = path.join(sourceRoot, operation.sourceRelativePath);if (!fs.existsSync(sourcePath)) {return [];diff --git a/scripts/lib/install-targets/cursor-project.js b/scripts/lib/install-targets/cursor-project.jsindex ceba1cb76..66fd19df3 100644--- a/scripts/lib/install-targets/cursor-project.js+++ b/scripts/lib/install-targets/cursor-project.js@@ -18,6 +18,39 @@ function toCursorRuleFileName(fileName, sourceRelativeFile) {: fileName;}+function readJsonObject(filePath, label) {+ let parsed;+ try {+ parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));+ } catch (error) {+ throw new Error(`Failed to parse ${label} at ${filePath}: ${error.message}`);+ }++ if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {+ throw new Error(`Invalid ${label} at ${filePath}: expected a JSON object`);+ }++ return parsed;+}++function createJsonMergeOperation({ moduleId, repoRoot, sourceRelativePath, destinationPath }) {+ const sourcePath = path.join(repoRoot, sourceRelativePath);+ if (!fs.existsSync(sourcePath) || !fs.statSync(sourcePath).isFile()) {+ return null;+ }++ return createManagedOperation({+ kind: 'merge-json',+ moduleId,+ sourceRelativePath,+ destinationPath,+ strategy: 'merge-json',+ ownership: 'managed',+ scaffoldOnly: false,+ mergePayload: readJsonObject(sourcePath, sourceRelativePath),+ });+}+module.exports = createInstallTargetAdapter({id: 'cursor-project',target: 'cursor',@@ -93,6 +126,13 @@ module.exports = createInstallTargetAdapter({}return entries.flatMap(({ module, sourceRelativePath }) => {+ const cursorMcpOperation = createJsonMergeOperation({+ moduleId: module.id,+ repoRoot,+ sourceRelativePath: '.mcp.json',+ destinationPath: path.join(targetRoot, 'mcp.json'),+ });+if (sourceRelativePath === 'rules') {return takeUniqueOperations(createFlatRuleOperations({moduleId: module.id,@@ -127,7 +167,21 @@ module.exports = createInstallTargetAdapter({destinationNameTransform: toCursorRuleFileName,});- return takeUniqueOperations([...childOperations, ...ruleOperations]);+ return takeUniqueOperations([+ ...childOperations,+ ...(cursorMcpOperation ? [cursorMcpOperation] : []),+ ...ruleOperations,+ ]);+ }++ if (sourceRelativePath === 'mcp-configs') {+ const operations = [+ adapter.createScaffoldOperation(module.id, sourceRelativePath, planningInput),+ ];+ if (cursorMcpOperation) {+ operations.push(cursorMcpOperation);+ }+ return takeUniqueOperations(operations);}return takeUniqueOperations([diff --git a/scripts/lib/install/apply.js b/scripts/lib/install/apply.jsindex b74e73f3b..42497c42d 100644--- a/scripts/lib/install/apply.js+++ b/scripts/lib/install/apply.js@@ -21,6 +21,38 @@ function readJsonObject(filePath, label) {return parsed;}+function cloneJsonValue(value) {+ if (value === undefined) {+ return undefined;+ }++ return JSON.parse(JSON.stringify(value));+}++function isPlainObject(value) {+ return Boolean(value) && typeof value === 'object' && !Array.isArray(value);+}++function deepMergeJson(baseValue, patchValue) {+ if (!isPlainObject(baseValue) || !isPlainObject(patchValue)) {+ return cloneJsonValue(patchValue);+ }++ const merged = { ...baseValue };+ for (const [key, value] of Object.entries(patchValue)) {+ if (isPlainObject(value) && isPlainObject(merged[key])) {+ merged[key] = deepMergeJson(merged[key], value);+ } else {+ merged[key] = cloneJsonValue(value);+ }+ }+ return merged;+}++function formatJson(value) {+ return `${JSON.stringify(value, null, 2)}\n`;+}+function replacePluginRootPlaceholders(value, pluginRoot) {if (!pluginRoot) {return value;@@ -56,44 +88,6 @@ function isMcpConfigPath(filePath) {return basename === '.mcp.json' || basename === 'mcp.json';}-function buildFilteredMcpWrites(plan) {- const disabledServers = parseDisabledMcpServers(process.env.ECC_DISABLED_MCPS);- if (disabledServers.length === 0) {- return [];- }-- const writes = [];-- for (const operation of plan.operations) {- if (!isMcpConfigPath(operation.destinationPath) || !operation.sourcePath || !fs.existsSync(operation.sourcePath)) {- continue;- }-- let sourceConfig;- try {- sourceConfig = readJsonObject(operation.sourcePath, 'MCP config');- } catch {- continue;- }-- if (!sourceConfig.mcpServers || typeof sourceConfig.mcpServers !== 'object' || Array.isArray(sourceConfig.mcpServers)) {- continue;- }-- const filtered = filterMcpConfig(sourceConfig, disabledServers);- if (filtered.removed.length === 0) {- continue;- }-- writes.push({- destinationPath: operation.destinationPath,- filteredConfig: filtered.config,- });- }-- return writes;-}-function buildResolvedClaudeHooks(plan) {if (!plan.adapter || plan.adapter.target !== 'claude') {return null;@@ -123,10 +117,38 @@ function buildResolvedClaudeHooks(plan) {function applyInstallPlan(plan) {const resolvedClaudeHooksPlan = buildResolvedClaudeHooks(plan);- const filteredMcpWrites = buildFilteredMcpWrites(plan);+ const disabledServers = parseDisabledMcpServers(process.env.ECC_DISABLED_MCPS);for (const operation of plan.operations) {fs.mkdirSync(path.dirname(operation.destinationPath), { recursive: true });++ if (operation.kind === 'merge-json') {+ const payload = cloneJsonValue(operation.mergePayload);+ if (payload === undefined) {+ throw new Error(`Missing merge payload for ${operation.destinationPath}`);+ }++ const filteredPayload = (+ isMcpConfigPath(operation.destinationPath) && disabledServers.length > 0+ )+ ? filterMcpConfig(payload, disabledServers).config+ : payload;++ const currentValue = fs.existsSync(operation.destinationPath)+ ? readJsonObject(operation.destinationPath, 'existing JSON config')+ : {};+ const mergedValue = deepMergeJson(currentValue, filteredPayload);+ fs.writeFileSync(operation.destinationPath, formatJson(mergedValue), 'utf8');+ continue;+ }++ if (operation.kind === 'copy-file' && isMcpConfigPath(operation.destinationPath) && disabledServers.length > 0) {+ const sourceConfig = readJsonObject(operation.sourcePath, 'MCP config');+ const filteredConfig = filterMcpConfig(sourceConfig, disabledServers).config;+ fs.writeFileSync(operation.destinationPath, formatJson(filteredConfig), 'utf8');+ continue;+ }+fs.copyFileSync(operation.sourcePath, operation.destinationPath);}@@ -139,15 +161,6 @@ function applyInstallPlan(plan) {);}- for (const writePlan of filteredMcpWrites) {- fs.mkdirSync(path.dirname(writePlan.destinationPath), { recursive: true });- fs.writeFileSync(- writePlan.destinationPath,- JSON.stringify(writePlan.filteredConfig, null, 2) + '\n',- 'utf8'- );- }-writeInstallState(plan.installStatePath, plan.statePreview);return {diff --git a/tests/lib/install-manifests.test.js b/tests/lib/install-manifests.test.jsindex 652567efb..d8a79060f 100644--- a/tests/lib/install-manifests.test.js+++ b/tests/lib/install-manifests.test.js@@ -122,6 +122,15 @@ function runTests() {)),'Should preserve non-rule Cursor platform files');+ assert.ok(+ plan.operations.some(operation => (+ operation.sourceRelativePath === '.mcp.json'+ && operation.destinationPath === path.join(projectRoot, '.cursor', 'mcp.json')+ && operation.kind === 'merge-json'+ && operation.strategy === 'merge-json'+ )),+ 'Should materialize Cursor MCP config at the native project path'+ );assert.ok(plan.operations.some(operation => (operation.sourceRelativePath === '.cursor/rules/common-agents.md'diff --git a/tests/lib/install-targets.test.js b/tests/lib/install-targets.test.jsindex f26ce3f58..e0908a62e 100644--- a/tests/lib/install-targets.test.js+++ b/tests/lib/install-targets.test.js@@ -93,6 +93,9 @@ function runTests() {const hooksJson = plan.operations.find(operation => (normalizedRelativePath(operation.sourceRelativePath) === '.cursor/hooks.json'));+ const mcpJson = plan.operations.find(operation => (+ normalizedRelativePath(operation.sourceRelativePath) === '.mcp.json'+ ));const preserved = plan.operations.find(operation => (normalizedRelativePath(operation.sourceRelativePath) === '.cursor/rules/common-coding-style.md'));@@ -100,6 +103,10 @@ function runTests() {assert.ok(hooksJson, 'Should preserve non-rule Cursor platform config files');assert.strictEqual(hooksJson.strategy, 'preserve-relative-path');assert.strictEqual(hooksJson.destinationPath, path.join(projectRoot, '.cursor', 'hooks.json'));+ assert.ok(mcpJson, 'Should materialize a Cursor MCP config from the shared root MCP config');+ assert.strictEqual(mcpJson.kind, 'merge-json');+ assert.strictEqual(mcpJson.strategy, 'merge-json');+ assert.strictEqual(mcpJson.destinationPath, path.join(projectRoot, '.cursor', 'mcp.json'));assert.ok(preserved, 'Should include flattened Cursor rule scaffold operations');assert.strictEqual(preserved.strategy, 'flatten-copy');@@ -201,6 +208,14 @@ function runTests() {)),'Should preserve non-rule Cursor platform config files');+ assert.ok(+ plan.operations.some(operation => (+ normalizedRelativePath(operation.sourceRelativePath) === '.mcp.json'+ && operation.kind === 'merge-json'+ && operation.destinationPath === path.join(projectRoot, '.cursor', 'mcp.json')+ )),+ 'Should materialize a project-level Cursor MCP config'+ );assert.ok(!plan.operations.some(operation => (operation.destinationPath === path.join(projectRoot, '.cursor', 'rules', 'README.mdc')diff --git a/tests/scripts/install-apply.test.js b/tests/scripts/install-apply.test.jsindex 4943ef93a..cb505e6fe 100644--- a/tests/scripts/install-apply.test.js+++ b/tests/scripts/install-apply.test.js@@ -138,11 +138,19 @@ function runTests() {assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'agents', 'architect.md')));assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'commands', 'plan.md')));assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'hooks.json')));+ assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'mcp.json')));assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'hooks', 'session-start.js')));assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'scripts', 'lib', 'utils.js')));assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'skills', 'tdd-workflow', 'SKILL.md')));assert.ok(fs.existsSync(path.join(projectDir, '.cursor', 'skills', 'coding-standards', 'SKILL.md')));+ const hooksConfig = readJson(path.join(projectDir, '.cursor', 'hooks.json'));+ const mcpConfig = readJson(path.join(projectDir, '.cursor', 'mcp.json'));+ assert.strictEqual(hooksConfig.version, 1);+ assert.ok(hooksConfig.hooks.sessionStart, 'Should keep Cursor sessionStart hooks');+ assert.ok(mcpConfig.mcpServers.github, 'Should install shared MCP servers into Cursor');+ assert.ok(mcpConfig.mcpServers.context7, 'Should include bundled documentation MCPs');+const statePath = path.join(projectDir, '.cursor', 'ecc-install-state.json');const state = readJson(statePath);const normalizedProjectDir = fs.realpathSync(projectDir);@@ -163,6 +171,35 @@ function runTests() {}})) passed++; else failed++;+ if (test('installs Cursor MCP config by merging bundled servers into an existing mcp.json', () => {+ const homeDir = createTempDir('install-apply-home-');+ const projectDir = createTempDir('install-apply-project-');++ try {+ const cursorRoot = path.join(projectDir, '.cursor');+ fs.mkdirSync(cursorRoot, { recursive: true });+ fs.writeFileSync(path.join(cursorRoot, 'mcp.json'), JSON.stringify({+ mcpServers: {+ custom: {+ command: 'node',+ args: ['custom-mcp.js'],+ },+ },+ }, null, 2));++ const result = run(['--target', 'cursor', 'typescript'], { cwd: projectDir, homeDir });+ assert.strictEqual(result.code, 0, result.stderr);++ const mcpConfig = readJson(path.join(projectDir, '.cursor', 'mcp.json'));+ assert.ok(mcpConfig.mcpServers.custom, 'Should preserve existing custom Cursor MCP servers');+ assert.ok(mcpConfig.mcpServers.github, 'Should merge bundled GitHub MCP server');+ assert.ok(mcpConfig.mcpServers.playwright, 'Should merge bundled Playwright MCP server');+ } finally {+ cleanup(homeDir);+ cleanup(projectDir);+ }+ })) passed++; else failed++;+if (test('installs Antigravity configs and writes install-state', () => {const homeDir = createTempDir('install-apply-home-');const projectDir = createTempDir('install-apply-project-');