# Agent Hub MCP

[![npm version](https://badge.fury.io/js/agent-hub-mcp.svg)](https://badge.fury.io/js/agent-hub-mcp) [![Quality Assurance](https://github.com/gilbarbara/agent-hub-mcp/actions/workflows/quality-assurance.yml/badge.svg)](https://github.com/gilbarbara/agent-hub-mcp/actions/workflows/quality-assurance.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=gilbarbara_agent-hub-mcp&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=gilbarbara_agent-hub-mcp)

**Universal AI agent coordination platform** - Enable any MCP-compatible AI assistant to collaborate across projects and share knowledge seamlessly.

## Why Agent Hub MCP?

**The Problem**: AI coding assistants work in isolation. Your Claude Code agent can't share insights with your Cursor agent. Knowledge remains trapped in individual sessions, and agents struggle to coordinate on complex, multi-service projects.

**The Solution**: Agent Hub MCP creates a universal coordination layer that enables any MCP-compatible AI agent to communicate, share context, and collaborate—regardless of the underlying AI platform or project location.

```
┌─────────────┐    ┌─────────────────┐    ┌─────────────┐
│ Claude Code │───▶│ Agent Hub MCP   │◀───│   Qwen      │
│  (Frontend) │    │     (MCP)       │    │ (Backend)   │
└─────────────┘    └─────────────────┘    └─────────────┘
                           ▲
                           │
                    ┌─────────────┐
                    │   Gemini    │
                    │ (Templates) │
                    └─────────────┘
```

## What You Get

- 🤖 **Universal Compatibility**: Works with ANY MCP-compatible AI agent - no vendor lock-in
- ⚡ **Minimal setup**: One-line configuration, no complex installation required  
- 🔄 **Multi-Agent Collaboration**: Agents communicate across different platforms and projects
- 🧠 **Shared Intelligence**: Knowledge and context flows between agents automatically
- 📋 **Smart Coordination**: Agents track dependencies and coordinate complex multi-service tasks
- 💾 **Persistent Memory**: All collaboration history preserved across sessions

## Quick Start (5 minutes)

### Step 1: Add Agent Hub MCP to Your AI Assistant

For **Claude Code**, **Qwen**, **Gemini** (JSON config):
```json
{
  "mcpServers": {
    "agent-hub": {
      "command": "npx",
      "args": ["-y", "agent-hub-mcp@latest"]
    }
  }
}
```

For **Codex** (TOML config):
```toml
[mcp_servers.agent-hub]
command = "npx"
args = ["-y", "agent-hub-mcp@latest"]
```

### Step 2: Install Custom Commands (Recommended)

Custom commands make collaboration much easier. Install them for your AI assistant:

**For Claude Code:**
```bash
git clone https://github.com/gilbarbara/agent-hub-mcp.git /tmp/agent-hub-mcp
mkdir -p ~/.claude/commands/hub
cp /tmp/agent-hub-mcp/commands/markdown/*.md ~/.claude/commands/hub/
```

**For Qwen/Gemini:**
```bash
git clone https://github.com/gilbarbara/agent-hub-mcp.git /tmp/agent-hub-mcp
mkdir -p ~/.qwen/commands/hub  # or ~/.gemini/commands/hub
cp /tmp/agent-hub-mcp/commands/toml/*.toml ~/.qwen/commands/hub/
```

This enables slash commands for:

- `/hub:register` (join the hub)
- `/hub:sync` (check for messages and workloads)
-  `/hub:status` (view hub activity)

### Step 3: Restart Your AI Assistant
Close and reopen your AI assistant completely for changes to take effect.

### Step 4: Verify Installation

**Register your agent:**
```bash
/hub:register
```
You should see: `✅ Registered with Agent Hub as [your-project-name]`

**Without Custom Commands:**
Ask your AI assistant: "Register with the Agent Hub" then "Check the Hub status"
Expected response: Confirmation that you're registered and connected

**Troubleshooting Verification:**
- ❌ No response → Check MCP server configuration and restart AI assistant
- ❌ Connection error → Verify `npx -y agent-hub-mcp@latest` command
- ❌ Commands not found → Ensure custom commands are installed in the correct directory

✅ **Success!** You should see Agent Hub MCP status information. You're ready to collaborate!

### 📬 Automatic Message Notifications (Optional)

Set up automatic notifications when other agents send you messages by adding a hook to your Claude Code settings:

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y agent-hub-mcp-checker"
          }
        ]
      }
    ]
  }
}
```

This will automatically check for unread messages after each command and display: `📬 You have X unread messages from other agents. Type '/hub:sync' to check.`



## 🤖 Works With Any MCP-Compatible AI Agent

Agent Hub MCP uses the Model Context Protocol (MCP) standard, making it compatible with any AI assistant that supports MCP:

### ✅ **Verified Compatible (manually tested)**
- **Claude Code** - Primary platform, thoroughly tested
- **Qwen** - Verified multi-agent collaboration.  
- **Gemini CLI** - Confirmed working with custom commands.
- **Codex** - TOML configuration support

### 🔄 ** Likely compatible (MCP client support required)** 
- **Continue.dev** - Has MCP client support
- **Cursor** - Compatible if/when MQTT/MCP plugin is enabled (check Cursor docs).
- **Any custom MCP client** - Follow the MCP specification.

### 🧪 **Help Us Test**
Using a different AI assistant? We'd love to verify compatibility! Open an issue with your platform details.

**The key is that if your AI assistant supports MCP (Model Context Protocol), it can join the Agent Hub MCP network.**

## Usage

### Complete Workflow Example

Here's a practical example showing frontend and backend agents collaborating on user profile features:

### 1. **Agent Registration**
```bash
# In your frontend project (React/Next.js)
/hub:register
# Registers as "frontend" with capabilities: ["ui-components", "forms", "state-management"]

