fix: preserve existing MCP config entries in init wizard

Avoid overwriting existing Cursor/OpenCode MCP entries by merging only the codebase-context server config, and remove the unused init import in index to clear Quality Checks.

Author: PatrickSys

src/cli-init.ts

@@ -19,6 +19,8 @@ export type McpConfigResult =
   | { kind: 'file'; path: string; content: string }
   | { kind: 'command'; args: string[] };
 
+type JsonObject = Record<string, unknown>;
+
 export function generateMcpConfig(client: Client): McpConfigResult {
   switch (client) {
     case 'claude-code':
@@ -121,6 +123,70 @@ export async function _appendInstructionBlock(filePath: string): Promise<'writte
   return 'written';
 }
 
+function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Merge generated MCP config into an existing JSON config file when possible.
+ * Preserves unrelated keys and only updates the codebase-context server entry.
+ */
+export async function _buildMergedMcpContent(
+  filePath: string,
+  generatedContent: string,
+  client: Extract<Client, 'cursor' | 'opencode'>
+): Promise<{ content: string; mergedFromExisting: boolean }> {
+  let existing: unknown;
+  try {
+    existing = JSON.parse(await fs.readFile(filePath, 'utf8'));
+  } catch {
+    return { content: generatedContent, mergedFromExisting: false };
+  }
+
+  const generated = JSON.parse(generatedContent) as unknown;
+  if (!isJsonObject(existing) || !isJsonObject(generated)) {
+    return { content: generatedContent, mergedFromExisting: false };
+  }
+
+  if (client === 'cursor') {
+    const existingServers = isJsonObject(existing.mcpServers) ? existing.mcpServers : {};
+    const generatedServers = isJsonObject(generated.mcpServers) ? generated.mcpServers : {};
+    return {
+      content: JSON.stringify(
+        {
+          ...existing,
+          ...generated,
+          mcpServers: {
+            ...existingServers,
+            ...generatedServers
+          }
+        },
+        null,
+        2
+      ),
+      mergedFromExisting: true
+    };
+  }
+
+  const existingMcp = isJsonObject(existing.mcp) ? existing.mcp : {};
+  const generatedMcp = isJsonObject(generated.mcp) ? generated.mcp : {};
+  return {
+    content: JSON.stringify(
+      {
+        ...existing,
+        ...generated,
+        mcp: {
+          ...existingMcp,
+          ...generatedMcp
+        }
+      },
+      null,
+      2
+    ),
+    mergedFromExisting: true
+  };
+}
+
 export async function handleInitCli(_argv: string[]): Promise<void> {
   console.log('\nSet up codebase-context for your AI client\n');
 
@@ -138,6 +204,12 @@ export async function handleInitCli(_argv: string[]): Promise<void> {
 
   console.log('\n--- MCP Config Preview ---');
   if (mcpResult.kind === 'file') {
+    try {
+      await fs.access(mcpResult.path);
+      console.log(`Warning: ${mcpResult.path} already exists; existing entries will be preserved.`);
+    } catch {
+      // file does not exist
+    }
     console.log(`File: ${mcpResult.path}\n${mcpResult.content}`);
   } else {
     console.log(`Command to run: ${mcpResult.args[0]} ${mcpResult.args.slice(1).join(' ')}`);
@@ -181,7 +253,14 @@ export async function handleInitCli(_argv: string[]): Promise<void> {
       if (dir && dir !== '.') {
         await fs.mkdir(dir, { recursive: true });
       }
-      await fs.writeFile(mcpResult.path, mcpResult.content, 'utf8');
+      const mergedConfig =
+        client === 'cursor' || client === 'opencode'
+          ? await _buildMergedMcpContent(mcpResult.path, mcpResult.content, client)
+          : { content: mcpResult.content, mergedFromExisting: false };
+      await fs.writeFile(mcpResult.path, mergedConfig.content, 'utf8');
+      if (mergedConfig.mergedFromExisting) {
+        console.log(`Merged: ${mcpResult.path} (existing entries preserved)`);
+      }
       console.log(`Written: ${mcpResult.path}`);
     } else {
       const [cmd, ...rest] = mcpResult.args;

src/index.ts

@@ -38,7 +38,6 @@ import { GenericAnalyzer } from './analyzers/generic/index.js';
 import { IndexCorruptedError } from './errors/index.js';
 import { appendMemoryFile } from './memory/store.js';
 import { handleCliCommand } from './cli.js';
-import { handleInitCli } from './cli-init.js';
 import { startFileWatcher } from './core/file-watcher.js';
 import { parseGitLogLineToMemory } from './memory/git-memory.js';
 import {

tests/cli-init.test.ts

@@ -18,7 +18,8 @@ import {
   generateMcpConfig,
   generateInstructionBlock,
   resolveInstructionFilePath,
-  _appendInstructionBlock
+  _appendInstructionBlock,
+  _buildMergedMcpContent
 } from '../src/cli-init.js';
 
 // --- generateMcpConfig ---
@@ -151,3 +152,75 @@ describe('_appendInstructionBlock', () => {
     expect(writeFileMock).not.toHaveBeenCalled();
   });
 });
+
+describe('_buildMergedMcpContent', () => {
+  const readFileMock = vi.mocked(fsMod.readFile);
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('preserves existing cursor mcpServers entries and adds codebase-context', async () => {
+    readFileMock.mockResolvedValue(
+      JSON.stringify({
+        mcpServers: {
+          'existing-server': { type: 'http', url: 'http://127.0.0.1:4000/mcp' }
+        },
+        someOtherKey: true
+      }) as unknown as Buffer
+    );
+
+    const generated = generateMcpConfig('cursor');
+    if (generated.kind !== 'file') throw new Error('expected file config');
+
+    const merged = await _buildMergedMcpContent('/test/.cursor/mcp.json', generated.content, 'cursor');
+    const parsed = JSON.parse(merged.content) as {
+      mcpServers: Record<string, { type: string; url: string }>;
+      someOtherKey: boolean;
+    };
+
+    expect(merged.mergedFromExisting).toBe(true);
+    expect(parsed.someOtherKey).toBe(true);
+    expect(parsed.mcpServers['existing-server']).toEqual({
+      type: 'http',
+      url: 'http://127.0.0.1:4000/mcp'
+    });
+    expect(parsed.mcpServers['codebase-context']).toEqual({
+      type: 'http',
+      url: 'http://127.0.0.1:3100/mcp'
+    });
+  });
+
+  it('preserves existing opencode mcp entries and updates codebase-context deterministically', async () => {
+    readFileMock.mockResolvedValue(
+      JSON.stringify({
+        $schema: 'https://opencode.ai/config.json',
+        mcp: {
+          'existing-server': { type: 'remote', url: 'http://127.0.0.1:5000/mcp' },
+          'codebase-context': { type: 'remote', url: 'http://old-host/mcp' }
+        },
+        extra: 'value'
+      }) as unknown as Buffer
+    );
+
+    const generated = generateMcpConfig('opencode');
+    if (generated.kind !== 'file') throw new Error('expected file config');
+
+    const merged = await _buildMergedMcpContent('/test/opencode.json', generated.content, 'opencode');
+    const parsed = JSON.parse(merged.content) as {
+      mcp: Record<string, { type: string; url: string }>;
+      extra: string;
+    };
+
+    expect(merged.mergedFromExisting).toBe(true);
+    expect(parsed.extra).toBe('value');
+    expect(parsed.mcp['existing-server']).toEqual({
+      type: 'remote',
+      url: 'http://127.0.0.1:5000/mcp'
+    });
+    expect(parsed.mcp['codebase-context']).toEqual({
+      type: 'remote',
+      url: 'http://127.0.0.1:3100/mcp'
+    });
+  });
+});