@evolvedqube/gmcp 0.1.0-alpha.5

package/README.md

@@ -0,0 +1,245 @@
+# gmcp - Global MCP Config Manager
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Tested%20on-macOS-2e7d32?style=for-the-badge&logo=apple&logoColor=white" alt="Tested on macOS"/>
+  <img src="https://img.shields.io/badge/Windows%20support-coming%20soon-bdbdbd?style=for-the-badge&logo=windows&logoColor=white" alt="Windows support coming soon"/>
+</p>
+
+Manage MCP (Model Context Protocol) server configurations across Claude Code, Copilot CLI, and Windsurf from a single command-line interface. Stop manually editing config files for each platform.
+
+## Installation
+
+```bash
+npm install -g gmcp
+```
+
+## Quick Start
+
+```bash
+# First time setup - select your platforms
+gmcp init
+
+# Browse available servers
+gmcp market
+
+# Add a server to all configured platforms
+gmcp add fetch
+
+# See what's installed
+gmcp list
+
+# Remove a server
+gmcp remove fetch
+
+# Update gmcp
+gmcp update
+```
+
+## Supported Platforms
+
+- **Claude Code** (`~/.claude.json`)
+- **Copilot CLI** (`~/.copilot/mcp-config.json`)
+- **Windsurf** (`~/.codeium/windsurf/mcp_config.json`)
+
+## All Commands
+
+### `gmcp init`
+
+Interactive setup to select which platforms you want to manage.
+
+```bash
+gmcp init
+```
+
+### `gmcp platforms`
+
+Display configured platforms and their detection status.
+
+```bash
+gmcp platforms
+```
+
+### `gmcp market`
+
+Browse all available MCP servers from the registry. Results paginate in groups of 20.
+
+```bash
+gmcp market
+```
+
+### `gmcp search <query>`
+
+Search for a server by name.
+
+```bash
+gmcp search github
+gmcp search filesystem
+gmcp search database
+```
+
+### `gmcp add <name>`
+
+Add a server to your configured platforms.
+
+```bash
+# Add to all configured platforms
+gmcp add fetch
+
+# Add to specific platforms only
+gmcp add github --only claude-code,windsurf
+```
+
+If a server offers multiple runtimes (npm or Docker), you'll be prompted to choose:
+
+```
+This server offers multiple runtimes:
+  1. npm (via npx)
+  2. Docker (via OCI)
+
+Select runtime: _
+```
+
+### `gmcp add --manual`
+
+Add a custom server that's not in the registry. You'll be prompted for the server details.
+
+```bash
+gmcp add --manual
+```
+
+Interactive flow:
+
+```
+Server name: my-custom-server
+Command: npx
+Arguments: @myorg/custom-server
+```
+
+This adds your custom server to all configured platforms. To target specific platforms:
+
+```bash
+gmcp add --manual --only claude-code,windsurf
+```
+
+**Use cases:**
+- Internal company MCP servers
+- Local development servers
+- Servers from private registries
+- Experimental or forked servers
+
+### `gmcp remove <name>`
+
+Remove a server from your platforms (with confirmation).
+
+```bash
+# Remove from all platforms
+gmcp remove fetch
+
+# Remove from specific platforms only
+gmcp remove github --only claude-code
+```
+
+### `gmcp list`
+
+View all installed servers and their status on each platform.
+
+```bash
+gmcp list
+```
+
+Output example:
+
+```
+MCP Servers:
+
+Server       Claude Code  Copilot CLI  Windsurf
+─────────────────────────────────────────────────
+fetch        active       active       —
+github       active       —            active
+filesystem   disabled     active       active
+```
+
+### `gmcp sync`
+
+Sync servers across platforms. Shows servers installed on some platforms but missing on others, then lets you selectively add them everywhere. Safe to run multiple times.
+
+```bash
+gmcp sync
+```
+
+### `gmcp enable <name>` / `gmcp disable <name>`
+
+Enable or disable a server on your platforms.
+
+```bash
+gmcp enable fetch
+gmcp disable github
+```
+
+**Note:** Only Windsurf fully supports the disable flag. Other platforms will ignore it.
+
+### `gmcp update`
+
+Update gmcp to the latest version.
+
+```bash
+gmcp update
+```
+
+## Important: Server Names
+
+Server names in the registry are automatically cleaned up for cross-platform compatibility:
+
+- `io.github.upstash/context7` → `context7`
+- `ai.smithery/example-server` → `example-server`
+- `server.name` → `server-name`
+
+Always use the cleaned name when removing or managing servers:
+
+```bash
+gmcp add io.github.upstash/context7  # Adds as "context7"
+gmcp list                             # Shows "context7"
+gmcp remove context7                  # Use the cleaned name
+```
+
+## Requirements
+
+- **Network access required** for: `add`, `search`, `market` commands
+- **Offline OK** for: `list`, `remove`, `sync`, `enable`, `disable` commands
+
+gmcp fetches server data from the official MCP Registry API. Ensure you have an active internet connection for registry operations.
+
+## Supported Runtimes
+
+Servers can run via:
+
+- **npm (npx)** - Installed via npm registry
+- **Docker** - Runs as OCI container
+
+gmcp will prompt you to choose if a server supports both options.
+
+## Troubleshooting
+
+### Cannot reach the MCP Registry API
+
+```
+Error: Cannot reach MCP Registry API. Check your internet connection.
+```
+
+Ensure you have internet access and the API is reachable.
+
+### Registry API temporarily unavailable
+
+```
+Error: Registry API is temporarily unavailable. Try again later.
+```
+
+Try again in a few moments.
+
+### Works offline
+
+Commands that don't need the registry (`list`, `remove`, `sync`, `enable`, `disable`) work without internet.
+
+## License
+
+MIT

