fusion-mcp-cli/COMMUNITY-SERVERS.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)

# Community Servers Feature

## Overview

The Fusion MCP CLI now supports browsing, installing, and configuring pre-configured community MCP servers alongside custom servers. This feature enables users to quickly discover and install from a curated collection of 16+ MCP servers.

## Implementation Summary

### Architecture

**Backend Integration:**
- Uses existing `/api/servers` endpoints from isc-code-connect-mcp-hub
- Fetches server data from MongoDB `mcp_servers` collection
- Supports filtering, search, and sorting

**CLI Structure:**
```
fusion-mcp-cli/
├── src/
│   ├── api/
│   │   └── client.ts                    # Added community server API methods
│   ├── commands/
│   │   ├── community.ts                 # NEW: Community server commands
│   │   ├── config/
│   │   │   └── index.ts                 # Added helper for community configs
│   │   ├── server.ts                    # Existing custom server commands
│   │   └── ...
│   ├── utils/
│   │   ├── community.ts                 # NEW: Installation & metadata utilities
│   │   └── ...
│   └── index.ts                         # Registered community command
```

### Key Components

#### 1. API Client Extensions (`src/api/client.ts`)

**New Interfaces:**
```typescript
interface CommunityServer {
  id: string;
  name: string;
  version: string;
  language: string;
  category: string;
  hostingType: "local" | "remote";
  npmPackage?: string;
  githubUrl?: string;
  tools: Tool[];
  configurationJson: ConfigurationJSON;
  // ... more fields
}

interface CommunityServerFilters {
  category?: string;
  language?: string;
  search?: string;
  sortBy?: "popularity" | "rating" | "recent" | "alphabetical";
  limit?: number;
  skip?: number;
}
```

**New Methods:**
```typescript
async listCommunityServers(filters): Promise<ApiResponse<CommunityServer[]>>
async getCommunityServer(serverId): Promise<ApiResponse<CommunityServer>>
```

#### 2. Community Commands (`src/commands/community.ts`)

**Available Commands:**

1. **`fmcp community list [options]`**
   - List all community servers
   - Options: `--category`, `--language`, `--search`, `--sort`, `--limit`, `--installed`
   - Displays table with name, category, language, hosting type, tools count, rating, downloads

2. **`fmcp community info <server-name>`**
   - Show detailed server information
   - Displays: description, version, author, tools, features, use cases, connection modes, statistics
   - Shows installation status and location if already installed

3. **`fmcp community search <query>`**
   - Search servers by name, description, or tags
   - Options: `--category`, `--language`, `--limit`

4. **`fmcp community install <server-name>`**
   - Install a community server
   - Options: `--tool <claude|bob|copilot>`, `--project`, `--skip-deps`
   - Handles npm packages, git repos, and remote servers
   - Automatically configures AI tools if `--tool` specified

5. **`fmcp community configure <server-name>`**
   - Configure installed/remote server for AI tools
   - Options: `--tool <claude|bob|copilot>`, `--project`
   - Adds server to tool's configuration file

6. **`fmcp community installed`**
   - List all installed community servers
   - Shows installation date, version, type, location

#### 3. Installation Utilities (`src/utils/community.ts`)

**Installation Strategies:**

1. **NPM Package Installation:**
   ```typescript
   async installNpmPackage(packageName, targetDir, skipDeps)
   ```
   - Creates package.json if needed
   - Runs `npm install <package>`
   - Installs to `~/.fusion-mcp/community/<server-id>`

2. **Git Clone Installation:**
   ```typescript
   async cloneGitRepo(repoUrl, targetDir, skipDeps)
   ```
   - Clones GitHub repository
   - Runs `npm install` if package.json exists
   - Stores in `~/.fusion-mcp/community/<server-id>`

3. **Remote Server (No Installation):**
   ```typescript
   async installCommunityServer(server, projectMode, skipDeps)
   ```
   - For `hostingType: "remote"`, only saves metadata
   - No local files downloaded
   - Configuration added directly to AI tools

