mcpick 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# mcpick
+
+## 0.0.1
+
+### Patch Changes
+
+- debe3ad: initial release

package/README.md

@@ -0,0 +1,143 @@
+# MCPick
+
+A CLI tool for dynamically managing MCP server configurations in
+Claude Code. Enable and disable MCP servers on-demand to optimize
+context usage and performance.
+
+## The Problem
+
+Using the Claude Code `/doctor` command you may see something like
+this if you have many MCP servers configured:
+
+```bash
+ Context Usage Warnings
+ └ ⚠ Large MCP tools context (~66,687 tokens > 25,000)
+   └ MCP servers:
+     └ mcp-omnisearch-testing: 20 tools (~10,494 tokens)
+     └ mcp-omnisearch: 20 tools (~10,454 tokens)
+     └ mcp-sqlite-tools-testing: 19 tools (~9,910 tokens)
+     └ mcp-sqlite-tools: 19 tools (~9,872 tokens)
+     └ playwright: 21 tools (~9,804 tokens)
+     └ (7 more servers)
+```
+
+Claude Code loads **all** MCP servers from your `.claude.json` file at
+startup, regardless of whether you need them for your current task.
+This can lead to:
+
+- 🐌 Slower Claude Code startup times
+- 💾 High context token usage
+- 🧠 Cognitive overload from too many available tools
+
+## The Solution
+
+MCPick provides an intuitive CLI menu to:
+
+- ✅ **Toggle servers on/off** - Enable only the MCP servers you need
+  for your current task
+- 📁 **Manage server registry** - Keep a database of all your
+  available MCP servers
+- 🔄 **Safe configuration** - Only modifies the `mcpServers` section,
+  preserving other Claude Code settings
+- 💾 **Backup & restore** - Create focused backups of your MCP server
+  configurations
+- 🚀 **Quick launch** - Start Claude Code with your optimized
+  configuration
+
+## Features
+
+### Interactive Menu
+
+```bash
+┌  MCPick - MCP Server Configuration Manager
+│
+◆  What would you like to do?
+│  ● Edit config (Toggle MCP servers on/off)
+│  ○ Backup config
+│  ○ Add MCP server
+│  ○ Restore from backup
+│  ○ Launch Claude Code
+│  ○ Exit
+└
+```
+
+### Smart Server Management
+
+- **Auto-discovery**: Automatically imports servers from your existing
+  `.claude.json`
+- **Registry sync**: Maintains a registry of available servers for
+  quick selection
+- **Selective enabling**: Choose exactly which servers to enable via
+  multiselect
+- **Configuration safety**: Preserves all non-MCP settings in your
+  Claude Code config
+
+### Backup System
+
+- **Focused backups**: Only backs up MCP server configurations (not
+  the entire 30k+ line config)
+- **Automatic cleanup**: Keeps last 10 backups to prevent storage
+  bloat
+- **Easy restoration**: Restore from any previous backup with a simple
+  menu
+
+### Typical Workflow
+
+1. **Before a coding session**: Run MCPick and enable only relevant
+   servers (e.g., just database tools for DB work)
+2. **Launch Claude Code**: Use MCPick's "Launch Claude Code" option
+3. **Switch contexts**: Re-run MCPick to enable different servers for
+   different tasks
+
+### Adding New Servers
+
+1. Select "Add MCP server"
+2. Provide server details:
+   - Name (e.g., "mcp-sqlite-tools")
+   - Command (e.g., "npx")
+   - Arguments (e.g., "-y", "mcp-sqlite-tools")
+   - Description (optional)
+   - Environment variables (optional)
+
+## Configuration
+
+MCPick works with the standard Claude Code configuration format:
+
+```json
+{
+	"mcpServers": {
+		"server-name": {
+			"command": "npx",
+			"args": ["-y", "mcp-server-package"],
+			"env": {
+				"API_KEY": "your-key"
+			}
+		}
+	}
+}
+```
+
+### File Locations
+
+- **Claude Config**: `~/.claude.json` (your main Claude Code
+  configuration)
+- **MCPick Registry**: `~/.claude/mcpick/servers.json` (MCPick's
+  server database)
+- **Backups**: `~/.claude/mcpick/backups/` (MCP configuration backups)
+
+## Safety Features
+
+- **Non-destructive**: Only modifies the `mcpServers` section of your
+  Claude Code config
+- **Backup integration**: Automatically creates backups before major
+  changes
+- **Validation**: Ensures all server configurations are valid before
+  writing
+- **Error handling**: Graceful failure modes with helpful error
+  messages
+
+## Requirements
+
+- Node.js 22+
+- Claude Code installed and configured
+- pnpm (for building from source)

