fusion-mcp-cli/README.md

CLI tool for Fusion MCP Hub - Manage custom and community MCP servers. Web App: https://fusion-mcp-hub.vercel.app (General) | https://fusion-mcp-prod.isc-code-connect.dal.app.cirrus.ibm.com (IBM)

# Fusion MCP CLI

[![npm version](https://img.shields.io/npm/v/fusion-mcp-cli.svg)](https://www.npmjs.com/package/fusion-mcp-cli)
[![npm downloads](https://img.shields.io/npm/dm/fusion-mcp-cli.svg)](https://www.npmjs.com/package/fusion-mcp-cli)

Command-line interface for managing Fusion MCP custom servers with automated configuration for AI tools.

**📦 Published on npm**: https://www.npmjs.com/package/fusion-mcp-cli

## 🌐 Fusion MCP Hub Applications

This CLI connects to the Fusion MCP Hub web application for managing MCP servers:

- **IBM Employees**: https://fusion-mcp-prod.isc-code-connect.dal.app.cirrus.ibm.com
- **General Users**: https://fusion-mcp-hub.vercel.app/

The web application provides:
- Browse and search 16+ community MCP servers
- Create and manage custom server compositions
- Visual server configuration and deployment
- Team workspace management
- API token generation for CLI access

## Installation

### For Users

#### Option 1: Use npx (Recommended - No Installation Needed)

```bash
# Run directly without installation
npx fusion-mcp-cli auth login
npx fusion-mcp-cli server list

# Create an alias for convenience (add to ~/.zshrc or ~/.bashrc)
alias fmcp="npx fusion-mcp-cli"
```

#### Option 2: Install Globally

```bash
# Install from npm
npm install -g fusion-mcp-cli

# Verify installation
fmcp --version
```

**Note:** If you get permission errors (EACCES) on macOS/Linux:
- Use `npx fusion-mcp-cli` instead (no installation needed), or
- Configure npm to use your home directory: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

### For Local Development

```bash
# Clone the repository
git clone https://github.ibm.com/BPManagementTools/fusion-mcp-cli.git
cd fusion-mcp-cli

# Install dependencies
npm install

# Build the CLI
npm run build

# Link globally for development
npm link

# Now you can use the CLI
fmcp --help
```

## Features

- ✅ **Server Management**: Pull, push, and sync MCP servers
- ✅ **Community Servers**: Browse, search, and install pre-configured MCP servers
- ✅ **Installation Automation**: Automatic dependency installation (npm/git)
- ✅ **Multi-Tool Config**: Automated configuration for Claude Desktop, IBM Bob IDE, and GitHub Copilot Chat
- ✅ **Project & Global Config**: Support for both project-level and global configurations
- ✅ **Version Control**: History tracking and rollback support
- ✅ **Authentication**: API Token-based authentication
- ✅ **Workspace Management**: Multi-workspace support

## Quick Start

### 1. Run with npx (No Installation)

```bash
# Check version
npx fusion-mcp-cli --version

# View all commands
npx fusion-mcp-cli --help

# Login to Fusion MCP Hub (URL required)
npx fusion-mcp-cli auth login -u https://fusion-mcp-hub.vercel.app

# List workspaces
npx fusion-mcp-cli workspace list
```

**Tip**: Create an alias for convenience:
```bash
# Add to ~/.zshrc or ~/.bashrc
alias fmcp="npx fusion-mcp-cli"

# Now you can use:
fmcp auth login -u https://fusion-mcp-hub.vercel.app
fmcp server list
```

### 2. Authentication

```bash
# Login to Fusion MCP Hub (using npx or installed version)
npx fusion-mcp-cli auth login

# For IBM employees, use the IBM URL
npx fusion-mcp-cli auth login -u https://fusion-mcp-prod.isc-code-connect.dal.app.cirrus.ibm.com

# For general users, use the public URL (default)
npx fusion-mcp-cli auth login -u https://fusion-mcp-hub.vercel.app

# Check authentication status
npx fusion-mcp-cli auth status
```

### 3. Server Management

```bash
# List available servers
npx fusion-mcp-cli server list

# Pull a server (with automatic installation)
npx fusion-mcp-cli server pull <server-id> --install

# Or pull and install separately
npx fusion-mcp-cli server pull <server-id>
npx fusion-mcp-cli server install <server-id>

# View server information
npx fusion-mcp-cli server info <server-id>

# Check sync status
npx fusion-mcp-cli server status <server-id>

# Push local changes
npx fusion-mcp-cli server push <server-id>
```

### 4. AI Tool Configuration

The CLI automatically configures your AI tools - just run:

```bash
# Add server to Claude Desktop, Bob IDE, and/or Copilot Chat
npx fusion-mcp-cli config add <server-id>

# The CLI will:
# 1. Detect which tools are installed
# 2. Show you which tools it found
# 3. Ask which tools you want to configure
# 4. Automatically update all selected tool configs
```

#### Manual Configuration Examples

```bash
# List configured servers
npx fusion-mcp-cli config list

# Remove a server configuration
npx fusion-mcp-cli config remove <server-id>

# Validate configuration
npx fusion-mcp-cli config validate

# Remove server
fmcp config remove <server-name> --tool claude
```

#### IBM Bob IDE

```bash
# Add to Bob IDE (Global)
fmcp config add <server-id> --tool bob

# Add to Bob IDE (Project-level)
fmcp config add <server-id> --tool bob --project

# List Bob IDE servers
fmcp config list --tool bob --project

# Show Bob IDE config path
fmcp config path --tool bob --project

# Remove from Bob IDE
fmcp config remove <server-name> --tool bob --project
```

#### GitHub Copilot Chat (VS Code)

```bash
# Add to Copilot (User-wide)
fmcp config add <server-id> --tool copilot

# Add to Copilot (Project-level)
fmcp config add <server-id> --tool copilot --project

# List Copilot servers
fmcp config list --tool copilot

# Show Copilot config path
fmcp config path --tool copilot --project

# Remove from Copilot
fmcp config remove <server-name> --tool copilot
```

### 4. Transport Options

```bash
# Use stdio transport (default)
fmcp config add <server-id> --tool claude --transport stdio

# Use HTTP transport
fmcp config add <server-id> --tool claude --transport http --port 3000
```

## Community Servers

Browse and install pre-configured MCP servers from the community.

### Browse Community Servers

```bash
# List all community servers
fmcp community list

# Filter by category
fmcp community list --category development

# Filter by language
fmcp community list --language typescript

# Search servers
fmcp community search "github"

# Sort by popularity, rating, or recent
fmcp community list --sort popularity
fmcp community list --sort rating
```

### Get Server Information

```bash
# Show detailed information about a server
fmcp community info notion

# View tools, features, setup instructions, and more
fmcp community info hugging-face
```

### Install Community Servers

```bash
# Install a community server
fmcp community install <server-name>

# Install and configure for Claude Desktop
fmcp community install notion --tool claude

# Install and configure for Bob IDE (project-level)
fmcp community install github --tool bob --project

# Install and configure for Copilot
fmcp community install salesforce --tool copilot

# Skip dependency installation (for remote servers)
fmcp community install mongodb --skip-deps
```

### Configure Installed Servers

```bash
# Configure a server for AI tools (without reinstalling)
fmcp community configure <server-name> --tool claude

# Configure for project-level (Bob/Copilot)
fmcp community configure <server-name> --tool bob --project
```

### List Installed Servers

```bash
# Show all installed community servers
fmcp community installed

# Show only installed servers in main list
fmcp community list --installed
```

### Community Server Types

**Local Servers** (require installation):
- NPM packages: Installed via `npm install`
- GitHub repos: Cloned via `git clone`
- Automatically installs dependencies

**Remote Servers** (no installation needed):
- Hosted MCP servers
- Just configure in AI tools
- No local setup required

## Complete Workflow Example

```bash
# 1. Authenticate
fmcp auth login

# === CUSTOM SERVERS ===
# 2. Find and pull a custom server
fmcp server list
fmcp server pull my-custom-server --install

# 3. Configure for your AI tool
fmcp config add my-custom-server --tool claude

# 4. Restart Claude Desktop to use the server

# 5. Later, push updates
fmcp server push my-custom-server

# === COMMUNITY SERVERS ===
# 6. Browse community servers
fmcp community list --sort popularity

# 7. Get server details
fmcp community info notion

# 8. Install and configure
fmcp community install notion --tool claude

# 9. View installed servers
fmcp community installed
```

## Configuration Files

The CLI manages configurations in multiple locations:

### CLI Config

`~/.fusion-mcp/config.json`

```json
{
  "apiUrl": "https://fusion-mcp-hub.vercel.app",
  "apiToken": "mcp_your_token_here",
  "currentWorkspace": "workspace-id"
}
```

### AI Tool Configurations

**Claude Desktop (macOS):**

- `~/Library/Application Support/Claude/claude_desktop_config.json`

**IBM Bob IDE (macOS):**

- Global: `~/Library/Application Support/Bob-IDE/User/globalStorage/ibm.bob-code/settings/mcp_settings.json`
- Project: `<project>/.Bob/mcp.json`

**GitHub Copilot Chat (VS Code - macOS):**

- User-wide: `~/.config/Code/User/settings.json`
- Project: `<project>/.vscode/mcp.json`

## Command Reference

### Authentication Commands

```bash
# Login with API token (URL required)
fmcp auth login -u https://fusion-mcp-hub.vercel.app -t <your-token>

# For IBM Cirrus deployment
fmcp auth login -u https://your-cirrus-instance.ibm.com -t <your-token>

# For local development
fmcp auth login -u http://localhost:3000 -t <your-token>

# Logout and clear token
fmcp auth logout

# Check authentication status
fmcp auth status
```

### Workspace Commands

```bash
fmcp workspace list          # List available workspaces
fmcp workspace use <id>      # Switch to a workspace
fmcp workspace current       # Show current workspace
```

### Server Commands

```bash
fmcp server list                    # List all servers
fmcp server pull <id>               # Pull server to local
fmcp server pull <id> --install     # Pull and install dependencies
fmcp server install <id>            # Install server dependencies
fmcp server push <id>               # Push local changes
fmcp server status <id>             # Check sync status
fmcp server diff <id>               # View differences
fmcp server merge <id>              # Interactive merge
fmcp server history <id>            # View change history
fmcp server rollback <id> <ver>     # Rollback to version
fmcp server info <id>               # Show server details
```

### Config Commands

```bash
# Add server to AI tool
fmcp config add <server-id> [options]
  --tool <tool>          # claude, bob, copilot (default: claude)
  --project              # Use project-level config (Bob/Copilot)
  --transport <type>     # stdio or http (default: stdio)
  --port <port>          # Port for HTTP transport (default: 3000)
  --force                # Overwrite existing config
  -d, --dir <path>       # Server directory (auto-detect if not set)

# List configured servers
fmcp config list [options]
  --tool <tool>          # claude, bob, copilot (default: claude)
  --project              # List project-level config (Bob/Copilot)

# Remove server from config
fmcp config remove <server-name> [options]
  --tool <tool>          # claude, bob, copilot (default: claude)
  --project              # Remove from project-level config

# Show config file path
fmcp config path [options]
  --tool <tool>          # claude, bob, copilot (default: claude)
  --project              # Show project-level config path

# Open config in editor
fmcp config edit [options]
  --tool <tool>          # claude, bob, copilot (default: claude)
  --project              # Edit project-level config
```

## Architecture

The CLI uses a modular adapter pattern for AI tool configurations:

```
src/commands/config/
├── index.ts              # Main config commands
├── types.ts              # Shared types
├── utils.ts              # Helper utilities
└── adapters/
    ├── index.ts          # Adapter factory
    ├── claude.ts         # Claude Desktop adapter
    ├── bob.ts            # IBM Bob IDE adapter
    └── copilot.ts        # GitHub Copilot Chat adapter
```

Each adapter implements the `ToolAdapter` interface, making it easy to add support for new AI tools.

## Development

```bash
# Run in development mode
npm run dev

# Build
npm run build

# Watch mode
npm run watch

# Link globally for testing
npm link
```

## 🌐 Related Resources

### Fusion MCP Hub Web Application

Access the full-featured web application for visual server management:

**For IBM Employees:**
- URL: https://fusion-mcp-prod.isc-code-connect.dal.app.cirrus.ibm.com
- Features: Enterprise authentication, team workspaces, custom server composition

**For General Users:**
- URL: https://fusion-mcp-hub.vercel.app/
- Features: Community server browsing, API token management, server documentation

### Documentation

- **CLI Documentation**: This README
- **Technical Implementation**: [COMMUNITY-SERVERS.md](./COMMUNITY-SERVERS.md)
- **Release Process**: [RELEASE.md](./RELEASE.md)
- **Web App**: Visit the links above for in-app documentation

### Support

- **Issues**: Report bugs or request features via GitHub issues
- **Email**: kirtijha@in.ibm.com
- **Web App**: Use the feedback form in the Fusion MCP Hub application

## Troubleshooting

### Config file not found

Make sure the AI tool is installed and has been run at least once. The CLI will show the expected file location.

### Permission denied

On macOS/Linux, you may need to grant permission to access configuration directories.

### Server not found after pull

Use `fmcp server list` to verify the server exists and check the server ID.

### Dependencies installation failed

Run `fmcp server install <server-id>` manually to see detailed error messages.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT