mcpick 0.0.1 → 0.0.3

package/.github/copilot-instructions.md

@@ -0,0 +1,32 @@
+# McPick Development Instructions
+
+**Always reference these instructions first and fallback to search or
+bash commands only when you encounter unexpected information that does
+not match the info here.**
+
+## Working Effectively
+
+### Prerequisites and Setup
+
+- Install Node.js >=22.0.0
+- Install pnpm globally: `npm install -g pnpm` (takes ~2 seconds)
+
+### Development Commands
+
+- **Format code**: `pnpm run format`
+- **Build**: `pnpm run build`
+
+## Validation Requirements
+
+### ALWAYS run these before submitting changes:
+
+1. `pnpm run format` - Auto-format all code
+2. `pnpm run build` - Check for build issues
+
+#### Add changeset once you're done
+
+Run `pnpm changeset` then follow the prompts. Use this after having
+finished the task. Most of the time this is a patch release for
+`mcpick`. Use a short and descriptive message. Always prefix the
+message with either `fix`, `feat`, `breaking`, or `chore` (most likely
+`fix` since you're mostly working on bugfixes).

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # mcpick
 
+## 0.0.3
+
+### Patch Changes
+
+- 158520e: fix: extract duplicated server details display logic into
+  reusable function
+
+## 0.0.2
+
+### Patch Changes
+
+- 6a3eec7: paste json server config
+- a62953b: Removed estimated_tokens prompt and references, Enhanced
+  add-server dialogue
+- 491d543: make json first options for adding server
+- 3242ff1: remove unused docs
+
 ## 0.0.1
 
 ### Patch Changes

package/README.md

@@ -1,9 +1,27 @@
-# MCPick
+# 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.
 
+## Installation
+
+### One-time Usage
+
+```bash
+pnpm dlx mcpick
+# or
+npx mcpick
+```
+
+### Global Installation
+
+```bash
+pnpm install -g mcpick
+# or
+npm install -g mcpick
+```
+
 ## The Problem
 
 Using the Claude Code `/doctor` command you may see something like
@@ -31,7 +49,7 @@ This can lead to:
 
 ## The Solution
 
-MCPick provides an intuitive CLI menu to:
+McPick provides an intuitive CLI menu to:
 
 - ✅ **Toggle servers on/off** - Enable only the MCP servers you need
   for your current task
@@ -49,7 +67,7 @@ MCPick provides an intuitive CLI menu to:
 ### Interactive Menu
 
 ```bash
-┌  MCPick - MCP Server Configuration Manager
+┌  McPick - MCP Server Configuration Manager
 │
 ◆  What would you like to do?
 │  ● Edit config (Toggle MCP servers on/off)

package/dist/commands/add-server.js

@@ -1,8 +1,50 @@
-import { confirm, note, text } from '@clack/prompts';
+import { confirm, note, select, text } from '@clack/prompts';
 import { add_server_to_registry } from '../core/registry.js';
 import { validate_mcp_server } from '../core/validation.js';
+function format_server_details(server) {
+    const details = [`Name: ${server.name}`];
+    if ('command' in server) {
+        details.push(`Command: ${server.command} ${(server.args || []).join(' ')}`);
+    }
+    if ('url' in server) {
+        details.push(`URL: ${server.url}`);
+    }
+    details.push(`Description: ${server.description || 'None'}`);
+    if (server.type) {
+        details.push(`Transport: ${server.type}`);
+    }
+    if (server.env) {
+        details.push(`Environment: ${Object.keys(server.env).length} variables`);
+    }
+    if ('headers' in server && server.headers) {
+        details.push(`Headers: ${Object.keys(server.headers).length} headers`);
+    }
+    return details;
+}
 export async function add_server() {
     try {
+        // First, ask how they want to configure the server
+        const config_method = await select({
+            message: 'How would you like to add the server?',
+            options: [
+                {
+                    value: 'json',
+                    label: 'Paste JSON configuration',
+                    hint: 'Paste complete server config as JSON',
+                },
+                {
+                    value: 'form',
+                    label: 'Step-by-step form',
+                    hint: 'Fill out fields one by one',
+                },
+            ],
+            initialValue: 'json',
+        });
+        if (typeof config_method === 'symbol')
+            return;
+        if (config_method === 'json') {
+            return await add_server_from_json();
+        }
         const name = await text({
             message: 'Server name:',
             placeholder: 'e.g., mcp-sqlite-tools',
@@ -44,37 +86,102 @@ export async function add_server() {
         });
         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;
-            },
+        // Advanced configuration
+        const configure_advanced = await confirm({
+            message: 'Configure advanced settings (env variables, transport, etc.)?',
+            initialValue: false,
         });
-        if (typeof estimated_tokens_input === 'symbol')
+        if (typeof configure_advanced === 'symbol')
             return;
-        const server_data = {
+        let server_data = {
             name: name.trim(),
+            type: 'stdio',
             command: command.trim(),
             args,
             ...(description &&
                 description.trim() && { description: description.trim() }),
-            ...(estimated_tokens_input &&
-                estimated_tokens_input.trim() && {
-                estimated_tokens: parseInt(estimated_tokens_input.trim()),
-            }),
         };
+        if (configure_advanced) {
+            // Transport type
+            const transport_type = await select({
+                message: 'Transport type:',
+                options: [
+                    {
+                        value: 'stdio',
+                        label: 'stdio (default)',
+                        hint: 'Standard input/output',
+                    },
+                    { value: 'sse', label: 'sse', hint: 'Server-sent events' },
+                    { value: 'http', label: 'http', hint: 'HTTP transport' },
+                ],
+                initialValue: 'stdio',
+            });
+            if (typeof transport_type === 'symbol')
+                return;
+            server_data.type = transport_type;
+            // URL for non-stdio transports
+            if (transport_type === 'sse' || transport_type === 'http') {
+                // Remove stdio-specific fields
+                delete server_data.command;
+                delete server_data.args;
+                const url = await text({
+                    message: 'Server URL:',
+                    placeholder: 'e.g., http://localhost:3000',
+                    validate: (value) => {
+                        if (!value || value.trim().length === 0) {
+                            return 'URL is required for non-stdio transport';
+                        }
+                        return undefined;
+                    },
+                });
+                if (typeof url === 'symbol')
+                    return;
+                server_data.url = url.trim();
+            }
+            // Environment variables
+            const env_input = await text({
+                message: 'Environment variables (KEY=value, comma-separated):',
+                placeholder: 'e.g., API_KEY=abc123, TIMEOUT=30',
+            });
+            if (typeof env_input === 'symbol')
+                return;
+            if (env_input && env_input.trim()) {
+                const env = {};
+                env_input.split(',').forEach((pair) => {
+                    const [key, ...valueParts] = pair.split('=');
+                    if (key && valueParts.length > 0) {
+                        env[key.trim()] = valueParts.join('=').trim();
+                    }
+                });
+                if (Object.keys(env).length > 0) {
+                    server_data.env = env;
+                }
+            }
+            // Headers for HTTP transport
+            if (transport_type === 'http') {
+                const headers_input = await text({
+                    message: 'HTTP headers (KEY=value, comma-separated):',
+                    placeholder: 'e.g., Authorization=Bearer token, Content-Type=application/json',
+                });
+                if (typeof headers_input === 'symbol')
+                    return;
+                if (headers_input && headers_input.trim()) {
+                    const headers = {};
+                    headers_input.split(',').forEach((pair) => {
+                        const [key, ...valueParts] = pair.split('=');
+                        if (key && valueParts.length > 0) {
+                            headers[key.trim()] = valueParts.join('=').trim();
+                        }
+                    });
+                    if (Object.keys(headers).length > 0) {
+                        server_data.headers = headers;
+                    }
+                }
+            }
+        }
         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 details = format_server_details(validated_server);
+        note(`Server to add:\n${details.join('\n')}`);
         const should_add = await confirm({
             message: 'Add this server to the registry?',
         });
@@ -88,4 +195,69 @@ export async function add_server() {
         throw new Error(`Failed to add server: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
 }
