MCP Aggregator

English | Русский

MCP-сервер агрегатор, который читает конфигурацию из MCP.json, автоматически запускает дочерние MCP-серверы и проксирует их инструменты, ресурсы и промпты через единый интерфейс для LLM.

Возможности

• 🚀 Автозапуск дочерних MCP-серверов из конфигурации
• 🔄 Автоперезапуск при падении (экспоненциальный backoff, до 5 попыток)
• 🛠 Tools — проксирование с префиксами {serverName}-{toolName}
• 📄 Resources — проксирование через URI agg://{serverName}/{originalUri}
• 💬 Prompts — проксирование с префиксами {serverName}-{promptName}
• 🪶 Неинвазивность — дочерние серверы не знают об агрегаторе
• 📝 Логирование в stderr (stdout зарезервирован для MCP-протокола)
• 🛡️ Устойчивость к ошибкам — падение одного сервера не ломает остальные

Установка

Через npm (глобально)

npm install -g @vugu/mcp-aggregator

Через npx (без установки)

npx @vugu/mcp-aggregator --config MCP.json

Из исходников

git clone https://github.com/vuguzum/mcp-aggregator.git
cd mcp-aggregator
npm install

Быстрый старт

1. Создайте файл MCP.json с конфигурацией ваших MCP-серверов:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/path"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "./memory.jsonl"
      }
    }
  }
}

2. Запустите агрегатор:

npx @vugu/mcp-aggregator --config MCP.json

Запуск

# С конфигом по умолчанию (MCP.json в текущей директории)
mcp-aggregator

# С указанием пути к конфигу
mcp-aggregator --config /path/to/mcp.json

# С отладочными сообщениями
DEBUG=1 mcp-aggregator --config MCP.json

Подключение к Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "aggregator": {
      "command": "npx",
      "args": ["-y", "@vugu/mcp-aggregator", "--config", "/path/to/MCP.json"]
    }
  }
}

Или с локальной установкой:

{
  "mcpServers": {
    "aggregator": {
      "command": "node",
      "args": ["/path/to/mcp-aggregator/src/index.js", "--config", "/path/to/MCP.json"]
    }
  }
}

Формат конфигурации (MCP.json)

{
  "mcpServers": {
    "имя-сервера": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "env": {
        "KEY": "value"
      }
    }
  }
}

Каждый сервер описывается полями:

• command (обязательно) — команда для запуска
• args (опционально) — массив аргументов
• env (опционально) — дополнительные переменные окружения

Именование инструментов

Инструменты получают префикс имени сервера для уникальности:

| Сервер | Оригинальное имя | Имя через агрегатор | |--------|------------------|---------------------| | filesystem | read_file | filesystem-read_file | | web-search | search | web-search-search | | memory | create_entities | memory-create_entities | | sequential-thinking | sequentialthinking | sequential-thinking-sequentialthinking |

Описание каждого инструмента получает префикс [serverName] для ясности.

Переменные окружения

| Переменная | Описание | |------------|----------| | MCP_CONFIG | Путь к конфигу (если не указан --config) | | DEBUG=1 | Включить отладочные сообщения |

Структура проекта

mcp-aggregator/
├── package.json          # зависимости и скрипты
├── MCP.json              # конфигурация дочерних серверов
├── MCP.json.example      # пример конфигурации
├── README.md             # английская документация
├── README.ru.md          # русская документация
├── LICENSE
├── .gitignore
└── src/
    ├── index.js          # точка входа, запуск, stdio transport
    ├── aggregator.js     # главный агрегатор, обработчики MCP
    ├── child-server.js   # обёртка над дочерним MCP-сервером
    ├── config.js         # загрузка и валидация конфигурации
    └── logger.js         # логирование в stderr

Отладка

Используйте MCP Inspector:

npx @modelcontextprotocol/inspector node src/index.js --config MCP.json

Или включите отладочный режим:

DEBUG=1 mcp-aggregator --config MCP.json

Устойчивость к ошибкам

• Если один дочерний сервер не смог запуститься — агрегатор продолжает работу с остальными
• При потере соединения с дочерним сервером — автоматический перезапуск с экспоненциальным backoff (до 5 попыток)
• Ошибки при вызове инструментов возвращаются как isError: true, не прерывая работу
• Graceful shutdown при SIGINT/SIGTERM/закрытии stdin

Как это работает

1. Загрузка конфигурации — читает MCP.json, парсит mcpServers
2. Запуск дочерних серверов — для каждого запускает процесс через StdioClientTransport (как MCP-клиент)
3. Обнаружение capabilities — запрашивает listTools, listResources, listPrompts
4. Проксирование — регистрирует свои обработчики и маршрутизирует вызовы, добавляя префиксы

Лицензия

MIT © А. Казанцев