imcp 0.1.5 → 0.1.6

package/memory-bank/decisionLog.md

@@ -0,0 +1,91 @@
+# Decision Log
+
+This file records significant architectural or technical decisions, including rationale and implications.  
+Update this file with a timestamped entry whenever a major decision is made.
+
+---
+
+---
+
+[2025-05-15 19:56:12] - Memory Bank updated to reflect onboarding page architecture and features as described in [`docs/ONBOARDING_PAGE_DESIGN.md`](../docs/ONBOARDING_PAGE_DESIGN.md).
+
+- Modular JS architecture for onboarding UI, form-to-JSON, validation, publishing, and state.
+- Central `FeedConfiguration` model for category/server/requirement data.
+- Enhanced UX: dynamic sections, toggling, notifications, robust validation/publishing.
+- Recent improvements: server visibility, requirement lookup, async feedback, tab/view handling.
+  [2025-05-15 20:48:27] - Implemented MCP Server Duplication Feature.
+- Added a duplicate button to the right of the delete button in the server item template (`src/web/public/js/onboard/templates.js`).
+- Modified `duplicateServer` function in `src/web/public/js/onboard/uiHandlers.js` to correctly retrieve data from the server to be duplicated, even if it's read-only. This was achieved by temporarily enabling form fields of the source server item before calling `getFormData`.
+- Ensured that the duplicated server is always created as a new, editable server, and all its content (including environment variables and requirements) is copied from the original server.
+- The `populateServerManually` function ensures that sub-items (env vars, requirements) of the duplicated server are also created in an editable state.
+- This functionality applies to both "Create New Category" and "Create Server in Existing Category" tabs.
+- Fixed the error "Could not retrieve data for the server to duplicate" when duplicating read-only servers.
+
+[2025-05-16 00:34:40] - [Fixed duplicate server functionality]
+- Issue: Duplicating non-first servers failed with "Could not retrieve data" error
+- Fix: Modified duplicateServer() to temporarily enable ALL disabled fields before form submission
+- Impact: Ensures complete server data is captured regardless of position in list
+- Files affected: src/web/public/js/onboard/uiHandlers.js
+[2025-05-16 13:27:43] - Refactored requirement management logic from `InstallationService` into a new dedicated `RequirementService`. `InstallationService` now delegates requirement-related tasks (checking status, installing, updating) to `RequirementService`. This improves separation of concerns and modularity.
+
+[2025-05-16 16:07:20] - Redesigned the operation status and polling mechanism for Installation in both frontend and backend. This involved creating a new InstallOperationManager, new types for operation details, an API endpoint for status retrieval, and integrating step recording into InstallationService, RequirementService, and BaseClientInstaller. This provides more granular tracking of installation progress.
+
+[2025-05-16 16:50:05] - Added 'overallStatus' to InstallOperationDetails and updated InstallOperationManager to manage it. Modified frontend polling in 'src/web/public/js/modal/installation.js' to use the new installation status API and display detailed steps.
+
+[2025-05-16 17:03:17] - Enhanced the display of installation steps in the loading modal. Modified 'messageQueue.js' to support step-specific formatting (icons, success/failure states) and updated 'installation.js' to pass these options. Added CSS in 'modal.css' for the new step display styles.
+
+[2025-05-16 17:08:31] - Refined installation step display: made fonts smaller, increased compactness, and added timestamps for each step. Updated 'modal.css' and 'messageQueue.js' accordingly. 'installation.js' now passes the timestamp.
+
+[2025-05-16 17:19:37] - Overhauled the installation loading modal UI. 'loadingModal.js' now dynamically creates a new structure with an overall status (icon + text) and a detailed steps list. 'installation.js' was updated to use new functions in 'loadingModal.js' for status and step updates. 'messageQueue.js' was simplified as direct DOM manipulation for steps is now in 'loadingModal.js'. Added extensive CSS in 'modal.css' for the new layout and styling.
+
+[2025-05-16 17:23:42] - Fixed error caused by removed 'delayedAppendInstallLoadingMessage'. Updated 'modalSetup.js' and 'installation.js' (uninstallTools function) to use the new 'updateOverallInstallStatus' from 'loadingModal.js' for general status messages during uninstallation.
+
+[2025-05-16 17:26:13] - Final fix for 'delayedAppendInstallLoadingMessage' error: removed unused import from 'installModal.js'.
+
+[2025-05-16 17:29:59] - Corrected 'src/web/public/js/modal/index.js' barrel file: removed imports and re-exports of 'delayedAppendInstallLoadingMessage' and 'appendInstallLoadingMessage' as they no longer exist. Added new exports for 'updateOverallInstallStatus' and 'addInstallationStep'.
+
+[2025-05-16 17:31:35] - Corrected 'src/web/public/js/modal.js' (another barrel file): removed import and global assignment of 'appendInstallLoadingMessage'. Added missing exports for 'showInstallLoadingModal' and 'hideInstallLoadingModal'.
+
+[2025-05-16 17:46:59] - Implemented reset of installation operation status. Added `resetOperation` method to `InstallOperationManager.ts` to delete existing status for a server. Called this method at the beginning of `InstallationService.ts#install` to ensure a clean state for new installations.
+
+[2025-05-16 17:51:01] - UI adjustments for installation loading modal:
+  - Added a close button (X) to the top-right corner with functionality to hide the modal.
+  - Ensured installation steps are explicitly left-aligned using `justify-content: flex-start`.
+  - Modified the 'completed' status icon to be a checkmark within a green circle.
+  - Reviewed and confirmed the 'in-progress' spinner icon.
+
+[2025-05-16 17:53:42] - Refined step message alignment in installation loading modal: Added `align-items: flex-start` and `text-align: left` to `.step-info`, and `text-align: left` with `width: 100%` to `.step-message` in `modal.css` to ensure text content is fully left-aligned.
+
+[2025-05-16 17:55:32] - UI adjustment for installation loading modal: Removed the "Details" header text from above the steps list in `loadingModal.js`.
+
+[2025-05-16 17:57:02] - Corrected removal of "Details" header in installation loading modal: Entire line `<div class="steps-list-header">Details</div>` was removed from `loadingModal.js` instead of being commented out with an invalid HTML comment.
+
+[2025-05-17 00:26:02] - Refactored InstallOperationManager to require categoryName and serverName in the constructor, removed singleton/static pattern, and changed status file storage to per-category/server at Settings_Dir/InstallOperationStatus/CategoryName/ServerName.json. This enables instance-based management and more granular status persistence.
+
+[2025-05-17 15:02:27] - Refactored `RequirementService.ts` to use instance-based `InstallOperationManager`.
+- The `processRequirementUpdates` and `checkAndInstallRequirements` (including its helper `installRequirementsInBackground`) methods in [`src/services/RequirementService.ts`](src/services/RequirementService.ts:0) were updated.
+- They now obtain an `InstallOperationManager` instance using `InstallOperationManager.getInstance(categoryName, serverName)`.
+- The core logic within these methods, and the individual requirement processing loops, are now wrapped with `iom.recording()` or `iom.recordingAsync()` for robust step tracking and error handling.
+- This change aligns `RequirementService.ts` with the new instance-based, per-category/server architecture of `InstallOperationManager` introduced in [2025-05-17 00:26:02].
+- Rationale: Simplifies step recording, centralizes status management within the `InstallOperationManager` instance, and improves consistency across services.
+- Implications: Removed direct calls to the deprecated global `installOperationManager.recordStep` and adopted the more structured `recording` pattern.
+
+[2025-05-17 15:26:09] - Updated all requirement installer classes and interface to support step recording via InstallOperationManager. All install methods now accept an optional recorder and record critical steps using recordStep/recording.
+
+[2025-05-18 13:21:30] - Implemented main modal refresh on loading modal close, replacing page reload.
+- Rationale: Improve UX by maintaining main modal context and avoiding disruptive page reloads after installation/uninstallation operations shown in the loading modal.
+- Implementation Details:
+  - `src/web/public/js/modal/loadingModal.js`: Modified `hideInstallLoadingModal` to dispatch a custom event `refreshMainModalContent` instead of causing a page reload.
+  - `src/web/public/js/modal/installation.js`: Modified `handleBulkClientInstall` to store `categoryName` as `lastSelectedCategory` and `serverName` as `lastSelectedServerName` in `localStorage` when an installation process begins. This ensures the context is available for the refresh.
+  - `src/web/public/js/modal.js`: Added an event listener for `refreshMainModalContent`. This listener retrieves `lastSelectedCategory` and `lastSelectedServerName` from `localStorage`. If both are valid, it calls `window.showInstallModal(lastSelectedCategory, lastSelectedServerName)` to refresh the content of the main installation modal.
+- Debugging: Iteratively refined the logic in `modal.js` to correctly handle and validate `lastSelectedCategory` and `lastSelectedServerName` to prevent errors when calling `showInstallModal`. This was crucial for ensuring `showInstallModal` received the necessary `serverName` argument, resolving "Server configuration not found" errors.
+[2025-05-18 11:33:12] - Added `src/core/metadatas/recordingConstants.ts` as the canonical source for all step recording names used in installation and onboarding operations. This file centralizes all static step names as constants and documents dynamic step name patterns, improving consistency and discoverability for step-based operation tracking across backend and frontend.
+
+[2025-05-18 20:46:46] - Reduced the height and key size in the System Environment Variables section of the settings UI for a more compact and modern appearance. This involved decreasing row padding, shrinking the key column width, and reducing the key font size in `src/web/public/js/settings.js`.
+
+[2025-05-18 21:00:26] - Macro resolution logic updated: Now resolves macro values (${PYTHON_PACKAGE}, ${NPMPATH}, ${BROWSER_PATH}) by first checking SystemSettingsManager (system settings), and only falls back to previous behavior if not found. This centralizes macro configuration and improves consistency across the system.
+
+[2025-05-19 00:14:06] - Updated settings page UI and functionality:
+  - Removed "NPM Global Package Path" field from `src/web/public/settings.html` and `src/web/public/js/settings.js`.
+  - Added a descriptive prompt "Stored and used for mcp server installation environments." with a question icon (`bx-help-circle`) on the same line as the "User Configurations" title in `src/web/public/settings.html`.
+  - Modified `src/web/public/js/settings.js` to render user configuration values as `type="password"` if the key contains "key". Added an eye icon button *inside* the value input field to toggle visibility for these password fields, maintaining original input box sizes.

