mcp-orchestrator/README.md

MCP Orchestrator - Discover and install MCPs with automatic OAuth support. Uses Claude CLI for OAuth MCPs (Canva, Asana, etc). 34 trusted MCPs from Claude Partners.

# MCP Orchestrator

**The Magic Layer Between Your Agent and 1000+ MCP Servers**

> *"Want to install Pandas MCP? It can analyze large CSV files efficiently..."*
> Your agent suggests this at **exactly** the right moment. That's the magic.

## 🎯 The Problem

You're working with Claude/Cursor on a coding project:
- **Agent gets stuck**: "I can't analyze this 2GB CSV file efficiently"
- **You don't know**: There are 1000+ MCP servers out there, but which one solves this?
- **Manual hassle**: Even if you knew, you'd have to stop, install it, configure it, restart...
- **Tool overload**: If you connect all MCPs upfront, the agent gets confused (30-50% performance drop)

## ✨ The Vision (What We're Building)

```
You: "Claude, analyze sales_data.csv and show trends"

Agent: "💡 This CSV is large (2GB). I found a specialized tool:

**Pandas MCP** (score: 95)
- Best for CSV/Excel operations
- Handles millions of rows efficiently
- Built-in data cleaning

Install it? (takes ~30 sec)"

You: "Yes"

Agent: "✅ Pandas installed! Analyzing now..."
[continues working seamlessly with new capabilities]
```

**Zero interruption. Pure magic.**

## 🚀 How It Works

The MCP Orchestrator sits between your agent and the MCP ecosystem:

1. **Intelligent Discovery**: Agent realizes it needs help → Orch suggests relevant MCPs
2. **Auto-Installation**: User approves → Orch downloads and installs the MCP
3. **Seamless Integration**: New tools appear → Agent continues working
4. **Just-in-Time Loading**: Only connect MCPs when needed → Better performance

## 🏗️ Architecture

```
Agent (Claude/Cursor/etc.)
         ↓
   MCP Orchestrator (this server)
         ↓
   [Filesystem MCP] [GitHub MCP] [SQLite MCP] ...
```

## 📦 Installation

```bash
# Clone the repo
git clone <repo-url>
cd mcp-orchestrator

# Install dependencies
npm install

# Install at least one MCP server to test with
npm install -g @modelcontextprotocol/server-filesystem
```

## 🎮 Usage

### Start the orchestrator

```bash
npm run dev
```

### Test with MCP Inspector

```bash
npm run inspector
```

This will open a browser at `http://localhost:6274` where you can:
1. See available meta-tools
2. Call `list_available_mcps` to browse the registry
3. Call `connect_mcp` to connect to an MCP
4. Use tools from connected MCPs

### Available Meta-Tools

#### 🎯 `discover_mcps` (THE MAGIC TOOL)
Intelligently discovers which MCPs would help with your current task.

**Example:**
```json
{
  "taskDescription": "I need to analyze a large CSV file with sales data"
}
```

**Returns:**
```json
{
  "recommendations": [
    {
      "id": "pandas",
      "name": "Pandas",
      "score": 95,
      "reasons": [
        "Best for CSV/Excel operations",
        "Handles millions of rows efficiently"
      ],
      "pros": ["Fast", "Mature ecosystem"],
      "cons": ["Heavy dependency"],
      "installTime": "~30 seconds"
    }
    // ... more recommendations
  ]
}
```

The agent uses this tool **automatically** when it senses it needs help.

#### `connect_mcp`
Connects to a specific MCP server (with auto-installation coming soon)

```json
{
  "mcpId": "filesystem"
}
```

#### `list_available_mcps`
Browse all 10+ MCPs in the registry

#### `list_active_mcps`
Show currently connected MCPs

#### `disconnect_mcp`
Disconnect from an MCP

## 📋 Current Registry (MVP)

The orchestrator currently knows about these MCPs:

- **filesystem** - Read, write, and manage files and directories
- **git** - Git repository operations
- **github** - GitHub API integration
- **sqlite** - Query and manage SQLite databases
- **postgres** - Query and manage PostgreSQL databases
- **fetch** - Fetch web pages and make HTTP requests
- **brave-search** - Search the web using Brave Search API
- **puppeteer** - Browser automation
- **slack** - Slack API integration
- **google-drive** - Google Drive integration

