@cleocode/adapters 2026.4.0 → 2026.4.2

package/src/providers/cursor/install.ts

@@ -2,7 +2,6 @@
  * Cursor Install Provider
  *
  * Handles CLEO installation into Cursor environments:
- * - Registers CLEO MCP server in .cursor/mcp.json
  * - Ensures .cursorrules has CLEO @-references (legacy format)
  * - Creates .cursor/rules/cleo.mdc with CLEO references (modern format)
  *
@@ -22,54 +21,43 @@ import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cle
 /** Lines that should appear in instruction files to reference CLEO. */
 const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
 
-/** MCP server registration key used in Cursor config. */
-const MCP_SERVER_KEY = 'cleo';
-
 /**
  * Install provider for Cursor.
  *
  * Manages CLEO's integration with Cursor by:
- * 1. Registering the CLEO MCP server in .cursor/mcp.json
- * 2. Creating/updating .cursorrules with @-references (legacy)
- * 3. Creating .cursor/rules/cleo.mdc with @-references (modern)
+ * 1. Creating/updating .cursorrules with @-references (legacy)
+ * 2. Creating .cursor/rules/cleo.mdc with @-references (modern)
+ *
+ * @remarks
+ * Installation is idempotent and writes to both instruction file formats
+ * for maximum compatibility. The legacy `.cursorrules` file is only modified
+ * if it already exists (never created from scratch). The modern MDC file
+ * is always created or updated to ensure Cursor's rule engine picks it up.
  */
 export class CursorInstallProvider implements AdapterInstallProvider {
-  private installedProjectDir: string | null = null;
-
   /**
    * Install CLEO into a Cursor project.
    *
-   * @param options - Installation options including project directory and MCP server path
+   * @param options - Installation options including project directory
    * @returns Result describing what was installed
    */
   async install(options: InstallOptions): Promise<InstallResult> {
-    const { projectDir, mcpServerPath } = options;
+    const { projectDir } = options;
     const installedAt = new Date().toISOString();
     let instructionFileUpdated = false;
-    let mcpRegistered = false;
     const details: Record<string, unknown> = {};
 
-    // Step 1: Register MCP server in .cursor/mcp.json
-    if (mcpServerPath) {
-      mcpRegistered = this.registerMcpServer(projectDir, mcpServerPath);
-      if (mcpRegistered) {
-        details.mcpConfigPath = join(projectDir, '.cursor', 'mcp.json');
-      }
-    }
-
-    // Step 2: Ensure instruction files have @-references
+    // Step 1: Ensure instruction files have @-references
     instructionFileUpdated = this.updateInstructionFiles(projectDir);
     if (instructionFileUpdated) {
       details.instructionFiles = this.getUpdatedFileList(projectDir);
     }
 
-    this.installedProjectDir = projectDir;
-
     return {
       success: true,
       installedAt,
       instructionFileUpdated,
-      mcpRegistered,
+      mcpRegistered: false,
       details,
     };
   }
@@ -77,42 +65,26 @@ export class CursorInstallProvider implements AdapterInstallProvider {
   /**
    * Uninstall CLEO from the current Cursor project.
    *
-   * Removes the MCP server registration from .cursor/mcp.json.
    * Does not remove instruction file references (they are harmless if CLEO is not present).
    */
-  async uninstall(): Promise<void> {
-    if (!this.installedProjectDir) return;
-
-    const mcpPath = join(this.installedProjectDir, '.cursor', 'mcp.json');
-    if (existsSync(mcpPath)) {
-      try {
-        const raw = readFileSync(mcpPath, 'utf-8');
-        const config = JSON.parse(raw) as Record<string, unknown>;
-        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
-        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
-          delete mcpServers[MCP_SERVER_KEY];
-          writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-        }
-      } catch {
-        // Ignore errors during uninstall
-      }
-    }
-
-    this.installedProjectDir = null;
-  }
+  async uninstall(): Promise<void> {}
 
   /**
    * Check whether CLEO is installed in the current environment.
    *
-   * Checks for MCP server registered in .cursor/mcp.json.
+   * Checks for .cursor/rules/cleo.mdc or .cursorrules with CLEO references.
    */
   async isInstalled(): Promise<boolean> {
-    const mcpPath = join(process.cwd(), '.cursor', 'mcp.json');
-    if (existsSync(mcpPath)) {
+    const mdcPath = join(process.cwd(), '.cursor', 'rules', 'cleo.mdc');
+    if (existsSync(mdcPath)) {
+      return true;
+    }
+
+    const rulesPath = join(process.cwd(), '.cursorrules');
+    if (existsSync(rulesPath)) {
       try {
-        const config = JSON.parse(readFileSync(mcpPath, 'utf-8'));
-        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
-        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
+        const content = readFileSync(rulesPath, 'utf-8');
+        if (INSTRUCTION_REFERENCES.some((ref) => content.includes(ref))) {
           return true;
         }
       } catch {
@@ -134,43 +106,6 @@ export class CursorInstallProvider implements AdapterInstallProvider {
     this.updateInstructionFiles(projectDir);
   }
 
-  /**
-   * Register the CLEO MCP server in .cursor/mcp.json.
-   *
-   * Cursor stores MCP server configuration in .cursor/mcp.json
-   * under the mcpServers key.
-   *
-   * @returns true if registration was performed or updated
-   */
-  private registerMcpServer(projectDir: string, mcpServerPath: string): boolean {
-    const cursorDir = join(projectDir, '.cursor');
-    const mcpPath = join(cursorDir, 'mcp.json');
-    let config: Record<string, unknown> = {};
-
-    mkdirSync(cursorDir, { recursive: true });
-
-    if (existsSync(mcpPath)) {
-      try {
-        config = JSON.parse(readFileSync(mcpPath, 'utf-8'));
-      } catch {
-        // Start fresh on parse error
-      }
-    }
-
-    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
-      config.mcpServers = {};
-    }
-
-    const mcpServers = config.mcpServers as Record<string, unknown>;
-    mcpServers[MCP_SERVER_KEY] = {
-      command: 'node',
-      args: [mcpServerPath],
-    };
-
-    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-    return true;
-  }
-
   /**
    * Update instruction files with CLEO @-references.
    *

package/src/providers/cursor/manifest.json

@@ -10,7 +10,7 @@
     "supportedHookEvents": [],
     "supportsSpawn": false,
     "supportsInstall": true,
-    "supportsMcp": true,
+    "supportsMcp": false,
     "supportsInstructionFiles": true,
     "instructionFilePattern": ".cursor/rules/*.mdc",
     "supportsContextMonitor": false,

package/src/providers/gemini-cli/adapter.ts

@@ -28,16 +28,26 @@ const execAsync = promisify(exec);
  *
  * Bridges CLEO's adapter system with Gemini CLI's native capabilities:
  * - Hooks: Maps Gemini CLI events (SessionStart, PreToolUse, etc.) to CAAMP events
- * - Install: Registers MCP server in ~/.gemini/settings.json and ensures AGENTS.md references
+ * - Install: Ensures AGENTS.md references for CLEO instruction files
+ *
+ * @remarks
+ * Gemini CLI supports 10 canonical CAAMP events through its hook system,
+ * including PreModel and PostModel which most other providers lack. It has
+ * no spawn or transport capabilities. Integration is through AGENTS.md
+ * instruction files and the Gemini CLI's configuration at `~/.gemini/`.
  *
  * @task T161
  * @epic T134
  */
 export class GeminiCliAdapter implements CLEOProviderAdapter {
+  /** Unique provider identifier. */
   readonly id = 'gemini-cli';
+  /** Human-readable provider name. */
   readonly name = 'Gemini CLI';
+  /** Adapter version string. */
   readonly version = '1.0.0';
 
+  /** Declared capabilities for this provider. */
   capabilities: AdapterCapabilities = {
     supportsHooks: true,
     supportedHookEvents: [
@@ -54,7 +64,7 @@ export class GeminiCliAdapter implements CLEOProviderAdapter {
     ],
     supportsSpawn: false,
     supportsInstall: true,
-    supportsMcp: true,
+    supportsMcp: false,
     supportsInstructionFiles: false,
     supportsContextMonitor: false,
     supportsStatusline: false,
@@ -63,10 +73,14 @@ export class GeminiCliAdapter implements CLEOProviderAdapter {
     supportsTaskSync: false,
   };
 
+  /** Hook provider for CAAMP event mapping. */
   hooks: GeminiCliHookProvider;
+  /** Install provider for managing instruction files. */
   install: GeminiCliInstallProvider;
 
+  /** Project directory this adapter was initialized with, or null. */
   private projectDir: string | null = null;
+  /** Whether {@link initialize} has been called. */
   private initialized = false;
 
   constructor() {

package/src/providers/gemini-cli/hooks.ts

@@ -52,10 +52,17 @@ const GEMINI_CLI_EVENT_MAP: Record<string, string> = {
  * the install provider), registerNativeHooks and unregisterNativeHooks
  * track registration state without performing filesystem operations.
  *
+ * @remarks
+ * Gemini CLI uses its own event naming convention (e.g. BeforeAgent,
+ * AfterTool, PreCompress) which differs from both the PascalCase CAAMP
+ * canonical names and other providers' conventions. The static event map
+ * covers all 10 supported canonical events.
+ *
  * @task T161
  * @epic T134
  */
 export class GeminiCliHookProvider implements AdapterHookProvider {
+  /** Whether hooks have been registered for the current session. */
   private registered = false;
 
   /**

package/src/providers/gemini-cli/index.ts

@@ -1,5 +1,5 @@
 /**
- * Gemini CLI provider adapter.
+ * @packageDocumentation
  *
  * CLEO provider adapter for Google Gemini CLI.
  * Default export is the adapter class for dynamic loading by AdapterManager.
@@ -20,6 +20,21 @@ export default GeminiCliAdapter;
  * Factory function for creating adapter instances.
  * Used by AdapterManager's dynamic import fallback.
  *
+ * @remarks
+ * This is the primary entry point for dynamic adapter loading.
+ * AdapterManager calls this function when it resolves the gemini-cli
+ * provider via its import-based discovery mechanism.
+ *
+ * @returns A new {@link GeminiCliAdapter} instance ready for initialization
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@cleocode/adapters/providers/gemini-cli';
+ *
+ * const adapter = createAdapter();
+ * await adapter.initialize('/path/to/project');
+ * ```
+ *
  * @task T161
  */
 export function createAdapter(): GeminiCliAdapter {

package/src/providers/gemini-cli/install.ts

@@ -2,30 +2,29 @@
  * Gemini CLI Install Provider
  *
  * Handles CLEO installation into Gemini CLI environments:
- * - Registers CLEO MCP server in ~/.gemini/settings.json
  * - Ensures AGENTS.md has CLEO @-references
  *
  * @task T161
  * @epic T134
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { AdapterInstallProvider, InstallOptions, InstallResult } from '@cleocode/contracts';
 
 /** Lines that should appear in AGENTS.md to reference CLEO. */
 const INSTRUCTION_REFERENCES = ['@~/.cleo/templates/CLEO-INJECTION.md', '@.cleo/memory-bridge.md'];
 
-/** MCP server registration key used in Gemini CLI settings. */
-const MCP_SERVER_KEY = 'cleo';
-
 /**
  * Install provider for Gemini CLI.
  *
  * Manages CLEO's integration with Gemini CLI by:
- * 1. Registering the CLEO MCP server in ~/.gemini/settings.json
- * 2. Ensuring AGENTS.md contains @-references to CLEO instruction files
+ * 1. Ensuring AGENTS.md contains @-references to CLEO instruction files
+ *
+ * @remarks
+ * Installation is idempotent -- running install multiple times on the same
+ * project produces the same result. Only AGENTS.md is managed; Gemini CLI
+ * does not have an MCP or plugin registration mechanism.
  *
  * @task T161
  * @epic T134
@@ -34,26 +33,17 @@ export class GeminiCliInstallProvider implements AdapterInstallProvider {
   /**
    * Install CLEO into a Gemini CLI environment.
    *
-   * @param options - Installation options including project directory and MCP server path
+   * @param options - Installation options including project directory
    * @returns Result describing what was installed
    * @task T161
    */
   async install(options: InstallOptions): Promise<InstallResult> {
-    const { projectDir, mcpServerPath } = options;
+    const { projectDir } = options;
     const installedAt = new Date().toISOString();
     let instructionFileUpdated = false;
-    let mcpRegistered = false;
     const details: Record<string, unknown> = {};
 
-    // Step 1: Register MCP server in ~/.gemini/settings.json
-    if (mcpServerPath) {
-      mcpRegistered = this.registerMcpServer(mcpServerPath);
-      if (mcpRegistered) {
-        details.mcpConfigPath = join(homedir(), '.gemini', 'settings.json');
-      }
-    }
-
-    // Step 2: Ensure AGENTS.md has @-references
+    // Step 1: Ensure AGENTS.md has @-references
     instructionFileUpdated = this.updateInstructionFile(projectDir);
     if (instructionFileUpdated) {
       details.instructionFile = join(projectDir, 'AGENTS.md');
@@ -63,7 +53,7 @@ export class GeminiCliInstallProvider implements AdapterInstallProvider {
       success: true,
       installedAt,
       instructionFileUpdated,
-      mcpRegistered,
+      mcpRegistered: false,
       details,
     };
   }
@@ -71,41 +61,25 @@ export class GeminiCliInstallProvider implements AdapterInstallProvider {
   /**
    * Uninstall CLEO from the Gemini CLI environment.
    *
-   * Removes the MCP server registration from ~/.gemini/settings.json.
    * Does not remove AGENTS.md references (they are harmless if CLEO is not present).
    * @task T161
    */
   async uninstall(): Promise<void> {
-    const settingsPath = join(homedir(), '.gemini', 'settings.json');
-    if (existsSync(settingsPath)) {
-      try {
-        const raw = readFileSync(settingsPath, 'utf-8');
-        const config = JSON.parse(raw) as Record<string, unknown>;
-        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
-        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
-          delete mcpServers[MCP_SERVER_KEY];
-          writeFileSync(settingsPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-        }
-      } catch {
-        // Ignore errors during uninstall
-      }
-    }
+    // No-op: no MCP registration to remove
   }
 
   /**
    * Check whether CLEO is installed in the Gemini CLI environment.
    *
-   * Checks for MCP server registered in ~/.gemini/settings.json.
-   * Returns true if the CLEO MCP server entry is found.
+   * Checks for CLEO references in AGENTS.md.
    * @task T161
    */
   async isInstalled(): Promise<boolean> {
-    const settingsPath = join(homedir(), '.gemini', 'settings.json');
-    if (existsSync(settingsPath)) {
+    const agentsMdPath = join(process.cwd(), 'AGENTS.md');
+    if (existsSync(agentsMdPath)) {
       try {
-        const config = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        const mcpServers = config.mcpServers as Record<string, unknown> | undefined;
-        if (mcpServers && MCP_SERVER_KEY in mcpServers) {
+        const content = readFileSync(agentsMdPath, 'utf-8');
+        if (INSTRUCTION_REFERENCES.some((ref) => content.includes(ref))) {
           return true;
         }
       } catch {
@@ -128,44 +102,6 @@ export class GeminiCliInstallProvider implements AdapterInstallProvider {
     this.updateInstructionFile(projectDir);
   }
 
-  /**
-   * Register the CLEO MCP server in ~/.gemini/settings.json.
-   *
-   * Gemini CLI stores its MCP server configuration in ~/.gemini/settings.json
-   * under the mcpServers key.
-   *
-   * @param mcpServerPath - Absolute path to the MCP server entry point
-   * @returns true if registration was performed or updated
-   */
-  private registerMcpServer(mcpServerPath: string): boolean {
-    const geminiDir = join(homedir(), '.gemini');
-    const settingsPath = join(geminiDir, 'settings.json');
-    let config: Record<string, unknown> = {};
-
-    mkdirSync(geminiDir, { recursive: true });
-
-    if (existsSync(settingsPath)) {
-      try {
-        config = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-      } catch {
-        // Start fresh on parse error
-      }
-    }
-
-    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
-      config.mcpServers = {};
-    }
-
-    const mcpServers = config.mcpServers as Record<string, unknown>;
-    mcpServers[MCP_SERVER_KEY] = {
-      command: 'node',
-      args: [mcpServerPath],
-    };
-
-    writeFileSync(settingsPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-    return true;
-  }
-
   /**
    * Update AGENTS.md with CLEO @-references.
    *

package/src/providers/gemini-cli/manifest.json

@@ -21,7 +21,7 @@
     ],
     "supportsSpawn": false,
     "supportsInstall": true,
-    "supportsMcp": true,
+    "supportsMcp": false,
     "supportsInstructionFiles": false,
     "supportsContextMonitor": false,
     "supportsStatusline": false,

package/src/providers/kimi/adapter.ts

@@ -3,7 +3,7 @@
  *
  * Main CLEOProviderAdapter implementation for Moonshot AI Kimi.
  * Provides install-only capabilities for CLEO integration.
- * Kimi has no native hook system, so integration is via MCP only.
+ * Kimi has no native hook system; integration is via instruction files.
  *
  * @task T163
  * @epic T134
@@ -29,22 +29,31 @@ const execAsync = promisify(exec);
  *
  * Bridges CLEO's adapter system with Kimi's integration surface:
  * - Hooks: No-op (Kimi has no native hook system)
- * - Install: Registers MCP server in ~/.kimi/mcp.json and ensures AGENTS.md references
+ * - Install: Ensures AGENTS.md references for CLEO instruction files
+ *
+ * @remarks
+ * Kimi has no native hook or event system, so all hook-related capabilities
+ * are disabled. The adapter is install-only, managing AGENTS.md references
+ * for CLEO instruction injection.
  *
  * @task T163
  * @epic T134
  */
 export class KimiAdapter implements CLEOProviderAdapter {
+  /** Unique provider identifier. */
   readonly id = 'kimi';
+  /** Human-readable provider name. */
   readonly name = 'Kimi';
+  /** Adapter version string. */
   readonly version = '1.0.0';
 
+  /** Declared capabilities for this provider. */
   capabilities: AdapterCapabilities = {
     supportsHooks: false,
     supportedHookEvents: [],
     supportsSpawn: false,
     supportsInstall: true,
-    supportsMcp: true,
+    supportsMcp: false,
     supportsInstructionFiles: false,
     supportsContextMonitor: false,
     supportsStatusline: false,
@@ -53,10 +62,14 @@ export class KimiAdapter implements CLEOProviderAdapter {
     supportsTaskSync: false,
   };
 
+  /** Hook provider (no-op since Kimi has no event system). */
   hooks: KimiHookProvider;
+  /** Install provider for managing instruction files. */
   install: KimiInstallProvider;
 
+  /** Project directory this adapter was initialized with, or null. */
   private projectDir: string | null = null;
+  /** Whether {@link initialize} has been called. */
   private initialized = false;
 
   constructor() {

package/src/providers/kimi/hooks.ts

@@ -18,10 +18,16 @@ import type { AdapterHookProvider } from '@cleocode/contracts';
  * All hook-related methods are no-ops; mapProviderEvent always
  * returns null since there are no events to map.
  *
+ * @remarks
+ * Since Kimi has no hookable events, the event map is empty and
+ * `mapProviderEvent` always returns null. Registration state is tracked
+ * purely for interface compliance with {@link AdapterHookProvider}.
+ *
  * @task T163
  * @epic T134
  */
 export class KimiHookProvider implements AdapterHookProvider {
+  /** Whether hooks have been registered (always a no-op for Kimi). */
   private registered = false;
 
   /**

package/src/providers/kimi/index.ts

@@ -1,5 +1,5 @@
 /**
- * Kimi provider adapter.
+ * @packageDocumentation
  *
  * CLEO provider adapter for Moonshot AI Kimi.
  * Default export is the adapter class for dynamic loading by AdapterManager.
@@ -20,6 +20,21 @@ export default KimiAdapter;
  * Factory function for creating adapter instances.
  * Used by AdapterManager's dynamic import fallback.
  *
+ * @remarks
+ * This is the primary entry point for dynamic adapter loading.
+ * AdapterManager calls this function when it resolves the kimi
+ * provider via its import-based discovery mechanism.
+ *
+ * @returns A new {@link KimiAdapter} instance ready for initialization
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@cleocode/adapters/providers/kimi';
+ *
+ * const adapter = createAdapter();
+ * await adapter.initialize('/path/to/project');
+ * ```
+ *
  * @task T163
  */
 export function createAdapter(): KimiAdapter {