agent-aggregator/
├── src/
│   ├── index.js                 # Main MCP server entry point
│   ├── aggregator/
│   │   ├── AgentAggregator.js   # Core aggregation logic
│   │   ├── MCPConnection.js     # Individual MCP server connection
│   │   └── OpenRouterClient.js  # OpenRouter API integration
│   ├── config/
│   │   └── ConfigLoader.js      # Configuration management
│   └── mcp-servers/            # Custom MCP server implementations
│       ├── README.md           # MCP servers documentation
│       └── qwen_mcp_server.py  # Qwen AI MCP server
├── config/
│   └── agents.json             # Agent configuration file
├── tests/
│   └── integration.test.js     # Integration tests with real services
├── scripts/
│   └── test-server.js          # Manual server testing script
└── docs/                       # Documentation

# Install globally from npm
npm install -g agent-aggregator

# Or clone the repository for development
git clone https://github.com/rnd-pro/agent-aggregator.git
cd agent-aggregator

# Install dependencies
npm install

{
  "mcpServers": {
    "agent-aggregator": {
      "command": "npx",
      "args": ["agent-aggregator"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key",
        "NODE_ENV": "production"
      }
    }
  }
}

{
  "agents": [
    {
      "name": "filesystem",
      "type": "mcp",
      "enabled": true,
      "description": "File system operations server",
      "connection": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
        "env": {}
      },
      "model": {
        "provider": "openrouter",
        "name": "qwen/qwen3-coder:free",
        "apiKey": "${OPENROUTER_API_KEY}"
      }
    }
  ],
  "aggregator": {
    "timeout": 30000,
    "retryAttempts": 3,
    "retryDelay": 1000
  },
  "defaults": {
    "model": {
      "provider": "openrouter",
      "name": "qwen/qwen3-coder:free",
      "apiKey": "${OPENROUTER_API_KEY}",
      "baseUrl": "https://openrouter.ai/api/v1"
    }
  }
}

# For current session
export OPENROUTER_API_KEY="sk-or-v1-your-actual-key-here"

# Or create .env file in project root:
echo "OPENROUTER_API_KEY=sk-or-v1-your-actual-key-here" > .env

# For permanent setup (add to ~/.bashrc or ~/.zshrc):
echo 'export OPENROUTER_API_KEY="sk-or-v1-your-actual-key-here"' >> ~/.zshrc

# Start the MCP server
npm start

# Test the server
npm run test:server

# Run integration tests
npm test

# Development mode with auto-reload
npm run dev

{
  "mcpServers": {
    "agent-aggregator": {
      "command": "npx",
      "args": ["agent-aggregator"]
    }
  }
}

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │────│ Agent Aggregator │────│  Filesystem     │
│   (Cursor)      │    │   (This Server)  │    │   MCP Server    │
└─────────────────┘    │                  │    └─────────────────┘
                       │                  │    ┌─────────────────┐
                       │                  │────│  Qwen AI        │
                       │                  │    │   MCP Server    │
                       │                  │    └─────────────────┘
                       │                  │    ┌─────────────────┐
                       │                  │────│  Claude Code    │
                       │                  │    │   MCP Server    │
                       │                  │    └─────────────────┘
                       │                  │    ┌─────────────────┐
                       │                  │────│  OpenRouter     │
                       │                  │    │  AI Models      │
                       └──────────────────┘    └─────────────────┘

# Debug with MCP inspector
npx @modelcontextprotocol/inspector node src/index.js

{
  "name": "unique-agent-name",
  "type": "mcp",
  "enabled": true,
  "description": "Agent description",
  "connection": {
    "command": "command-to-run",
    "args": ["--arg1", "--arg2"],
    "env": {
      "ENV_VAR": "value"
    }
  },
  "model": {
    "provider": "openrouter",
    "name": "qwen/qwen3-coder:free",
    "apiKey": "${OPENROUTER_API_KEY}"
  }
}

{
  "aggregator": {
    "timeout": 30000,        // Connection timeout in ms
    "retryAttempts": 3,      // Number of retry attempts
    "retryDelay": 1000,      // Delay between retries in ms
    "concurrentConnections": 2  // Max concurrent connections
  },
  "defaults": {
    "model": {
      "provider": "openrouter",
      "name": "qwen/qwen3-coder:free",
      "apiKey": "${OPENROUTER_API_KEY}",
      "baseUrl": "https://openrouter.ai/api/v1"
    }
  }
}

## 🔍 Troubleshooting

### Common Issues

1. **"Could not attach to MCP server"**
   - Check that the MCP server package is installed
   - Verify the command and arguments in configuration
   - Ensure the server supports the MCP protocol

2. **"Connection timeout"**
   - Increase timeout in aggregator configuration
   - Check that the MCP server starts properly
   - Verify network connectivity

3. **"Tool not found"**
   - Ensure the downstream MCP server is connected
   - Check tool name prefixing (format: `agent-name__tool-name`)
   - Verify the tool exists in the downstream server

4. **"OpenRouter API error"**
   - Verify your OPENROUTER_API_KEY is set correctly
   - Check that you have credits/access to the specified model
   - Ensure the model name is correct (e.g., `qwen/qwen3-coder:free`)

5. **"No AI model configured"**
   - Add a `model` section to your agent configuration
   - Ensure the model configuration includes provider, name, and apiKey
   - Check that environment variables are properly expanded

### Debug Mode

Enable debug logging by setting environment variables:

```bash
DEBUG=1 npm start