package/memory-bank/productContext.md

@@ -0,0 +1,41 @@
+# Product Context
+
+This file contains the high-level project description, goals, features, and overall architecture for the onboarding page and related systems.
+
+---
+
+## Onboarding Page Overview
+
+- **Purpose:** Dynamic onboarding UI for configuring new server categories and MCP servers.
+- **Frontend Structure:** Modular JavaScript in [`src/web/public/js/onboard/`](src/web/public/js/onboard):
+  - `index.js`: Entry point, tab switching, event listeners, loading/editing categories.
+  - `formProcessor.js`: Converts form ↔ JSON (`FeedConfiguration`), validation, populating UI.
+  - `uiHandlers.js`: Dynamic UI (add/remove servers, env vars, requirements), view toggling, section collapsing.
+  - `templates.js`: HTML templates for servers, env vars, requirements.
+  - `state.js`: Tracks counters for dynamic elements.
+  - `validationHandlers.js`: Validation logic, polling, progress display.
+  - `publishHandler.js`: Handles publishing, status polling, and feedback.
+
+---
+
+## Core Data Model
+
+- **FeedConfiguration** (see [`src/core/types.ts`](src/core/types.ts)):
+  - `name`, `displayName`, `description`, `repository`
+  - `mcpServers`: Array of server configs (mode, install, env, dependencies)
+  - `requirements`: Unique, fully defined requirements (type, name, version, registry, alias)
+
+---
+
+## Key Features
+
+- Dynamic form sections for servers, environment variables, and requirements.
+- Toggle between form and JSON editor views.
+- Robust validation and publishing flows with polling and progress UI.
+- Custom notification system for user feedback.
+- Enhanced UX for editing, tab switching, and error handling.
+- All code and UI logic is aligned with [`docs/ONBOARDING_PAGE_DESIGN.md`](../docs/ONBOARDING_PAGE_DESIGN.md).
+
+---
+
+_Last updated: 2025-05-15_

