feat: persistent Gemini ACP provider + status spinner

Replace per-call gemini CLI spawning (~10s cold start each time) with
persistent ACP (Agent Client Protocol) subprocess. First call absorbs
the cold start, subsequent calls are near-instant over JSON-RPC stdio.

- Add AcpClient: manages persistent gemini --experimental-acp subprocess
  with lazy init, auto-restart on crash/timeout, NDJSON framing
- Add GeminiAcpProvider: LlmProvider wrapper with serial queue for
  concurrent calls, same interface as GeminiCliProvider
- Add dispose() to LlmProvider interface + disposeAll() to registry
- Wire provider disposal into mcplocal shutdown handler
- Add status command spinner with progressive output and color-coded
  LLM health check results (green checkmark/red cross)
- 25 new tests (17 ACP client + 8 provider)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/cli/src/commands/config-setup.ts

@@ -0,0 +1,347 @@
+import { Command } from 'commander';
+import http from 'node:http';
+import https from 'node:https';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { loadConfig, saveConfig } from '../config/index.js';
+import type { ConfigLoaderDeps, McpctlConfig, LlmConfig, LlmProviderName } from '../config/index.js';
+import type { SecretStore } from '@mcpctl/shared';
+import { createSecretStore } from '@mcpctl/shared';
+
+const execFileAsync = promisify(execFile);
+
+export interface ConfigSetupPrompt {
+  select<T>(message: string, choices: Array<{ name: string; value: T; description?: string }>): Promise<T>;
+  input(message: string, defaultValue?: string): Promise<string>;
+  password(message: string): Promise<string>;
+  confirm(message: string, defaultValue?: boolean): Promise<boolean>;
+}
+
+export interface ConfigSetupDeps {
+  configDeps: Partial<ConfigLoaderDeps>;
+  secretStore: SecretStore;
+  log: (...args: string[]) => void;
+  prompt: ConfigSetupPrompt;
+  fetchModels: (url: string, path: string) => Promise<string[]>;
+  whichBinary: (name: string) => Promise<string | null>;
+}
+
+interface ProviderChoice {
+  name: string;
+  value: LlmProviderName;
+  description: string;
+}
+
+const PROVIDER_CHOICES: ProviderChoice[] = [
+  { name: 'Gemini CLI', value: 'gemini-cli', description: 'Google Gemini via local CLI (free, no API key)' },
+  { name: 'Ollama', value: 'ollama', description: 'Local models via Ollama' },
+  { name: 'Anthropic (Claude)', value: 'anthropic', description: 'Claude API (requires API key)' },
+  { name: 'vLLM', value: 'vllm', description: 'Self-hosted vLLM (OpenAI-compatible)' },
+  { name: 'OpenAI', value: 'openai', description: 'OpenAI API (requires API key)' },
+  { name: 'DeepSeek', value: 'deepseek', description: 'DeepSeek API (requires API key)' },
+  { name: 'None (disable)', value: 'none', description: 'Disable LLM features' },
+];
+
+const GEMINI_MODELS = ['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.0-flash'];
+const ANTHROPIC_MODELS = ['claude-haiku-3-5-20241022', 'claude-sonnet-4-20250514', 'claude-opus-4-20250514'];
+const DEEPSEEK_MODELS = ['deepseek-chat', 'deepseek-reasoner'];
+
+function defaultFetchModels(baseUrl: string, path: string): Promise<string[]> {
+  return new Promise((resolve) => {
+    const url = new URL(path, baseUrl);
+    const isHttps = url.protocol === 'https:';
+    const transport = isHttps ? https : http;
+
+    const req = transport.get({
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname,
+      timeout: 5000,
+    }, (res) => {
+      const chunks: Buffer[] = [];
+      res.on('data', (chunk: Buffer) => chunks.push(chunk));
+      res.on('end', () => {
+        try {
+          const raw = Buffer.concat(chunks).toString('utf-8');
+          const data = JSON.parse(raw) as { models?: Array<{ name: string }>; data?: Array<{ id: string }> };
+          // Ollama format: { models: [{ name }] }
+          if (data.models) {
+            resolve(data.models.map((m) => m.name));
+            return;
+          }
+          // OpenAI/vLLM format: { data: [{ id }] }
+          if (data.data) {
+            resolve(data.data.map((m) => m.id));
+            return;
+          }
+          resolve([]);
+        } catch {
+          resolve([]);
+        }
+      });
+    });
+    req.on('error', () => resolve([]));
+    req.on('timeout', () => { req.destroy(); resolve([]); });
+  });
+}
+
+async function defaultSelect<T>(message: string, choices: Array<{ name: string; value: T; description?: string }>): Promise<T> {
+  const { default: inquirer } = await import('inquirer');
+  const { answer } = await inquirer.prompt([{
+    type: 'list',
+    name: 'answer',
+    message,
+    choices: choices.map((c) => ({
+      name: c.description ? `${c.name} — ${c.description}` : c.name,
+      value: c.value,
+      short: c.name,
+    })),
+  }]);
+  return answer as T;
+}
+
+async function defaultInput(message: string, defaultValue?: string): Promise<string> {
+  const { default: inquirer } = await import('inquirer');
+  const { answer } = await inquirer.prompt([{
+    type: 'input',
+    name: 'answer',
+    message,
+    default: defaultValue,
+  }]);
+  return answer as string;
+}
+
+async function defaultPassword(message: string): Promise<string> {
+  const { default: inquirer } = await import('inquirer');
+  const { answer } = await inquirer.prompt([{ type: 'password', name: 'answer', message }]);
+  return answer as string;
+}
+
+async function defaultConfirm(message: string, defaultValue?: boolean): Promise<boolean> {
+  const { default: inquirer } = await import('inquirer');
+  const { answer } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'answer',
+    message,
+    default: defaultValue ?? true,
+  }]);
+  return answer as boolean;
+}
+
+const defaultPrompt: ConfigSetupPrompt = {
+  select: defaultSelect,
+  input: defaultInput,
+  password: defaultPassword,
+  confirm: defaultConfirm,
+};
+
+async function defaultWhichBinary(name: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync('which', [name], { timeout: 3000 });
+    const path = stdout.trim();
+    return path || null;
+  } catch {
+    return null;
+  }
+}
+
+export function createConfigSetupCommand(deps?: Partial<ConfigSetupDeps>): Command {
+  return new Command('setup')
+    .description('Interactive LLM provider setup wizard')
+    .action(async () => {
+      const configDeps = deps?.configDeps ?? {};
+      const log = deps?.log ?? ((...args: string[]) => console.log(...args));
+      const prompt = deps?.prompt ?? defaultPrompt;
+      const fetchModels = deps?.fetchModels ?? defaultFetchModels;
+      const whichBinary = deps?.whichBinary ?? defaultWhichBinary;
+      const secretStore = deps?.secretStore ?? await createSecretStore();
+
+      const config = loadConfig(configDeps);
+      const currentLlm = config.llm;
+
+      // Annotate current provider in choices
+      const choices = PROVIDER_CHOICES.map((c) => {
+        if (currentLlm?.provider === c.value) {
+          return { ...c, name: `${c.name} (current)` };
+        }
+        return c;
+      });
+
+      const provider = await prompt.select<LlmProviderName>('Select LLM provider:', choices);
+
+      if (provider === 'none') {
+        const updated: McpctlConfig = { ...config, llm: { provider: 'none' } };
+        saveConfig(updated, configDeps);
+        log('LLM disabled. Restart mcplocal: systemctl --user restart mcplocal');
+        return;
+      }
+
+      let llmConfig: LlmConfig;
+
+      switch (provider) {
+        case 'gemini-cli':
+          llmConfig = await setupGeminiCli(prompt, log, whichBinary, currentLlm);
+          break;
+        case 'ollama':
+          llmConfig = await setupOllama(prompt, fetchModels, currentLlm);
+          break;
+        case 'anthropic':
+          llmConfig = await setupApiKeyProvider(prompt, secretStore, 'anthropic', 'anthropic-api-key', ANTHROPIC_MODELS, currentLlm);
+          break;
+        case 'vllm':
+          llmConfig = await setupVllm(prompt, fetchModels, currentLlm);
+          break;
+        case 'openai':
+          llmConfig = await setupApiKeyProvider(prompt, secretStore, 'openai', 'openai-api-key', [], currentLlm);
+          break;
+        case 'deepseek':
+          llmConfig = await setupApiKeyProvider(prompt, secretStore, 'deepseek', 'deepseek-api-key', DEEPSEEK_MODELS, currentLlm);
+          break;
+        default:
+          return;
+      }
+
+      const updated: McpctlConfig = { ...config, llm: llmConfig };
+      saveConfig(updated, configDeps);
+      log(`\nLLM configured: ${llmConfig.provider}${llmConfig.model ? ` / ${llmConfig.model}` : ''}`);
+      log('Restart mcplocal: systemctl --user restart mcplocal');
+    });
+}
+
+async function setupGeminiCli(
+  prompt: ConfigSetupPrompt,
+  log: (...args: string[]) => void,
+  whichBinary: (name: string) => Promise<string | null>,
+  current?: LlmConfig,
+): Promise<LlmConfig> {
+  const model = await prompt.select<string>('Select model:', [
+    ...GEMINI_MODELS.map((m) => ({
+      name: m === current?.model ? `${m} (current)` : m,
+      value: m,
+    })),
+    { name: 'Custom...', value: '__custom__' },
+  ]);
+
+  const finalModel = model === '__custom__'
+    ? await prompt.input('Model name:', current?.model)
+    : model;
+
+  // Auto-detect gemini binary path
+  let binaryPath: string | undefined;
+  const detected = await whichBinary('gemini');
+  if (detected) {
+    log(`Found gemini at: ${detected}`);
+    binaryPath = detected;
+  } else {
+    log('Warning: gemini binary not found in PATH');
+    const manualPath = await prompt.input('Binary path (or install with: npm i -g @google/gemini-cli):');
+    if (manualPath) binaryPath = manualPath;
+  }
+
+  return { provider: 'gemini-cli', model: finalModel, binaryPath };
+}
+
+async function setupOllama(prompt: ConfigSetupPrompt, fetchModels: ConfigSetupDeps['fetchModels'], current?: LlmConfig): Promise<LlmConfig> {
+  const url = await prompt.input('Ollama URL:', current?.url ?? 'http://localhost:11434');
+
+  // Try to fetch models from Ollama
+  const models = await fetchModels(url, '/api/tags');
+  let model: string;
+
+  if (models.length > 0) {
+    const choices = models.map((m) => ({
+      name: m === current?.model ? `${m} (current)` : m,
+      value: m,
+    }));
+    choices.push({ name: 'Custom...', value: '__custom__' });
+    model = await prompt.select<string>('Select model:', choices);
+    if (model === '__custom__') {
+      model = await prompt.input('Model name:', current?.model);
+    }
+  } else {
+    model = await prompt.input('Model name (could not fetch models):', current?.model ?? 'llama3.2');
+  }
+
+  return { provider: 'ollama', model, url };
+}
+
+async function setupVllm(prompt: ConfigSetupPrompt, fetchModels: ConfigSetupDeps['fetchModels'], current?: LlmConfig): Promise<LlmConfig> {
+  const url = await prompt.input('vLLM URL:', current?.url ?? 'http://localhost:8000');
+
+  // Try to fetch models from vLLM (OpenAI-compatible)
+  const models = await fetchModels(url, '/v1/models');
+  let model: string;
+
+  if (models.length > 0) {
+    const choices = models.map((m) => ({
+      name: m === current?.model ? `${m} (current)` : m,
+      value: m,
+    }));
+    choices.push({ name: 'Custom...', value: '__custom__' });
+    model = await prompt.select<string>('Select model:', choices);
+    if (model === '__custom__') {
+      model = await prompt.input('Model name:', current?.model);
+    }
+  } else {
+    model = await prompt.input('Model name (could not fetch models):', current?.model ?? 'default');
+  }
+
+  return { provider: 'vllm', model, url };
+}
+
+async function setupApiKeyProvider(
+  prompt: ConfigSetupPrompt,
+  secretStore: SecretStore,
+  provider: LlmProviderName,
+  secretKey: string,
+  hardcodedModels: string[],
+  current?: LlmConfig,
+): Promise<LlmConfig> {
+  // Check for existing API key
+  const existingKey = await secretStore.get(secretKey);
+  let apiKey: string;
+
+  if (existingKey) {
+    const masked = `****${existingKey.slice(-4)}`;
+    const changeKey = await prompt.confirm(`API key stored (${masked}). Change it?`, false);
+    if (changeKey) {
+      apiKey = await prompt.password('API key:');
+    } else {
+      apiKey = existingKey;
+    }
+  } else {
+    apiKey = await prompt.password('API key:');
+  }
+
+  // Store API key
+  if (apiKey !== existingKey) {
+    await secretStore.set(secretKey, apiKey);
+  }
+
+  // Model selection
+  let model: string;
+  if (hardcodedModels.length > 0) {
+    const choices = hardcodedModels.map((m) => ({
+      name: m === current?.model ? `${m} (current)` : m,
+      value: m,
+    }));
+    choices.push({ name: 'Custom...', value: '__custom__' });
+    model = await prompt.select<string>('Select model:', choices);
+    if (model === '__custom__') {
+      model = await prompt.input('Model name:', current?.model);
+    }
+  } else {
+    model = await prompt.input('Model name:', current?.model ?? 'gpt-4o');
+  }
+
+  // Optional custom URL for openai
+  let url: string | undefined;
+  if (provider === 'openai') {
+    const customUrl = await prompt.confirm('Use custom API endpoint?', false);
+    if (customUrl) {
+      url = await prompt.input('API URL:', current?.url ?? 'https://api.openai.com');
+    }
+  }
+
+  return { provider, model, url };
+}

