npm package: @myorb.ai/mcp-bridge
Description: Model Context Protocol bridge for MyOrb.ai - Connect any MCP-compatible AI client to MyOrb expert Orbs
Author: MyOrb.ai
Latest version: 1.0.2

# @myorb/mcp-bridge

**Model Context Protocol Bridge for MyOrb.ai**

Connect any MCP-compatible AI client (Claude Desktop, Cursor, etc.) to MyOrb.ai expert Orbs.

[![npm version](https://badge.fury.io/js/%40myorb%2Fmcp-bridge.svg)](https://www.npmjs.com/package/@myorb/mcp-bridge)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## 🎯 **What is This?**

MyOrb MCP Bridge enables universal access to expert Orbs across all MCP-compatible AI platforms. Instead of platform-specific integrations, one bridge works everywhere.

**Supported AI Clients:**
- ✅ Claude Desktop (Anthropic)
- ✅ Cursor IDE
- ✅ Any MCP-compatible client

**Supported Orbs:**
- 🧠 **Charles Orb** - AI development expert (free)
- 📚 **Dimple SAT Orb** - SAT prep tutor (subscription)
- 🔮 **Future Orbs** - Expanding ecosystem

---

## 📦 **Installation**

### **Method 1: NPX (Recommended)**

No installation required! Use directly with `npx`:

```bash
npx @myorb/mcp-bridge
```

### **Method 2: Global Install**

```bash
npm install -g @myorb/mcp-bridge
```

Then run:

```bash
myorb-bridge
```

---

## 🚀 **Quick Start**

### **1. Configure Your AI Client**

#### **For Claude Desktop / Cursor**

Edit your `mcp.json` (or `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "charles-orb": {
      "command": "npx",
      "args": ["@myorb/mcp-bridge"],
      "env": {
        "MCP_SERVER_URL": "https://api.myorb.ai",
        "ORB_ID": "charles"
      }
    }
  }
}
```

**Config File Locations:**
- **Cursor**: `~/.cursor/mcp.json`
- **Claude Desktop (Mac)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`

### **2. Restart Your AI Client**

Quit and relaunch Cursor/Claude Desktop to load the new configuration.

### **3. Verify Connection**

In your AI client, type:
```
Can you search your knowledge base for "DBAG Protocol"?
```

If configured correctly, the AI will access Charles Orb's knowledge!

---

## 🔐 **Authentication (Paid Orbs)**

Some orbs require a subscription (like Dimple SAT). Use authentication tokens:

### **Option 1: Bearer Token**

```json
{
  "mcpServers": {
    "dimplesat-orb": {
      "command": "npx",
      "args": ["@myorb/mcp-bridge"],
      "env": {
        "MCP_SERVER_URL": "https://api.myorb.ai",
        "ORB_ID": "dimplesat",
        "MYORB_AUTH_TOKEN": "your_subscription_token_here"
      }
    }
  }
}
```

### **Option 2: API Key**

```json
{
  "env": {
    "MCP_SERVER_URL": "https://api.myorb.ai",
    "ORB_ID": "dimplesat",
    "MYORB_API_KEY": "your_api_key_here"
  }
}
```

**Get Your Token:**
- Free Orbs: No token needed
- Paid Orbs: Login at [myorb.ai](https://myorb.ai) → Account → API Keys

---

## 🌐 **Multi-Orb Configuration**

Access multiple orbs simultaneously:

```json
{
  "mcpServers": {
    "charles-orb": {
      "command": "npx",
      "args": ["@myorb/mcp-bridge"],
      "env": {
        "MCP_SERVER_URL": "https://api.myorb.ai",
        "ORB_ID": "charles"
      }
    },
    "dimplesat-orb": {
      "command": "npx",
      "args": ["@myorb/mcp-bridge"],
      "env": {
        "MCP_SERVER_URL": "https://api.myorb.ai",
        "ORB_ID": "dimplesat",
        "MYORB_AUTH_TOKEN": "your_token"
      }
    }
  }
}
```

Now you can ask the AI to consult either expert!

---

## 🛠️ **Available Tools**

The bridge exposes these MCP tools to your AI client:

### **search_orb**
Search the orb's knowledge base using optimized indexed search (46x faster).

```javascript
{
  "query": "DBAG Protocol",
  "max_documents": 5
}
```

### **get_orb_context**
Get full context including manifest, capabilities, and relevant documents.

```javascript
{
  "query": "strategic planning protocols"
}
```

### **batch_load_documents**
Efficiently load multiple documents in one request.

```javascript
{
  "doc_ids": ["11.00.02", "11.00.01", "70.01.01"]
}
```

### **wake_up** (Prompt)
Initialize the orb with full personality and context.

---

## 📊 **Performance**

**Indexed Search Optimization:**
- 🚀 **46x faster** than full-text search
- ⚡ **~145ms** average response time
- 💰 **99% reduction** in S3 data transfer
- 🎯 Smart relevance scoring

---

## 🏗️ **Architecture**

```
┌─────────────────────────┐
│  AI Client (Cursor)     │
│  ┌─────────────────────┐│
│  │  Claude/GPT Model   ││
│  └─────────┬───────────┘│
└────────────┼─────────────┘
             │ MCP Protocol (stdio)
             ▼
┌─────────────────────────┐
│  @myorb/mcp-bridge      │
│  (Local Node.js)        │
└────────────┬────────────┘
             │ HTTPS REST API
             ▼
┌─────────────────────────┐
│  api.myorb.ai           │
│  (AWS Lambda)           │
└────────────┬────────────┘
             │
             ▼
┌─────────────────────────┐
│  S3 Content Buckets     │
│  (Per-Orb Storage)      │
└─────────────────────────┘
```

**Why a Bridge?**
- MCP protocol requires local stdio communication
- Our API is HTTP REST (cloud-hosted)
- Bridge translates: stdio ↔ HTTP

---

## 🔧 **Configuration Options**

### **Environment Variables**

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `MCP_SERVER_URL` | No | `https://api.myorb.ai` | MyOrb API endpoint |
| `ORB_ID` | Yes | `charles` | Which orb to connect to |
| `MYORB_AUTH_TOKEN` | No | `null` | Bearer token for paid orbs |
| `MYORB_API_KEY` | No | `null` | API key for paid orbs |

### **Available Orb IDs**

| ORB_ID | Name | Type | Status |
|--------|------|------|--------|
| `charles` | Charles Vachon AI | Development Expert | ✅ Free |
| `dimplesat` | Dimple SAT Tutor | Education | 🔐 Subscription |
| More coming soon! | | | |

---

## 🐛 **Troubleshooting**

### **Bridge Not Connecting**

1. **Check Node.js version**: Requires Node.js ≥18.0.0
   ```bash
   node --version
   ```

2. **Test API connectivity**:
   ```bash
   curl https://api.myorb.ai/health
   ```

3. **Check logs**: Bridge outputs to stderr
   - Look for "✅ Bridge started successfully"

### **Authentication Errors**

```
API Error (401): Unauthorized
```

**Solutions:**
- Verify `MYORB_AUTH_TOKEN` is correct
- Check token hasn't expired
- Ensure orb requires authentication (charles is free)

### **Orb Not Found**

```
API Error (404): Orb {orb_id} not found
```

**Solutions:**
- Double-check `ORB_ID` spelling
- Verify orb exists: `curl https://api.myorb.ai/orbs`

---

## 📚 **Examples**

### **Ask Charles for Python Help**

```
I need help implementing the DBAG protocol in Python. 
Can you search your knowledge base for the DBAG specification?
```

### **Get SAT Math Help (Dimple)**

```
I'm stuck on this SAT quadratic equation problem. 
Can you help me understand the approach?
```

### **Load Multiple Documents**

```
Please load documents 11.00.02, 11.00.01, and 70.01.01 
from Charles's knowledge base.
```

---

## 🤝 **Contributing**

We welcome contributions!

**Report Issues**: [GitLab Issues](https://gitlab.com/myorb-platform/myorb-sentinel/-/issues)

**Submit PRs**: 
1. Fork the repository
2. Create feature branch
3. Make your changes
4. Submit merge request

---

## 📄 **License**

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🔗 **Links**

- 🌐 **Website**: [myorb.ai](https://myorb.ai)
- 📦 **NPM Package**: [@myorb/mcp-bridge](https://www.npmjs.com/package/@myorb/mcp-bridge)
- 🔧 **GitLab Repo**: [myorb-sentinel](https://gitlab.com/myorb-platform/myorb-sentinel)
- 📚 **Documentation**: [docs.myorb.ai](https://docs.myorb.ai)
- 💬 **Support**: hello@myorb.ai

---

## 🚀 **Roadmap**

- ✅ Multi-orb support
- ✅ Authentication for paid orbs
- ✅ Optimized indexed search
- 🔄 WebSocket support for streaming
- 🔄 Offline caching
- 🔄 Advanced analytics
- 🔄 Custom orb creation toolkit

---

**Built with ❤️ by the MyOrb.ai team**

*Empowering AI assistants with expert knowledge, one Orb at a time.*