npm package: @roobyrm/mcp-bridge
Description: Token-efficient MCP bridge server that aggregates multiple MCP servers into 5-6 category-based tools, reducing token overhead by 97%
Author: roobyrm
Latest version: 1.0.0

# MCP Bridge Server

> **Token-efficient Model Context Protocol aggregator** - Reduce MCP token overhead by 95%+

[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

⚡ **Quick Setup**: Only need `TAVILY_API_KEY` - [See SIMPLE_SETUP.md](SIMPLE_SETUP.md)

---

## The Problem

Using multiple MCP servers directly with Claude Code creates massive token overhead:

```
Serena (23 tools)    → ~23,000 tokens
Playwright (21 tools) → ~21,000 tokens
shadcn (7 tools)     → ~7,000 tokens
Tavily (4 tools)     → ~4,000 tokens
Context7 (2 tools)   → ~2,000 tokens
────────────────────────────────────
Total                → ~57,000 tokens 😱
```

This consumes your context window before you even start working!

## The Solution

MCP Bridge aggregates all downstream servers into **5-6 category-based tools**:

```
code_operations         → All 23 Serena tools
documentation_lookup    → All 2 Context7 tools
browser_testing         → All 21 Playwright tools
web_research           → All 4 Tavily tools
ui_components          → All 7 shadcn tools
batch_operations       → Parallel execution
────────────────────────────────────
Total                  → ~1,800 tokens ✨ (97% reduction)
```

## Quick Start

### Option 1: Remote (Recommended)

**No installation needed!** Just one environment variable required:

```json
// ~/.claude.json
{
  "mcpServers": {
    "mcp-bridge": {
      "command": "npx",
      "args": ["mcp-bridge@latest"],
      "env": {
        "TAVILY_API_KEY": "tvly-dev-your-key-here"
      }
    }
  }
}
```

Get your free Tavily API key at https://tavily.com

**That's it!** All 5 MCP servers (57 tools) enabled by default.

📖 [See SIMPLE_SETUP.md](SIMPLE_SETUP.md) for details and optional configuration

### Option 2: Local Development

```bash
# Clone and install
git clone https://github.com/yourusername/mcp-bridge.git
cd mcp-bridge
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your TAVILY_API_KEY (required)
# All MCP servers enabled by default

# Build and run
npm run build
npm start

# Add to ~/.claude.json
{
  "mcpServers": {
    "mcp-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-bridge/dist/index.js"]
    }
  }
}
```

## Features

✨ **95%+ Token Reduction** - 57k → 1.8k tokens
⚡ **Smart Caching** - TTL-based with auto-invalidation
🚀 **Parallel Execution** - Batch operations with concurrency control
🔄 **Auto-Retry** - Exponential backoff for transient failures
📊 **Real-time Metrics** - Token usage and performance tracking
🎯 **Response Compression** - Automatic output optimization
🎨 **UI Components** - shadcn/ui integration with registry management

## Usage Example

### Traditional MCP (Inefficient)
```typescript
// Multiple sequential calls, high token overhead
await findSymbol({ name: "User" });
await findSymbol({ name: "Post" });
await getLibraryDocs({ library: "react" });
```

### MCP Bridge (Efficient)
```typescript
// Single batch call, parallel execution
{
  name: "batch_operations",
  arguments: {
    operations: [
      { category: "code_operations", operation: "findSymbol", params: { name_path: "User" } },
      { category: "code_operations", operation: "findSymbol", params: { name_path: "Post" } },
      { category: "documentation_lookup", operation: "getLibraryDocs", params: { library_id: "react" } }
    ]
  }
}
```

## Architecture

```
┌─────────────────────────────┐
│      Claude Code Agent      │  (Sees only 4-5 tools)
└──────────────┬──────────────┘
               │ ~1.5k tokens
┌──────────────▼──────────────┐
│      MCP Bridge Server      │
│  • Smart routing            │
│  • Caching & compression    │
│  • Parallel execution       │
│  • Error handling           │
└──┬─────┬─────┬─────┬────────┘
   │     │     │     │
   ▼     ▼     ▼     ▼
┌─────┐┌───┐┌────┐┌──────┐
│Serena││C7 ││Play││Tavily│  50 downstream tools
└─────┘└───┘└────┘└──────┘
```

## Documentation

- [Complete API Reference](docs/API.md)
- [Usage Examples](examples/usage-examples.ts)
- [Full Documentation](docs/README.md)

## Bridge Tools

### 🔧 `code_operations` (Serena)
Code analysis, editing, memory, and project operations
- **Search**: `findSymbol`, `findFiles`, `searchInFiles`
- **Edit**: `editFile`, `writeFile`, `createFile`
- **Memory**: `readMemory`, `writeMemory`, `listMemories`
- **Project**: `getProjectStructure`, `analyzeProject`

### 📚 `documentation_lookup` (Context7)
Official library documentation queries
- **Docs**: `resolveLibraryId`, `getLibraryDocs`

### 🌐 `browser_testing` (Playwright)
Browser automation and testing
- **Navigation**: `navigate`, `goBack`, `goForward`
- **Interaction**: `click`, `fill`, `select`
- **Inspection**: `takeSnapshot`, `screenshot`

### 🔍 `web_research` (Tavily)
Web search and content extraction
- **Research**: `search`, `extract`, `crawl`, `map`

### ⚡ `batch_operations`
Execute multiple operations in parallel

## Performance

| Metric | Value |
|--------|-------|
| Token Reduction | **97%** (50k → 1.5k) |
| Cache Hit Rate | **40-60%** (read ops) |
| Parallel Speedup | **60-80%** (batch ops) |
| Latency Overhead | **~10-20ms** (uncached) |

## Configuration

Key environment variables:

```bash
TAVILY_API_KEY=tvly-dev-xxx          # Required for Tavily
CACHE_ENABLED=true                    # Enable caching
CACHE_TTL_SECONDS=300                 # 5 minute TTL
MAX_CONCURRENT_OPERATIONS=10          # Parallel limit
METRICS_ENABLED=true                  # Track metrics
```

See [.env.example](.env.example) for complete configuration.

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Development mode
npm run dev

# Lint and format
npm run lint
npm run format
```

## Requirements

- **Node.js** ≥ 18.0.0
- **Downstream servers**:
  - Serena: `uvx --from git+https://github.com/oraios/serena`
  - Context7: `npx -y @upstash/context7-mcp`
  - Playwright: `npx -y @playwright/mcp`
  - Tavily: `npx -y tavily-mcp@latest` (requires API key)

## Monitoring

View real-time dashboard:

```
╔════════════════════════════════════════════════════════════════╗
║                    MCP Bridge Dashboard                        ║
╚════════════════════════════════════════════════════════════════╝

📊 Operations
   Total: 150
   Successful: 147 (98.0%)
   Avg Duration: 245.32ms

🎯 Token Efficiency
   Bridge Tokens: 2,450
   Direct MCP Est: 75,000
   Reduction: 96.7%

💾 Cache
   Size: 45/1000
   Hit Rate: 52.3%
```

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (`npm test`)
5. Submit a pull request

## License

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

## Credits

Inspired by [Anthropic's Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)

Built with:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
- [Serena](https://github.com/oraios/serena)
- [Playwright MCP](https://github.com/microsoft/playwright-mcp)
- [Tavily](https://tavily.com)
- [Context7](https://upstash.com/context7)

## Support

- 📖 [Documentation](docs/README.md)
- 💬 [Issues](https://github.com/yourusername/mcp-bridge/issues)
- 🌟 [Star on GitHub](https://github.com/yourusername/mcp-bridge)

---

**Made with ❤️ for the MCP community**