package/memory-bank/progress.md

@@ -0,0 +1,35 @@
+# Progress Log
+
+- [YYYY-MM-DD HH:MM:SS] - Initializing Memory Bank.
+
+- [2025-05-16 09:22:36] - Completed: Made "IMCP Server Manager" title clickable in `src/web/public/index.html`.
+- [2025-05-16 13:28:10] - Completed: Refactored requirement management from `InstallationService` to `RequirementService`. Fixed `reqConfig` scoping and type fallbacks in `RequirementService.processRequirementUpdates`.
+
+[2025-05-16 16:07:34] - Completed: Redesign installation operation status and polling mechanism.
+  - Added `InstallOperationDetails` type to `src/core/metadatas/types.ts`.
+  - Created `InstallOperationManager` in `src/core/loaders/InstallOperationManager.ts`.
+  - Added API endpoint for installation status in `src/web/server.ts`.
+  - Integrated `recordStep` in `InstallationService`, `RequirementService`, and `BaseClientInstaller`.
+
+[2025-05-16 16:50:21] - Enhanced installation status:
+  - Added `overallStatus` to `InstallOperationDetails` in `src/core/metadatas/types.ts`.
+  - Updated `InstallOperationManager` in `src/core/loaders/InstallOperationManager.ts` to manage `overallStatus`.
+  - Modified frontend polling in `src/web/public/js/modal/installation.js` to use the new API `/api/categories/:categoryName/servers/:serverName/installation/status` and display detailed steps.
+
+[2025-05-17 00:26:16] - Began refactoring InstallOperationManager to be instance-based per category/server, with new file structure for status. Memory bank updated to reflect architectural and pattern changes.
+
+[2025-05-17 15:02:44] - Completed: Refactored `RequirementService.ts` to use instance-based `InstallOperationManager` and its `recording`/`recordingAsync` methods. This involved updating `processRequirementUpdates`, `checkAndInstallRequirements`, and `installRequirementsInBackground`.
+
+[2025-05-18 11:33:23] - Completed: Standardized step recording names by creating `src/core/metadatas/recordingConstants.ts`. This centralizes static step names and documents dynamic patterns for installation/onboarding operations.
+
+[2025-05-18 13:21:30] - Completed: Implemented main modal refresh logic to replace page reload.
+  - `loadingModal.js`: Dispatches `refreshMainModalContent` event on close.
+  - `installation.js`: Stores `categoryName` and `serverName` in `localStorage`.
+  - `modal.js`: Listens for event, retrieves context from `localStorage`, and calls `showInstallModal` with both `categoryName` and `serverName`.
+  - This resolves "Server configuration not found" errors and improves UX.
+[2025-05-17 15:26:15] - Refactored all requirement installer classes and factory to support InstallOperationManager step recording. All install methods now accept a recorder and log critical steps.
+
+[2025-05-19 00:14:13] - Completed: Updated settings page (`src/web/public/settings.html` and `src/web/public/js/settings.js`):
+  - Removed "NPM Global Package Path" display.
+  - Added prompt with a question icon for User Configurations, displayed on the same line as the section title.
+  - Implemented secret input type for keys containing "key" in User Configurations, with an eye icon button *inside* the value input field to toggle visibility (maintaining original input box sizes).

