# hive-mcp Ecosystem

The hive-mcp project is part of a broader ecosystem of tools for AI-assisted development. This page explains how the components fit together and our open-source strategy.

## Architecture Overview

```
                    ┌─────────────────────┐
                    │   hive-gateway      │
                    │ Telegram/Slack/Voice│
                    └──────────┬──────────┘
                               │
┌─────────────────┐    ┌──────▼──────┐    ┌─────────────────┐
│ hive-connectors │◄───│   hive-mcp  │───►│  olympus-web-ui │
│ GitHub/Linear   │    │   (core)    │    │  (dashboard)    │
└─────────────────┘    └──────┬──────┘    └─────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │  Knowledge Graph    │
                    └─────────────────────┘
```

## Component Overview

### hive-mcp (Core Engine)

**Repository:** [github.com/hive-agi/hive-mcp](https://github.com/hive-agi/hive-mcp)
**License:** AGPL-3.0
**Status:** Active development

The core engine providing:
- **Persistent Memory** - Project-scoped notes, conventions, decisions, snippets
- **Semantic Search** - Ollama embeddings + Chroma vector store
- **Knowledge Graph** - DataScript-based relationship tracking
- **Multi-Agent Swarm** - Coordinate Claude, Ollama, and OpenRouter workers
- **Hivemind Coordination** - Real-time agent status and communication
- **172+ MCP Tools** - Full Emacs integration via emacsclient

### olympus-web-ui (Dashboard)

**Repository:** [github.com/hive-agi/olympus-web-ui](https://github.com/hive-agi/olympus-web-ui)
**License:** MIT
**Status:** Active development

Real-time web dashboard for monitoring and controlling the swarm:
- **Agent Grid** - Live view of all lings
- **Status Visualization** - Event streams, progress bars, health indicators
- **Interactive Graph** - Visualize agent relationships and task dependencies
- **WebSocket Streaming** - Real-time updates from hive-mcp

Built with:
- React + TypeScript
- React Flow for graph visualization
- Dagre for automatic layout
- WebSocket client for live updates

### hive-connectors (Integrations)

**Repository:** [github.com/hive-agi/hive-connectors](https://github.com/hive-agi/hive-connectors)
**License:** MIT
**Status:** Planned (Q1 2026)

External service integrations following the `IConnector` protocol:
- **GitHub** - Issues, PRs, Actions, webhooks
- **Slack** - Channels, threads, reactions
- **Linear** - Issues, projects, cycles
- **Notion** - Pages, databases, blocks

Each connector provides:
- OAuth2 authentication
- Rate limiting and caching
- Webhook handlers
- Bidirectional sync

### hive-gateway (Multi-Channel Messaging)

**Repository:** Planned
**License:** MIT (planned)
**Status:** Planned (Q2 2026)

Multi-channel messaging hub for interacting with agents:
- **Telegram** - Bot API integration
- **Discord** - Guild and DM support
- **Slack** - Workspace integration
- **WhatsApp** - Business API
- **Voice** - openWakeWord + Whisper + Piper pipeline

Implements the `IChannel` protocol for unified message handling.

## Open Source Strategy

### Tier 1: MIT Licensed (Community Extensible)

| Repository | Purpose | Why MIT? |
|------------|---------|----------|
| olympus-web-ui | Web dashboard | Encourage UI contributions and forks |
| hive-connectors | External integrations | Enable community connectors |
| hive-gateway | Messaging channels | Enable custom channel adapters |

MIT license enables:
- Commercial use without restrictions
- Easy adoption by enterprises
- Community-driven connector ecosystem
- Custom forks for specific use cases

### Tier 2: AGPL Licensed (Open but Copyleft)

| Repository | Purpose | Why AGPL? |
|------------|---------|-----------|
| hive-mcp | Core engine | Protect core IP while remaining open |

AGPL ensures:
- All modifications must be shared
- Network use triggers copyleft
- Core improvements flow back to community
- Prevents proprietary forks

### Tier 3: Enterprise (Future)

Planned commercial features:
- Multi-tenant cloud hosting
- SSO and RBAC
- Audit logging and compliance
- Priority support

Enterprise features will be proprietary add-ons while core remains AGPL.

## Contributing

### Contributing to olympus-web-ui

```bash
# Clone and setup
git clone https://github.com/hive-agi/olympus-web-ui
cd olympus-web-ui
npm install

# Development
npm run dev

# Build for production
npm run build
```

Key areas for contribution:
- New visualization components
- Performance optimizations
- Accessibility improvements
- Mobile responsiveness

### Adding a Connector

Connectors implement the `IConnector` protocol:

```clojure
(defprotocol IConnector
  (connect! [this config] "Establish connection with credentials")
  (disconnect! [this] "Clean up resources")
  (sync! [this direction] "Sync data bidirectionally")
  (handle-webhook [this event] "Process incoming webhooks")
  (health-check [this] "Return connector health status"))
```

To add a new connector:

1. **Fork** [hive-connectors](https://github.com/hive-agi/hive-connectors)
2. **Create** `src/connectors/<service>/core.clj`
3. **Implement** the `IConnector` protocol
4. **Add tests** in `test/connectors/<service>/`
5. **Document** in `docs/connectors/<service>.md`
6. **Submit PR** with test coverage and docs

### Adding a Channel

Channels implement the `IChannel` protocol:

```clojure
(defprotocol IChannel
  (send-message! [this recipient content] "Send message to user/channel")
  (receive-messages [this] "Poll or stream incoming messages")
  (register-webhook! [this url] "Register webhook for push updates")
  (format-message [this msg-type data] "Format message for channel"))
```

To add a new channel:

1. **Fork** the gateway repository
2. **Create** `src/channels/<platform>/core.clj`
3. **Implement** the `IChannel` protocol
4. **Handle** platform-specific auth (OAuth, API keys, etc.)
5. **Add tests** with mock API responses
6. **Submit PR** with documentation

### Contributing to hive-mcp Core

```bash
# Clone and setup
git clone https://github.com/hive-agi/hive-mcp
cd hive-mcp
bb dev  # Start development server

# Run tests
bb test

# Lint
bb lint
```

Note: hive-mcp is AGPL licensed. By contributing, you agree that your contributions will be licensed under AGPL-3.0.

Key areas for contribution:
- New MCP tools
- Memory and KG improvements
- Swarm coordination features
- Performance optimizations
- Documentation

## Roadmap

### Q1 2026 (Current)
- [ ] olympus-web-ui v1.0 release
- [ ] GitHub connector MVP
- [ ] Slack connector MVP
- [ ] Protocol extraction for connectors

### Q2 2026
- [ ] hive-gateway Telegram/Discord support
- [ ] Linear connector
- [ ] Notion connector
- [ ] Voice pipeline MVP

### Q3 2026
- [ ] WhatsApp Business integration
- [ ] Enterprise features planning
- [ ] Multi-tenant architecture

## Related Resources

- [[Home]] - Main wiki home
- [[Installation]] - Getting started with hive-mcp
- [[Tools-Reference]] - MCP tools documentation
- [[Presets]] - Agent specialization presets