The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: support disabling bundled mcp servers
Affaan Mustafa786f46dad5fd
diff --git a/README.md b/README.mdindex adc6491fa..11cc92cb9 100644--- a/README.md+++ b/README.md@@ -708,6 +708,14 @@ Copy the hooks from `hooks/hooks.json` to your `~/.claude/settings.json`.Copy desired MCP server definitions from `mcp-configs/mcp-servers.json` into your official Claude Code config in `~/.claude/settings.json`, or into a project-scoped `.mcp.json` if you want repo-local MCP access.+If you already run your own copies of ECC-bundled MCPs, set:++```bash+export ECC_DISABLED_MCPS="github,context7,exa,playwright,sequential-thinking,memory"+```++ECC-managed install and Codex sync flows will skip or remove those bundled servers instead of re-adding duplicates.+**Important:** Replace `YOUR_*_HERE` placeholders with your actual API keys.---diff --git a/mcp-configs/mcp-servers.json b/mcp-configs/mcp-servers.jsonindex e2227dab9..d163d9375 100644--- a/mcp-configs/mcp-servers.json+++ b/mcp-configs/mcp-servers.json@@ -175,7 +175,7 @@"_comments": {"usage": "Copy the servers you need to your ~/.claude.json mcpServers section","env_vars": "Replace YOUR_*_HERE placeholders with actual values",- "disabling": "Use disabledMcpServers array in project config to disable per-project",+ "disabling": "Use ECC_DISABLED_MCPS=github,context7,... to disable bundled ECC MCPs during install/sync, or use disabledMcpServers in project config for per-project overrides","context_warning": "Keep under 10 MCPs enabled to preserve context window"}}diff --git a/scripts/codex/merge-mcp-config.js b/scripts/codex/merge-mcp-config.jsindex 38138dade..0acb00853 100644--- a/scripts/codex/merge-mcp-config.js+++ b/scripts/codex/merge-mcp-config.js@@ -19,6 +19,7 @@const fs = require('fs');const path = require('path');+const { parseDisabledMcpServers } = require('../lib/mcp-config');let TOML;try {@@ -210,6 +211,7 @@ function main() {const configPath = args.find(a => !a.startsWith('-'));const dryRun = args.includes('--dry-run');const updateMcp = args.includes('--update-mcp');+ const disabledServers = new Set(parseDisabledMcpServers(process.env.ECC_DISABLED_MCPS));if (!configPath) {console.error('Usage: merge-mcp-config.js <config.toml> [--dry-run] [--update-mcp]');@@ -222,6 +224,9 @@ function main() {}log(`Package manager: ${PM_NAME} (exec: ${PM_EXEC})`);+ if (disabledServers.size > 0) {+ log(`Disabled via ECC_DISABLED_MCPS: ${[...disabledServers].join(', ')}`);+ }let raw = fs.readFileSync(configPath, 'utf8');let parsed;@@ -249,6 +254,18 @@ function main() {const finalEntry = resolvedEntry || urlEntry;const resolvedLabel = hasCanonical ? name : legacyName || name;+ if (disabledServers.has(name)) {+ if (finalEntry) {+ toRemoveLog.push(`mcp_servers.${resolvedLabel} (disabled)`);+ raw = removeServerFromText(raw, resolvedLabel, existing);+ if (resolvedLabel !== name) {+ raw = removeServerFromText(raw, name, existing);+ }+ }+ log(` [skip] mcp_servers.${name} (disabled)`);+ continue;+ }+if (finalEntry) {if (updateMcp) {// --update-mcp: remove existing section (and legacy alias), will re-add below@@ -278,7 +295,9 @@ function main() {}}- if (toAppend.length === 0) {+ const hasRemovals = toRemoveLog.length > 0;++ if (toAppend.length === 0 && !hasRemovals) {log('All ECC MCP servers already present. Nothing to do.');return;}@@ -297,14 +316,19 @@ function main() {// Write: for add-only, append to preserve existing content byte-for-byte.// For --update-mcp, we modified `raw` above, so write the full file + appended sections.- if (updateMcp) {+ if (updateMcp || hasRemovals) {for (const label of toRemoveLog) log(` [update] ${label}`);const cleaned = raw.replace(/\n+$/, '\n');- fs.writeFileSync(configPath, cleaned + appendText, 'utf8');+ fs.writeFileSync(configPath, cleaned + (toAppend.length > 0 ? appendText : ''), 'utf8');} else {fs.appendFileSync(configPath, appendText, 'utf8');}+ if (hasRemovals && toAppend.length === 0) {+ log(`Done. Removed ${toRemoveLog.length} disabled server(s).`);+ return;+ }+log(`Done. ${toAppend.length} server(s) ${updateMcp ? 'updated' : 'added'}.`);}diff --git a/scripts/lib/install/apply.js b/scripts/lib/install/apply.jsindex 40f3b55bc..f4d662286 100644--- a/scripts/lib/install/apply.js+++ b/scripts/lib/install/apply.js@@ -4,6 +4,7 @@ const fs = require('fs');const path = require('path');const { writeInstallState } = require('../install-state');+const { filterMcpConfig, parseDisabledMcpServers } = require('../mcp-config');function readJsonObject(filePath, label) {let parsed;@@ -124,6 +125,49 @@ function findHooksSourcePath(plan, hooksDestinationPath) {return operation ? operation.sourcePath : null;}+function isMcpConfigPath(filePath) {+ const basename = path.basename(String(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 buildMergedSettings(plan) {if (!plan.adapter || plan.adapter.target !== 'claude') {return null;@@ -177,6 +221,7 @@ function buildMergedSettings(plan) {function applyInstallPlan(plan) {const mergedSettingsPlan = buildMergedSettings(plan);+ const filteredMcpWrites = buildFilteredMcpWrites(plan);for (const operation of plan.operations) {fs.mkdirSync(path.dirname(operation.destinationPath), { recursive: true });@@ -198,6 +243,15 @@ 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/scripts/lib/mcp-config.js b/scripts/lib/mcp-config.jsnew file mode 100644index 000000000..bce45de07--- /dev/null+++ b/scripts/lib/mcp-config.js@@ -0,0 +1,56 @@+'use strict';++function parseDisabledMcpServers(value) {+ return [...new Set(+ String(value || '')+ .split(',')+ .map((entry) => entry.trim())+ .filter(Boolean)+ )];+}++function filterMcpConfig(config, disabledServerNames = []) {+ if (!config || typeof config !== 'object' || Array.isArray(config)) {+ throw new Error('MCP config must be a JSON object');+ }++ const servers = config.mcpServers;+ if (!servers || typeof servers !== 'object' || Array.isArray(servers)) {+ throw new Error('MCP config must include an mcpServers object');+ }++ const disabled = new Set(parseDisabledMcpServers(disabledServerNames));+ if (disabled.size === 0) {+ return {+ config: {+ ...config,+ mcpServers: { ...servers },+ },+ removed: [],+ };+ }++ const nextServers = {};+ const removed = [];++ for (const [name, serverConfig] of Object.entries(servers)) {+ if (disabled.has(name)) {+ removed.push(name);+ continue;+ }+ nextServers[name] = serverConfig;+ }++ return {+ config: {+ ...config,+ mcpServers: nextServers,+ },+ removed,+ };+}++module.exports = {+ filterMcpConfig,+ parseDisabledMcpServers,+};diff --git a/tests/lib/mcp-config.test.js b/tests/lib/mcp-config.test.jsnew file mode 100644index 000000000..76eb7fe0f--- /dev/null+++ b/tests/lib/mcp-config.test.js@@ -0,0 +1,62 @@+'use strict';++const assert = require('assert');++const { filterMcpConfig, parseDisabledMcpServers } = require('../../scripts/lib/mcp-config');++function test(name, fn) {+ try {+ fn();+ console.log(` \u2713 ${name}`);+ return true;+ } catch (error) {+ console.log(` \u2717 ${name}`);+ console.log(` Error: ${error.message}`);+ return false;+ }+}++function runTests() {+ console.log('\n=== Testing mcp-config.js ===\n');++ let passed = 0;+ let failed = 0;++ if (test('parseDisabledMcpServers dedupes and trims values', () => {+ assert.deepStrictEqual(+ parseDisabledMcpServers(' github,exa ,github,,playwright '),+ ['github', 'exa', 'playwright']+ );+ })) passed++; else failed++;++ if (test('filterMcpConfig removes disabled servers and preserves others', () => {+ const result = filterMcpConfig({+ mcpServers: {+ github: { command: 'npx' },+ exa: { url: 'https://mcp.exa.ai/mcp' },+ memory: { command: 'npx' },+ },+ _comments: { usage: 'demo' },+ }, ['github', 'memory']);++ assert.deepStrictEqual(result.removed, ['github', 'memory']);+ assert.deepStrictEqual(Object.keys(result.config.mcpServers), ['exa']);+ assert.deepStrictEqual(result.config._comments, { usage: 'demo' });+ })) passed++; else failed++;++ if (test('filterMcpConfig leaves config unchanged when no disabled servers are provided', () => {+ const result = filterMcpConfig({+ mcpServers: {+ github: { command: 'npx' },+ },+ }, []);++ assert.deepStrictEqual(result.removed, []);+ assert.deepStrictEqual(Object.keys(result.config.mcpServers), ['github']);+ })) passed++; else failed++;++ console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);+ process.exit(failed > 0 ? 1 : 0);+}++runTests();diff --git a/tests/scripts/install-apply.test.js b/tests/scripts/install-apply.test.jsindex 234b22e2f..91b162ae8 100644--- a/tests/scripts/install-apply.test.js+++ b/tests/scripts/install-apply.test.js@@ -7,6 +7,7 @@ const fs = require('fs');const os = require('os');const path = require('path');const { execFileSync } = require('child_process');+const { applyInstallPlan } = require('../../scripts/lib/install/apply');const SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'install-apply.js');@@ -440,6 +441,80 @@ function runTests() {}})) passed++; else failed++;+ if (test('filters copied mcp config files when ECC_DISABLED_MCPS is set', () => {+ const tempDir = createTempDir('install-apply-mcp-');+ const sourcePath = path.join(tempDir, '.mcp.json');+ const destinationPath = path.join(tempDir, 'installed', '.mcp.json');+ const installStatePath = path.join(tempDir, 'installed', 'ecc-install-state.json');+ const previousValue = process.env.ECC_DISABLED_MCPS;++ try {+ fs.mkdirSync(path.dirname(sourcePath), { recursive: true });+ fs.writeFileSync(sourcePath, JSON.stringify({+ mcpServers: {+ github: { command: 'npx' },+ exa: { url: 'https://mcp.exa.ai/mcp' },+ memory: { command: 'npx' },+ },+ }, null, 2));++ process.env.ECC_DISABLED_MCPS = 'github,memory';++ applyInstallPlan({+ targetRoot: path.join(tempDir, 'installed'),+ installStatePath,+ statePreview: {+ schemaVersion: 'ecc.install.v1',+ installedAt: new Date().toISOString(),+ target: {+ id: 'test-install',+ kind: 'project',+ root: path.join(tempDir, 'installed'),+ installStatePath,+ },+ request: {+ profile: null,+ modules: ['test-mcp'],+ includeComponents: [],+ excludeComponents: [],+ legacyLanguages: [],+ legacyMode: false,+ },+ resolution: {+ selectedModules: ['test-mcp'],+ skippedModules: [],+ },+ source: {+ repoVersion: null,+ repoCommit: null,+ manifestVersion: 1,+ },+ operations: [],+ },+ operations: [{+ kind: 'copy-file',+ moduleId: 'test-mcp',+ sourcePath,+ sourceRelativePath: '.mcp.json',+ destinationPath,+ strategy: 'preserve-relative-path',+ ownership: 'managed',+ scaffoldOnly: false,+ }],+ });++ const installed = readJson(destinationPath);+ assert.deepStrictEqual(Object.keys(installed.mcpServers), ['exa']);+ } finally {+ if (previousValue === undefined) {+ delete process.env.ECC_DISABLED_MCPS;+ } else {+ process.env.ECC_DISABLED_MCPS = previousValue;+ }+ cleanup(tempDir);+ }+ })) passed++; else failed++;+if (test('reinstall does not duplicate managed hook entries', () => {const homeDir = createTempDir('install-apply-home-');const projectDir = createTempDir('install-apply-project-');