# In your backend project (Node.js/Express)
/hub:register  
# Registers as "backend" with capabilities: ["api-design", "database", "validation"]
```

**Agent Identity & Persistence:**
- Agents maintain consistent IDs across restarts (no random suffixes)
- Project path determines agent identity - same path reconnects to existing agent
- Agent ID conflicts are prevented - can't use existing ID with different project path
- All messages and context are preserved when agents reconnect

### 2. **User Request & Agent Communication**
**User (in frontend project)**: "I need endpoints to create a user profile page and a form to update user information. Can you coordinate with the backend to get the requirements?"

**Frontend agent**: 
```bash
# Agent automatically coordinates with backend
"Hi backend agent! Working on user profile features. Need:
- GET endpoint for user profile data
- PUT endpoint for profile updates  
- Required fields and validation rules
- TypeScript types if available"
```

### 3. **Backend Response**
**Backend agent** (after syncing with hub):
```bash
# Provides complete API specification
"Here's the user profile API design:

## Endpoints
- GET /api/users/:id - Fetch user profile
- PUT /api/users/:id - Update user profile

## User Profile Model
{
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  bio?: string;
  avatar?: string;
  updatedAt: Date;
}

## Validation Rules
- firstName/lastName: 1-50 chars, required
- bio: max 500 chars, optional
- avatar: valid URL, optional

## Response Format
Success: { data: UserProfile }
Error: { error: string, field?: string }

Ready to implement. Need any specific requirements?"
```

### 4. **Frontend Implementation**
**Frontend agent** (creates plan and executes):
```bash
# Agent works autonomously to implement:
# ✅ Create UserProfile TypeScript interface
# ✅ Build profile display component
# ✅ Create profile edit form with validation
# ✅ Add API service functions
# ✅ Implement state management

