byterover-cli 1.1.0 → 1.2.0

package/dist/infra/cipher/tools/implementations/curate-tool.js

@@ -1,3 +1,4 @@
+import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { z } from 'zod';
 import { ToolName } from '../../../../core/domain/cipher/tools/constants.js';
@@ -48,19 +49,70 @@ const ContentSchema = z.object({
         .describe('Related topics using domain/topic/title.md or domain/topic/subtopic/title.md notation'),
     snippets: z.array(z.string()).optional().describe('Code/text snippets'),
 });
+/**
+ * Domain context schema for domain-level context.md files.
+ * Provides metadata about a domain's purpose, scope, ownership, and usage.
+ */
+const DomainContextSchema = z.object({
+    ownership: z
+        .string()
+        .optional()
+        .describe('Which system, team, or layer owns this domain (e.g., "Platform Security Team")'),
+    purpose: z
+        .string()
+        .describe('Describe what this domain represents and why it exists (e.g., "Contains all knowledge related to user and service authentication mechanisms")'),
+    scope: z.object({
+        excluded: z
+            .array(z.string())
+            .optional()
+            .describe('What does NOT belong in this domain (e.g., ["Authorization and permission models", "User profile management"])'),
+        included: z
+            .array(z.string())
+            .describe('What belongs in this domain (e.g., ["Login and signup flows", "Token-based authentication", "OAuth integrations"])'),
+    }).describe('Define what belongs and does not belong in this domain'),
+    usage: z
+        .string()
+        .optional()
+        .describe('How this domain should be used by agents and contributors'),
+});
+const TopicContextSchema = z.object({
+    keyConcepts: z
+        .array(z.string())
+        .optional()
+        .describe('Key concepts covered in this topic (e.g., ["JWT tokens", "Refresh token rotation", "Token blacklisting"])'),
+    overview: z
+        .string()
+        .describe('Describe what this topic covers and its main focus (e.g., "Covers all aspects of JWT-based authentication including token generation, validation, and refresh mechanisms")'),
+    relatedTopics: z
+        .array(z.string())
+        .optional()
+        .describe('Related topics and how they connect (e.g., ["authentication/session - for session-based alternatives", "security/encryption - for token signing"])'),
+});
+const SubtopicContextSchema = z.object({
+    focus: z
+        .string()
+        .describe('Describe the specific focus of this subtopic (e.g., "Focuses on refresh token rotation strategy and invalidation mechanisms")'),
+    parentRelation: z
+        .string()
+        .optional()
+        .describe('How this subtopic relates to its parent topic (e.g., "Handles the token refresh aspect of JWT authentication")'),
+});
 /**
  * Single operation schema for curating knowledge.
  */
 const OperationSchema = z.object({
     content: ContentSchema.optional().describe('Content for ADD/UPDATE operations'),
+    domainContext: DomainContextSchema.optional().describe('Domain-level context for new domains. When creating content in a NEW domain, provide this to auto-generate domain/context.md with purpose, scope, ownership, and usage. Only needed when the domain does not exist yet.'),
     mergeTarget: z.string().optional().describe('Target path for MERGE operation'),
     mergeTargetTitle: z.string().optional().describe('Title of the target file for MERGE operation'),
     path: z.string().describe('Path: domain/topic/title.md or domain/topic/subtopic/title.md'),
     reason: z.string().describe('Reasoning for this operation'),
+    subtopicContext: SubtopicContextSchema.optional().describe('Subtopic-level context for new subtopics. When creating content in a NEW subtopic, provide this to auto-generate subtopic/context.md with focus and parent relation. Only needed when the subtopic does not exist yet.'),
     title: z
         .string()
         .optional()
         .describe('Title for the context file (saved as {title}.md in snake_case). Required for ADD/UPDATE/MERGE, optional for DELETE'),
+    topicContext: TopicContextSchema.optional().describe('Topic-level context for new topics. When creating content in a NEW topic, provide this to auto-generate topic/context.md with overview, key concepts, and related topics. Only needed when the topic does not exist yet.'),
     type: OperationType.describe('Operation type: ADD, UPDATE, MERGE, or DELETE'),
 });
 /**
@@ -70,6 +122,170 @@ const CurateInputSchema = z.object({
     basePath: z.string().default('.brv/context-tree').describe('Base path for knowledge storage'),
     operations: z.array(OperationSchema).describe('Array of curate operations to apply'),
 });
+function generateDomainContextMarkdown(domainName, context) {
+    const sections = [
+        `# Domain: ${domainName}`,
+        '',
+        '## Purpose',
+        context.purpose,
+        '',
+        '## Scope',
+    ];
+    if (context.scope.included.length > 0) {
+        sections.push('Included in this domain:', ...context.scope.included.map((item) => `- ${item}`), '');
+    }
+    if (context.scope.excluded && context.scope.excluded.length > 0) {
+        sections.push('Excluded from this domain:', ...context.scope.excluded.map((item) => `- ${item}`), '');
+    }
+    if (context.ownership) {
+        sections.push('## Ownership', context.ownership, '');
+    }
+    if (context.usage) {
+        sections.push('## Usage', context.usage, '');
+    }
+    return sections.join('\n');
+}
+function generateMinimalDomainContextMarkdown(domainName) {
+    return `# Domain: ${domainName}
+
+## Purpose
+Describe what this domain represents and why it exists.
+
+## Scope
+Define what belongs in this domain and what does not.
+
+## Ownership
+Which system, team, or layer owns this domain.
+
+## Usage
+How this domain should be used by agents and contributors.
+`;
+}
+function generateMinimalTopicContextMarkdown(topicName) {
+    return `# Topic: ${topicName}
+
+## Overview
+Describe what this topic covers and its key concepts.
+
+## Related Topics
+List related topics and how they connect to this one.
+`;
+}
+function generateTopicContextMarkdown(topicName, context) {
+    const sections = [
+        `# Topic: ${topicName}`,
+        '',
+        '## Overview',
+        context.overview,
+        '',
+    ];
+    if (context.keyConcepts && context.keyConcepts.length > 0) {
+        sections.push('## Key Concepts', ...context.keyConcepts.map((concept) => `- ${concept}`), '');
+    }
+    if (context.relatedTopics && context.relatedTopics.length > 0) {
+        sections.push('## Related Topics', ...context.relatedTopics.map((topic) => `- ${topic}`), '');
+    }
+    return sections.join('\n');
+}
+function generateMinimalSubtopicContextMarkdown(subtopicName) {
+    return `# Subtopic: ${subtopicName}
+
+## Overview
+Describe what this subtopic covers and its specific focus.
+`;
+}
+function generateSubtopicContextMarkdown(subtopicName, context) {
+    const sections = [
+        `# Subtopic: ${subtopicName}`,
+        '',
+        '## Focus',
+        context.focus,
+        '',
+    ];
+    if (context.parentRelation) {
+        sections.push('## Parent Relation', context.parentRelation, '');
+    }
+    return sections.join('\n');
+}
+async function createDomainContextIfMissing(basePath, domain, domainContext) {
+    const normalizedDomain = toSnakeCase(domain);
+    const contextPath = join(basePath, normalizedDomain, 'context.md');
+    const exists = await DirectoryManager.fileExists(contextPath);
+    if (exists) {
+        return { created: false };
+    }
+    const content = domainContext
+        ? generateDomainContextMarkdown(normalizedDomain, domainContext)
+        : generateMinimalDomainContextMarkdown(normalizedDomain);
+    await DirectoryManager.writeFileAtomic(contextPath, content);
+    return { created: true, path: contextPath };
+}
+async function ensureTopicContextMd(basePath, domain, topic, topicContext) {
+    const normalizedDomain = toSnakeCase(domain);
+    const normalizedTopic = toSnakeCase(topic);
+    const topicPath = join(basePath, normalizedDomain, normalizedTopic);
+    const contextPath = join(topicPath, 'context.md');
+    // Check if topic folder exists first
+    const folderExists = await DirectoryManager.folderExists(topicPath);
+    if (!folderExists) {
+        return { created: false };
+    }
+    // Check if context.md already exists
+    const exists = await DirectoryManager.fileExists(contextPath);
+    if (exists) {
+        return { created: false };
+    }
+    const content = topicContext
+        ? generateTopicContextMarkdown(normalizedTopic, topicContext)
+        : generateMinimalTopicContextMarkdown(normalizedTopic);
+    await DirectoryManager.writeFileAtomic(contextPath, content);
+    return { created: true, path: contextPath };
+}
+/**
+ * Ensure context.md exists at subtopic level.
+ * Creates a context.md with LLM-provided content if available, otherwise creates a minimal template.
+ */
+async function ensureSubtopicContextMd(options) {
+    const { basePath, domain, subtopic, subtopicContext, topic } = options;
+    const normalizedDomain = toSnakeCase(domain);
+    const normalizedTopic = toSnakeCase(topic);
+    const normalizedSubtopic = toSnakeCase(subtopic);
+    const subtopicPath = join(basePath, normalizedDomain, normalizedTopic, normalizedSubtopic);
+    const contextPath = join(subtopicPath, 'context.md');
+    // Check if subtopic folder exists first
+    const folderExists = await DirectoryManager.folderExists(subtopicPath);
+    if (!folderExists) {
+        return { created: false };
+    }
+    // Check if context.md already exists
+    const exists = await DirectoryManager.fileExists(contextPath);
+    if (exists) {
+        return { created: false };
+    }
+    const content = subtopicContext
+        ? generateSubtopicContextMarkdown(normalizedSubtopic, subtopicContext)
+        : generateMinimalSubtopicContextMarkdown(normalizedSubtopic);
+    await DirectoryManager.writeFileAtomic(contextPath, content);
+    return { created: true, path: contextPath };
+}
+/**
+ * Ensure context.md exists at all levels for a given path (topic and subtopic).
+ * This is called during ADD operations to create context.md files with LLM-provided content.
+ */
+async function ensureContextMd(basePath, parsed, topicContext, subtopicContext) {
+    // Ensure topic-level context.md exists
+    await ensureTopicContextMd(basePath, parsed.domain, parsed.topic, topicContext);
+    // If subtopic exists, ensure subtopic-level context.md exists
+    if (parsed.subtopic) {
+        await ensureSubtopicContextMd({
+            basePath,
+            domain: parsed.domain,
+            subtopic: parsed.subtopic,
+            subtopicContext,
+            topic: parsed.topic,
+        });
+    }
+}
 /**
  * Parse a path into domain, topic, and optional subtopic.
  */