package/dist/adapters/claude-code.js

@@ -0,0 +1,48 @@
+import * as fs from 'fs';
+import { readJsonFile, writeJsonFile, expandHomeDir } from '../utils.js';
+export class ClaudeCodeAdapter {
+    constructor() {
+        this.name = 'claude-code';
+    }
+    configPath() {
+        return expandHomeDir('~/.claude.json');
+    }
+    detect() {
+        return fs.existsSync(this.configPath());
+    }
+    readServers() {
+        const config = readJsonFile(this.configPath());
+        const servers = new Map();
+        if (config.mcpServers) {
+            for (const [name, entry] of Object.entries(config.mcpServers)) {
+                servers.set(name, entry);
+            }
+        }
+        return servers;
+    }
+    addServer(name, definition, env) {
+        const config = readJsonFile(this.configPath());
+        if (!config.mcpServers) {
+            config.mcpServers = {};
+        }
+        config.mcpServers[name] = {
+            command: definition.runtime,
+            args: definition.args,
+            ...(Object.keys(env).length > 0 && { env }),
+        };
+        writeJsonFile(this.configPath(), config);
+    }
+    removeServer(name) {
+        const config = readJsonFile(this.configPath());
+        if (config.mcpServers && config.mcpServers[name]) {
+            delete config.mcpServers[name];
+            writeJsonFile(this.configPath(), config);
+        }
+    }
+    enableServer(name) {
+        return null;
+    }
+    disableServer(name) {
+        return null;
+    }
+}

package/dist/adapters/copilot-cli.js

@@ -0,0 +1,49 @@
+import * as fs from 'fs';
+import { readJsonFile, writeJsonFile, expandHomeDir } from '../utils.js';
+export class CopilotCliAdapter {
+    constructor() {
+        this.name = 'copilot-cli';
+    }
+    configPath() {
+        return expandHomeDir('~/.copilot/mcp-config.json');
+    }
+    detect() {
+        return fs.existsSync(this.configPath());
+    }
+    readServers() {
+        const config = readJsonFile(this.configPath());
+        const servers = new Map();
+        if (config.mcpServers) {
+            for (const [name, entry] of Object.entries(config.mcpServers)) {
+                servers.set(name, entry);
+            }
+        }
+        return servers;
+    }
+    addServer(name, definition, env) {
+        const config = readJsonFile(this.configPath());
+        if (!config.mcpServers) {
+            config.mcpServers = {};
+        }
+        config.mcpServers[name] = {
+            type: 'stdio',
+            command: definition.runtime,
+            args: definition.args,
+            env: env,
+        };
+        writeJsonFile(this.configPath(), config);
+    }
+    removeServer(name) {
+        const config = readJsonFile(this.configPath());
+        if (config.mcpServers && config.mcpServers[name]) {
+            delete config.mcpServers[name];
+            writeJsonFile(this.configPath(), config);
+        }
+    }
+    enableServer(name) {
+        return null;
+    }
+    disableServer(name) {
+        return null;
+    }
+}

package/dist/adapters/index.js