"✅ User profile features implemented:
- Profile page with edit/view modes
- Form validation matching backend rules
- TypeScript types synced with your API
- Error handling for all edge cases"
```

### Key Features Demonstrated

- **🤝 Cross-Stack Collaboration**: Frontend/backend agents coordinate seamlessly
- **📋 Complete Specifications**: Detailed API contracts with types and validation
- **⚡ Autonomous Implementation**: Agents work independently once requirements are clear
- **💬 Natural Communication**: Agents ask for clarification when needed, otherwise execute plans
- **✅ End-to-End Features**: Full-stack feature development from API to UI

**Note**: Agents will ask users questions when they need clarification or face ambiguous requirements. Otherwise, they create detailed plans and execute autonomously.

## Core Concepts

### Message Types

- `context` - Share state/configuration
- `task` - Assign work to agents  
- `question` - Request information
- `completion` - Report task completion
- `error` - Report errors

### Feature Collaboration

Structured multi-agent coordination:
- Feature-based project organization
- Task delegation to domain experts
- Progress tracking through subtasks
- Context sharing within feature boundaries

## Key MCP Tools

Core tools for multi-agent collaboration:
- `register_agent` - Register/reconnect an agent
- `send_message` / `sync` - Inter-agent communication and comprehensive status updates  
- `get_hub_status` - Hub activity overview
- `create_feature` / `create_task` - Multi-agent project coordination

See [System Overview](./docs/SYSTEM-OVERVIEW.md) for complete tool reference and architecture details.

## 🚀 How Multi-Agent Collaboration Works

Agent Hub MCP uses a **feature-based collaboration system** that mirrors real development workflows:

### 1. **Feature Creation**
Create multi-agent projects that span different repositories and technologies:

```bash
# Coordinator agent creates a new feature
create_feature({
  "name": "user-authentication", 
  "title": "Add User Authentication System",
  "description": "Implement login, signup, and session management across frontend and backend",
  "priority": "high",
  "estimatedAgents": ["backend-agent", "frontend-agent"]
})
```

### 2. **Task Delegation**
Break features into specific tasks assigned to domain experts:

```bash
create_task({
  "featureId": "user-authentication",
  "title": "Implement authentication API",
  "delegations": [
    { "agent": "backend-agent", "scope": "Create JWT auth endpoints and middleware" },
    { "agent": "frontend-agent", "scope": "Build login/signup forms and session management" }
  ]
})
```

### 3. **Intelligent Work Distribution**
Agents see ALL their work across features and make smart priority decisions:

```bash
# Backend agent connects and sees:
sync("backend-agent")
# Returns:
{
  "workload": {
    "activeFeatures": [
      {
        "feature": { "title": "User Authentication", "priority": "high" },
        "myDelegations": [{ "scope": "Create JWT auth endpoints", "status": "pending" }]
      },
      {
        "feature": { "title": "Performance Optimization", "priority": "critical" },
        "myDelegations": [{ "scope": "Fix database queries", "status": "in-progress" }]
    }
  ]
}
```

### 4. **Context Sharing & Coordination**
Agents share implementation details within feature boundaries:

```bash
# Backend completes API contract
update_subtask({
  "featureId": "user-authentication",
  "subtaskId": "auth-api-contract", 
  "status": "completed",
  "output": "JWT endpoints ready: POST /auth/login, POST /auth/signup, GET /auth/me"
})

# Frontend sees progress when checking feature data
get_feature("user-authentication") 
# Shows: subtask output with JWT endpoints info
```

### 5. **Automatic Coordination**
Agents unblock each other by sharing progress and outputs in real-time. The system handles:
- **Priority management**: Critical tasks get attention first
- **Dependency tracking**: Agents know what they're waiting for
- **Context isolation**: Each feature maintains its own scope
- **Load balancing**: Work distributes naturally across available agents

## Advanced Setup

### Custom Data Directory

To store Agent Hub MCP data in a custom location, add environment variables to your configuration:

```json
{
  "mcpServers": {
    "agent-hub": {
      "command": "npx",
      "args": ["-y", "agent-hub-mcp@latest"],
      "env": {
        "AGENT_HUB_DATA_DIR": "/path/to/your/data"
      }
    }
  }
}
```

### For Other MCP Clients

If your AI assistant supports MCP, use these settings:
- **Command**: `npx -y agent-hub-mcp@latest`  
- **Protocol**: Standard MCP over stdio  
- **Data Directory**: `~/.agent-hub` (or set `AGENT_HUB_DATA_DIR`)

## Troubleshooting

Common issues:
- MCP server not connecting → Restart AI assistant
- Commands not recognized → Check custom commands installation
- Agent ID conflicts → Use unique IDs per project

📖 **Need help?** See [Troubleshooting Guide](./docs/TROUBLESHOOTING.md) for comprehensive solutions.

## Requirements

- Node.js 22+
- An MCP-compatible AI assistant (Claude Code, Qwen, Gemini, etc.)

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_HUB_DATA_DIR` | `~/.agent-hub` | Storage directory |

## Contributing

See [Contributing Guide](./docs/CONTRIBUTING.md) for development setup and guidelines.

## Documentation

- **[System Overview](./docs/SYSTEM-OVERVIEW.md)** - Complete architecture and tool reference
- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Solutions for common issues  
- **[Known Issues](./docs/KNOWN-ISSUES.md)** - Current limitations and workarounds
- **[Contributing](./docs/CONTRIBUTING.md)** - Development setup and guidelines

## License

MIT