package/dist/commands/add-server.js

@@ -0,0 +1,91 @@
+import { confirm, note, text } from '@clack/prompts';
+import { add_server_to_registry } from '../core/registry.js';
+import { validate_mcp_server } from '../core/validation.js';
+export async function add_server() {
+    try {
+        const name = await text({
+            message: 'Server name:',
+            placeholder: 'e.g., mcp-sqlite-tools',
+            validate: (value) => {
+                if (!value || value.trim().length === 0) {
+                    return 'Server name is required';
+                }
+                return undefined;
+            },
+        });
+        if (typeof name === 'symbol')
+            return;
+        const command = await text({
+            message: 'Command to run:',
+            placeholder: 'e.g., uvx, npx, node',
+            validate: (value) => {
+                if (!value || value.trim().length === 0) {
+                    return 'Command is required';
+                }
+                return undefined;
+            },
+        });
+        if (typeof command === 'symbol')
+            return;
+        const args_input = await text({
+            message: 'Arguments (comma-separated):',
+            placeholder: 'e.g., mcp-sqlite-tools, --port, 3000',
+            defaultValue: '',
+        });
+        if (typeof args_input === 'symbol')
+            return;
+        const args = args_input
+            .split(',')
+            .map((arg) => arg.trim())
+            .filter((arg) => arg.length > 0);
+        const description = await text({
+            message: 'Description (optional):',
+            placeholder: 'Brief description of what this server provides',
+        });
+        if (typeof description === 'symbol')
+            return;
+        const estimated_tokens_input = await text({
+            message: 'Estimated tokens (optional):',
+            placeholder: 'e.g., 5000',
+            validate: (value) => {
+                if (value && value.trim().length > 0) {
+                    const num = parseInt(value.trim());
+                    if (isNaN(num) || num < 0) {
+                        return 'Must be a positive number';
+                    }
+                }
+                return undefined;
+            },
+        });
+        if (typeof estimated_tokens_input === 'symbol')
+            return;
+        const server_data = {
+            name: name.trim(),
+            command: command.trim(),
+            args,
+            ...(description &&
+                description.trim() && { description: description.trim() }),
+            ...(estimated_tokens_input &&
+                estimated_tokens_input.trim() && {
+                estimated_tokens: parseInt(estimated_tokens_input.trim()),
+            }),
+        };
+        const validated_server = validate_mcp_server(server_data);
+        note(`Server to add:\n` +
+            `Name: ${validated_server.name}\n` +
+            `Command: ${validated_server.command} ${validated_server.args.join(' ')}\n` +
+            `Description: ${validated_server.description || 'None'}`);
+        const should_add = await confirm({
+            message: 'Add this server to the registry?',
+        });
+        if (typeof should_add === 'symbol' || !should_add) {
+            return;
+        }
+        await add_server_to_registry(validated_server);
+        note(`Server "${validated_server.name}" added to registry successfully!`);
+    }
+    catch (error) {
+        throw new Error(`Failed to add server: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+//# sourceMappingURL=add-server.js.map

package/dist/commands/backup.js

@@ -0,0 +1,54 @@
+import { note } from '@clack/prompts';
+import { readdir, unlink, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { read_claude_config } from '../core/config.js';
+import { ensure_directory_exists, get_backup_filename, get_backups_dir, } from '../utils/paths.js';
+const MAX_BACKUPS = 10;
+export async function backup_config() {
+    try {
+        const current_config = await read_claude_config();
+        const backups_dir = get_backups_dir();
+        await ensure_directory_exists(backups_dir);
+        const backup_filename = get_backup_filename();
+        const backup_path = join(backups_dir, backup_filename);
+        const mcp_backup = {
+            mcpServers: current_config.mcpServers || {},
+        };
+        const backup_content = JSON.stringify(mcp_backup, null, 2);
+        await writeFile(backup_path, backup_content, 'utf-8');
+        await cleanup_old_backups();
+        const server_count = Object.keys(current_config.mcpServers || {}).length;
+        note(`MCP servers backup created:\n${backup_path}\n(${server_count} servers backed up)`);
+    }
+    catch (error) {
+        throw new Error(`Failed to create backup: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+async function cleanup_old_backups() {
+    try {
+        const backups_dir = get_backups_dir();
+        const files = await readdir(backups_dir);
+        const backup_files = files
+            .filter((file) => file.startsWith('mcp-servers-') && file.endsWith('.json'))
+            .map((file) => {
+            const timestamp_match = file.match(/mcp-servers-(\d{4})-(\d{2})-(\d{2})-(\d{2})(\d{2})(\d{2})\.json/);
+            if (!timestamp_match)
+                return null;
+            const [, year, month, day, hour, minute, second] = timestamp_match;
+            const timestamp = new Date(parseInt(year), parseInt(month) - 1, parseInt(day), parseInt(hour), parseInt(minute), parseInt(second));
+            return { file, timestamp };
+        })
+            .filter((backup) => backup !== null)
+            .sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+        if (backup_files.length > MAX_BACKUPS) {
+            const files_to_delete = backup_files.slice(MAX_BACKUPS);
+            for (const { file } of files_to_delete) {
+                await unlink(join(backups_dir, file));
+            }
+        }
+    }
+    catch (error) {
+        console.warn('Warning: Failed to cleanup old backups:', error);
+    }
+}
+//# sourceMappingURL=backup.js.map

package/dist/commands/edit-config.js

@@ -0,0 +1,47 @@
+import { multiselect, note } from '@clack/prompts';
+import { create_config_from_servers, get_enabled_servers, read_claude_config, write_claude_config, } from '../core/config.js';
+import { get_all_available_servers, sync_servers_to_registry, } from '../core/registry.js';
+export async function edit_config() {
+    try {
+        const current_config = await read_claude_config();
+        // If registry is empty but .claude.json has servers, populate registry from config
+        let all_servers = await get_all_available_servers();
+        if (all_servers.length === 0 && current_config.mcpServers) {
+            const current_servers = get_enabled_servers(current_config);
+            if (current_servers.length > 0) {
+                await sync_servers_to_registry(current_servers);
+                all_servers = current_servers;
+                note(`Imported ${current_servers.length} servers from your .claude.json file into registry.`);
+            }
+        }
+        if (all_servers.length === 0) {
+            note('No MCP servers found in .claude.json or registry. Add servers first.');
+            return;
+        }
+        const currently_enabled = Object.keys(current_config.mcpServers || {});
+        const server_choices = all_servers.map((server) => ({
+            value: server.name,
+            label: server.name,
+            hint: server.description || '',
+        }));
+        const selected_server_names = await multiselect({
+            message: 'Select MCP servers to enable:',
+            options: server_choices,
+            initialValues: currently_enabled,
+            required: false,
+        });
+        if (typeof selected_server_names === 'symbol') {
+            return;
+        }
+        const selected_servers = all_servers.filter((server) => selected_server_names.includes(server.name));
+        const new_config = create_config_from_servers(selected_servers);
+        await write_claude_config(new_config);
+        await sync_servers_to_registry(selected_servers);
+        note(`Configuration updated!\n` +
+            `Enabled servers: ${selected_servers.length}`);
+    }
+    catch (error) {
+        throw new Error(`Failed to edit configuration: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+//# sourceMappingURL=edit-config.js.map

package/dist/commands/launch.js

@@ -0,0 +1,32 @@
+import { spinner } from '@clack/prompts';
+import { spawn } from 'node:child_process';
+export async function launch_claude_code() {
+    const s = spinner();
+    try {
+        s.start('Launching Claude Code...');
+        const claude_process = spawn('claude', ['code'], {
+            stdio: 'inherit',
+            detached: true,
+        });
+        claude_process.unref();
+        await new Promise((resolve, reject) => {
+            claude_process.on('error', (error) => {
+                if (error.message.includes('ENOENT')) {
+                    reject(new Error('Claude Code not found. Make sure it is installed and in your PATH.'));
+                }
+                else {
+                    reject(error);
+                }
+            });
+            setTimeout(() => {
+                resolve(void 0);
+            }, 1000);
+        });
+        s.stop('Claude Code launched successfully!');
+    }
+    catch (error) {
+        s.stop('Failed to launch Claude Code');
+        throw new Error(`Failed to launch Claude Code: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+//# sourceMappingURL=launch.js.map

package/dist/commands/restore.js

@@ -0,0 +1,67 @@
+import { confirm, note, select } from '@clack/prompts';
+import { readFile } from 'node:fs/promises';
+import { read_claude_config, write_claude_config, } from '../core/config.js';
+import { list_backups } from '../core/registry.js';
+export async function restore_config() {
+    try {
+        const backups = await list_backups();
+        if (backups.length === 0) {
+            note('No backups found.');
+            return;
+        }
+        const backup_choices = backups.map((backup) => ({
+            value: backup.path,
+            label: `${backup.filename} (${backup.timestamp.toLocaleString()})`,
+            hint: format_time_ago(backup.timestamp),
+        }));
+        const selected_backup_path = await select({
+            message: 'Select backup to restore:',
+            options: backup_choices,
+        });
+        if (typeof selected_backup_path === 'symbol') {
+            return;
+        }
+        const should_restore = await confirm({
+            message: 'This will replace your current MCP servers configuration. Continue?',
+        });
+        if (typeof should_restore === 'symbol' || !should_restore) {
+            return;
+        }
+        // Read the backup file
+        const backup_content = await readFile(selected_backup_path, 'utf-8');
+        const backup_data = JSON.parse(backup_content);
+        // Read current config and merge
+        const current_config = await read_claude_config();
+        const updated_config = {
+            ...current_config,
+            mcpServers: backup_data.mcpServers || {},
+        };
+        // Write back only the updated config
+        await write_claude_config(updated_config);
+        const server_count = Object.keys(backup_data.mcpServers || {}).length;
+        note(`MCP servers configuration restored successfully!\n(${server_count} servers restored)`);
+    }
+    catch (error) {
+        throw new Error(`Failed to restore configuration: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+function format_time_ago(date) {
+    const now = new Date();
+    const diff = now.getTime() - date.getTime();
+    const minutes = Math.floor(diff / 60000);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0) {
+        return `${days} day${days > 1 ? 's' : ''} ago`;
+    }
+    else if (hours > 0) {
+        return `${hours} hour${hours > 1 ? 's' : ''} ago`;
+    }
+    else if (minutes > 0) {
+        return `${minutes} minute${minutes > 1 ? 's' : ''} ago`;
+    }
+    else {
+        return 'just now';
+    }
+}
+//# sourceMappingURL=restore.js.map

package/dist/core/config.js

@@ -0,0 +1,54 @@
+import { access, readFile, writeFile } from 'node:fs/promises';
+import { get_claude_config_path } from '../utils/paths.js';
+import { validate_claude_config } from './validation.js';
+export async function read_claude_config() {
+    const config_path = get_claude_config_path();
+    try {
+        await access(config_path);
+        const config_content = await readFile(config_path, 'utf-8');
+        const parsed_config = JSON.parse(config_content);
+        return validate_claude_config(parsed_config);
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return { mcpServers: {} };
+        }
+        throw error;
+    }
+}
+export async function write_claude_config(config) {
+    const config_path = get_claude_config_path();
+    // Read the entire existing file to preserve all other sections
+    let existing_config = {};
+    try {
+        const existing_content = await readFile(config_path, 'utf-8');
+        existing_config = JSON.parse(existing_content);
+    }
+    catch (error) {
+        // If file doesn't exist or is invalid, start with empty object
+    }
+    // Only update the mcpServers section, preserve everything else
+    existing_config.mcpServers = config.mcpServers;
+    const config_content = JSON.stringify(existing_config, null, 2);
+    await writeFile(config_path, config_content, 'utf-8');
+}
+export function get_enabled_servers(config) {
+    if (!config.mcpServers) {
+        return [];
+    }
+    return Object.entries(config.mcpServers).map(([name, server]) => ({
+        ...server,
+        name,
+    }));
+}
+export function create_config_from_servers(selected_servers) {
+    const mcp_servers = {};
+    selected_servers.forEach((server) => {
+        const { name, ...server_config } = server;
+        mcp_servers[name] = server_config;
+    });
+    return { mcpServers: mcp_servers };
+}
+//# sourceMappingURL=config.js.map

package/dist/core/registry.js

@@ -0,0 +1,91 @@
+import { access, readdir, readFile, writeFile, } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ensure_directory_exists, get_backups_dir, get_mcpick_dir, get_server_registry_path, } from '../utils/paths.js';
+import { validate_server_registry } from './validation.js';
+export async function read_server_registry() {
+    const registry_path = get_server_registry_path();
+    try {
+        await access(registry_path);
+        const registry_content = await readFile(registry_path, 'utf-8');
+        const parsed_registry = JSON.parse(registry_content);
+        return validate_server_registry(parsed_registry);
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            await ensure_directory_exists(get_mcpick_dir());
+            const default_registry = { servers: [] };
+            await write_server_registry(default_registry);
+            return default_registry;
+        }
+        throw error;
+    }
+}
+export async function write_server_registry(registry) {
+    const registry_path = get_server_registry_path();
+    await ensure_directory_exists(get_mcpick_dir());
+    const registry_content = JSON.stringify(registry, null, 2);
+    await writeFile(registry_path, registry_content, 'utf-8');
+}
+export async function add_server_to_registry(server) {
+    const registry = await read_server_registry();
+    const existing_index = registry.servers.findIndex((s) => s.name === server.name);
+    if (existing_index >= 0) {
+        registry.servers[existing_index] = server;
+    }
+    else {
+        registry.servers.push(server);
+    }
+    await write_server_registry(registry);
+}
+export async function get_all_available_servers() {
+    const registry = await read_server_registry();
+    return registry.servers;
+}
+export async function sync_servers_to_registry(servers) {
+    const registry = await read_server_registry();
+    servers.forEach((server) => {
+        const existing_index = registry.servers.findIndex((s) => s.name === server.name);
+        if (existing_index >= 0) {
+            registry.servers[existing_index] = server;
+        }
+        else {
+            registry.servers.push(server);
+        }
+    });
+    await write_server_registry(registry);
+}
+export async function list_backups() {
+    const backups_dir = get_backups_dir();
+    try {
+        await access(backups_dir);
+        const files = await readdir(backups_dir);
+        const backup_files = files
+            .filter((file) => file.startsWith('mcp-servers-') && file.endsWith('.json'))
+            .map((file) => {
+            const timestamp_match = file.match(/mcp-servers-(\d{4})-(\d{2})-(\d{2})-(\d{2})(\d{2})(\d{2})\.json/);
+            if (!timestamp_match)
+                return null;
+            const [, year, month, day, hour, minute, second] = timestamp_match;
+            const timestamp = new Date(parseInt(year), parseInt(month) - 1, parseInt(day), parseInt(hour), parseInt(minute), parseInt(second));
+            return {
+                filename: file,
+                timestamp,
+                path: join(backups_dir, file),
+            };
+        })
+            .filter((backup) => backup !== null)
+            .sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+        return backup_files;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/validation.js

@@ -0,0 +1,43 @@
+import * as v from 'valibot';
+export const mcp_server_schema = v.object({
+    name: v.pipe(v.string(), v.minLength(1)),
+    type: v.optional(v.union([
+        v.literal('stdio'),
+        v.literal('sse'),
+        v.literal('http'),
+    ])),
+    command: v.pipe(v.string(), v.minLength(1)),
+    args: v.array(v.string()),
+    env: v.optional(v.record(v.string(), v.string())),
+    url: v.optional(v.string()),
+    headers: v.optional(v.record(v.string(), v.string())),
+    description: v.optional(v.string()),
+});
+export const claude_config_schema = v.object({
+    mcpServers: v.optional(v.record(v.string(), v.object({
+        type: v.optional(v.union([
+            v.literal('stdio'),
+            v.literal('sse'),
+            v.literal('http'),
+        ])),
+        command: v.pipe(v.string(), v.minLength(1)),
+        args: v.array(v.string()),
+        env: v.optional(v.record(v.string(), v.string())),
+        url: v.optional(v.string()),
+        headers: v.optional(v.record(v.string(), v.string())),
+        description: v.optional(v.string()),
+    }))),
+});
+export const server_registry_schema = v.object({
+    servers: v.array(mcp_server_schema),
+});
+export function validate_mcp_server(data) {
+    return v.parse(mcp_server_schema, data);
+}
+export function validate_claude_config(data) {
+    return v.parse(claude_config_schema, data);
+}
+export function validate_server_registry(data) {
+    return v.parse(server_registry_schema, data);
+}
+//# sourceMappingURL=validation.js.map

package/dist/index.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { cancel, intro, isCancel, outro, select, } from '@clack/prompts';
+import { add_server } from './commands/add-server.js';
+import { backup_config } from './commands/backup.js';
+import { edit_config } from './commands/edit-config.js';
+import { launch_claude_code } from './commands/launch.js';
+import { restore_config } from './commands/restore.js';
+async function main() {
+    intro('MCPick - MCP Server Configuration Manager');
+    while (true) {
+        try {
+            const action = await select({
+                message: 'What would you like to do?',
+                options: [
+                    {
+                        value: 'edit-config',
+                        label: 'Edit config',
+                        hint: 'Toggle MCP servers on/off',
+                    },
+                    {
+                        value: 'backup',
+                        label: 'Backup config',
+                        hint: 'Create a timestamped backup',
+                    },
+                    {
+                        value: 'add-server',
+                        label: 'Add MCP server',
+                        hint: 'Register a new MCP server',
+                    },
+                    {
+                        value: 'restore',
+                        label: 'Restore from backup',
+                        hint: 'Restore from a previous backup',
+                    },
+                    {
+                        value: 'launch',
+                        label: 'Launch Claude Code',
+                        hint: 'Start Claude Code with current config',
+                    },
+                    {
+                        value: 'exit',
+                        label: 'Exit',
+                        hint: 'Quit MCPick',
+                    },
+                ],
+            });
+            if (isCancel(action)) {
+                cancel('Operation cancelled');
+                break;
+            }
+            switch (action) {
+                case 'edit-config':
+                    await edit_config();
+                    break;
+                case 'backup':
+                    await backup_config();
+                    break;
+                case 'add-server':
+                    await add_server();
+                    break;
+                case 'restore':
+                    await restore_config();
+                    break;
+                case 'launch':
+                    await launch_claude_code();
+                    break;
+                case 'exit':
+                    outro('Goodbye!');
+                    process.exit(0);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                cancel(error.message);
+            }
+            else {
+                cancel('An unexpected error occurred');
+            }
+            const should_continue = await select({
+                message: 'Would you like to continue?',
+                options: [
+                    { value: true, label: 'Yes, return to main menu' },
+                    { value: false, label: 'No, exit' },
+                ],
+            });
+            if (isCancel(should_continue) || !should_continue) {
+                outro('Goodbye!');
+                break;
+            }
+        }
+    }
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/paths.js

@@ -0,0 +1,34 @@
+import { access, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function get_claude_config_path() {
+    return join(homedir(), '.claude.json');
+}
+export function get_mcpick_dir() {
+    return join(homedir(), '.claude', 'mcpick');
+}
+export function get_server_registry_path() {
+    return join(get_mcpick_dir(), 'servers.json');
+}
+export function get_backups_dir() {
+    return join(get_mcpick_dir(), 'backups');
+}
+export function get_backup_filename() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    const hour = String(now.getHours()).padStart(2, '0');
+    const minute = String(now.getMinutes()).padStart(2, '0');
+    const second = String(now.getSeconds()).padStart(2, '0');
+    return `mcp-servers-${year}-${month}-${day}-${hour}${minute}${second}.json`;
+}
+export async function ensure_directory_exists(dir_path) {
+    try {
+        await access(dir_path);
+    }
+    catch {
+        await mkdir(dir_path, { recursive: true });
+    }
+}
+//# sourceMappingURL=paths.js.map

package/mcpick-plan.md

@@ -0,0 +1,223 @@
+# MCPick Implementation Plan
+
+## Overview
+
+Build a minimal Node.js CLI tool using TypeScript and Clack prompts to
+dynamically manage MCP server configurations for Claude Code sessions.
+
+## The Problem
+
+Claude Code loads ALL configured MCP servers at session startup,
+consuming massive amounts of context tokens (66,687+ tokens reported)
+regardless of whether you actually use those tools. Users need a way
+to dynamically select which MCP servers to load per session.
+
+## Architecture - Minimal Dependencies
+
+**Only 2 Dependencies:**
+
+```json
+{
+	"@clack/prompts": "^0.7.0",
+	"valibot": "^0.25.0"
+}
+```
+
+**Use Node.js Built-ins:**
+
+- `fs/promises` for all file operations
+- `path`, `os.homedir()` for path handling
+- `child_process.spawn` to launch Claude Code
+- `JSON.parse/stringify` for config files
+
+## TypeScript Configuration
+
+**tsconfig.json:**
+
+```json
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "node16",
+		"strict": true,
+		"outDir": "./dist",
+		"sourceMap": true,
+		"esModuleInterop": true,
+		"allowSyntheticDefaultImports": true,
+		"skipLibCheck": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules", "dist"]
+}
+```
+
+**package.json additions:**
+
+- `"type": "module"` for ESM
+- `"bin": { "mcpick": "./dist/index.js" }`
+- `"engines": { "node": ">=22.0.0" }`
+
+## User Flow - Pure Interactive
+
+```bash
+mcpick  # Single entry point - no CLI arguments
+```
+
+**Main Menu (Clack select):**
+
+```
+┌ What would you like to do?
+│ ○ Edit config
+│ ○ Backup config
+│ ○ Add MCP server
+│ ○ Restore from backup
+│ ○ Launch Claude Code
+└ ○ Exit
+```
+
+### Edit Config Flow:
+
+1. Read `.claude.json` from current directory
+2. Show multiselect with all servers (currently enabled ones checked)
+3. User toggles servers on/off with spacebar
+4. Save deselected servers to `~/.claude/mcpick/servers.json` registry
+5. Update `.claude.json` with only selected servers
+6. Show token count reduction
+
+### Backup Config Flow:
+
+1. Create timestamped backup of current `.claude.json`
+2. Store in `~/.claude/mcpick/backups/`
+3. Confirm backup location to user
+
+### Add MCP Server Flow:
+
+1. Text prompts for server details:
+   - Name
+   - Command
+   - Arguments (array)
+   - Description (optional)
+2. Validate configuration with Valibot
+3. Add to both `.claude.json` and servers registry
+
+### Restore Flow:
+
+1. List available backups with timestamps
+2. User selects backup to restore
+3. Confirm destructive operation
+4. Restore `.claude.json` from backup
+
+## File Structure
+
+```
+mcpick/
+├── src/
+│   ├── commands/
+│   │   ├── edit-config.ts    # Toggle servers on/off
+│   │   ├── backup.ts         # Create config backups
+│   │   ├── add-server.ts     # Add new MCP server
+│   │   ├── restore.ts        # Restore from backup
+│   │   └── launch.ts         # Launch Claude Code
+│   ├── core/
+│   │   ├── config.ts         # .claude.json read/write operations
+│   │   ├── registry.ts       # servers.json management
+│   │   └── validation.ts     # Valibot schemas
+│   ├── utils/
+│   │   └── paths.ts          # Path resolution utilities
+│   ├── types.ts              # TypeScript type definitions
+│   └── index.ts              # Main entry point with menu
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Configuration Storage
+
+**Current directory: `.claude.json`**
+
+- Standard Claude Code configuration file
+- Only contains currently selected MCP servers
+
+**~/.claude/mcpick/servers.json** - Registry of all available servers:
+
+```json
+{
+	"servers": [
+		{
+			"name": "mcp-sqlite-tools",
+			"command": "uvx",
+			"args": ["mcp-sqlite-tools"],
+			"description": "SQLite database tools",
+			"estimatedTokens": 9872
+		},
+		{
+			"name": "mcp-omnisearch",
+			"command": "npx",
+			"args": ["-y", "@modelcontextprotocol/server-omnisearch"],
+			"description": "Web search capabilities",
+			"estimatedTokens": 10454
+		}
+	]
+}
+```
+
+**~/.claude/mcpick/backups/** - Timestamped backup files:
+
+- Format: `claude-YYYY-MM-DD-HHMMSS.json`
+- Keep last 10 backups automatically
+
+## Error Handling Strategy
+
+- **Valibot schemas** for all configuration validation
+- **Try/catch blocks** with Clack `cancel()` for user-friendly error
+  messages
+- **File permission checks** before attempting operations
+- **Create missing directories/files** with sensible defaults
+- **Graceful handling** of malformed JSON files
+
+## Token Estimation
+
+- Static analysis of MCP server tool definitions
+- Cache estimates in servers.json to avoid repeated calculations
+- Display real-time totals during server selection
+- Show before/after token counts
+
+## Implementation Steps
+
+1. **Project Setup**
+   - Initialize Node.js/TypeScript project with minimal dependencies
+   - Configure ESM, TypeScript, and build scripts
+
+2. **Core Infrastructure**
+   - Implement config file I/O using only Node.js built-ins
+   - Create server registry management
+   - Build backup/restore functionality
+
+3. **Clack Interface**
+   - Main interactive menu system
+   - Multiselect for server toggling
+   - Text prompts for server addition
+
+4. **Config Management**
+   - Edit existing configurations
+   - Add new MCP servers
+   - Backup and restore operations
+
+5. **Polish & Testing**
+   - Error handling and validation
+   - User experience improvements
+   - Documentation
+
+## Benefits
+
+- **95% token reduction** by loading only needed tools
+- **Zero session restarts** for MCP configuration changes
+- **Intuitive interface** with beautiful Clack prompts
+- **Minimal dependencies** - only 2 external packages
+- **Fast startup** with lightweight codebase
+- **Backup safety** for configuration changes
+
+This approach transforms MCP configuration from a static, manual
+process into a dynamic, user-friendly workflow that maximizes both
+functionality and efficiency.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "mcpick",
+  "version": "0.0.1",
+  "description": "Dynamic MCP server configuration manager for Claude Code",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "mcpick": "./dist/index.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "claude",
+    "mcp",
+    "cli",
+    "configuration",
+    "claude-code"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "valibot": "^1.1.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "@types/node": "^24.5.2",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node ./dist/index.js",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "pnpm run build && changeset publish"
+  }
+}

package/plan.md

@@ -0,0 +1,102 @@
+# MCP Session Manager: Dynamic Tool Configuration for Claude Code
+
+## The Problem
+
+Claude Code loads ALL configured MCP servers at session startup,
+consuming massive amounts of context tokens regardless of whether you
+actually use those tools. Users report:
+
+- **66,687 tokens consumed** by 20+ MCP tools before even starting
+  work
+- **25-30% of context window** used by unused tool definitions
+- **No way to dynamically enable/disable** MCP servers during sessions
+- **Session restart required** for any MCP configuration changes
+- **Forced to choose** between comprehensive tool access and efficient
+  resource usage
+
+This creates a fundamental workflow problem: you either load
+everything (wasting tokens) or manually edit JSON configs before each
+session (time-consuming and error-prone).
+
+## The Solution: Session-Specific MCP Configuration Manager
+
+A CLI tool that manages your MCP server configurations dynamically by
+manipulating the `.claude.json` file before Claude Code sessions
+start.
+
+### Core Concept
+
+Instead of fighting Claude Code's static loading, work with it by
+making configuration changes fast and intelligent:
+
+1. **Store all available MCP servers** in a separate configuration
+   repository
+2. **Select servers per session** using an interactive interface
+3. **Automatically update** `.claude.json` with only selected servers
+4. **Launch Claude Code** with optimized configuration
+5. **Save successful combinations** as reusable presets
+
+### Key Features
+
+**Interactive Server Selection**
+
+- Checkbox interface showing all available MCP servers
+- Real-time token usage estimates for each server
+- Smart warnings when approaching context limits
+- Tag-based filtering (e.g., "web-dev", "data-analysis", "automation")
+
+**Preset Management**
+
+- Save frequently used server combinations
+- Load preset configurations instantly
+- Project-specific presets (auto-detect based on directory)
+- Share presets with team members
+
+**Intelligent Recommendations**
+
+- Suggest optimal server combinations for detected project types
+- Learn from usage patterns to recommend relevant tools
+- Context-aware suggestions based on file types in current directory
+
+**Seamless Integration**
+
+- One command to select servers and launch Claude Code
+- Backup and restore previous configurations
+- Zero impact on existing Claude Code functionality
+
+### User Experience
+
+```bash
+# Interactive selection for this session
+mcp-manager select
+
+# Quick preset loading
+mcp-manager start --preset "web-development"
+
+# Enable specific servers by name
+mcp-manager enable context7 github filesystem
+
+# Save current successful combination
+mcp-manager save-preset "data-pipeline" --current
+```
+
+### Benefits
+
+- **95% token reduction** by loading only needed tools
+- **No session restarts** for configuration changes
+- **Faster startup times** with fewer servers to initialize
+- **Better resource utilization** and longer conversation capacity
+- **Experimentation-friendly** - try new tool combinations easily
+- **Team collaboration** through shared preset configurations
+
+### Storage Location
+
+Extends existing Claude configuration structure:
+
+- Available servers stored in `~/.claude/mcp-manager/`
+- Presets and settings in `~/.claude/settings.json`
+- No modification to Claude Code's core configuration patterns
+
+This solution transforms the MCP configuration experience from a
+static, all-or-nothing choice into a dynamic, session-optimized
+workflow that maximizes both functionality and efficiency.