# MCP Router
A secure, enterprise-grade Model Context Protocol (MCP) server aggregation platform built with Electron.
## Overview
MCP Router acts as a centralized gateway for managing multiple MCP servers, providing:
- **Server Aggregation**: Connect and manage multiple MCP servers from a single interface
- **Policy-Based Access Control**: Fine-grained control over tool and resource access
- **Token Authentication**: Secure API token management with scoping and expiration
- **Approval Workflows**: Human-in-the-loop approval for sensitive operations
- **Rate Limiting**: Protect against abuse with configurable rate limits
- **Audit Logging**: Complete audit trail of all operations
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ MCP Router │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Clients │ │ Policy │ │ Approval │ │
│ │ (Claude, │──│ Engine │──│ Queue │ │
│ │ etc.) │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ MCP Aggregator │ │
│ │ - Tool routing - Resource proxying - Audit log │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ MCP Server│ │ MCP Server│ │ MCP Server│ │
│ │ A │ │ B │ │ C │ │
│ └───────────┘ └───────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## Features
### Server Management
- Support for stdio and HTTP transport protocols
- Automatic server health monitoring
- Tool and resource discovery
- Per-server configuration
### Security
- Token-based authentication with scopes
- Policy rules with glob pattern matching
- Rate limiting per client/token
- Secure credential storage via system keychain
### Policy Engine
- Global, client-specific, and server-specific policies
- Allow, deny, and require_approval actions
- Priority-based rule evaluation
- Wildcard pattern matching
### Approval System
- Real-time approval notifications
- Configurable timeout and expiration
- Audit trail for all decisions
## Quick Start
### Prerequisites
- Node.js 20+
- pnpm 9+
### Installation
```bash
# Clone the repository
git clone https://github.com/your-org/mcp-router.git
cd mcp-router
# Install dependencies
pnpm install
# Start development server
pnpm dev
```
### Building
```bash
# Build for production
pnpm build
# Package for distribution
pnpm package
```
## Project Structure
```
mcp-router/
├── apps/
│ └── desktop/ # Electron desktop application
│ ├── src/
│ │ ├── main/ # Main process (Node.js)
│ │ │ ├── core/ # DI container, types, interfaces
│ │ │ ├── services/ # Business logic services
│ │ │ ├── repositories/ # Data access layer
│ │ │ └── ipc/ # IPC handlers
│ │ ├── preload/ # Preload scripts (context bridge)
│ │ └── renderer/ # React UI
│ │ ├── components/ # Reusable UI components
│ │ ├── features/ # Feature modules
│ │ ├── hooks/ # Custom React hooks
│ │ └── stores/ # Zustand state stores
│ └── tests/ # Test files
├── docs/ # Documentation
│ ├── adr/ # Architecture Decision Records
│ ├── api/ # API documentation
│ └── guides/ # User and developer guides
└── packages/ # Shared packages (future)
```
## Technology Stack
| Layer | Technology |
|-------|------------|
| Framework | Electron 28 |
| UI | React 18 + TypeScript |
| Styling | Tailwind CSS + shadcn/ui |
| State | Zustand |
| DI | InversifyJS |
| Database | SQLite (better-sqlite3) |
| Build | electron-vite + Vite |
| Testing | Vitest + Playwright |
## Documentation
- [Architecture Overview](./docs/architecture.md)
- [Development Guide](./docs/guides/development.md)
- [API Reference](./docs/api/README.md)
- [Architecture Decisions](./docs/adr/README.md)
## Scripts
| Command | Description |
|---------|-------------|
| `pnpm dev` | Start development server |
| `pnpm build` | Build for production |
| `pnpm test` | Run unit tests |
| `pnpm test:watch` | Run tests in watch mode |
| `pnpm lint` | Run ESLint |
| `pnpm lint:fix` | Fix linting issues |
| `pnpm typecheck` | Run TypeScript type checking |
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
MIT License - see [LICENSE](./LICENSE) for details.