@@ -128,7 +344,7 @@ function buildFullPath(basePath, knowledgePath) {
  * Execute ADD operation - create new domain/topic/subtopic with {title}.md
  */
 async function executeAdd(basePath, operation) {
-    const { content, path, reason, title } = operation;
+    const { content, domainContext, path, reason, subtopicContext, title, topicContext } = operation;
     if (!title) {
         return {
             message: 'ADD operation requires a title',
@@ -155,7 +371,6 @@ async function executeAdd(basePath, operation) {
                 type: 'ADD',
             };
         }
-        // Validate domain before creating
         const domainValidation = validateDomain(parsed.domain);
         if (!domainValidation.allowed) {
             return {
@@ -165,12 +380,10 @@ async function executeAdd(basePath, operation) {
                 type: 'ADD',
             };
         }
-        // Build the final folder path (topic or subtopic)
+        await createDomainContextIfMissing(basePath, parsed.domain, domainContext);
         const domainPath = join(basePath, toSnakeCase(parsed.domain));
         const topicPath = join(domainPath, toSnakeCase(parsed.topic));
         const finalPath = parsed.subtopic ? join(topicPath, toSnakeCase(parsed.subtopic)) : topicPath;
-        // Generate and write {title}.md (snake_case filename)
-        // Note: writeFileAtomic creates parent directories as needed, avoiding empty folder creation
         const contextContent = MarkdownWriter.generateContext({
             name: title,
             narrative: content.narrative,
@@ -181,6 +394,7 @@ async function executeAdd(basePath, operation) {
         const filename = `${toSnakeCase(title)}.md`;
         const contextPath = join(finalPath, filename);
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
+        await ensureContextMd(basePath, parsed, topicContext, subtopicContext);
         return {
             filePath: contextPath,
             message: `Created ${path}/${filename} with ${content.snippets?.length || 0} snippets. Reason: ${reason}`,
@@ -202,7 +416,7 @@ async function executeAdd(basePath, operation) {
  * Execute UPDATE operation - modify existing {title}.md
  */
 async function executeUpdate(basePath, operation) {
-    const { content, path, reason, title } = operation;
+    const { content, domainContext, path, reason, subtopicContext, title, topicContext } = operation;
     if (!title) {
         return {
             message: 'UPDATE operation requires a title',
@@ -220,10 +434,18 @@ async function executeUpdate(basePath, operation) {
         };
     }
     try {
+        const parsed = parsePath(path);
+        if (!parsed) {
+            return {
+                message: `Invalid path format: ${path}. Expected domain/topic or domain/topic/subtopic`,
+                path,
+                status: 'failed',
+                type: 'UPDATE',
+            };
+        }
         const fullPath = buildFullPath(basePath, path);
         const filename = `${toSnakeCase(title)}.md`;
         const contextPath = join(fullPath, filename);
-        // Check if the specific titled file exists
         const exists = await DirectoryManager.fileExists(contextPath);
         if (!exists) {
             return {
@@ -233,7 +455,7 @@ async function executeUpdate(basePath, operation) {
                 type: 'UPDATE',
             };
         }
-        // Generate and write updated content (full replacement)
+        await createDomainContextIfMissing(basePath, parsed.domain, domainContext);
         const contextContent = MarkdownWriter.generateContext({
             name: title,
             narrative: content.narrative,
@@ -242,6 +464,7 @@ async function executeUpdate(basePath, operation) {
             snippets: content.snippets ?? [],
         });
         await DirectoryManager.writeFileAtomic(contextPath, contextContent);
+        await ensureContextMd(basePath, parsed, topicContext, subtopicContext);
         return {
             filePath: contextPath,
             message: `Updated ${path}/${filename}. Reason: ${reason}`,
@@ -263,7 +486,7 @@ async function executeUpdate(basePath, operation) {
  * Execute MERGE operation - combine source file into target file, delete source file
  */
 async function executeMerge(basePath, operation) {
-    const { mergeTarget, mergeTargetTitle, path, reason, title } = operation;
+    const { domainContext, mergeTarget, mergeTargetTitle, path, reason, subtopicContext, title, topicContext } = operation;
     if (!title) {
         return {
             message: 'MERGE operation requires a title (source file)',
@@ -289,13 +512,22 @@ async function executeMerge(basePath, operation) {
         };
     }
     try {
+        const sourceParsed = parsePath(path);
+        const targetParsed = parsePath(mergeTarget);
+        if (!sourceParsed || !targetParsed) {
+            return {
+                message: `Invalid path format. Expected domain/topic or domain/topic/subtopic`,
+                path,
+                status: 'failed',
+                type: 'MERGE',
+            };
+        }
         const sourceFolderPath = buildFullPath(basePath, path);
         const targetFolderPath = buildFullPath(basePath, mergeTarget);
         const sourceFilename = `${toSnakeCase(title)}.md`;
         const targetFilename = `${toSnakeCase(mergeTargetTitle)}.md`;
         const sourceContextPath = join(sourceFolderPath, sourceFilename);
         const targetContextPath = join(targetFolderPath, targetFilename);
-        // Check if both files exist
         const sourceExists = await DirectoryManager.fileExists(sourceContextPath);
         const targetExists = await DirectoryManager.fileExists(targetContextPath);
         if (!sourceExists) {
@@ -314,14 +546,15 @@ async function executeMerge(basePath, operation) {
                 type: 'MERGE',
             };
         }
-        // Read both files
+        await createDomainContextIfMissing(basePath, sourceParsed.domain, domainContext);
+        await createDomainContextIfMissing(basePath, targetParsed.domain, domainContext);
         const sourceContent = await DirectoryManager.readFile(sourceContextPath);
         const targetContent = await DirectoryManager.readFile(targetContextPath);
-        // Merge the contents using MarkdownWriter
         const mergedContent = MarkdownWriter.mergeContexts(sourceContent, targetContent);
         await DirectoryManager.writeFileAtomic(targetContextPath, mergedContent);
-        // Delete source file (not the entire folder, just the file)
         await DirectoryManager.deleteFile(sourceContextPath);
+        await ensureContextMd(basePath, sourceParsed, topicContext, subtopicContext);
+        await ensureContextMd(basePath, targetParsed, topicContext, subtopicContext);
         return {
             filePath: targetContextPath,
             message: `Merged ${path}/${sourceFilename} into ${mergeTarget}/${targetFilename}. Reason: ${reason}`,
@@ -420,6 +653,20 @@ async function executeCurate(input, _context) {
         };
     }
     const { basePath, operations } = parseResult.data;
+    const touchedDomains = new Set();
+    for (const op of operations) {
+        const parsed = parsePath(op.path);
+        if (parsed) {
+            touchedDomains.add(toSnakeCase(parsed.domain));
+        }
+        if (op.type === 'MERGE' && op.mergeTarget) {
+            const targetParsed = parsePath(op.mergeTarget);
+            if (targetParsed) {
+                touchedDomains.add(toSnakeCase(targetParsed.domain));
+            }
+        }
+    }
+    await backfillDomainContextFiles(basePath, touchedDomains);
     const applied = [];
     const summary = {
         added: 0,
@@ -428,7 +675,6 @@ async function executeCurate(input, _context) {
         merged: 0,
         updated: 0,
     };
-    // Process operations sequentially to maintain consistency
     /* eslint-disable no-await-in-loop -- Sequential processing required for dependent operations */
     for (const operation of operations) {
         let result;
@@ -476,14 +722,38 @@ async function executeCurate(input, _context) {
     /* eslint-enable no-await-in-loop */
     return { applied, summary };
 }
-/**
- * Creates the curate tool.
- *
- * This tool manages knowledge topics with atomic operations (ADD, UPDATE, MERGE, DELETE).
- * It applies patterns from the ACE Curator for intelligent knowledge curation.
- *
- * @returns Configured curate tool
- */
+export async function backfillDomainContextFiles(basePath, excludeDomains = new Set()) {
+    const createdPaths = [];
+    const baseExists = await DirectoryManager.folderExists(basePath);
+    if (!baseExists) {
+        return createdPaths;
+    }
+    let entries;
+    try {
+        entries = await readdir(basePath, { withFileTypes: true });
+    }
+    catch {
+        return createdPaths;
+    }
+    const domains = entries.filter((entry) => entry.isDirectory());
+    /* eslint-disable no-await-in-loop */
+    for (const domain of domains) {
+        if (excludeDomains.has(domain.name)) {
+            continue;
+        }
+        const contextPath = join(basePath, domain.name, 'context.md');
+        const exists = await DirectoryManager.fileExists(contextPath);
+        if (!exists) {
+            const mdFiles = await DirectoryManager.listMarkdownFiles(join(basePath, domain.name));
+            if (mdFiles.length > 0) {
+                const content = generateMinimalDomainContextMarkdown(domain.name);
+                await DirectoryManager.writeFileAtomic(contextPath, content);
+                createdPaths.push(contextPath);
+            }
+        }
+    }
+    return createdPaths;
+}
 export function createCurateTool() {
     return {
         description: `Curate knowledge topics with atomic operations. This tool manages the knowledge structure using four operation types and supports a two-part context model: Raw Concept + Narrative.
@@ -579,6 +849,74 @@ export function createCurateTool() {
 - Avoid overly specific names that only fit one topic
 - Keep domain count reasonable by consolidating related concepts
 
+**Automatic Domain Context (context.md):**
+- When any operation (ADD/UPDATE/MERGE) touches a domain for the first time, a context.md file is automatically created at the domain root
+- This context.md describes the domain's purpose, scope, ownership, and usage guidelines
+- **IMPORTANT**: When creating content in a NEW domain, provide the \`domainContext\` field with:
+  - \`purpose\` (required): What this domain represents and why it exists
+  - \`scope.included\` (required): Array of what belongs in this domain
+  - \`scope.excluded\` (optional): Array of what does NOT belong in this domain
+  - \`ownership\` (optional): Which team/system owns this domain
+  - \`usage\` (optional): How this domain should be used
+- Example with domainContext:
+  {
+    type: "ADD",
+    path: "authentication/jwt",
+    title: "Token Handling",
+    content: { ... },
+    domainContext: {
+      purpose: "Contains all knowledge related to user and service authentication mechanisms used across the platform.",
+      scope: {
+        included: ["Login and signup flows", "Token-based authentication (JWT, refresh tokens)", "OAuth integrations", "Session handling"],
+        excluded: ["Authorization and permission models", "User profile management"]
+      },
+      ownership: "Platform Security Team",
+      usage: "Use this domain for documenting authentication flows, token handling, and identity verification patterns."
+    },
+    reason: "Documenting JWT token handling"
+  }
+- If domainContext is not provided for a new domain, a minimal template is created that can be updated later
+
+**Topic Context (context.md at topic level):**
+- When creating content in a NEW topic, provide the \`topicContext\` field to auto-generate topic/context.md
+- **IMPORTANT**: When creating content in a NEW topic, provide the \`topicContext\` field with:
+  - \`overview\` (required): What this topic covers and its main focus
+  - \`keyConcepts\` (optional): Array of key concepts covered in this topic
+  - \`relatedTopics\` (optional): Array of related topics and how they connect
+- Example with topicContext:
+  {
+    type: "ADD",
+    path: "authentication/jwt",
+    title: "Token Handling",
+    content: { ... },
+    topicContext: {
+      overview: "Covers all aspects of JWT-based authentication including token generation, validation, and refresh mechanisms.",
+      keyConcepts: ["JWT tokens", "Refresh token rotation", "Token blacklisting", "Token validation middleware"],
+      relatedTopics: ["authentication/session - for session-based alternatives", "security/encryption - for token signing"]
+    },
+    reason: "Documenting JWT token handling"
+  }
+- If topicContext is not provided for a new topic, a minimal template is created that can be updated later
+
+**Subtopic Context (context.md at subtopic level):**
+- When creating content in a NEW subtopic, provide the \`subtopicContext\` field to auto-generate subtopic/context.md
+- **IMPORTANT**: When creating content in a NEW subtopic, provide the \`subtopicContext\` field with:
+  - \`focus\` (required): The specific focus of this subtopic
+  - \`parentRelation\` (optional): How this subtopic relates to its parent topic
+- Example with subtopicContext:
+  {
+    type: "ADD",
+    path: "authentication/jwt/refresh_tokens",
+    title: "Rotation Strategy",
+    content: { ... },
+    subtopicContext: {
+      focus: "Focuses on refresh token rotation strategy and invalidation mechanisms to prevent token reuse attacks.",
+      parentRelation: "Handles the token refresh aspect of JWT authentication, specifically how old tokens are invalidated when new ones are issued."
+    },
+    reason: "Documenting refresh token rotation"
+  }
+- If subtopicContext is not provided for a new subtopic, a minimal template is created that can be updated later
+
 **Backward Compatibility:** Existing context entries using only snippets and relations continue to work.
 
 **Output:** Returns applied operations with status (success/failed), filePath (for created/modified files), and a summary of counts.`,

package/dist/infra/connectors/connector-manager.js

@@ -1,6 +1,7 @@
 import { AGENT_CONNECTOR_CONFIG, AGENT_VALUES } from '../../core/domain/entities/agent.js';
 import { CONNECTOR_TYPES } from '../../core/domain/entities/connector-type.js';
 import { HookConnector } from './hook/hook-connector.js';
+import { McpConnector } from './mcp/mcp-connector.js';
 import { RulesConnector } from './rules/rules-connector.js';
 /**
  * Factory and orchestration layer for connectors.
@@ -13,6 +14,7 @@ export class ConnectorManager {
         // Create connector instances
         this.connectors = new Map([
             ['hook', new HookConnector({ fileService, projectRoot })],
+            ['mcp', new McpConnector({ fileService, projectRoot, templateService })],
             ['rules', new RulesConnector({ fileService, projectRoot, templateService })],
         ]);
     }

package/dist/infra/connectors/mcp/index.d.ts

@@ -0,0 +1,4 @@
+export * from './json-mcp-config-writer.js';
+export * from './mcp-connector-config.js';
+export * from './mcp-connector.js';
+export * from './toml-mcp-config-writer.js';

package/dist/infra/connectors/mcp/index.js

@@ -0,0 +1,4 @@
+export * from './json-mcp-config-writer.js';
+export * from './mcp-connector-config.js';
+export * from './mcp-connector.js';
+export * from './toml-mcp-config-writer.js';

package/dist/infra/connectors/mcp/json-mcp-config-writer.d.ts

@@ -0,0 +1,26 @@
+import type { IFileService } from '../../../core/interfaces/i-file-service.js';
+import type { IMcpConfigWriter, McpConfigExistsResult } from '../../../core/interfaces/i-mcp-config-writer.js';
+import type { McpServerConfig } from './mcp-connector-config.js';
+/**
+ * Options for constructing JsonMcpConfigWriter.
+ */
+export type JsonMcpConfigWriterOptions = {
+    fileService: IFileService;
+    /**
+     * JSON key path to the MCP server entry, including server name.
+     * e.g., ['mcpServers', 'brv'] navigates to { mcpServers: { brv: ... } }
+     */
+    serverKeyPath: readonly string[];
+};
+/**
+ * MCP config writer for JSON format files.
+ * Handles nested key path navigation for reading/writing MCP server config.
+ */
+export declare class JsonMcpConfigWriter implements IMcpConfigWriter {
+    private readonly fileService;
+    private readonly serverKeyPath;
+    constructor(options: JsonMcpConfigWriterOptions);
+    exists(filePath: string): Promise<McpConfigExistsResult>;
+    remove(filePath: string): Promise<boolean>;
+    write(filePath: string, serverConfig: McpServerConfig): Promise<void>;
+}

package/dist/infra/connectors/mcp/json-mcp-config-writer.js

@@ -0,0 +1,71 @@
+import { has, set, unset } from 'lodash-es';
+import { isRecord } from '../../../utils/type-guards.js';
+/**
+ * Parse JSON and validate it's a Record object.
+ * @throws Error if JSON is invalid or not an object
+ */
+function parseJsonAsRecord(content) {
+    const parsed = JSON.parse(content);
+    if (!isRecord(parsed)) {
+        throw new Error('Expected JSON object');
+    }
+    return parsed;
+}
+/**
+ * MCP config writer for JSON format files.
+ * Handles nested key path navigation for reading/writing MCP server config.
+ */
+export class JsonMcpConfigWriter {
+    fileService;
+    serverKeyPath;
+    constructor(options) {
+        this.fileService = options.fileService;
+        this.serverKeyPath = options.serverKeyPath;
+    }
+    async exists(filePath) {
+        const fileExists = await this.fileService.exists(filePath);
+        if (!fileExists) {
+            return { fileExists: false, serverExists: false };
+        }
+        try {
+            const content = await this.fileService.read(filePath);
+            const json = parseJsonAsRecord(content);
+            const serverExists = has(json, this.serverKeyPath);
+            return {
+                fileExists: true,
+                serverExists,
+            };
+        }
+        catch {
+            return { fileExists: true, serverExists: false };
+        }
+    }
+    async remove(filePath) {
+        const fileExists = await this.fileService.exists(filePath);
+        if (!fileExists) {
+            return false;
+        }
+        const content = await this.fileService.read(filePath);
+        const json = parseJsonAsRecord(content);
+        // Check if property exists before attempting to unset
+        if (!has(json, this.serverKeyPath)) {
+            return false;
+        }
+        unset(json, this.serverKeyPath);
+        await this.fileService.write(JSON.stringify(json, null, 2), filePath, 'overwrite');
+        return true;
+    }
+    async write(filePath, serverConfig) {
+        const fileExists = await this.fileService.exists(filePath);
+        let json;
+        if (fileExists) {
+            const content = await this.fileService.read(filePath);
+            json = parseJsonAsRecord(content);
+        }
+        else {
+            json = {};
+        }
+        set(json, this.serverKeyPath, { ...serverConfig });
+        await this.fileService.write(JSON.stringify(json, null, 2), filePath, 'overwrite');
+    }
+}