@@ -0,0 +1,14 @@
+import { ClaudeCodeAdapter } from './claude-code.js';
+import { CopilotCliAdapter } from './copilot-cli.js';
+import { WindsurfAdapter } from './windsurf.js';
+export const adapters = {
+    'claude-code': new ClaudeCodeAdapter(),
+    'copilot-cli': new CopilotCliAdapter(),
+    'windsurf': new WindsurfAdapter(),
+};
+export function getAdapter(platform) {
+    return adapters[platform];
+}
+export function getAllAdapters() {
+    return Object.values(adapters);
+}

package/dist/adapters/windsurf.js

@@ -0,0 +1,59 @@
+import * as fs from 'fs';
+import { readJsonFile, writeJsonFile, expandHomeDir } from '../utils.js';
+export class WindsurfAdapter {
+    constructor() {
+        this.name = 'windsurf';
+    }
+    configPath() {
+        return expandHomeDir('~/.codeium/windsurf/mcp_config.json');
+    }
+    detect() {
+        return fs.existsSync(this.configPath());
+    }
+    readServers() {
+        const config = readJsonFile(this.configPath());
+        const servers = new Map();
+        if (config.mcpServers) {
+            for (const [name, entry] of Object.entries(config.mcpServers)) {
+                servers.set(name, entry);
+            }
+        }
+        return servers;
+    }
+    addServer(name, definition, env) {
+        const config = readJsonFile(this.configPath());
+        if (!config.mcpServers) {
+            config.mcpServers = {};
+        }
+        config.mcpServers[name] = {
+            command: definition.runtime,
+            args: definition.args,
+            disabled: false,
+            env: env,
+        };
+        writeJsonFile(this.configPath(), config);
+    }
+    removeServer(name) {
+        const config = readJsonFile(this.configPath());
+        if (config.mcpServers && config.mcpServers[name]) {
+            delete config.mcpServers[name];
+            writeJsonFile(this.configPath(), config);
+        }
+    }
+    enableServer(name) {
+        const config = readJsonFile(this.configPath());
+        if (!config.mcpServers || !config.mcpServers[name]) {
+            return null;
+        }
+        config.mcpServers[name].disabled = false;
+        writeJsonFile(this.configPath(), config);
+    }
+    disableServer(name) {
+        const config = readJsonFile(this.configPath());
+        if (!config.mcpServers || !config.mcpServers[name]) {
+            return null;
+        }
+        config.mcpServers[name].disabled = true;
+        writeJsonFile(this.configPath(), config);
+    }
+}

package/dist/api-client.js

@@ -0,0 +1,88 @@
+/**
+ * API client for the official MCP Registry
+ * https://registry.modelcontextprotocol.io
+ */
+export const API_BASE_URL = 'https://registry.modelcontextprotocol.io/v0.1';
+/**
+ * Fetch all servers from the MCP Registry API with pagination
+ */
+export async function fetchServers() {
+    const servers = [];
+    let cursor = null;
+    do {
+        const url = cursor
+            ? `${API_BASE_URL}/servers?limit=100&cursor=${encodeURIComponent(cursor)}`
+            : `${API_BASE_URL}/servers?limit=100`;
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                if (response.status >= 500) {
+                    throw new Error('Registry API is temporarily unavailable. Please try again later.\n' +
+                        'If the issue persists, check: https://status.modelcontextprotocol.io');
+                }
+                throw new Error(`Registry API returned status ${response.status}.\n` +
+                    'Please try again or check: https://status.modelcontextprotocol.io');
+            }
+            const data = await response.json();
+            // Extract servers from response
+            for (const item of data.servers) {
+                servers.push(item.server);
+            }
+            cursor = data.metadata.nextCursor || null;
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message.includes('fetch')) {
+                throw new Error('Cannot reach MCP Registry API. Check your internet connection.\n' +
+                    'Note: You can still use `gmcp list`, `gmcp remove`, and `gmcp sync` offline.');
+            }
+            if (error instanceof SyntaxError) {
+                throw new Error('Received invalid data from Registry API.\n' +
+                    'This may indicate an API issue. Please try again or report at:\n' +
+                    'https://github.com/modelcontextprotocol/registry');
+            }
+            throw error;
+        }
+    } while (cursor);
+    return servers;
+}
+/**
+ * Search servers by name using the API search endpoint
+ */
+export async function searchServers(query) {
+    const servers = [];
+    let cursor = null;
+    do {
+        const url = cursor
+            ? `${API_BASE_URL}/servers?search=${encodeURIComponent(query)}&limit=100&cursor=${encodeURIComponent(cursor)}`
+            : `${API_BASE_URL}/servers?search=${encodeURIComponent(query)}&limit=100`;
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                if (response.status >= 500) {
+                    throw new Error('Registry API is temporarily unavailable. Please try again later.\n' +
+                        'If the issue persists, check: https://status.modelcontextprotocol.io');
+                }
+                throw new Error(`Registry API returned status ${response.status}.\n` +
+                    'Please try again or check: https://status.modelcontextprotocol.io');
+            }
+            const data = await response.json();
+            for (const item of data.servers) {
+                servers.push(item.server);
+            }
+            cursor = data.metadata.nextCursor || null;
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message.includes('fetch')) {
+                throw new Error('Cannot reach MCP Registry API. Check your internet connection.\n' +
+                    'Note: You can still use `gmcp list`, `gmcp remove`, and `gmcp sync` offline.');
+            }
+            if (error instanceof SyntaxError) {
+                throw new Error('Received invalid data from Registry API.\n' +
+                    'This may indicate an API issue. Please try again or report at:\n' +
+                    'https://github.com/modelcontextprotocol/registry');
+            }
+            throw error;
+        }
+    } while (cursor);
+    return servers;
+}