package/memory-bank/systemPatterns.md

@@ -0,0 +1,10 @@
+# System Patterns
+
+- [YYYY-MM-DD HH:MM:SS] - Initializing Memory Bank.
+
+[2025-05-18 13:21:30] - Implemented an event-driven modal refresh pattern for the installation UI.
+  - Pattern: Instead of page reloads, the loading modal (`loadingModal.js`) dispatches a custom DOM event (`refreshMainModalContent`) upon closing.
+  - Context Persistence: The initiating action (e.g., in `installation.js`) stores necessary context (like `lastSelectedCategory` and `lastSelectedServerName`) in `localStorage`.
+  - Event Handling: The main modal controller (`modal.js`) listens for this event, retrieves context from `localStorage`, and re-initializes/refreshes its content (`showInstallModal`) with the persisted context.
+  - Benefit: This decouples the loading modal from the main modal, allows for non-disruptive UI updates, and maintains user context effectively.
+[2025-05-17 00:26:06] - Changed InstallOperationManager from singleton/static to instance-based, with per-category/server file storage pattern: Settings_Dir/InstallOperationStatus/CategoryName/ServerName.json. This introduces a more granular, object-oriented persistence and management pattern for install operation status.

package/package.json

@@ -1,16 +1,12 @@
 {
   "name": "imcp",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Node.js SDK for Model Context Protocol (MCP)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
     "imcp": "./dist/cli/index.js"
   },