**Metadata Management:**
```typescript
interface CommunityServerMetadata {
  serverId: string;
  serverType: "community";
  serverName: string;
  version: string;
  installedAt: string;
  npmPackage?: string;
  githubUrl?: string;
  installMethod?: "npm" | "git" | "remote";
  hostingType?: string;
}
```

Stored at: `~/.fusion-mcp/community/<server-id>/.fusion-mcp-metadata.json`

#### 4. Configuration Integration (`src/commands/config/index.ts`)

**New Helper Function:**
```typescript
async function addServerToToolConfig(
  tool: string,
  serverId: string,
  serverName: string,
  configurationJson?: ConfigurationJSON,
  projectMode?: boolean
)
```

**Integration with Existing Adapters:**
- Uses existing Claude, Bob, Copilot adapters
- Parses `configurationJson.local.configJson` from server metadata
- Converts to `ServerInfo` format for adapters
- Writes to appropriate tool config file

## Usage Examples

### Example 1: Browse and Install Notion Server

```bash
# Browse servers
fmcp community list --category productivity

# Get server details
fmcp community info notion

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

# Restart Claude Desktop
```

### Example 2: Search and Install GitHub Server

```bash
# Search for GitHub-related servers
fmcp community search github

# View detailed info
fmcp community info github

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

### Example 3: Configure Remote Server

```bash
# MongoDB is a remote server (no installation needed)
fmcp community info mongodb
# Shows: Hosting Type: Remote

# Just configure it for Copilot
fmcp community configure mongodb --tool copilot

# Server URL and credentials added to config
```

### Example 4: List Installed Servers

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

# Output:
# ✓ 3 Installed Community Servers
# ┌─────────────┬─────────┬────────┬────────────┬────────────────────────────┐
# │ Name        │ Version │ Type   │ Installed  │ Location                   │
# ├─────────────┼─────────┼────────┼────────────┼────────────────────────────┤
# │ Notion      │ 1.2.0   │ npm    │ 10/28/2025 │ ~/.fusion-mcp/community/... │
# │ GitHub      │ 2.0.1   │ git    │ 10/28/2025 │ ~/.fusion-mcp/community/... │
# │ MongoDB     │ 1.0.0   │ remote │ 10/28/2025 │ Remote server (no local)   │
# └─────────────┴─────────┴────────┴────────────┴────────────────────────────┘
```

## Directory Structure

```
~/.fusion-mcp/
├── config.json                          # CLI config (auth, workspace)
├── servers/                             # Custom servers (existing)
│   └── <custom-server-id>/
│       ├── package.json
│       ├── server.js
│       └── .fusion-mcp-metadata.json
└── community/                           # Community servers (NEW)
    ├── notion/
    │   ├── node_modules/
    │   ├── package.json
    │   └── .fusion-mcp-metadata.json
    ├── github/
    │   ├── .git/
    │   ├── src/
    │   ├── package.json
    │   └── .fusion-mcp-metadata.json
    └── mongodb/
        └── .fusion-mcp-metadata.json    # Remote server (no files)
```

## Configuration JSON Format

Community servers include pre-configured JSON for AI tools:

```json
{
  "configurationJson": {
    "local": {
      "prerequisites": "npm install -g @modelcontextprotocol/server-notion",
      "configJson": "{\"notion\": {\"command\": \"npx\", \"args\": [\"-y\", \"@modelcontextprotocol/server-notion\"], \"env\": {\"NOTION_API_KEY\": \"your-api-key\"}}}",
      "notes": "Set NOTION_API_KEY environment variable"
    },
    "remote": {
      "configJson": "{\"notion-remote\": {\"url\": \"https://mcp.example.com/notion\", \"transport\": \"sse\"}}",
      "notes": "Remote server endpoint"
    }
  }
}
```

The CLI:
1. Fetches this JSON from the server
2. Parses the `configJson` string
3. Adds it to Claude/Bob/Copilot config files
4. User only needs to set environment variables

## Server Types in Database