src/cli/src/commands/config.ts

@@ -6,6 +6,7 @@ import { loadConfig, saveConfig, mergeConfig, getConfigPath, DEFAULT_CONFIG } fr
 import type { McpctlConfig, ConfigLoaderDeps } from '../config/index.js';
 import { formatJson, formatYaml } from '../formatters/index.js';
 import { saveCredentials, loadCredentials } from '../auth/index.js';
+import { createConfigSetupCommand } from './config-setup.js';
 import type { CredentialsDeps, StoredCredentials } from '../auth/index.js';
 import type { ApiClient } from '../api-client.js';
 
@@ -138,6 +139,8 @@ export function createConfigCommand(deps?: Partial<ConfigCommandDeps>, apiDeps?:
   registerClaudeCommand('claude', false);
   registerClaudeCommand('claude-generate', true); // backward compat
 
+  config.addCommand(createConfigSetupCommand({ configDeps }));
+
   if (apiDeps) {
     const { client, credentialsDeps, log: apiLog } = apiDeps;
 

src/cli/src/commands/status.ts

@@ -1,17 +1,31 @@
 import { Command } from 'commander';
 import http from 'node:http';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { loadConfig } from '../config/index.js';
-import type { ConfigLoaderDeps } from '../config/index.js';
+import type { ConfigLoaderDeps, LlmConfig } from '../config/index.js';
 import { loadCredentials } from '../auth/index.js';
 import type { CredentialsDeps } from '../auth/index.js';
 import { formatJson, formatYaml } from '../formatters/index.js';
 import { APP_VERSION } from '@mcpctl/shared';
 
+const execFileAsync = promisify(execFile);
+
+// ANSI helpers
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const CLEAR_LINE = '\x1b[2K\r';
+
 export interface StatusCommandDeps {
   configDeps: Partial<ConfigLoaderDeps>;
   credentialsDeps: Partial<CredentialsDeps>;
   log: (...args: string[]) => void;
+  write: (text: string) => void;
   checkHealth: (url: string) => Promise<boolean>;
+  checkLlm: (llm: LlmConfig) => Promise<string>;
+  isTTY: boolean;
 }
 
 function defaultCheckHealth(url: string): Promise<boolean> {
@@ -28,15 +42,51 @@ function defaultCheckHealth(url: string): Promise<boolean> {
   });
 }
 
+/**
+ * Quick LLM health check. Returns 'ok', 'binary not found', 'auth error', etc.
+ */
+async function defaultCheckLlm(llm: LlmConfig): Promise<string> {
+  if (llm.provider === 'gemini-cli') {
+    const bin = llm.binaryPath ?? 'gemini';
+    try {
+      const { stdout } = await execFileAsync(bin, ['-p', 'respond with exactly: ok', '-m', llm.model ?? 'gemini-2.5-flash', '-o', 'text'], { timeout: 15000 });
+      return stdout.trim().toLowerCase().includes('ok') ? 'ok' : 'unexpected response';
+    } catch (err) {
+      const msg = (err as Error).message;
+      if (msg.includes('ENOENT')) return 'binary not found';
+      if (msg.includes('auth') || msg.includes('token') || msg.includes('login') || msg.includes('401')) return 'not authenticated';
+      return `error: ${msg.slice(0, 80)}`;
+    }
+  }
+
+  if (llm.provider === 'ollama') {
+    const url = llm.url ?? 'http://localhost:11434';
+    try {
+      const ok = await defaultCheckHealth(url);
+      return ok ? 'ok' : 'unreachable';
+    } catch {
+      return 'unreachable';
+    }
+  }
+
+  // For API-key providers, we don't want to make a billable call on every status check
+  return 'ok (key stored)';
+}
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
 const defaultDeps: StatusCommandDeps = {
   configDeps: {},
   credentialsDeps: {},
   log: (...args) => console.log(...args),
+  write: (text) => process.stdout.write(text),
   checkHealth: defaultCheckHealth,
+  checkLlm: defaultCheckLlm,
+  isTTY: process.stdout.isTTY ?? false,
 };
 
 export function createStatusCommand(deps?: Partial<StatusCommandDeps>): Command {
-  const { configDeps, credentialsDeps, log, checkHealth } = { ...defaultDeps, ...deps };
+  const { configDeps, credentialsDeps, log, write, checkHealth, checkLlm, isTTY } = { ...defaultDeps, ...deps };
 
   return new Command('status')
     .description('Show mcpctl status and connectivity')
@@ -45,33 +95,85 @@ export function createStatusCommand(deps?: Partial<StatusCommandDeps>): Command
       const config = loadConfig(configDeps);
       const creds = loadCredentials(credentialsDeps);
 
+      const llmLabel = config.llm && config.llm.provider !== 'none'
+        ? `${config.llm.provider}${config.llm.model ? ` / ${config.llm.model}` : ''}`
+        : null;
+
+      if (opts.output !== 'table') {
+        // JSON/YAML: run everything in parallel, wait, output at once
+        const [mcplocalReachable, mcpdReachable, llmStatus] = await Promise.all([
+          checkHealth(config.mcplocalUrl),
+          checkHealth(config.mcpdUrl),
+          llmLabel ? checkLlm(config.llm!) : Promise.resolve(null),
+        ]);
+
+        const llm = llmLabel
+          ? llmStatus === 'ok' ? llmLabel : `${llmLabel} (${llmStatus})`
+          : null;
+
+        const status = {
+          version: APP_VERSION,
+          mcplocalUrl: config.mcplocalUrl,
+          mcplocalReachable,
+          mcpdUrl: config.mcpdUrl,
+          mcpdReachable,
+          auth: creds ? { user: creds.user } : null,
+          registries: config.registries,
+          outputFormat: config.outputFormat,
+          llm,
+          llmStatus,
+        };
+
+        log(opts.output === 'json' ? formatJson(status) : formatYaml(status));
+        return;
+      }
+
+      // Table format: print lines progressively, LLM last with spinner
+
+      // Fast health checks first
       const [mcplocalReachable, mcpdReachable] = await Promise.all([
         checkHealth(config.mcplocalUrl),
         checkHealth(config.mcpdUrl),
       ]);
 
-      const status = {
+      log(`mcpctl v${APP_VERSION}`);
-        version: APP_VERSION,
+      log(`mcplocal:   ${config.mcplocalUrl} (${mcplocalReachable ? 'connected' : 'unreachable'})`);
-        mcplocalUrl: config.mcplocalUrl,
+      log(`mcpd:       ${config.mcpdUrl} (${mcpdReachable ? 'connected' : 'unreachable'})`);
-        mcplocalReachable,
+      log(`Auth:       ${creds ? `logged in as ${creds.user}` : 'not logged in'}`);
-        mcpdUrl: config.mcpdUrl,
+      log(`Registries: ${config.registries.join(', ')}`);
-        mcpdReachable,
+      log(`Output:     ${config.outputFormat}`);
-        auth: creds ? { user: creds.user } : null,
-        registries: config.registries,
-        outputFormat: config.outputFormat,
-      };
 
-      if (opts.output === 'json') {
+      if (!llmLabel) {
-        log(formatJson(status));
+        log(`LLM:        not configured (run 'mcpctl config setup')`);
-      } else if (opts.output === 'yaml') {
+        return;
-        log(formatYaml(status));
+      }
+
+      // LLM check with spinner
+      const llmPromise = checkLlm(config.llm!);
+
+      if (isTTY) {
+        let frame = 0;
+        const interval = setInterval(() => {
+          write(`${CLEAR_LINE}LLM:        ${llmLabel} ${DIM}${SPINNER_FRAMES[frame % SPINNER_FRAMES.length]} checking...${RESET}`);
+          frame++;
+        }, 80);
+
+        const llmStatus = await llmPromise;
+        clearInterval(interval);
+
+        if (llmStatus === 'ok' || llmStatus === 'ok (key stored)') {
+          write(`${CLEAR_LINE}LLM:        ${llmLabel} ${GREEN}✓ ${llmStatus}${RESET}\n`);
+        } else {
+          write(`${CLEAR_LINE}LLM:        ${llmLabel} ${RED}✗ ${llmStatus}${RESET}\n`);
+        }
       } else {
-        log(`mcpctl v${status.version}`);
+        // Non-TTY: no spinner, just wait and print
-        log(`mcplocal:   ${status.mcplocalUrl} (${mcplocalReachable ? 'connected' : 'unreachable'})`);
+        const llmStatus = await llmPromise;
-        log(`mcpd:       ${status.mcpdUrl} (${mcpdReachable ? 'connected' : 'unreachable'})`);
+        if (llmStatus === 'ok' || llmStatus === 'ok (key stored)') {
-        log(`Auth:       ${creds ? `logged in as ${creds.user}` : 'not logged in'}`);
+          log(`LLM:        ${llmLabel} ✓ ${llmStatus}`);
-        log(`Registries: ${status.registries.join(', ')}`);
+        } else {
-        log(`Output:     ${status.outputFormat}`);
+          log(`LLM:        ${llmLabel} ✗ ${llmStatus}`);
+        }
       }
     });
 }

src/cli/src/config/index.ts

@@ -1,4 +1,4 @@
-export { McpctlConfigSchema, DEFAULT_CONFIG } from './schema.js';
+export { McpctlConfigSchema, LlmConfigSchema, LLM_PROVIDERS, DEFAULT_CONFIG } from './schema.js';
-export type { McpctlConfig } from './schema.js';
+export type { McpctlConfig, LlmConfig, LlmProviderName } from './schema.js';
 export { loadConfig, saveConfig, mergeConfig, getConfigPath } from './loader.js';
 export type { ConfigLoaderDeps } from './loader.js';

src/cli/src/config/schema.ts

@@ -1,5 +1,21 @@
 import { z } from 'zod';
 