package/dist/cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { isInitialized } from './config.js';
+import { initCommand } from './commands/init.js';
+import { addCommand } from './commands/add.js';
+import { removeCommand } from './commands/remove.js';
+import { listCommand } from './commands/list.js';
+import { searchCommand } from './commands/search.js';
+import { enableCommand, disableCommand } from './commands/enable-disable.js';
+import { syncCommand } from './commands/sync.js';
+import { updateCommand } from './commands/update.js';
+import { platformsCommand } from './commands/platforms.js';
+import { marketCommand } from './commands/market.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+const program = new Command();
+program
+    .name('gmcp')
+    .description('Global MCP config manager - manage MCP servers across platforms')
+    .version(packageJson.version);
+function validateOS(commandName) {
+    if (commandName !== 'init') {
+        return;
+    }
+    if (process.platform !== 'darwin' && process.platform !== 'win32') {
+        console.error('Error: gmcp only supports macOS and Windows');
+        process.exit(1);
+    }
+}
+function requireInit(commandName) {
+    if (commandName === 'init' || commandName === 'update' || commandName === 'platforms') {
+        return;
+    }
+    if (!isInitialized()) {
+        console.error('No platforms configured. Run `gmcp init` first.');
+        process.exit(1);
+    }
+}
+program.hook('preAction', (_thisCommand, actionCommand) => {
+    validateOS(actionCommand.name());
+    requireInit(actionCommand.name());
+});
+program
+    .command('init')
+    .description('Select platforms to manage with gmcp')
+    .action(initCommand);
+program
+    .command('add [name]')
+    .description('Add an MCP server from the API registry (npm/Docker packages). Prompts for package type if multiple options available.')
+    .option('--only <platforms>', 'Only add to specific platforms (comma-separated, e.g., "claude-code,windsurf")')
+    .option('--manual', 'Manually add a server (not from registry). Detects duplicates by command/args.')
+    .action(addCommand);
+program
+    .command('remove <name>')
+    .description('Remove an MCP server from platforms')
+    .option('--only <platforms>', 'Only remove from specific platforms (comma-separated, e.g., "claude-code,windsurf")')
+    .action(removeCommand);
+program
+    .command('list')
+    .description('List all MCP servers across platforms')
+    .action(listCommand);
+program
+    .command('platforms')
+    .description('Display configured platforms and their detection status')
+    .action(platformsCommand);
+program
+    .command('search <query>')
+    .description('Search MCP servers by name using the API. Shows local packages (npm/Docker) with interactive install.')
+    .action(searchCommand);
+program
+    .command('market')
+    .description('Browse all MCP servers from the API registry (200+ servers). Paginated display with interactive install.')
+    .action(marketCommand);
+program
+    .command('enable <name>')
+    .description('Enable an MCP server (Windsurf only)')
+    .action(enableCommand);
+program
+    .command('disable <name>')
+    .description('Disable an MCP server (Windsurf only)')
+    .action(disableCommand);
+program
+    .command('sync')
+    .description('Sync MCP servers across platforms')
+    .action(syncCommand);
+program
+    .command('update')
+    .description('Update gmcp to the latest version')
+    .action(updateCommand);
+program.parse();