*Note: You need to install these MCPs separately for them to work.*

## 🔮 Current Status & Roadmap

### ✅ What's Working Now (MVP)
- **Intelligent Discovery**: `discover_mcps` tool with context analysis
  - Extracts keywords, categories, task types
  - Ranks MCPs by relevance (scoring algorithm)
  - Returns top 5 recommendations with reasons
- **Dynamic Connection**: Connect/disconnect MCPs on-demand
- **Tool Routing**: Seamlessly proxy calls to connected MCPs
- **Registry**: 10 curated MCP servers (filesystem, git, github, sqlite, etc.)
- **Node.js Support**: Works with all Node.js MCPs via stdio

### 🚧 What's Next (The Magic)

#### Phase 1: Auto-Installation (CRITICAL) 🎯
**This is what makes it feel magical**
- [ ] Check if MCP is installed before connecting
- [ ] Auto-run `npm install -g` or `pip install` if missing
- [ ] Show installation progress to user
- [ ] Seamlessly continue after installation
- **Goal**: User says "yes" → 30 seconds later → tools are available

#### Phase 2: Proactive Suggestions
**Make the agent smarter about when to suggest**
- [ ] Enhanced tool descriptions (teach agent when to call discover)
- [ ] Add `analyze_task_and_suggest` meta-tool for proactive checking
- [ ] MCP notifications (`tools/list_changed`) after connecting
- [ ] Rich recommendations (pros, cons, install time, use cases)

#### Phase 3: Production Ready
- [ ] Sync with official MCP registry (1000+ servers)
- [ ] Support Python MCPs
- [ ] HTTP transport support
- [ ] Database layer (replace hardcoded registry)
- [ ] Performance metrics and analytics

#### Phase 4: Polish
- [ ] Auto-disconnect unused MCPs (LRU cache)
- [ ] Connection health checks
- [ ] Web dashboard for registry browsing
- [ ] Usage analytics

## 🧪 Testing

### Run the proof-of-concept

```bash
npm run poc
```

This tests basic MCP spawning and connection.

### Run the orchestrator

```bash
npm run dev
```

### Test with an agent

Configure your MCP client (Claude Desktop, Cursor, etc.) to connect to the orchestrator via stdio.

Example config for Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "orchestrator": {
      "command": "node",
      "args": ["C:/path/to/mcp-orch/dist/index.js"]
    }
  }
}
```

## 💡 Key Design Decisions

### How does the agent know when to suggest MCPs?
**The agent is smart enough on its own.** Modern agents (Claude, GPT-4) can:
- Recognize when they lack capabilities
- Read tool descriptions to understand when to call them
- Make decisions about when to extend themselves

We make it work by:
1. **Clear tool descriptions** - Tell the agent exactly when to call `discover_mcps`
2. **Smart prompting** - Agent learns from conversation patterns
3. **Proactive tools** - `analyze_task_and_suggest` tool for explicit checking

### How does auto-installation work?
```typescript
connect_mcp("pandas")
  → Check: is pandas-mcp installed?
  → No: Run `pip install mcp-server-pandas`
  → Spawn process and connect
  → Notify agent: "New tools available!"
  → Agent continues seamlessly
```

### How does the agent continue working after installation?
**MCP Protocol Notifications**: After installing a new MCP, we send:
```typescript
server.notification({
  method: 'notifications/tools/list_changed'
});
```

The agent receives this, refreshes its tool list, and sees the new tools. No interruption needed!

---

## 🎯 Tomorrow's Work

**Priority 1: Build Auto-Installer**
- `src/auto-installer.ts` - Check if installed, run npm/pip install
- Update `connect_mcp` tool to use auto-installer
- Test with filesystem MCP (should install if missing)

**Priority 2: Rich Recommendations**
- Add pros/cons/installTime to discovery results
- Update MCP registry with package names for installation
- Test discover → install → use workflow

**Priority 3: Agent Integration Testing**
- Test with Claude Desktop
- Verify proactive suggestions work
- Measure the "magic" feeling

---

## 🤝 Contributing

This is a work in progress. The goal: make MCP discovery feel like magic.

## 📄 License

MIT