+export const LLM_PROVIDERS = ['gemini-cli', 'ollama', 'anthropic', 'openai', 'deepseek', 'vllm', 'none'] as const;
+export type LlmProviderName = typeof LLM_PROVIDERS[number];
+
+export const LlmConfigSchema = z.object({
+  /** LLM provider name */
+  provider: z.enum(LLM_PROVIDERS),
+  /** Model name */
+  model: z.string().optional(),
+  /** Provider URL (for ollama, vllm, openai with custom endpoint) */
+  url: z.string().optional(),
+  /** Binary path override (for gemini-cli) */
+  binaryPath: z.string().optional(),
+}).strict();
+
+export type LlmConfig = z.infer<typeof LlmConfigSchema>;
+
 export const McpctlConfigSchema = z.object({
   /** mcplocal daemon endpoint (local LLM pre-processing proxy) */
   mcplocalUrl: z.string().default('http://localhost:3200'),
@@ -19,6 +35,8 @@ export const McpctlConfigSchema = z.object({
   outputFormat: z.enum(['table', 'json', 'yaml']).default('table'),
   /** Smithery API key */
   smitheryApiKey: z.string().optional(),
+  /** LLM provider configuration for smart features (pagination summaries, etc.) */
+  llm: LlmConfigSchema.optional(),
 }).transform((cfg) => {
   // Backward compatibility: if old daemonUrl is set but mcplocalUrl wasn't explicitly changed,
   // use daemonUrl as mcplocalUrl

src/cli/tests/commands/config-setup.test.ts

@@ -0,0 +1,293 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createConfigSetupCommand } from '../../src/commands/config-setup.js';
+import type { ConfigSetupDeps, ConfigSetupPrompt } from '../../src/commands/config-setup.js';
+import type { SecretStore } from '@mcpctl/shared';
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+let tempDir: string;
+let logs: string[];
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'mcpctl-config-setup-test-'));
+  logs = [];
+});
+
+function cleanup() {
+  rmSync(tempDir, { recursive: true, force: true });
+}
+
+function mockSecretStore(secrets: Record<string, string> = {}): SecretStore {
+  const store: Record<string, string> = { ...secrets };
+  return {
+    get: vi.fn(async (key: string) => store[key] ?? null),
+    set: vi.fn(async (key: string, value: string) => { store[key] = value; }),
+    delete: vi.fn(async () => true),
+    backend: () => 'mock',
+  };
+}
+
+function mockPrompt(answers: unknown[]): ConfigSetupPrompt {
+  let callIndex = 0;
+  return {
+    select: vi.fn(async () => answers[callIndex++]),
+    input: vi.fn(async () => answers[callIndex++] as string),
+    password: vi.fn(async () => answers[callIndex++] as string),
+    confirm: vi.fn(async () => answers[callIndex++] as boolean),
+  };
+}
+
+function buildDeps(overrides: {
+  secrets?: Record<string, string>;
+  answers?: unknown[];
+  fetchModels?: ConfigSetupDeps['fetchModels'];
+  whichBinary?: ConfigSetupDeps['whichBinary'];
+} = {}): ConfigSetupDeps {
+  return {
+    configDeps: { configDir: tempDir },
+    secretStore: mockSecretStore(overrides.secrets),
+    log: (...args: string[]) => logs.push(args.join(' ')),
+    prompt: mockPrompt(overrides.answers ?? []),
+    fetchModels: overrides.fetchModels ?? vi.fn(async () => []),
+    whichBinary: overrides.whichBinary ?? vi.fn(async () => '/usr/bin/gemini'),
+  };
+}
+
+function readConfig(): Record<string, unknown> {
+  const raw = readFileSync(join(tempDir, 'config.json'), 'utf-8');
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+async function runSetup(deps: ConfigSetupDeps): Promise<void> {
+  const cmd = createConfigSetupCommand(deps);
+  await cmd.parseAsync([], { from: 'user' });
+}
+
+describe('config setup wizard', () => {
+  describe('provider: none', () => {
+    it('disables LLM and saves config', async () => {
+      const deps = buildDeps({ answers: ['none'] });
+      await runSetup(deps);
+
+      const config = readConfig();
+      expect(config.llm).toEqual({ provider: 'none' });
+      expect(logs.some((l) => l.includes('LLM disabled'))).toBe(true);
+      cleanup();
+    });
+  });
+
+  describe('provider: gemini-cli', () => {
+    it('auto-detects binary path and saves config', async () => {
+      // Answers: select provider, select model (no binary prompt — auto-detected)
+      const deps = buildDeps({
+        answers: ['gemini-cli', 'gemini-2.5-flash'],
+        whichBinary: vi.fn(async () => '/home/user/.npm-global/bin/gemini'),
+      });
+      await runSetup(deps);
+
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.provider).toBe('gemini-cli');
+      expect(llm.model).toBe('gemini-2.5-flash');
+      expect(llm.binaryPath).toBe('/home/user/.npm-global/bin/gemini');
+      expect(logs.some((l) => l.includes('Found gemini at'))).toBe(true);
+      cleanup();
+    });
+
+    it('prompts for manual path when binary not found', async () => {
+      // Answers: select provider, select model, enter manual path
+      const deps = buildDeps({
+        answers: ['gemini-cli', 'gemini-2.5-flash', '/opt/gemini'],
+        whichBinary: vi.fn(async () => null),
+      });
+      await runSetup(deps);
+
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.binaryPath).toBe('/opt/gemini');
+      expect(logs.some((l) => l.includes('not found'))).toBe(true);
+      cleanup();
+    });
+
+    it('saves gemini-cli with custom model', async () => {
+      // Answers: select provider, select custom, enter model name
+      const deps = buildDeps({
+        answers: ['gemini-cli', '__custom__', 'gemini-3.0-flash'],
+        whichBinary: vi.fn(async () => '/usr/bin/gemini'),
+      });
+      await runSetup(deps);
+
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.model).toBe('gemini-3.0-flash');
+      cleanup();
+    });
+  });
+
+  describe('provider: ollama', () => {
+    it('fetches models and allows selection', async () => {
+      const fetchModels = vi.fn(async () => ['llama3.2', 'codellama', 'mistral']);
+      // Answers: select provider, enter URL, select model
+      const deps = buildDeps({
+        answers: ['ollama', 'http://localhost:11434', 'codellama'],
+        fetchModels,
+      });
+      await runSetup(deps);
+
+      expect(fetchModels).toHaveBeenCalledWith('http://localhost:11434', '/api/tags');
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.provider).toBe('ollama');
+      expect(llm.model).toBe('codellama');
+      expect(llm.url).toBe('http://localhost:11434');
+      cleanup();
+    });
+
+    it('falls back to manual input when fetch fails', async () => {
+      const fetchModels = vi.fn(async () => []);
+      // Answers: select provider, enter URL, enter model manually
+      const deps = buildDeps({
+        answers: ['ollama', 'http://localhost:11434', 'llama3.2'],
+        fetchModels,
+      });
+      await runSetup(deps);
+
+      const config = readConfig();
+      expect((config.llm as Record<string, unknown>).model).toBe('llama3.2');
+      cleanup();
+    });
+  });
+
+  describe('provider: anthropic', () => {
+    it('prompts for API key and saves to secret store', async () => {
+      // Answers: select provider, enter API key, select model
+      const deps = buildDeps({
+        answers: ['anthropic', 'sk-ant-new-key', 'claude-haiku-3-5-20241022'],
+      });
+      await runSetup(deps);
+
+      expect(deps.secretStore.set).toHaveBeenCalledWith('anthropic-api-key', 'sk-ant-new-key');
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.provider).toBe('anthropic');
+      expect(llm.model).toBe('claude-haiku-3-5-20241022');
+      // API key should NOT be in config file
+      expect(llm).not.toHaveProperty('apiKey');
+      cleanup();
+    });
+
+    it('shows existing key masked and allows keeping it', async () => {
+      // Answers: select provider, confirm change=false, select model
+      const deps = buildDeps({
+        secrets: { 'anthropic-api-key': 'sk-ant-existing-key-1234' },
+        answers: ['anthropic', false, 'claude-sonnet-4-20250514'],
+      });
+      await runSetup(deps);
+
+      // Should NOT have called set (kept existing key)
+      expect(deps.secretStore.set).not.toHaveBeenCalled();
+      const config = readConfig();
+      expect((config.llm as Record<string, unknown>).model).toBe('claude-sonnet-4-20250514');
+      cleanup();
+    });
+
+    it('allows replacing existing key', async () => {
+      // Answers: select provider, confirm change=true, enter new key, select model
+      const deps = buildDeps({
+        secrets: { 'anthropic-api-key': 'sk-ant-old' },
+        answers: ['anthropic', true, 'sk-ant-new', 'claude-haiku-3-5-20241022'],
+      });
+      await runSetup(deps);
+
+      expect(deps.secretStore.set).toHaveBeenCalledWith('anthropic-api-key', 'sk-ant-new');
+      cleanup();
+    });
+  });
+
+  describe('provider: vllm', () => {
+    it('fetches models from vLLM and allows selection', async () => {
+      const fetchModels = vi.fn(async () => ['my-model', 'llama-70b']);
+      // Answers: select provider, enter URL, select model
+      const deps = buildDeps({
+        answers: ['vllm', 'http://gpu:8000', 'llama-70b'],
+        fetchModels,
+      });
+      await runSetup(deps);
+
+      expect(fetchModels).toHaveBeenCalledWith('http://gpu:8000', '/v1/models');
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.provider).toBe('vllm');
+      expect(llm.url).toBe('http://gpu:8000');
+      expect(llm.model).toBe('llama-70b');
+      cleanup();
+    });
+  });
+
+  describe('provider: openai', () => {
+    it('prompts for key, model, and optional custom endpoint', async () => {
+      // Answers: select provider, enter key, enter model, confirm custom URL=true, enter URL
+      const deps = buildDeps({
+        answers: ['openai', 'sk-openai-key', 'gpt-4o', true, 'https://custom.api.com'],
+      });
+      await runSetup(deps);
+
+      expect(deps.secretStore.set).toHaveBeenCalledWith('openai-api-key', 'sk-openai-key');
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.provider).toBe('openai');
+      expect(llm.model).toBe('gpt-4o');
+      expect(llm.url).toBe('https://custom.api.com');
+      cleanup();
+    });
+
+    it('skips custom URL when not requested', async () => {
+      // Answers: select provider, enter key, enter model, confirm custom URL=false
+      const deps = buildDeps({
+        answers: ['openai', 'sk-openai-key', 'gpt-4o-mini', false],
+      });
+      await runSetup(deps);
+
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.url).toBeUndefined();
+      cleanup();
+    });
+  });
+
+  describe('provider: deepseek', () => {
+    it('prompts for key and model', async () => {
+      // Answers: select provider, enter key, select model
+      const deps = buildDeps({
+        answers: ['deepseek', 'sk-ds-key', 'deepseek-chat'],
+      });
+      await runSetup(deps);
+
+      expect(deps.secretStore.set).toHaveBeenCalledWith('deepseek-api-key', 'sk-ds-key');
+      const config = readConfig();
+      const llm = config.llm as Record<string, unknown>;
+      expect(llm.provider).toBe('deepseek');
+      expect(llm.model).toBe('deepseek-chat');
+      cleanup();
+    });
+  });
+
+  describe('output messages', () => {
+    it('shows restart instruction', async () => {
+      const deps = buildDeps({ answers: ['gemini-cli', 'gemini-2.5-flash'] });
+      await runSetup(deps);
+
+      expect(logs.some((l) => l.includes('systemctl --user restart mcplocal'))).toBe(true);
+      cleanup();
+    });
+
+    it('shows configured provider and model', async () => {
+      const deps = buildDeps({ answers: ['gemini-cli', 'gemini-2.5-flash'] });
+      await runSetup(deps);
+
+      expect(logs.some((l) => l.includes('gemini-cli') && l.includes('gemini-2.5-flash'))).toBe(true);
+      cleanup();
+    });
+  });
+});

src/cli/tests/commands/status.test.ts

@@ -3,19 +3,38 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { createStatusCommand } from '../../src/commands/status.js';
+import type { StatusCommandDeps } from '../../src/commands/status.js';
 import { saveConfig, DEFAULT_CONFIG } from '../../src/config/index.js';
 import { saveCredentials } from '../../src/auth/index.js';
 
 let tempDir: string;
 let output: string[];
+let written: string[];
 
 function log(...args: string[]) {
   output.push(args.join(' '));
 }
 