**Current Community Servers (16+):**
1. Notion - Productivity
2. Context7 - Documentation
3. Playwright - Testing
4. Sequential Thinking - Development
5. Filesystem - Development
6. GitHub - Development
7. ISC Milvus - Database
8. Salesforce - CRM
9. Carbon for Salesforce - Integration
10. MCP Atlassian - Project Management
11. Box - Storage
12. MarkItDown - Documentation
13. Chrome DevTools - Debugging
14. Firecrawl - Web Scraping
15. MongoDB - Database
16. Hugging Face - AI/ML

**Hosting Types:**
- **Local**: Requires npm/git installation
- **Remote**: Hosted, no installation needed

**Connection Modes:**
- **STDIO**: Standard input/output (local servers)
- **HTTP**: REST API (remote servers)
- **WebSocket**: Real-time communication (remote servers)

## Testing Checklist

### Manual Testing Steps

1. **List Command:**
   ```bash
   fmcp community list
   fmcp community list --category development
   fmcp community list --sort rating
   fmcp community list --installed
   ```

2. **Info Command:**
   ```bash
   fmcp community info notion
   fmcp community info mongodb
   fmcp community info hugging-face
   ```

3. **Search Command:**
   ```bash
   fmcp community search github
   fmcp community search database
   fmcp community search "file system"
   ```

4. **Install Command:**
   ```bash
   # NPM package
   fmcp community install notion --tool claude
   
   # GitHub repo
   fmcp community install github --tool bob --project
   
   # Remote server
   fmcp community install mongodb --tool copilot
   ```

5. **Configure Command:**
   ```bash
   fmcp community configure notion --tool claude
   fmcp community configure github --tool bob --project
   ```

6. **Installed Command:**
   ```bash
   fmcp community installed
   ```

### Expected Results

- ✅ All commands compile without errors
- ✅ Help text displays correctly
- ✅ List shows servers with proper formatting
- ✅ Info shows detailed server information
- ✅ Search returns relevant results
- ✅ Install downloads and configures servers
- ✅ Configure adds to AI tool config files
- ✅ Installed tracks all community servers

## Future Enhancements

1. **Uninstall Command:**
   ```bash
   fmcp community uninstall <server-name>
   ```

2. **Update Command:**
   ```bash
   fmcp community update <server-name>
   fmcp community update --all
   ```

3. **Version Management:**
   ```bash
   fmcp community versions <server-name>
   fmcp community install <server-name>@1.2.0
   ```

4. **Server Ratings:**
   ```bash
   fmcp community rate <server-name> --stars 5
   ```

5. **Offline Mode:**
   - Cache server list locally
   - Work with cached data when offline

6. **Server Submission:**
   ```bash
   fmcp community submit --from-package ./package.json
   fmcp community submit --from-github https://github.com/user/repo
   ```

## Technical Notes

### Dependencies

**No new dependencies added!** The implementation uses existing packages:
- `commander` - CLI framework
- `axios` - API client
- `chalk` - Terminal colors
- `ora` - Spinners
- `inquirer` - Prompts
- `fs-extra` - File operations
- `console-table-printer` - Tables

### Compatibility

- **Node.js**: >=18.0.0 (same as before)
- **Operating Systems**: macOS, Linux, Windows
- **AI Tools**: Claude Desktop, IBM Bob IDE, GitHub Copilot Chat

### Error Handling

- Validates authentication before API calls
- Checks for npm/git availability before installation
- Handles missing configuration files gracefully
- Provides clear error messages with suggestions
- Supports `--skip-deps` for troubleshooting

### Performance

- Uses pagination (default limit: 50 servers)
- Caches nothing (always fetches fresh data)
- Parallel operations where possible
- Minimal memory footprint

## Conclusion

The community servers feature is **fully implemented and ready for use**. It provides a seamless way to discover, install, and configure pre-configured MCP servers alongside the existing custom server functionality.

**Key Benefits:**
- ✅ Unified CLI for both custom and community servers
- ✅ No backend changes required (uses existing APIs)
- ✅ Automatic installation and configuration
- ✅ Support for npm, git, and remote servers
- ✅ Integration with all supported AI tools
- ✅ Comprehensive documentation and help text

**Version:** 0.2.0  
**Status:** ✅ Complete and ready for deployment