-  "files": [
-    "dist",
-    "README.md"
-  ],
   "scripts": {
     "build": "tsc && npm run copy-public",
     "dev": "tsc -w",

package/src/cli/commands/install.ts

@@ -0,0 +1,139 @@
+import { Command } from 'commander';
+import { serverService } from '../../services/ServerService.js';
+import { Logger } from '../../utils/logger.js';
+import { hasLocalFeeds } from '../../utils/feedUtils.js';
+import { ServerInstallOptions } from '../../core/metadatas/types.js';
+import { SUPPORTED_CLIENT_NAMES } from '../../core/metadatas/constants.js';
+import { mcpManager } from '../../services/MCPManager.js';
+
+export function createInstallCommand(): Command {
+  return new Command('install')
+    .description('Install specific MCP servers')
+    .addHelpText('after', `
+Examples:
+  # Install a server
+  $ imcp install --category ai-coder-tools --name github-tools
+
+  # Install with specific client targets (semicolon separated)
+  $ imcp install --category ai-coder-tools --name github-tools --clients "MSRooCode;GithubCopilot"
+
+  # Install with environment variables
+  $ imcp install --category ai-coder-tools --name github-tools --envs "GITHUB_TOKEN=abc123;API_KEY=xyz789"
+    `)
+    .requiredOption(
+      '--category <category>',
+      'Server category'
+    )
+    .requiredOption(
+      '--name <name>',
+      'Server name to install'
+    )
+    .option(
+      '--clients <clients>',
+      'Target clients (semicolon separated). Supported values: Cline, MSRooCode, GithubCopilot. If not specified, installs for all clients'
+    )
+    .option(
+      '--envs <envs>',
+      'Environment variables (semicolon separated key=value pairs)'
+    )
+    .action(async (options: {
+      category: string;
+      name: string;
+      clients?: string;
+      envs?: string;
+      verbose?: boolean;
+    }) => {
+      try {
+        // Check for local feeds existence at the start
+        const feedsExist = await hasLocalFeeds();
+        if (!feedsExist) {
+          Logger.log('Local feeds not found, syncing from remote...');
+          await serverService.syncFeeds();
+        }
+        await mcpManager.initialize();
+        const { category, name, verbose, clients, envs } = options;
+
+        Logger.debug(`Install options: ${JSON.stringify({ category, name, verbose, clients, envs })}`);
+
+        const serverName = name.trim();
+        Logger.debug(`Server name: ${serverName}`);
+
+        if (!await serverService.validateServerName(category, serverName)) {
+          Logger.error(
+            'Invalid server name or category provided.\n' +
+            'This could be because:\n' +
+            '  1. The server name or category is misspelled\n' +
+            '  2. Your local feeds are outdated\n\n' +
+            'Try running "imcp pull" to update your local feeds from remote.',
+            { category, serverName }
+          );
+          process.exit(1);
+        }
+
+        // Parse and validate clients
+        const parsedClients = clients ? clients.split(';')
+          .map((c: string) => c.trim())
+          .filter(Boolean)
+          .map((c: string) => {
+            const clientName = c.toLowerCase();
+            const validClient = SUPPORTED_CLIENT_NAMES.find((name: string) => name.toLowerCase() === clientName);
+            if (!validClient) {
+              Logger.error(`Invalid client name: ${c}`);
+              return null;
+            }
+            return validClient;
+          })
+          .filter((c: string | null): c is string => c !== null) : undefined;
+
+        if (parsedClients && parsedClients.length > 0) {
+          Logger.debug(`Target clients: ${JSON.stringify(parsedClients)}`);
+        }
+
+        // Parse environment variables
+        const parsedEnvs: Record<string, string> = {};
+        if (envs) {
+          const pairs = envs.split(';');
+          for (const pair of pairs) {
+            const [key, value] = pair.split('=').map((s: string) => s.trim());
+            if (key && value) {
+              parsedEnvs[key] = value;
+            } else {
+              Logger.error(`Invalid environment variable format: ${pair}`);
+            }
+          }
+        }
+
+        if (Object.keys(parsedEnvs).length > 0) {
+          Logger.debug(`Environment variables: ${JSON.stringify(parsedEnvs)}`);
+        }
+
+        Logger.log(`Installing server: ${serverName}`);
+
+        const installOptions: ServerInstallOptions = {
+          force: false,
+          ...(parsedClients?.length && { targetClients: parsedClients }),
+          ...(Object.keys(parsedEnvs).length > 0 && { env: parsedEnvs })
+        };
+
+        const results = [await serverService.installMcpServer(category, serverName, installOptions)];
+
+        const { success, messages } = serverService.formatOperationResults(results);
+
+        messages.forEach((message: string) => {
+          if (success) {
+            Logger.log(`✓ ${message}`);
+          } else {
+            Logger.error(`✗ ${message}`);
+          }
+        });
+
+        if (!success) {
+          process.exit(1);
+        }
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        Logger.error('Installation failed:', message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/list.ts

@@ -0,0 +1,113 @@
+import { Command } from 'commander';
+import fs from 'fs/promises';
+import path from 'path';
+import { LOCAL_FEEDS_DIR } from '../../core/metadatas/constants.js';
+import { mcpManager } from '../../services/MCPManager.js';
+import { Logger } from '../../utils/logger.js';
+
+interface SimplifiedServer {
+  name: string;
+  description: string;
+}
+
+interface SimplifiedFeed {
+  name: string;
+  displayName: string;
+  description: string;
+  mcpServers: SimplifiedServer[];
+}
+
+export function createListCommand(): Command {
+  return new Command('list')
+    .description('List all available MCP servers from feeds')
+    .option('--pull', 'Sync with remote feeds before listing')
+    .action(async (options) => {
+      try {
+        Logger.debug({
+          action: 'list_command_started',
+          options
+        });
+
+        // If sync flag is provided, try to sync first
+        if (options.pull) {
+          try {
+            await mcpManager.syncFeeds();
+          } catch (syncError) {
+            Logger.error('Failed to sync feeds, falling back to local feeds', syncError);
+          }
+        }
+        await mcpManager.initialize();
+
+        Logger.debug({
+          action: 'ensuring_feeds_directory',
+          path: LOCAL_FEEDS_DIR
+        });
+
+        // Ensure feeds directory exists
+        await fs.mkdir(LOCAL_FEEDS_DIR, { recursive: true });
+
+        // Read all json files from feeds directory
+        Logger.debug('Reading feed files from directory...');
+        const files = await fs.readdir(LOCAL_FEEDS_DIR);
+        const jsonFiles = files.filter(file => file.endsWith('.json'));
+
+        Logger.debug({
+          action: 'found_feed_files',
+          count: jsonFiles.length,
+          files: jsonFiles
+        });
+
+        const feeds: SimplifiedFeed[] = [];
+
+        // Process each json file
+        for (const file of jsonFiles) {
+          Logger.debug(`Processing feed file: ${file}`);
+          try {
+            const filePath = path.join(LOCAL_FEEDS_DIR, file);
+            const content = await fs.readFile(filePath, 'utf8');
+            const feedConfig = JSON.parse(content);
+
+            Logger.debug({
+              action: 'processing_feed',
+              file,
+              feedName: feedConfig.name,
+              serverCount: feedConfig.mcpServers?.length ?? 0
+            });
+
+            // Extract only needed information
+            const simplifiedFeed: SimplifiedFeed = {
+              name: feedConfig.name,
+              displayName: feedConfig.displayName,
+              description: feedConfig.description,
+              mcpServers: feedConfig.mcpServers.map((server: any) => ({
+                name: server.name,
+                description: server.description
+              }))
+            };
+
+            feeds.push(simplifiedFeed);
+            Logger.debug(`Successfully processed feed: ${feedConfig.name}`);
+          } catch (error) {
+            Logger.error(`Failed to process feed file: ${file}`, error);
+          }
+        }
+
+        if (feeds.length === 0) {
+          Logger.log('No feeds found.');
+          return;
+        }
+
+        Logger.debug({
+          action: 'completed_processing',
+          totalFeeds: feeds.length,
+          totalServers: feeds.reduce((acc, feed) => acc + feed.mcpServers.length, 0)
+        });
+
+        // Output as formatted JSON
+        console.log(JSON.stringify(feeds, null, 2));
+      } catch (error) {
+        Logger.error('Failed to list servers', error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/pull.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import { serverService } from '../../services/ServerService.js';
+
+export function createPullCommand(): Command {
+  return new Command('pull')
+    .description('Pull MCP server configurations from remote feed source')
+    .action(async () => {
+      try {
+        await serverService.syncFeeds();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        console.error('Error syncing configurations:', message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/serve.ts

@@ -0,0 +1,39 @@
+import { Command } from 'commander';
+import { startWebServer } from '../../web/server.js';
+import { mcpManager } from '../../services/MCPManager.js';
+import { checkGithubAuth } from '../../utils/githubAuth.js';
+import { Logger } from '../../utils/logger.js';
+
+export function createServeCommand(): Command {
+  return new Command('serve')
+    .description('Serve local web interface')
+    .option('-p, --port <port>', 'Port to run the server on', '3000')
+    .option('-f, --feed-file <filepath>', 'Path to a custom feed configuration file')
+    .option('-s, --schemas-directory <path>', 'Path to a directory containing adhoc schema files')
+    .action(async (options) => {
+      try {
+        // Sync feeds before start the local UI
+        await mcpManager.syncFeeds();
+
+        // Ensure MCP manager is initialized before starting the web server
+        await mcpManager.initialize(options.feedFile, options.schemasDirectory);
+
+        const port = parseInt(options.port, 10);
+        if (isNaN(port) || port < 1 || port > 65535) {
+          throw new Error('Invalid port number');
+        }
+
+        await startWebServer(port);
+
+        // The server is running, keep the process alive
+        process.on('SIGINT', () => {
+          console.log('\nShutting down server...');
+          process.exit(0);
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        console.error('Failed to start web server:', message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/uninstall.ts

@@ -0,0 +1,64 @@
+import { Command } from 'commander';
+import { serverService } from '../../services/ServerService.js';
+
+export function createUninstallCommand(): Command {
+  return new Command('uninstall')
+    .description('Uninstall specific MCP servers')
+    .requiredOption(
+      '--category <category>',
+      'Server category'
+    )
+    .requiredOption(
+      '--names <names>',
+      'Server names (semicolon separated)'
+    )
+    .requiredOption(
+      '--targets <targets>',
+      'Target clients to uninstall from (semicolon separated)'
+    )
+    .option(
+      '--remove-data',
+      'Remove all associated data',
+      true  // Change default to true to ensure cleanup happens
+    )
+    .action(async (options) => {
+      try {
+        const serverNames = options.names.split(';').map((name: string) => name.trim());
+
+        const validNames = await serverService.validateServerName(options.category, serverNames);
+        if (!validNames) {
+          console.error('Invalid server names provided');
+          process.exit(1);
+        }
+
+        console.log(`Uninstalling servers: ${serverNames.join(', ')}`);
+
+        const results = await Promise.all(
+          serverNames.map((serverName: string) => {
+            const targets = options.targets ? options.targets.split(';').map((t: string) => t.trim()) : [];
+            return serverService.uninstallMcpServer(options.category, serverName, {
+              removeData: options.removeData,
+              targets: targets
+            });
+          })
+        );
+
+        const { success, messages } = serverService.formatOperationResults(results);
+        messages.forEach(message => {
+          if (success) {
+            console.log(`✓ ${message}`);
+          } else {
+            console.error(`✗ ${message}`);
+          }
+        });
+
+        if (!success) {
+          process.exit(1);
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        console.error('Uninstallation failed:', message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/index.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { createServeCommand } from './commands/serve.js';
+import { createListCommand } from './commands/list.js';
+import { createInstallCommand } from './commands/install.js';
+import { createUninstallCommand } from './commands/uninstall.js';
+import { createPullCommand } from './commands/pull.js';
+import { mcpManager } from '../services/MCPManager.js';
+import { Logger } from '../utils/logger.js';
+import { checkForUpdates } from '../utils/versionUtils.js';
+
+// Custom error interface for Commander.js errors
+interface CommanderError extends Error {
+  code?: string;
+}
+
+async function main(): Promise<void> {
+  // Initialize the MCP manager
+  // await mcpManager.initialize();
+
+  const program = new Command();
+  program
+    .name('imcp')
+    .description('IMCP (Install Model Context Protocol) CLI')
+    .option('--verbose', 'Show detailed logs for all commands');
+
+  // Parse global options first
+  program.parseOptions(process.argv);
+  const opts = program.opts();
+  Logger.setVerbose(!!opts.verbose);
+
+  // Add all commands
+  program.addCommand(createServeCommand());
+  // program.addCommand(createListCommand());
+  // program.addCommand(createInstallCommand());
+  // program.addCommand(createUninstallCommand());
+  // program.addCommand(createPullCommand());
+
+  // Error handling for the entire CLI
+  program.exitOverride();
+
+  // Check for updates
+  await checkForUpdates();
+
+  try {
+    await program.parseAsync(process.argv);
+  } catch (error) {
+    const commanderError = error as CommanderError;
+
+    if (commanderError.code === 'commander.help') {
+      // Help was displayed, exit normally
+      process.exit(0);
+    } else if (commanderError.code === 'commander.version') {
+      // Version was displayed, exit normally
+      process.exit(0);
+    } else {
+      console.error('Error:', commanderError.message || 'An unknown error occurred');
+      process.exit(1);
+    }
+  }
+}
+
+// Handle unhandled promise rejections
+process.on('unhandledRejection', (error: unknown) => {
+  if (error instanceof Error) {
+    console.error('Unhandled promise rejection:', error.message);
+  } else {
+    console.error('Unhandled promise rejection:', error);
+  }
+  process.exit(1);
+});
+
+// Start the CLI
+main().catch((error: unknown) => {
+  if (error instanceof Error) {
+    console.error('Fatal error:', error.message);
+  } else {
+    console.error('Fatal error:', error);
+  }
+  process.exit(1);
+});