+function write(text: string) {
+  written.push(text);
+}
+
+function baseDeps(overrides?: Partial<StatusCommandDeps>): Partial<StatusCommandDeps> {
+  return {
+    configDeps: { configDir: tempDir },
+    credentialsDeps: { configDir: tempDir },
+    log,
+    write,
+    checkHealth: async () => true,
+    isTTY: false,
+    ...overrides,
+  };
+}
+
 beforeEach(() => {
   tempDir = mkdtempSync(join(tmpdir(), 'mcpctl-status-test-'));
   output = [];
+  written = [];
 });
 
 afterEach(() => {
@@ -24,12 +43,7 @@ afterEach(() => {
 
 describe('status command', () => {
   it('shows status in table format', async () => {
-    const cmd = createStatusCommand({
+    const cmd = createStatusCommand(baseDeps());
-      configDeps: { configDir: tempDir },
-      credentialsDeps: { configDir: tempDir },
-      log,
-      checkHealth: async () => true,
-    });
     await cmd.parseAsync([], { from: 'user' });
     const out = output.join('\n');
     expect(out).toContain('mcpctl v');
@@ -39,46 +53,26 @@ describe('status command', () => {
   });
 
   it('shows unreachable when daemons are down', async () => {
-    const cmd = createStatusCommand({
+    const cmd = createStatusCommand(baseDeps({ checkHealth: async () => false }));
-      configDeps: { configDir: tempDir },
-      credentialsDeps: { configDir: tempDir },
-      log,
-      checkHealth: async () => false,
-    });
     await cmd.parseAsync([], { from: 'user' });
     expect(output.join('\n')).toContain('unreachable');
   });
 
   it('shows not logged in when no credentials', async () => {
-    const cmd = createStatusCommand({
+    const cmd = createStatusCommand(baseDeps());
-      configDeps: { configDir: tempDir },
-      credentialsDeps: { configDir: tempDir },
-      log,
-      checkHealth: async () => true,
-    });
     await cmd.parseAsync([], { from: 'user' });
     expect(output.join('\n')).toContain('not logged in');
   });
 
   it('shows logged in user when credentials exist', async () => {
     saveCredentials({ token: 'tok', mcpdUrl: 'http://x:3100', user: 'alice@example.com' }, { configDir: tempDir });
-    const cmd = createStatusCommand({
+    const cmd = createStatusCommand(baseDeps());
-      configDeps: { configDir: tempDir },
-      credentialsDeps: { configDir: tempDir },
-      log,
-      checkHealth: async () => true,
-    });
     await cmd.parseAsync([], { from: 'user' });
     expect(output.join('\n')).toContain('logged in as alice@example.com');
   });
 
   it('shows status in JSON format', async () => {
-    const cmd = createStatusCommand({
+    const cmd = createStatusCommand(baseDeps());
-      configDeps: { configDir: tempDir },
-      credentialsDeps: { configDir: tempDir },
-      log,
-      checkHealth: async () => true,
-    });
     await cmd.parseAsync(['-o', 'json'], { from: 'user' });
     const parsed = JSON.parse(output[0]) as Record<string, unknown>;
     expect(parsed['version']).toBe('0.1.0');
@@ -87,12 +81,7 @@ describe('status command', () => {
   });
 
   it('shows status in YAML format', async () => {
-    const cmd = createStatusCommand({
+    const cmd = createStatusCommand(baseDeps({ checkHealth: async () => false }));
-      configDeps: { configDir: tempDir },
-      credentialsDeps: { configDir: tempDir },
-      log,
-      checkHealth: async () => false,
-    });
     await cmd.parseAsync(['-o', 'yaml'], { from: 'user' });
     expect(output[0]).toContain('mcplocalReachable: false');
   });
@@ -100,15 +89,12 @@ describe('status command', () => {
   it('checks correct URLs from config', async () => {
     saveConfig({ ...DEFAULT_CONFIG, mcplocalUrl: 'http://local:3200', mcpdUrl: 'http://remote:3100' }, { configDir: tempDir });
     const checkedUrls: string[] = [];
-    const cmd = createStatusCommand({
+    const cmd = createStatusCommand(baseDeps({
-      configDeps: { configDir: tempDir },
-      credentialsDeps: { configDir: tempDir },
-      log,
       checkHealth: async (url) => {
         checkedUrls.push(url);
         return false;
       },
-    });
+    }));
     await cmd.parseAsync([], { from: 'user' });
     expect(checkedUrls).toContain('http://local:3200');
     expect(checkedUrls).toContain('http://remote:3100');
@@ -116,14 +102,90 @@ describe('status command', () => {
 
   it('shows registries from config', async () => {
     saveConfig({ ...DEFAULT_CONFIG, registries: ['official'] }, { configDir: tempDir });
-    const cmd = createStatusCommand({
+    const cmd = createStatusCommand(baseDeps());
-      configDeps: { configDir: tempDir },
-      credentialsDeps: { configDir: tempDir },
-      log,
-      checkHealth: async () => true,
-    });
     await cmd.parseAsync([], { from: 'user' });
     expect(output.join('\n')).toContain('official');
     expect(output.join('\n')).not.toContain('glama');
   });
+
+  it('shows LLM not configured hint when no LLM is set', async () => {
+    const cmd = createStatusCommand(baseDeps());
+    await cmd.parseAsync([], { from: 'user' });
+    const out = output.join('\n');
+    expect(out).toContain('LLM:');
+    expect(out).toContain('not configured');
+    expect(out).toContain('mcpctl config setup');
+  });
+
+  it('shows green check when LLM is healthy (non-TTY)', async () => {
+    saveConfig({ ...DEFAULT_CONFIG, llm: { provider: 'anthropic', model: 'claude-haiku-3-5-20241022' } }, { configDir: tempDir });
+    const cmd = createStatusCommand(baseDeps({ checkLlm: async () => 'ok' }));
+    await cmd.parseAsync([], { from: 'user' });
+    const out = output.join('\n');
+    expect(out).toContain('anthropic / claude-haiku-3-5-20241022');
+    expect(out).toContain('✓ ok');
+  });
+
+  it('shows red cross when LLM check fails (non-TTY)', async () => {
+    saveConfig({ ...DEFAULT_CONFIG, llm: { provider: 'gemini-cli', model: 'gemini-2.5-flash' } }, { configDir: tempDir });
+    const cmd = createStatusCommand(baseDeps({ checkLlm: async () => 'not authenticated' }));
+    await cmd.parseAsync([], { from: 'user' });
+    const out = output.join('\n');
+    expect(out).toContain('✗ not authenticated');
+  });
+
+  it('shows binary not found error', async () => {
+    saveConfig({ ...DEFAULT_CONFIG, llm: { provider: 'gemini-cli', model: 'gemini-2.5-flash' } }, { configDir: tempDir });
+    const cmd = createStatusCommand(baseDeps({ checkLlm: async () => 'binary not found' }));
+    await cmd.parseAsync([], { from: 'user' });
+    expect(output.join('\n')).toContain('✗ binary not found');
+  });
+
+  it('uses spinner on TTY and writes final result', async () => {
+    saveConfig({ ...DEFAULT_CONFIG, llm: { provider: 'gemini-cli', model: 'gemini-2.5-flash' } }, { configDir: tempDir });
+    const cmd = createStatusCommand(baseDeps({
+      isTTY: true,
+      checkLlm: async () => 'ok',
+    }));
+    await cmd.parseAsync([], { from: 'user' });
+    // On TTY, the final LLM line goes through write(), not log()
+    const finalWrite = written[written.length - 1];
+    expect(finalWrite).toContain('gemini-cli / gemini-2.5-flash');
+    expect(finalWrite).toContain('✓ ok');
+  });
+
+  it('uses spinner on TTY and shows failure', async () => {
+    saveConfig({ ...DEFAULT_CONFIG, llm: { provider: 'gemini-cli', model: 'gemini-2.5-flash' } }, { configDir: tempDir });
+    const cmd = createStatusCommand(baseDeps({
+      isTTY: true,
+      checkLlm: async () => 'not authenticated',
+    }));
+    await cmd.parseAsync([], { from: 'user' });
+    const finalWrite = written[written.length - 1];
+    expect(finalWrite).toContain('✗ not authenticated');
+  });
+
+  it('shows not configured when LLM provider is none', async () => {
+    saveConfig({ ...DEFAULT_CONFIG, llm: { provider: 'none' } }, { configDir: tempDir });
+    const cmd = createStatusCommand(baseDeps());
+    await cmd.parseAsync([], { from: 'user' });
+    expect(output.join('\n')).toContain('not configured');
+  });
+
+  it('includes llm and llmStatus in JSON output', async () => {
+    saveConfig({ ...DEFAULT_CONFIG, llm: { provider: 'gemini-cli', model: 'gemini-2.5-flash' } }, { configDir: tempDir });
+    const cmd = createStatusCommand(baseDeps({ checkLlm: async () => 'ok' }));
+    await cmd.parseAsync(['-o', 'json'], { from: 'user' });
+    const parsed = JSON.parse(output[0]) as Record<string, unknown>;
+    expect(parsed['llm']).toBe('gemini-cli / gemini-2.5-flash');
+    expect(parsed['llmStatus']).toBe('ok');
+  });
+
+  it('includes null llm in JSON output when not configured', async () => {
+    const cmd = createStatusCommand(baseDeps());
+    await cmd.parseAsync(['-o', 'json'], { from: 'user' });
+    const parsed = JSON.parse(output[0]) as Record<string, unknown>;
+    expect(parsed['llm']).toBeNull();
+    expect(parsed['llmStatus']).toBeNull();
+  });
 });

src/mcplocal/src/http/config.ts

@@ -37,6 +37,30 @@ function loadUserToken(): string {
   }
 }
 
+export interface LlmFileConfig {
+  provider: string;
+  model?: string;
+  url?: string;
+  binaryPath?: string;
+}
+
+/**
+ * Load LLM configuration from ~/.mcpctl/config.json.
+ * Returns undefined if no LLM section is configured.
+ */
+export function loadLlmConfig(): LlmFileConfig | undefined {
+  try {
+    const configPath = join(homedir(), '.mcpctl', 'config.json');
+    if (!existsSync(configPath)) return undefined;
+    const raw = readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(raw) as { llm?: LlmFileConfig };
+    if (!parsed.llm?.provider || parsed.llm.provider === 'none') return undefined;
+    return parsed.llm;
+  } catch {
+    return undefined;
+  }
+}
+
 export function loadHttpConfig(env: Record<string, string | undefined> = process.env): HttpConfig {
   const portStr = env['MCPLOCAL_HTTP_PORT'];
   const port = portStr !== undefined ? parseInt(portStr, 10) : DEFAULT_HTTP_PORT;

src/mcplocal/src/http/project-mcp-endpoint.ts

@@ -15,6 +15,7 @@ import { McpRouter } from '../router.js';
 import { ResponsePaginator } from '../llm/pagination.js';
 import { refreshProjectUpstreams } from '../discovery.js';
 import type { McpdClient } from './mcpd-client.js';
+import type { ProviderRegistry } from '../providers/registry.js';
 import type { JsonRpcRequest } from '../types.js';
 
 interface ProjectCacheEntry {
@@ -29,7 +30,7 @@ interface SessionEntry {
 
 const CACHE_TTL_MS = 60_000; // 60 seconds
 
-export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: McpdClient): void {
+export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: McpdClient, providerRegistry?: ProviderRegistry | null): void {
   const projectCache = new Map<string, ProjectCacheEntry>();
   const sessions = new Map<string, SessionEntry>();
 
@@ -45,8 +46,8 @@ export function registerProjectMcpEndpoint(app: FastifyInstance, mcpdClient: Mcp
     const router = existing?.router ?? new McpRouter();
     await refreshProjectUpstreams(router, mcpdClient, projectName, authToken);
 
-    // Wire pagination support (no LLM provider for now — simple index fallback)
+    // Wire pagination support with LLM provider if configured
-    router.setPaginator(new ResponsePaginator(null));
+    router.setPaginator(new ResponsePaginator(providerRegistry ?? null));
 
     // Configure prompt resources with SA-scoped client for RBAC
     const saClient = mcpdClient.withHeaders({ 'X-Service-Account': `project:${projectName}` });

src/mcplocal/src/http/server.ts

@@ -10,11 +10,13 @@ import { registerProjectMcpEndpoint } from './project-mcp-endpoint.js';
 import type { McpRouter } from '../router.js';
 import type { HealthMonitor } from '../health.js';
 import type { TieredHealthMonitor } from '../health/tiered.js';
+import type { ProviderRegistry } from '../providers/registry.js';
 
 export interface HttpServerDeps {
   router: McpRouter;
   healthMonitor?: HealthMonitor | undefined;
   tieredHealthMonitor?: TieredHealthMonitor | undefined;
+  providerRegistry?: ProviderRegistry | null | undefined;
 }
 
 export async function createHttpServer(
@@ -87,7 +89,7 @@ export async function createHttpServer(
   registerMcpEndpoint(app, deps.router);
 
   // Project-scoped MCP endpoint at /projects/:projectName/mcp
-  registerProjectMcpEndpoint(app, mcpdClient);
+  registerProjectMcpEndpoint(app, mcpdClient, deps.providerRegistry);
 
   return app;
 }

src/mcplocal/src/llm-config.ts

@@ -0,0 +1,97 @@
+import type { SecretStore } from '@mcpctl/shared';
+import type { LlmFileConfig } from './http/config.js';
+import { ProviderRegistry } from './providers/registry.js';
+import { GeminiAcpProvider } from './providers/gemini-acp.js';
+import { OllamaProvider } from './providers/ollama.js';
+import { AnthropicProvider } from './providers/anthropic.js';
+import { OpenAiProvider } from './providers/openai.js';
+import { DeepSeekProvider } from './providers/deepseek.js';
+import type { GeminiAcpConfig } from './providers/gemini-acp.js';
+import type { OllamaConfig } from './providers/ollama.js';
+import type { AnthropicConfig } from './providers/anthropic.js';
+import type { OpenAiConfig } from './providers/openai.js';
+import type { DeepSeekConfig } from './providers/deepseek.js';
+
+/**
+ * Create a ProviderRegistry from user config + secret store.
+ * Returns an empty registry if config is undefined or provider is 'none'.
+ */
+export async function createProviderFromConfig(
+  config: LlmFileConfig | undefined,
+  secretStore: SecretStore,
+): Promise<ProviderRegistry> {
+  const registry = new ProviderRegistry();
+  if (!config?.provider || config.provider === 'none') return registry;
+
+  switch (config.provider) {
+    case 'gemini-cli': {
+      const cfg: GeminiAcpConfig = {};
+      if (config.binaryPath) cfg.binaryPath = config.binaryPath;
+      if (config.model) cfg.defaultModel = config.model;
+      registry.register(new GeminiAcpProvider(cfg));
+      break;
+    }
+
+    case 'ollama': {
+      const cfg: OllamaConfig = {};
+      if (config.url) cfg.baseUrl = config.url;
+      if (config.model) cfg.defaultModel = config.model;
+      registry.register(new OllamaProvider(cfg));
+      break;
+    }
+
+    case 'anthropic': {
+      const apiKey = await secretStore.get('anthropic-api-key');
+      if (!apiKey) {
+        process.stderr.write('Warning: Anthropic API key not found in secret store. Run "mcpctl config setup" to configure.\n');
+        return registry;
+      }
+      const cfg: AnthropicConfig = { apiKey };
+      if (config.model) cfg.defaultModel = config.model;
+      registry.register(new AnthropicProvider(cfg));
+      break;
+    }
+
+    case 'openai': {
+      const apiKey = await secretStore.get('openai-api-key');
+      if (!apiKey) {
+        process.stderr.write('Warning: OpenAI API key not found in secret store. Run "mcpctl config setup" to configure.\n');
+        return registry;
+      }
+      const cfg: OpenAiConfig = { apiKey };
+      if (config.url) cfg.baseUrl = config.url;
+      if (config.model) cfg.defaultModel = config.model;
+      registry.register(new OpenAiProvider(cfg));
+      break;
+    }
+
+    case 'deepseek': {
+      const apiKey = await secretStore.get('deepseek-api-key');
+      if (!apiKey) {
+        process.stderr.write('Warning: DeepSeek API key not found in secret store. Run "mcpctl config setup" to configure.\n');
+        return registry;
+      }
+      const cfg: DeepSeekConfig = { apiKey };
+      if (config.url) cfg.baseUrl = config.url;
+      if (config.model) cfg.defaultModel = config.model;
+      registry.register(new DeepSeekProvider(cfg));
+      break;
+    }
+
+    case 'vllm': {
+      // vLLM uses OpenAI-compatible API
+      if (!config.url) {
+        process.stderr.write('Warning: vLLM URL not configured. Run "mcpctl config setup" to configure.\n');
+        return registry;
+      }
+      registry.register(new OpenAiProvider({
+        apiKey: 'unused',
+        baseUrl: config.url,
+        defaultModel: config.model ?? 'default',
+      }));
+      break;
+    }
+  }
+
+  return registry;
+}

src/mcplocal/src/main.ts

@@ -7,8 +7,11 @@ import { StdioProxyServer } from './server.js';
 import { StdioUpstream } from './upstream/stdio.js';
 import { HttpUpstream } from './upstream/http.js';
 import { createHttpServer } from './http/server.js';
-import { loadHttpConfig } from './http/config.js';
+import { loadHttpConfig, loadLlmConfig } from './http/config.js';
 import type { HttpConfig } from './http/config.js';
+import { createProviderFromConfig } from './llm-config.js';
+import { createSecretStore } from '@mcpctl/shared';
+import type { ProviderRegistry } from './providers/registry.js';
 
 interface ParsedArgs {
   configPath: string | undefined;
@@ -55,12 +58,22 @@ export interface MainResult {
   server: StdioProxyServer;
   httpServer: FastifyInstance | undefined;
   httpConfig: HttpConfig;
+  providerRegistry: ProviderRegistry;
 }
 
 export async function main(argv: string[] = process.argv): Promise<MainResult> {
   const args = parseArgs(argv);
   const httpConfig = loadHttpConfig();
 
+  // Load LLM provider from user config + secret store
+  const llmConfig = loadLlmConfig();
+  const secretStore = await createSecretStore();
+  const providerRegistry = await createProviderFromConfig(llmConfig, secretStore);
+  const activeLlm = providerRegistry.getActive();
+  if (activeLlm) {
+    process.stderr.write(`LLM provider: ${activeLlm.name}\n`);
+  }
+
   let upstreamConfigs: UpstreamConfig[] = [];
 
   if (args.configPath) {
@@ -115,7 +128,7 @@ export async function main(argv: string[] = process.argv): Promise<MainResult> {
   // Start HTTP server unless disabled
   let httpServer: FastifyInstance | undefined;
   if (!args.noHttp) {
-    httpServer = await createHttpServer(httpConfig, { router });
+    httpServer = await createHttpServer(httpConfig, { router, providerRegistry });
     await httpServer.listen({ port: httpConfig.httpPort, host: httpConfig.httpHost });
     process.stderr.write(`mcpctl-proxy HTTP server listening on ${httpConfig.httpHost}:${httpConfig.httpPort}\n`);
   }
@@ -126,6 +139,7 @@ export async function main(argv: string[] = process.argv): Promise<MainResult> {
     if (shuttingDown) return;
     shuttingDown = true;
 
+    providerRegistry.disposeAll();
     server.stop();
     if (httpServer) {
       await httpServer.close();
@@ -137,7 +151,7 @@ export async function main(argv: string[] = process.argv): Promise<MainResult> {
   process.on('SIGTERM', () => void shutdown());
   process.on('SIGINT', () => void shutdown());
 
-  return { router, server, httpServer, httpConfig };
+  return { router, server, httpServer, httpConfig, providerRegistry };
 }
 
 // Run when executed directly

src/mcplocal/src/providers/acp-client.ts

@@ -0,0 +1,287 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
+
+export interface AcpClientConfig {
+  binaryPath: string;
+  model: string;
+  /** Timeout for individual RPC requests in ms (default: 60000) */
+  requestTimeoutMs: number;
+  /** Timeout for process initialization in ms (default: 30000) */
+  initTimeoutMs: number;
+  /** Override spawn for testing */
+  spawn?: typeof spawn;
+}
+
+interface PendingRequest {
+  resolve: (result: unknown) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Low-level ACP (Agent Client Protocol) client.
+ * Manages a persistent `gemini --experimental-acp` subprocess and communicates
+ * via JSON-RPC 2.0 over NDJSON stdio.
+ *
+ * Pattern follows StdioUpstream: readline for parsing, pending request map with timeouts.
+ */
+export class AcpClient {
+  private process: ChildProcess | null = null;
+  private readline: ReadlineInterface | null = null;
+  private pendingRequests = new Map<number, PendingRequest>();
+  private nextId = 1;
+  private sessionId: string | null = null;
+  private ready = false;
+  private initPromise: Promise<void> | null = null;
+  private readonly config: AcpClientConfig;
+
+  /** Accumulates text chunks from session/update agent_message_chunk during a prompt. */
+  private activePromptChunks: string[] = [];
+
+  constructor(config: AcpClientConfig) {
+    this.config = config;
+  }
+
+  /** Ensure the subprocess is spawned and initialized. Idempotent and lazy. */
+  async ensureReady(): Promise<void> {
+    if (this.ready && this.process && !this.process.killed) return;
+
+    // If already initializing, wait for it
+    if (this.initPromise) return this.initPromise;
+
+    this.initPromise = this.doInit();
+    try {
+      await this.initPromise;
+    } catch (err) {
+      this.initPromise = null;
+      throw err;
+    }
+  }
+
+  /** Send a prompt and collect the streamed text response. */
+  async prompt(text: string): Promise<string> {
+    await this.ensureReady();
+
+    // Set up chunk accumulator
+    this.activePromptChunks = [];
+
+    const result = await this.sendRequest('session/prompt', {
+      sessionId: this.sessionId,
+      prompt: [{ type: 'text', text }],
+    }, this.config.requestTimeoutMs) as { stopReason: string };
+
+    const collected = this.activePromptChunks.join('');
+    this.activePromptChunks = [];
+
+    if (result.stopReason === 'refusal') {
+      throw new Error('Gemini refused to process the prompt');
+    }
+
+    return collected;
+  }
+
+  /** Kill the subprocess and clean up. */
+  dispose(): void {
+    this.cleanup();
+  }
+
+  /** Check if the subprocess is alive and initialized. */
+  get isAlive(): boolean {
+    return this.ready && this.process !== null && !this.process.killed;
+  }
+
+  // --- Private ---
+
+  private async doInit(): Promise<void> {
+    // Clean up any previous state
+    this.cleanup();
+
+    this.spawnProcess();
+    this.setupReadline();
+
+    // ACP handshake: initialize
+    await this.sendRequest('initialize', {
+      protocolVersion: 1,
+      clientCapabilities: {},
+      clientInfo: { name: 'mcpctl', version: '1.0.0' },
+    }, this.config.initTimeoutMs);
+
+    // ACP handshake: session/new
+    const sessionResult = await this.sendRequest('session/new', {
+      cwd: '/tmp',
+      mcpServers: [],
+    }, this.config.initTimeoutMs) as { sessionId: string };
+
+    this.sessionId = sessionResult.sessionId;
+    this.ready = true;
+  }
+
+  private spawnProcess(): void {
+    const spawnFn = this.config.spawn ?? spawn;
+    this.process = spawnFn(this.config.binaryPath, ['--experimental-acp'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: process.env,
+    });
+
+    this.process.on('exit', () => {
+      this.ready = false;
+      this.initPromise = null;
+      this.sessionId = null;
+
+      // Reject all pending requests
+      for (const [id, pending] of this.pendingRequests) {
+        clearTimeout(pending.timer);
+        pending.reject(new Error('Gemini ACP process exited'));
+        this.pendingRequests.delete(id);
+      }
+    });
+
+    this.process.on('error', (err) => {
+      this.ready = false;
+      this.initPromise = null;
+
+      for (const [id, pending] of this.pendingRequests) {
+        clearTimeout(pending.timer);
+        pending.reject(err);
+        this.pendingRequests.delete(id);
+      }
+    });
+  }
+
+  private setupReadline(): void {
+    if (!this.process?.stdout) return;
+
+    this.readline = createInterface({ input: this.process.stdout });
+    this.readline.on('line', (line) => this.handleLine(line));
+  }
+
+  private handleLine(line: string): void {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      // Skip non-JSON lines (e.g., debug output on stdout)
+      return;
+    }
+
+    // Response to a pending request (has 'id')
+    if ('id' in msg && msg.id !== undefined && ('result' in msg || 'error' in msg)) {
+      this.handleResponse(msg as { id: number; result?: unknown; error?: { code: number; message: string } });
+      return;
+    }
+
+    // Notification (has 'method', no 'id')
+    if ('method' in msg && !('id' in msg)) {
+      this.handleNotification(msg as { method: string; params?: Record<string, unknown> });
+      return;
+    }
+
+    // Request from agent (has 'method' AND 'id') — agent asking us for something
+    if ('method' in msg && 'id' in msg) {
+      this.handleAgentRequest(msg as { id: number; method: string; params?: Record<string, unknown> });
+      return;
+    }
+  }
+
+  private handleResponse(msg: { id: number; result?: unknown; error?: { code: number; message: string } }): void {
+    const pending = this.pendingRequests.get(msg.id);
+    if (!pending) return;
+
+    clearTimeout(pending.timer);
+    this.pendingRequests.delete(msg.id);
+
+    if (msg.error) {
+      pending.reject(new Error(`ACP error ${msg.error.code}: ${msg.error.message}`));
+    } else {
+      pending.resolve(msg.result);
+    }
+  }
+
+  private handleNotification(msg: { method: string; params?: Record<string, unknown> }): void {
+    if (msg.method !== 'session/update' || !msg.params) return;
+
+    const update = msg.params.update as Record<string, unknown> | undefined;
+    if (!update) return;
+
+    // Collect text from agent_message_chunk
+    if (update.sessionUpdate === 'agent_message_chunk') {
+      const content = update.content as Array<{ type: string; text?: string }> | undefined;
+      if (content) {
+        for (const block of content) {
+          if (block.type === 'text' && block.text) {
+            this.activePromptChunks.push(block.text);
+          }
+        }
+      }
+    }
+  }
+
+  /** Handle requests from the agent (e.g., session/request_permission). Reject them all. */
+  private handleAgentRequest(msg: { id: number; method: string; params?: Record<string, unknown> }): void {
+    if (!this.process?.stdin) return;
+
+    if (msg.method === 'session/request_permission') {
+      // Reject permission requests — we don't want tool use
+      const response = JSON.stringify({
+        jsonrpc: '2.0',
+        id: msg.id,
+        result: { outcome: { outcome: 'cancelled' } },
+      });
+      this.process.stdin.write(response + '\n');
+    } else {
+      // Unknown method — return error
+      const response = JSON.stringify({
+        jsonrpc: '2.0',
+        id: msg.id,
+        error: { code: -32601, message: 'Method not supported' },
+      });
+      this.process.stdin.write(response + '\n');
+    }
+  }
+
+  private sendRequest(method: string, params: Record<string, unknown>, timeoutMs: number): Promise<unknown> {
+    if (!this.process?.stdin) {
+      return Promise.reject(new Error('ACP process not started'));
+    }
+
+    const id = this.nextId++;
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        // Kill the process on timeout — it's hung
+        this.cleanup();
+        reject(new Error(`ACP request '${method}' timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      this.pendingRequests.set(id, { resolve, reject, timer });
+
+      const msg = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+      this.process!.stdin!.write(msg + '\n');
+    });
+  }
+
+  private cleanup(): void {
+    this.ready = false;
+    this.initPromise = null;
+    this.sessionId = null;
+    this.activePromptChunks = [];
+
+    // Reject all pending requests
+    for (const [id, pending] of this.pendingRequests) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('ACP client disposed'));
+      this.pendingRequests.delete(id);
+    }
+
+    if (this.readline) {
+      this.readline.close();
+      this.readline = null;
+    }
+
+    if (this.process) {
+      this.process.kill('SIGTERM');
+      this.process = null;
+    }
+  }
+}

src/mcplocal/src/providers/gemini-acp.ts

@@ -0,0 +1,97 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { LlmProvider, CompletionOptions, CompletionResult } from './types.js';
+import { AcpClient } from './acp-client.js';
+import type { AcpClientConfig } from './acp-client.js';
+
+const execFileAsync = promisify(execFile);
+
+export interface GeminiAcpConfig {
+  binaryPath?: string;
+  defaultModel?: string;
+  requestTimeoutMs?: number;
+  initTimeoutMs?: number;
+  /** Override for testing — passed through to AcpClient */
+  spawn?: AcpClientConfig['spawn'];
+}
+
+/**
+ * Gemini CLI provider using ACP (Agent Client Protocol) mode.
+ * Keeps the gemini process alive as a persistent subprocess, eliminating
+ * the ~10s cold-start per call. Auto-restarts on crash or timeout.
+ */
+export class GeminiAcpProvider implements LlmProvider {
+  readonly name = 'gemini-cli';
+  private client: AcpClient;
+  private binaryPath: string;
+  private defaultModel: string;
+  private queue: Promise<void> = Promise.resolve();
+
+  constructor(config?: GeminiAcpConfig) {
+    this.binaryPath = config?.binaryPath ?? 'gemini';
+    this.defaultModel = config?.defaultModel ?? 'gemini-2.5-flash';
+
+    const acpConfig: AcpClientConfig = {
+      binaryPath: this.binaryPath,
+      model: this.defaultModel,
+      requestTimeoutMs: config?.requestTimeoutMs ?? 60_000,
+      initTimeoutMs: config?.initTimeoutMs ?? 30_000,
+    };
+    if (config?.spawn) acpConfig.spawn = config.spawn;
+
+    this.client = new AcpClient(acpConfig);
+  }
+
+  async complete(options: CompletionOptions): Promise<CompletionResult> {
+    return this.enqueue(() => this.doComplete(options));
+  }
+
+  async listModels(): Promise<string[]> {
+    return ['gemini-2.5-flash', 'gemini-2.5-pro', 'gemini-2.0-flash'];
+  }
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      await execFileAsync(this.binaryPath, ['--version'], { timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  dispose(): void {
+    this.client.dispose();
+  }
+
+  // --- Private ---
+
+  private async doComplete(options: CompletionOptions): Promise<CompletionResult> {
+    const prompt = options.messages
+      .map((m) => {
+        if (m.role === 'system') return `System: ${m.content}`;
+        if (m.role === 'user') return m.content;
+        if (m.role === 'assistant') return `Assistant: ${m.content}`;
+        return m.content;
+      })
+      .join('\n\n');
+
+    const content = await this.client.prompt(prompt);
+
+    return {
+      content: content.trim(),
+      toolCalls: [],
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      finishReason: 'stop',
+    };
+  }
+
+  private enqueue<T>(fn: () => Promise<T>): Promise<T> {
+    const result = new Promise<T>((resolve, reject) => {
+      this.queue = this.queue.then(
+        () => fn().then(resolve, reject),
+        () => fn().then(resolve, reject),
+      );
+    });
+    return result;
+  }
+}

src/mcplocal/src/providers/index.ts

@@ -9,4 +9,8 @@ export { GeminiCliProvider } from './gemini-cli.js';
 export type { GeminiCliConfig } from './gemini-cli.js';
 export { DeepSeekProvider } from './deepseek.js';
 export type { DeepSeekConfig } from './deepseek.js';
+export { GeminiAcpProvider } from './gemini-acp.js';
+export type { GeminiAcpConfig } from './gemini-acp.js';
+export { AcpClient } from './acp-client.js';
+export type { AcpClientConfig } from './acp-client.js';
 export { ProviderRegistry } from './registry.js';

src/mcplocal/src/providers/registry.ts

@@ -45,4 +45,11 @@ export class ProviderRegistry {
   getActiveName(): string | null {
     return this.activeProvider;
   }
+
+  /** Dispose all registered providers that have a dispose method. */
+  disposeAll(): void {
+    for (const provider of this.providers.values()) {
+      provider.dispose?.();
+    }
+  }
 }

src/mcplocal/src/providers/types.ts

@@ -53,4 +53,6 @@ export interface LlmProvider {
   listModels(): Promise<string[]>;
   /** Check if the provider is configured and reachable */
   isAvailable(): Promise<boolean>;
+  /** Optional cleanup for providers with persistent resources (e.g., subprocesses). */
+  dispose?(): void;
 }

src/mcplocal/tests/acp-client.test.ts

@@ -0,0 +1,415 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EventEmitter, Readable } from 'node:stream';
+import { AcpClient } from '../src/providers/acp-client.js';
+import type { AcpClientConfig } from '../src/providers/acp-client.js';
+
+/**
+ * Creates a mock child process that speaks ACP protocol.
+ * Returns the mock process and helpers to send responses.
+ */
+function createMockProcess() {
+  const stdin = {
+    write: vi.fn(),
+    writable: true,
+  };
+
+  const stdoutEmitter = new EventEmitter();
+  const stdout = Object.assign(stdoutEmitter, {
+    readable: true,
+    // readline needs these
+    [Symbol.asyncIterator]: undefined,
+    pause: vi.fn(),
+    resume: vi.fn(),
+    isPaused: () => false,
+    setEncoding: vi.fn(),
+    read: vi.fn(),
+    destroy: vi.fn(),
+    pipe: vi.fn(),
+    unpipe: vi.fn(),
+    unshift: vi.fn(),
+    wrap: vi.fn(),
+  }) as unknown as Readable;
+
+  const proc = Object.assign(new EventEmitter(), {
+    stdin,
+    stdout,
+    stderr: new EventEmitter(),
+    pid: 12345,
+    killed: false,
+    kill: vi.fn(function (this: { killed: boolean }) {
+      this.killed = true;
+    }),
+  });
+
+  /** Send a line of JSON from the "agent" to our client */
+  function sendLine(data: unknown) {
+    stdoutEmitter.emit('data', Buffer.from(JSON.stringify(data) + '\n'));
+  }
+
+  /** Send a JSON-RPC response */
+  function sendResponse(id: number, result: unknown) {
+    sendLine({ jsonrpc: '2.0', id, result });
+  }
+
+  /** Send a JSON-RPC error */
+  function sendError(id: number, code: number, message: string) {
+    sendLine({ jsonrpc: '2.0', id, error: { code, message } });
+  }
+
+  /** Send a session/update notification with agent_message_chunk */
+  function sendChunk(sessionId: string, text: string) {
+    sendLine({
+      jsonrpc: '2.0',
+      method: 'session/update',
+      params: {
+        sessionId,
+        update: {
+          sessionUpdate: 'agent_message_chunk',
+          content: [{ type: 'text', text }],
+        },
+      },
+    });
+  }
+
+  /** Send a session/request_permission request */
+  function sendPermissionRequest(id: number, sessionId: string) {
+    sendLine({
+      jsonrpc: '2.0',
+      id,
+      method: 'session/request_permission',
+      params: { sessionId },
+    });
+  }
+
+  return { proc, stdin, stdout: stdoutEmitter, sendLine, sendResponse, sendError, sendChunk, sendPermissionRequest };
+}
+
+function createConfig(overrides?: Partial<AcpClientConfig>): AcpClientConfig {
+  return {
+    binaryPath: '/usr/bin/gemini',
+    model: 'gemini-2.5-flash',
+    requestTimeoutMs: 5000,
+    initTimeoutMs: 5000,
+    ...overrides,
+  };
+}
+
+describe('AcpClient', () => {
+  let client: AcpClient;
+  let mock: ReturnType<typeof createMockProcess>;
+
+  beforeEach(() => {
+    mock = createMockProcess();
+  });
+
+  afterEach(() => {
+    client?.dispose();
+  });
+
+  function createClient(configOverrides?: Partial<AcpClientConfig>) {
+    const config = createConfig({
+      spawn: (() => mock.proc) as unknown as AcpClientConfig['spawn'],
+      ...configOverrides,
+    });
+    client = new AcpClient(config);
+    return client;
+  }
+
+  /** Helper: auto-respond to the initialize + session/new handshake */
+  function autoHandshake(sessionId = 'test-session') {
+    mock.stdin.write.mockImplementation((data: string) => {
+      const msg = JSON.parse(data.trim()) as { id: number; method: string };
+      if (msg.method === 'initialize') {
+        // Respond async to simulate real behavior
+        setImmediate(() => mock.sendResponse(msg.id, {
+          protocolVersion: 1,
+          agentInfo: { name: 'gemini-cli', version: '1.0.0' },
+        }));
+      } else if (msg.method === 'session/new') {
+        setImmediate(() => mock.sendResponse(msg.id, { sessionId }));
+      }
+    });
+  }
+
+  describe('ensureReady', () => {
+    it('spawns process and completes ACP handshake', async () => {
+      createClient();
+      autoHandshake();
+
+      await client.ensureReady();
+
+      expect(client.isAlive).toBe(true);
+      // Verify initialize was sent
+      const calls = mock.stdin.write.mock.calls.map((c) => JSON.parse(c[0] as string));
+      expect(calls[0].method).toBe('initialize');
+      expect(calls[0].params.protocolVersion).toBe(1);
+      expect(calls[0].params.clientInfo.name).toBe('mcpctl');
+      // Verify session/new was sent
+      expect(calls[1].method).toBe('session/new');
+      expect(calls[1].params.cwd).toBe('/tmp');
+      expect(calls[1].params.mcpServers).toEqual([]);
+    });
+
+    it('is idempotent when already ready', async () => {
+      createClient();
+      autoHandshake();
+
+      await client.ensureReady();
+      await client.ensureReady();
+
+      // Should only have sent initialize + session/new once
+      const calls = mock.stdin.write.mock.calls;
+      expect(calls.length).toBe(2);
+    });
+
+    it('shares init promise for concurrent calls', async () => {
+      createClient();
+      autoHandshake();
+
+      const p1 = client.ensureReady();
+      const p2 = client.ensureReady();
+
+      await Promise.all([p1, p2]);
+      expect(mock.stdin.write.mock.calls.length).toBe(2);
+    });
+  });
+
+  describe('prompt', () => {
+    it('sends session/prompt and collects agent_message_chunk text', async () => {
+      createClient();
+      const sessionId = 'sess-123';
+      autoHandshake(sessionId);
+
+      await client.ensureReady();
+
+      // Now set up the prompt response handler
+      mock.stdin.write.mockImplementation((data: string) => {
+        const msg = JSON.parse(data.trim()) as { id: number; method: string };
+        if (msg.method === 'session/prompt') {
+          setImmediate(() => {
+            mock.sendChunk(sessionId, 'Hello ');
+            mock.sendChunk(sessionId, 'world!');
+            mock.sendResponse(msg.id, { stopReason: 'end_turn' });
+          });
+        }
+      });
+
+      const result = await client.prompt('Say hello');
+      expect(result).toBe('Hello world!');
+    });
+
+    it('handles multi-block content in a single chunk', async () => {
+      createClient();
+      autoHandshake('sess-1');
+      await client.ensureReady();
+
+      mock.stdin.write.mockImplementation((data: string) => {
+        const msg = JSON.parse(data.trim()) as { id: number; method: string };
+        if (msg.method === 'session/prompt') {
+          setImmediate(() => {
+            mock.sendLine({
+              jsonrpc: '2.0',
+              method: 'session/update',
+              params: {
+                sessionId: 'sess-1',
+                update: {
+                  sessionUpdate: 'agent_message_chunk',
+                  content: [
+                    { type: 'text', text: 'Part A' },
+                    { type: 'text', text: ' Part B' },
+                  ],
+                },
+              },
+            });
+            mock.sendResponse(msg.id, { stopReason: 'end_turn' });
+          });
+        }
+      });
+
+      const result = await client.prompt('test');
+      expect(result).toBe('Part A Part B');
+    });
+
+    it('calls ensureReady automatically (lazy init)', async () => {
+      createClient();
+      autoHandshake('sess-auto');
+
+      // After handshake, handle prompts
+      const originalWrite = mock.stdin.write;
+      let handshakeDone = false;
+      mock.stdin.write.mockImplementation((data: string) => {
+        const msg = JSON.parse(data.trim()) as { id: number; method: string };
+        if (msg.method === 'initialize') {
+          setImmediate(() => mock.sendResponse(msg.id, { protocolVersion: 1 }));
+        } else if (msg.method === 'session/new') {
+          setImmediate(() => {
+            mock.sendResponse(msg.id, { sessionId: 'sess-auto' });
+            handshakeDone = true;
+          });
+        } else if (msg.method === 'session/prompt') {
+          setImmediate(() => {
+            mock.sendChunk('sess-auto', 'ok');
+            mock.sendResponse(msg.id, { stopReason: 'end_turn' });
+          });
+        }
+      });
+
+      // Call prompt directly without ensureReady
+      const result = await client.prompt('test');
+      expect(result).toBe('ok');
+    });
+  });
+
+  describe('auto-restart', () => {
+    it('restarts after process exit', async () => {
+      createClient();
+      autoHandshake('sess-1');
+      await client.ensureReady();
+      expect(client.isAlive).toBe(true);
+
+      // Simulate process exit
+      mock.proc.killed = true;
+      mock.proc.emit('exit', 1);
+      expect(client.isAlive).toBe(false);
+
+      // Create a new mock for the respawned process
+      mock = createMockProcess();
+      // Update the spawn function to return new mock
+      (client as unknown as { config: { spawn: unknown } }).config.spawn = () => mock.proc;
+      autoHandshake('sess-2');
+
+      await client.ensureReady();
+      expect(client.isAlive).toBe(true);
+    });
+  });
+
+  describe('timeout', () => {
+    it('kills process and rejects on request timeout', async () => {
+      createClient({ requestTimeoutMs: 50 });
+      autoHandshake('sess-1');
+      await client.ensureReady();
+
+      // Don't respond to the prompt — let it timeout
+      mock.stdin.write.mockImplementation(() => {});
+
+      await expect(client.prompt('test')).rejects.toThrow('timed out');
+      expect(client.isAlive).toBe(false);
+    });
+
+    it('rejects on init timeout', async () => {
+      createClient({ initTimeoutMs: 50 });
+      // Don't respond to initialize
+      mock.stdin.write.mockImplementation(() => {});
+
+      await expect(client.ensureReady()).rejects.toThrow('timed out');
+    });
+  });
+
+  describe('error handling', () => {
+    it('rejects on ACP error response', async () => {
+      createClient();
+      mock.stdin.write.mockImplementation((data: string) => {
+        const msg = JSON.parse(data.trim()) as { id: number; method: string };
+        setImmediate(() => mock.sendError(msg.id, -32603, 'Internal error'));
+      });
+
+      await expect(client.ensureReady()).rejects.toThrow('ACP error -32603: Internal error');
+    });
+
+    it('rejects pending requests on process crash', async () => {
+      createClient();
+      autoHandshake('sess-1');
+      await client.ensureReady();
+
+      // Override write so prompt sends but gets no response; then crash the process
+      mock.stdin.write.mockImplementation(() => {
+        // After the prompt is sent, simulate a process crash
+        setImmediate(() => {
+          mock.proc.killed = true;
+          mock.proc.emit('exit', 1);
+        });
+      });
+
+      const promptPromise = client.prompt('test');
+      await expect(promptPromise).rejects.toThrow('process exited');
+    });
+  });
+
+  describe('permission requests', () => {
+    it('rejects session/request_permission from agent', async () => {
+      createClient();
+      autoHandshake('sess-1');
+      await client.ensureReady();
+
+      mock.stdin.write.mockImplementation((data: string) => {
+        const msg = JSON.parse(data.trim()) as { id: number; method: string };
+        if (msg.method === 'session/prompt') {
+          setImmediate(() => {
+            // Agent asks for permission first
+            mock.sendPermissionRequest(100, 'sess-1');
+            // Then provides the actual response
+            mock.sendChunk('sess-1', 'done');
+            mock.sendResponse(msg.id, { stopReason: 'end_turn' });
+          });
+        }
+      });
+
+      const result = await client.prompt('test');
+      expect(result).toBe('done');
+
+      // Verify we sent a rejection for the permission request
+      const writes = mock.stdin.write.mock.calls.map((c) => {
+        try { return JSON.parse(c[0] as string); } catch { return null; }
+      }).filter(Boolean);
+      const rejection = writes.find((w: Record<string, unknown>) => w.id === 100);
+      expect(rejection).toBeTruthy();
+      expect((rejection as { result: { outcome: { outcome: string } } }).result.outcome.outcome).toBe('cancelled');
+    });
+  });
+
+  describe('dispose', () => {
+    it('kills process and rejects pending', async () => {
+      createClient();
+      autoHandshake('sess-1');
+      await client.ensureReady();
+
+      // Override write so prompt is sent but gets no response; then dispose
+      mock.stdin.write.mockImplementation(() => {
+        setImmediate(() => client.dispose());
+      });
+
+      const promptPromise = client.prompt('test');
+      await expect(promptPromise).rejects.toThrow('disposed');
+      expect(mock.proc.kill).toHaveBeenCalledWith('SIGTERM');
+    });
+
+    it('is safe to call multiple times', () => {
+      createClient();
+      client.dispose();
+      client.dispose();
+      // No error thrown
+    });
+  });
+
+  describe('isAlive', () => {
+    it('returns false before init', () => {
+      createClient();
+      expect(client.isAlive).toBe(false);
+    });
+
+    it('returns true after successful init', async () => {
+      createClient();
+      autoHandshake();
+      await client.ensureReady();
+      expect(client.isAlive).toBe(true);
+    });
+
+    it('returns false after dispose', async () => {
+      createClient();
+      autoHandshake();
+      await client.ensureReady();
+      client.dispose();
+      expect(client.isAlive).toBe(false);
+    });
+  });
+});

src/mcplocal/tests/gemini-acp.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mockEnsureReady = vi.fn(async () => {});
+const mockPrompt = vi.fn(async () => 'mock response');
+const mockDispose = vi.fn();
+
+vi.mock('../src/providers/acp-client.js', () => ({
+  AcpClient: vi.fn(function (this: Record<string, unknown>) {
+    this.ensureReady = mockEnsureReady;
+    this.prompt = mockPrompt;
+    this.dispose = mockDispose;
+  }),
+}));
+
+// Must import after mock setup
+const { GeminiAcpProvider } = await import('../src/providers/gemini-acp.js');
+
+describe('GeminiAcpProvider', () => {
+  let provider: InstanceType<typeof GeminiAcpProvider>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockPrompt.mockResolvedValue('mock response');
+    provider = new GeminiAcpProvider({ binaryPath: '/usr/bin/gemini', defaultModel: 'gemini-2.5-flash' });
+  });
+
+  describe('complete', () => {
+    it('builds prompt from messages and returns CompletionResult', async () => {
+      mockPrompt.mockResolvedValueOnce('The answer is 42.');
+
+      const result = await provider.complete({
+        messages: [
+          { role: 'system', content: 'You are helpful.' },
+          { role: 'user', content: 'What is the answer?' },
+        ],
+      });
+
+      expect(result.content).toBe('The answer is 42.');
+      expect(result.toolCalls).toEqual([]);
+      expect(result.finishReason).toBe('stop');
+
+      const promptText = mockPrompt.mock.calls[0][0] as string;
+      expect(promptText).toContain('System: You are helpful.');
+      expect(promptText).toContain('What is the answer?');
+    });
+
+    it('formats assistant messages with prefix', async () => {
+      mockPrompt.mockResolvedValueOnce('ok');
+
+      await provider.complete({
+        messages: [
+          { role: 'user', content: 'Hello' },
+          { role: 'assistant', content: 'Hi there' },
+          { role: 'user', content: 'How are you?' },
+        ],
+      });
+
+      const promptText = mockPrompt.mock.calls[0][0] as string;
+      expect(promptText).toContain('Assistant: Hi there');
+    });
+
+    it('trims response content', async () => {
+      mockPrompt.mockResolvedValueOnce('  padded response  \n');
+
+      const result = await provider.complete({
+        messages: [{ role: 'user', content: 'test' }],
+      });
+
+      expect(result.content).toBe('padded response');
+    });
+
+    it('serializes concurrent calls', async () => {
+      const callOrder: number[] = [];
+      let callCount = 0;
+
+      mockPrompt.mockImplementation(async () => {
+        const myCall = ++callCount;
+        callOrder.push(myCall);
+        await new Promise((r) => setTimeout(r, 10));
+        return `response-${myCall}`;
+      });
+
+      const [r1, r2, r3] = await Promise.all([
+        provider.complete({ messages: [{ role: 'user', content: 'a' }] }),
+        provider.complete({ messages: [{ role: 'user', content: 'b' }] }),
+        provider.complete({ messages: [{ role: 'user', content: 'c' }] }),
+      ]);
+
+      expect(r1.content).toBe('response-1');
+      expect(r2.content).toBe('response-2');
+      expect(r3.content).toBe('response-3');
+      expect(callOrder).toEqual([1, 2, 3]);
+    });
+
+    it('continues queue after error', async () => {
+      mockPrompt
+        .mockRejectedValueOnce(new Error('first fails'))
+        .mockResolvedValueOnce('second works');
+
+      const results = await Promise.allSettled([
+        provider.complete({ messages: [{ role: 'user', content: 'a' }] }),
+        provider.complete({ messages: [{ role: 'user', content: 'b' }] }),
+      ]);
+
+      expect(results[0].status).toBe('rejected');
+      expect(results[1].status).toBe('fulfilled');
+      if (results[1].status === 'fulfilled') {
+        expect(results[1].value.content).toBe('second works');
+      }
+    });
+  });
+
+  describe('listModels', () => {
+    it('returns static model list', async () => {
+      const models = await provider.listModels();
+      expect(models).toContain('gemini-2.5-flash');
+      expect(models).toContain('gemini-2.5-pro');
+      expect(models).toContain('gemini-2.0-flash');
+    });
+  });
+
+  describe('dispose', () => {
+    it('delegates to AcpClient', () => {
+      provider.dispose();
+      expect(mockDispose).toHaveBeenCalled();
+    });
+  });
+
+  describe('name', () => {
+    it('is gemini-cli for config compatibility', () => {
+      expect(provider.name).toBe('gemini-cli');
+    });
+  });
+});

src/mcplocal/tests/http/config.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { loadLlmConfig } from '../../src/http/config.js';
+import { existsSync, readFileSync } from 'node:fs';
+
+vi.mock('node:fs', async () => {
+  const actual = await vi.importActual<typeof import('node:fs')>('node:fs');
+  return {
+    ...actual,
+    existsSync: vi.fn(),
+    readFileSync: vi.fn(),
+  };
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('loadLlmConfig', () => {
+  it('returns undefined when config file does not exist', () => {
+    vi.mocked(existsSync).mockReturnValue(false);
+    expect(loadLlmConfig()).toBeUndefined();
+  });
+
+  it('returns undefined when config has no llm section', () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify({ mcplocalUrl: 'http://localhost:3200' }));
+    expect(loadLlmConfig()).toBeUndefined();
+  });
+
+  it('returns undefined when provider is none', () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify({ llm: { provider: 'none' } }));
+    expect(loadLlmConfig()).toBeUndefined();
+  });
+
+  it('returns LLM config when provider is configured', () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+      llm: { provider: 'anthropic', model: 'claude-haiku-3-5-20241022' },
+    }));
+    const result = loadLlmConfig();
+    expect(result).toEqual({ provider: 'anthropic', model: 'claude-haiku-3-5-20241022' });
+  });
+
+  it('returns full LLM config with all fields', () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify({
+      llm: { provider: 'vllm', model: 'my-model', url: 'http://gpu:8000' },
+    }));
+    const result = loadLlmConfig();
+    expect(result).toEqual({ provider: 'vllm', model: 'my-model', url: 'http://gpu:8000' });
+  });
+
+  it('returns undefined on malformed JSON', () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(readFileSync).mockReturnValue('NOT JSON!!!');
+    expect(loadLlmConfig()).toBeUndefined();
+  });
+
+  it('returns undefined on read error', () => {
+    vi.mocked(existsSync).mockReturnValue(true);
+    vi.mocked(readFileSync).mockImplementation(() => { throw new Error('EACCES'); });
+    expect(loadLlmConfig()).toBeUndefined();
+  });
+});

src/mcplocal/tests/llm-config.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createProviderFromConfig } from '../src/llm-config.js';
+import type { SecretStore } from '@mcpctl/shared';
+
+function mockSecretStore(secrets: Record<string, string> = {}): SecretStore {
+  return {
+    get: vi.fn(async (key: string) => secrets[key] ?? null),
+    set: vi.fn(async () => {}),
+    delete: vi.fn(async () => true),
+    backend: () => 'mock',
+  };
+}
+
+describe('createProviderFromConfig', () => {
+  it('returns empty registry for undefined config', async () => {
+    const store = mockSecretStore();
+    const registry = await createProviderFromConfig(undefined, store);
+    expect(registry.getActive()).toBeNull();
+    expect(registry.list()).toEqual([]);
+  });
+
+  it('returns empty registry for provider=none', async () => {
+    const store = mockSecretStore();
+    const registry = await createProviderFromConfig({ provider: 'none' }, store);
+    expect(registry.getActive()).toBeNull();
+  });
+
+  it('creates gemini-cli provider using ACP', async () => {
+    const store = mockSecretStore();
+    const registry = await createProviderFromConfig(
+      { provider: 'gemini-cli', model: 'gemini-2.5-flash', binaryPath: '/usr/bin/gemini' },
+      store,
+    );
+    expect(registry.getActive()).not.toBeNull();
+    expect(registry.getActive()!.name).toBe('gemini-cli');
+    // ACP provider has dispose method
+    expect(typeof registry.getActive()!.dispose).toBe('function');
+  });
+
+  it('creates ollama provider', async () => {
+    const store = mockSecretStore();
+    const registry = await createProviderFromConfig(
+      { provider: 'ollama', model: 'llama3.2', url: 'http://localhost:11434' },
+      store,
+    );
+    expect(registry.getActive()!.name).toBe('ollama');
+  });
+
+  it('creates anthropic provider with API key from secret store', async () => {
+    const store = mockSecretStore({ 'anthropic-api-key': 'sk-ant-test' });
+    const registry = await createProviderFromConfig(
+      { provider: 'anthropic', model: 'claude-haiku-3-5-20241022' },
+      store,
+    );
+    expect(registry.getActive()!.name).toBe('anthropic');
+    expect(store.get).toHaveBeenCalledWith('anthropic-api-key');
+  });
+
+  it('returns empty registry when anthropic API key is missing', async () => {
+    const store = mockSecretStore();
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const registry = await createProviderFromConfig(
+      { provider: 'anthropic', model: 'claude-haiku-3-5-20241022' },
+      store,
+    );
+    expect(registry.getActive()).toBeNull();
+    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('Anthropic API key not found'));
+    stderrSpy.mockRestore();
+  });
+
+  it('creates openai provider with API key from secret store', async () => {
+    const store = mockSecretStore({ 'openai-api-key': 'sk-test' });
+    const registry = await createProviderFromConfig(
+      { provider: 'openai', model: 'gpt-4o', url: 'https://api.openai.com' },
+      store,
+    );
+    expect(registry.getActive()!.name).toBe('openai');
+    expect(store.get).toHaveBeenCalledWith('openai-api-key');
+  });
+
+  it('returns empty registry when openai API key is missing', async () => {
+    const store = mockSecretStore();
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const registry = await createProviderFromConfig(
+      { provider: 'openai' },
+      store,
+    );
+    expect(registry.getActive()).toBeNull();
+    stderrSpy.mockRestore();
+  });
+
+  it('creates deepseek provider with API key from secret store', async () => {
+    const store = mockSecretStore({ 'deepseek-api-key': 'sk-ds-test' });
+    const registry = await createProviderFromConfig(
+      { provider: 'deepseek', model: 'deepseek-chat' },
+      store,
+    );
+    expect(registry.getActive()!.name).toBe('deepseek');
+    expect(store.get).toHaveBeenCalledWith('deepseek-api-key');
+  });
+
+  it('returns empty registry when deepseek API key is missing', async () => {
+    const store = mockSecretStore();
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const registry = await createProviderFromConfig(
+      { provider: 'deepseek' },
+      store,
+    );
+    expect(registry.getActive()).toBeNull();
+    stderrSpy.mockRestore();
+  });
+
+  it('creates vllm provider using OpenAI provider', async () => {
+    const store = mockSecretStore();
+    const registry = await createProviderFromConfig(
+      { provider: 'vllm', model: 'my-model', url: 'http://gpu-server:8000' },
+      store,
+    );
+    // vLLM reuses OpenAI provider under the hood
+    expect(registry.getActive()).not.toBeNull();
+    expect(registry.getActive()!.name).toBe('openai');
+  });
+
+  it('returns empty registry when vllm URL is missing', async () => {
+    const store = mockSecretStore();
+    const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    const registry = await createProviderFromConfig(
+      { provider: 'vllm' },
+      store,
+    );
+    expect(registry.getActive()).toBeNull();
+    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('vLLM URL not configured'));
+    stderrSpy.mockRestore();
+  });
+});

src/shared/src/index.ts

@@ -2,3 +2,4 @@ export * from './types/index.js';
 export * from './validation/index.js';
 export * from './constants/index.js';
 export * from './utils/index.js';
+export * from './secrets/index.js';

src/shared/src/secrets/file-store.ts

@@ -0,0 +1,63 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { SecretStore, SecretStoreDeps } from './types.js';
+
+function defaultConfigDir(): string {
+  return join(homedir(), '.mcpctl');
+}
+
+function secretsPath(configDir: string): string {
+  return join(configDir, 'secrets');
+}
+
+export class FileSecretStore implements SecretStore {
+  private readonly configDir: string;
+
+  constructor(deps?: SecretStoreDeps) {
+    this.configDir = deps?.configDir ?? defaultConfigDir();
+  }
+
+  backend(): string {
+    return 'file';
+  }
+
+  async get(key: string): Promise<string | null> {
+    const data = this.readAll();
+    return data[key] ?? null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const data = this.readAll();
+    data[key] = value;
+    this.writeAll(data);
+  }
+
+  async delete(key: string): Promise<boolean> {
+    const data = this.readAll();
+    if (!(key in data)) return false;
+    delete data[key];
+    this.writeAll(data);
+    return true;
+  }
+
+  private readAll(): Record<string, string> {
+    const path = secretsPath(this.configDir);
+    if (!existsSync(path)) return {};
+    try {
+      const raw = readFileSync(path, 'utf-8');
+      return JSON.parse(raw) as Record<string, string>;
+    } catch {
+      return {};
+    }
+  }
+
+  private writeAll(data: Record<string, string>): void {
+    if (!existsSync(this.configDir)) {
+      mkdirSync(this.configDir, { recursive: true });
+    }
+    const path = secretsPath(this.configDir);
+    writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    chmodSync(path, 0o600);
+  }
+}

src/shared/src/secrets/gnome-keyring.ts

@@ -0,0 +1,97 @@
+import { spawn } from 'node:child_process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { SecretStore } from './types.js';
+
+const execFileAsync = promisify(execFile);
+const SERVICE = 'mcpctl';
+
+export type RunCommand = (cmd: string, args: string[], stdin?: string) => Promise<{ stdout: string; code: number }>;
+
+function defaultRunCommand(cmd: string, args: string[], stdin?: string): Promise<{ stdout: string; code: number }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    });
+
+    const stdoutChunks: Buffer[] = [];
+    child.stdout.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
+
+    child.on('error', reject);
+    child.on('close', (code) => {
+      const stdout = Buffer.concat(stdoutChunks).toString('utf-8');
+      resolve({ stdout, code: code ?? 1 });
+    });
+
+    if (stdin !== undefined) {
+      child.stdin.write(stdin);
+      child.stdin.end();
+    } else {
+      child.stdin.end();
+    }
+  });
+}
+
+export interface GnomeKeyringDeps {
+  run?: RunCommand;
+}
+
+export class GnomeKeyringStore implements SecretStore {
+  private readonly run: RunCommand;
+
+  constructor(deps?: GnomeKeyringDeps) {
+    this.run = deps?.run ?? defaultRunCommand;
+  }
+
+  backend(): string {
+    return 'gnome-keyring';
+  }
+
+  async get(key: string): Promise<string | null> {
+    try {
+      const { stdout, code } = await this.run(
+        'secret-tool', ['lookup', 'service', SERVICE, 'key', key],
+      );
+      if (code !== 0 || !stdout) return null;
+      return stdout;
+    } catch {
+      return null;
+    }
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const { code } = await this.run(
+      'secret-tool',
+      ['store', '--label', `mcpctl: ${key}`, 'service', SERVICE, 'key', key],
+      value,
+    );
+    if (code !== 0) {
+      throw new Error(`secret-tool store exited with code ${code}`);
+    }
+  }
+
+  async delete(key: string): Promise<boolean> {
+    try {
+      const { code } = await this.run(
+        'secret-tool', ['clear', 'service', SERVICE, 'key', key],
+      );
+      return code === 0;
+    } catch {
+      return false;
+    }
+  }
+
+  static async isAvailable(deps?: { run?: RunCommand }): Promise<boolean> {
+    try {
+      if (deps?.run) {
+        const { code } = await deps.run('secret-tool', ['--version']);
+        return code === 0;
+      }
+      await execFileAsync('secret-tool', ['--version'], { timeout: 3000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

src/shared/src/secrets/index.ts

@@ -0,0 +1,15 @@
+export type { SecretStore, SecretStoreDeps } from './types.js';
+export { FileSecretStore } from './file-store.js';
+export { GnomeKeyringStore } from './gnome-keyring.js';
+export type { GnomeKeyringDeps, RunCommand } from './gnome-keyring.js';
+
+import { GnomeKeyringStore } from './gnome-keyring.js';
+import { FileSecretStore } from './file-store.js';
+import type { SecretStore, SecretStoreDeps } from './types.js';
+
+export async function createSecretStore(deps?: SecretStoreDeps): Promise<SecretStore> {
+  if (await GnomeKeyringStore.isAvailable()) {
+    return new GnomeKeyringStore();
+  }
+  return new FileSecretStore(deps);
+}

src/shared/src/secrets/types.ts

@@ -0,0 +1,10 @@
+export interface SecretStore {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  backend(): string;
+}
+
+export interface SecretStoreDeps {
+  configDir?: string;
+}

src/shared/tests/secrets/factory.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { createSecretStore } from '../../src/secrets/index.js';
+import { GnomeKeyringStore } from '../../src/secrets/gnome-keyring.js';
+import { FileSecretStore } from '../../src/secrets/file-store.js';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('createSecretStore', () => {
+  it('returns GnomeKeyringStore when secret-tool is available', async () => {
+    vi.spyOn(GnomeKeyringStore, 'isAvailable').mockResolvedValue(true);
+    const store = await createSecretStore();
+    expect(store.backend()).toBe('gnome-keyring');
+    expect(store).toBeInstanceOf(GnomeKeyringStore);
+  });
+
+  it('returns FileSecretStore when secret-tool is not available', async () => {
+    vi.spyOn(GnomeKeyringStore, 'isAvailable').mockResolvedValue(false);
+    const store = await createSecretStore();
+    expect(store.backend()).toBe('file');
+    expect(store).toBeInstanceOf(FileSecretStore);
+  });
+});

src/shared/tests/secrets/file-store.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, statSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { FileSecretStore } from '../../src/secrets/file-store.js';
+
+let tempDir: string;
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), 'mcpctl-secrets-test-'));
+});
+
+afterEach(() => {
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+describe('FileSecretStore', () => {
+  it('returns null for missing key', async () => {
+    const store = new FileSecretStore({ configDir: tempDir });
+    expect(await store.get('nonexistent')).toBeNull();
+  });
+
+  it('stores and retrieves a secret', async () => {
+    const store = new FileSecretStore({ configDir: tempDir });
+    await store.set('api-key', 'sk-12345');
+    expect(await store.get('api-key')).toBe('sk-12345');
+  });
+
+  it('overwrites existing values', async () => {
+    const store = new FileSecretStore({ configDir: tempDir });
+    await store.set('api-key', 'old-value');
+    await store.set('api-key', 'new-value');
+    expect(await store.get('api-key')).toBe('new-value');
+  });
+
+  it('stores multiple keys', async () => {
+    const store = new FileSecretStore({ configDir: tempDir });
+    await store.set('key-a', 'value-a');
+    await store.set('key-b', 'value-b');
+    expect(await store.get('key-a')).toBe('value-a');
+    expect(await store.get('key-b')).toBe('value-b');
+  });
+
+  it('deletes a key', async () => {
+    const store = new FileSecretStore({ configDir: tempDir });
+    await store.set('api-key', 'sk-12345');
+    expect(await store.delete('api-key')).toBe(true);
+    expect(await store.get('api-key')).toBeNull();
+  });
+
+  it('returns false when deleting nonexistent key', async () => {
+    const store = new FileSecretStore({ configDir: tempDir });
+    expect(await store.delete('nonexistent')).toBe(false);
+  });
+
+  it('sets 0600 permissions on secrets file', async () => {
+    const store = new FileSecretStore({ configDir: tempDir });
+    await store.set('api-key', 'sk-12345');
+    const stat = statSync(join(tempDir, 'secrets'));
+    expect(stat.mode & 0o777).toBe(0o600);
+  });
+
+  it('creates config dir if missing', async () => {
+    const nested = join(tempDir, 'sub', 'dir');
+    const store = new FileSecretStore({ configDir: nested });
+    await store.set('api-key', 'sk-12345');
+    expect(existsSync(join(nested, 'secrets'))).toBe(true);
+  });
+
+  it('recovers from corrupted JSON', async () => {
+    writeFileSync(join(tempDir, 'secrets'), 'NOT JSON!!!', 'utf-8');
+    const store = new FileSecretStore({ configDir: tempDir });
+    // Should not throw, returns null for any key
+    expect(await store.get('api-key')).toBeNull();
+    // Should be able to write over corrupted file
+    await store.set('api-key', 'fresh-value');
+    expect(await store.get('api-key')).toBe('fresh-value');
+  });
+
+  it('reports file backend', () => {
+    const store = new FileSecretStore({ configDir: tempDir });
+    expect(store.backend()).toBe('file');
+  });
+
+  it('preserves other keys on delete', async () => {
+    const store = new FileSecretStore({ configDir: tempDir });
+    await store.set('key-a', 'value-a');
+    await store.set('key-b', 'value-b');
+    await store.delete('key-a');
+    expect(await store.get('key-a')).toBeNull();
+    expect(await store.get('key-b')).toBe('value-b');
+  });
+});

src/shared/tests/secrets/gnome-keyring.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, vi } from 'vitest';
+import { GnomeKeyringStore } from '../../src/secrets/gnome-keyring.js';
+import type { RunCommand } from '../../src/secrets/gnome-keyring.js';
+
+function mockRun(
+  responses: Record<string, { stdout: string; code: number }>,
+): RunCommand {
+  return vi.fn(async (cmd: string, args: string[], _stdin?: string) => {
+    const key = `${cmd} ${args.join(' ')}`;
+    for (const [pattern, response] of Object.entries(responses)) {
+      if (key.includes(pattern)) return response;
+    }
+    return { stdout: '', code: 1 };
+  });
+}
+
+describe('GnomeKeyringStore', () => {
+  describe('get', () => {
+    it('returns value on success', async () => {
+      const run = mockRun({ 'lookup': { stdout: 'my-secret', code: 0 } });
+      const store = new GnomeKeyringStore({ run });
+      expect(await store.get('api-key')).toBe('my-secret');
+    });
+
+    it('returns null on exit code 1', async () => {
+      const run = mockRun({ 'lookup': { stdout: '', code: 1 } });
+      const store = new GnomeKeyringStore({ run });
+      expect(await store.get('api-key')).toBeNull();
+    });
+
+    it('returns null on empty stdout', async () => {
+      const run = mockRun({ 'lookup': { stdout: '', code: 0 } });
+      const store = new GnomeKeyringStore({ run });
+      expect(await store.get('api-key')).toBeNull();
+    });
+
+    it('returns null on error', async () => {
+      const run = vi.fn().mockRejectedValue(new Error('timeout'));
+      const store = new GnomeKeyringStore({ run });
+      expect(await store.get('api-key')).toBeNull();
+    });
+
+    it('calls secret-tool with correct args', async () => {
+      const run = vi.fn().mockResolvedValue({ stdout: 'val', code: 0 });
+      const store = new GnomeKeyringStore({ run });
+      await store.get('my-key');
+      expect(run).toHaveBeenCalledWith(
+        'secret-tool',
+        ['lookup', 'service', 'mcpctl', 'key', 'my-key'],
+      );
+    });
+  });
+
+  describe('set', () => {
+    it('calls secret-tool store with value as stdin', async () => {
+      const run = vi.fn().mockResolvedValue({ stdout: '', code: 0 });
+      const store = new GnomeKeyringStore({ run });
+      await store.set('api-key', 'secret-value');
+      expect(run).toHaveBeenCalledWith(
+        'secret-tool',
+        ['store', '--label', 'mcpctl: api-key', 'service', 'mcpctl', 'key', 'api-key'],
+        'secret-value',
+      );
+    });
+
+    it('throws on non-zero exit code', async () => {
+      const run = vi.fn().mockResolvedValue({ stdout: '', code: 1 });
+      const store = new GnomeKeyringStore({ run });
+      await expect(store.set('api-key', 'val')).rejects.toThrow('exited with code 1');
+    });
+  });
+
+  describe('delete', () => {
+    it('returns true on success', async () => {
+      const run = mockRun({ 'clear': { stdout: '', code: 0 } });
+      const store = new GnomeKeyringStore({ run });
+      expect(await store.delete('api-key')).toBe(true);
+    });
+
+    it('returns false on failure', async () => {
+      const run = mockRun({ 'clear': { stdout: '', code: 1 } });
+      const store = new GnomeKeyringStore({ run });
+      expect(await store.delete('api-key')).toBe(false);
+    });
+
+    it('returns false on error', async () => {
+      const run = vi.fn().mockRejectedValue(new Error('fail'));
+      const store = new GnomeKeyringStore({ run });
+      expect(await store.delete('api-key')).toBe(false);
+    });
+
+    it('calls secret-tool clear with correct args', async () => {
+      const run = vi.fn().mockResolvedValue({ stdout: '', code: 0 });
+      const store = new GnomeKeyringStore({ run });
+      await store.delete('my-key');
+      expect(run).toHaveBeenCalledWith(
+        'secret-tool',
+        ['clear', 'service', 'mcpctl', 'key', 'my-key'],
+      );
+    });
+  });
+
+  describe('isAvailable', () => {
+    it('returns true when secret-tool exists', async () => {
+      const run = vi.fn().mockResolvedValue({ stdout: '0.20', code: 0 });
+      expect(await GnomeKeyringStore.isAvailable({ run })).toBe(true);
+    });
+
+    it('returns false when secret-tool not found', async () => {
+      const run = vi.fn().mockRejectedValue(new Error('ENOENT'));
+      expect(await GnomeKeyringStore.isAvailable({ run })).toBe(false);
+    });
+
+    it('returns false on non-zero exit', async () => {
+      const run = vi.fn().mockResolvedValue({ stdout: '', code: 127 });
+      expect(await GnomeKeyringStore.isAvailable({ run })).toBe(false);
+    });
+  });
+
+  it('reports gnome-keyring backend', () => {
+    const run = vi.fn().mockResolvedValue({ stdout: '', code: 0 });
+    const store = new GnomeKeyringStore({ run });
+    expect(store.backend()).toBe('gnome-keyring');
+  });
+});