+async function add_server_from_json() {
+    const json_input = await text({
+        message: 'Paste JSON configuration:',
+        placeholder: '{ "name": "mcp-sqlite-tools", "command": "npx", "args": ["-y", "mcp-sqlite-tools"] }',
+        validate: (value) => {
+            if (!value || value.trim().length === 0) {
+                return 'JSON configuration is required';
+            }
+            let jsonString = value.trim();
+            // If it doesn't start with {, wrap it in braces
+            if (!jsonString.startsWith('{')) {
+                jsonString = `{${jsonString}}`;
+            }
+            try {
+                const parsed = JSON.parse(jsonString);
+                if (typeof parsed !== 'object' || parsed === null) {
+                    return 'JSON must be an object';
+                }
+                if (!parsed.command) {
+                    return 'Server configuration must include a "command" field';
+                }
+            }
+            catch (error) {
+                return 'Invalid JSON format';
+            }
+            return undefined;
+        },
+    });
+    if (typeof json_input === 'symbol')
+        return;
+    try {
+        let jsonString = json_input.trim();
+        // If it doesn't start with {, wrap it in braces
+        if (!jsonString.startsWith('{')) {
+            jsonString = `{${jsonString}}`;
+        }
+        const parsed = JSON.parse(jsonString);
+        const server_data = parsed;
+        // Normalize the data to match schema expectations
+        if (!server_data.type && server_data.command) {
+            server_data.type = 'stdio';
+        }
+        if (server_data.type !== 'stdio') {
+            delete server_data.command;
+            delete server_data.args;
+        }
+        if (server_data.command && !server_data.args) {
+            server_data.args = [];
+        }
+        const validated_server = validate_mcp_server(server_data);
+        const details = format_server_details(validated_server);
+        note(`Server to add:\n${details.join('\n')}`);
+        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 parse or validate JSON: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
 //# sourceMappingURL=add-server.js.map

package/dist/commands/launch.js

@@ -5,7 +5,7 @@ export async function launch_claude_code() {
     try {
         s.start('Launching Claude Code...');
         const claude_process = spawn('claude', ['code'], {
-            stdio: 'inherit',
+            stdio: 'ignore',
             detached: true,
         });
         claude_process.unref();

package/dist/core/validation.js

@@ -1,32 +1,38 @@
 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'),
-    ])),
+export const mcp_server_schema_stdio = v.object({
+    type: v.optional(v.literal('stdio')),
     command: v.pipe(v.string(), v.minLength(1)),
-    args: v.array(v.string()),
+    args: v.optional(v.array(v.string())),
     env: v.optional(v.record(v.string(), v.string())),
-    url: v.optional(v.string()),
+    description: v.optional(v.string()),
+});
+export const mcp_server_schema_sse = v.object({
+    type: v.literal('sse'),
+    env: v.optional(v.record(v.string(), v.string())),
+    url: v.pipe(v.string(), v.minLength(1)),
+    headers: v.optional(v.record(v.string(), v.string())),
+    description: v.optional(v.string()),
+});
+export const mcp_server_schema_http = v.object({
+    type: v.literal('http'),
+    env: v.optional(v.record(v.string(), v.string())),
+    url: v.pipe(v.string(), v.minLength(1)),
     headers: v.optional(v.record(v.string(), v.string())),
     description: v.optional(v.string()),
 });
+export const mcp_server_schema_base = v.union([
+    mcp_server_schema_stdio,
+    mcp_server_schema_sse,
+    mcp_server_schema_http,
+]);
+export const mcp_server_schema = v.intersect([
+    v.object({
+        name: v.pipe(v.string(), v.minLength(1)),
+    }),
+    mcp_server_schema_base,
+]);
 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()),
-    }))),
+    mcpServers: v.optional(v.record(v.string(), mcp_server_schema_base)),
 });
 export const server_registry_schema = v.object({
     servers: v.array(mcp_server_schema),

package/dist/index.js

@@ -40,7 +40,7 @@ async function main() {
                     {
                         value: 'exit',
                         label: 'Exit',
-                        hint: 'Quit MCPick',
+                        hint: 'Quit MCPick (Esc)',
                     },
                 ],
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpick",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Dynamic MCP server configuration manager for Claude Code",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,9 +25,9 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.7",
-    "@types/node": "^24.5.2",
+    "@types/node": "^24.6.1",
     "prettier": "^3.6.2",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.3"
   },
   "scripts": {
     "build": "tsc",

package/mcpick-plan.md

@@ -1,223 +0,0 @@
-# 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/plan.md

@@ -1,102 +0,0 @@
-# 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.