MCP Tool Hub

Модульный, расширяемый мультисерверный хаб Model Context Protocol, созданный на TypeScript для команд автоматизации ИТ.

Предоставьте вашей LLM доступ к реальным инструментам: файлам, Git, веб-контенту и постоянной памяти. Развертывайте на любое количество клиентских машин одновременно с помощью Ansible.

Архитектура

mcp-tool-hub/
├── packages/
│   ├── core/              ← Shared types + BaseMCPServer abstract class
│   ├── server-filesystem/ ← Sandboxed local file access (read/write/list/delete)
│   ├── server-git/        ← Git log, diff, file contents, branches, status
│   ├── server-fetch/      ← Web fetching: HTML, JSON APIs, URL health checks
│   └── server-memory/     ← Persistent JSON knowledge base (survives restarts)
├── host/                  ← Orchestrator: registry + CLI + stdio JSON interface
├── ansible/               ← Playbook, inventory, systemd service templates
└── docs/                  ← How to add new servers (with template)

Архитектура следует шаблону Model Context Protocol:

Каждый сервер полностью независим — свой пакет, своя сборка
Реестр в хосте сопоставляет toolName → server во время выполнения
CLI предоставляет интерфейс stdio JSON — любая интеграция с LLM отправляет {"toolName":"...", "arguments":{...}} в stdin и считывает результат из stdout
Добавление нового сервера = создание пакета, расширение BaseMCPServer, регистрация в cli.ts

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

1. Установка и сборка

git clone https://github.com/your-org/mcp-tool-hub.git
cd mcp-tool-hub
npm install
npm run build

2. Настройка

cp .env.example .env
# Edit .env with your paths and settings

3. Запуск

# Via npm
npm run start --workspace=host

# Or directly
node host/dist/cli.js

4. Вызов инструмента

Отправьте JSON в stdin, получите JSON из stdout:

echo '{"toolName":"read_file","arguments":{"path":"hello.txt"}}' | node host/dist/cli.js

Доступные инструменты

📁 Сервер файловой системы

Все операции ограничены песочницей MCP_FS_ROOT. Обход путей (../) заблокирован.

Инструмент	Описание
`read_file`	Чтение содержимого файла (utf8 или base64)
`write_file`	Запись или добавление в файл
`list_directory`	Список содержимого директории (опционально рекурсивно)
`delete_file`	Удаление файла
`move_file`	Перемещение или переименование файла
`get_file_info`	Получение размера, дат и типа пути

🔀 Сервер Git

Только для чтения. Операции записи отсутствуют.

Инструмент	Описание
`git_log`	История коммитов для репозитория или файла
`git_show_file`	Содержимое файла в конкретном коммите/ветке
`git_diff`	Разница между двумя ссылками (refs)
`git_status`	Статус рабочего дерева
`git_branches`	Список веток (локальные + опционально удаленные)
`git_show_commit`	Полные детали коммита и diff

🌐 Сервер Fetch

Поддерживает опциональный список разрешенных доменов через MCP_FETCH_ALLOWED_DOMAINS.

Инструмент	Описание
`fetch_url`	Получение HTML или текста по URL
`fetch_json`	Получение и разбор ответа JSON API
`check_url`	Проверка доступности URL (HEAD-запрос)

🧠 Сервер памяти

Постоянная память между перезапусками. Работает на основе JSON-файла.

Инструмент	Описание
`memory_set`	Сохранение значения с ключом, пространством имен и тегами
`memory_get`	Получение значения по ключу
`memory_search`	Полнотекстовый поиск по всем записям
`memory_delete`	Удаление записи
`memory_list_namespaces`	Список всех пространств имен с количеством записей
`memory_clear_namespace`	Удаление всех записей в пространстве имен

Развертывание через Ansible

Развертывание на все клиентские машины одновременно:

cd ansible

# First time
ansible-playbook -i inventory.yml deploy-mcp-hub.yml

# Update only (rebuild + restart)
ansible-playbook -i inventory.yml deploy-mcp-hub.yml --tags update

# Deploy to specific group
ansible-playbook -i inventory.yml deploy-mcp-hub.yml --limit servers

Плейбук:

Устанавливает Node.js 20 (если отсутствует)
Создает выделенного системного пользователя mcp-hub
Копирует и собирает проект
Записывает конфигурацию .env из ваших переменных Ansible
Устанавливает и запускает systemd-службу (автоматический перезапуск при сбое)

Переменные для каждого хоста в inventory.yml позволяют настраивать разные разрешенные домены, уровни логирования и пути для каждой группы машин.

Добавление нового сервера

См. docs/adding-a-new-server.template.ts для получения полного шаблона с комментариями.

Вкратце:

// 1. Create packages/server-myservice/src/my-server.ts
export class MyServer extends BaseMCPServer {
  constructor(options: MyOptions) {
    super(SERVER_INFO, options);
    this.registerTool("my_tool", this.handleMyTool.bind(this));
  }
  private async handleMyTool(args) {
    return this.ok({ result: "done" });
  }
}

// 2. Register in host/src/cli.ts
hub.use(new MyServer({ apiKey: process.env.MY_API_KEY! }));

Идеи: server-slack, server-postgres, server-docker, server-ansible, server-ssh, server-jira

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

Переменная	По умолчанию	Описание
`MCP_DATA_DIR`	`./mcp-data`	Корневая директория для всех данных хаба
`MCP_FS_ROOT`	`./mcp-data/files`	Корень песочницы файловой системы
`MCP_GIT_WORKSPACE`	`./mcp-data/repos`	Базовый путь для репозиториев Git
`MCP_MEMORY_PATH`	`./mcp-data/memory.json`	Файл хранилища памяти
`MCP_FETCH_ALLOWED_DOMAINS`	(пусто = все)	Список разрешенных доменов через запятую
`MCP_LOG_LEVEL`	`info`	`debug\|info\|warn\|error`

Примечания по безопасности

Файловая система: Строго ограничена песочницей. Атаки обхода путей возвращают ошибку, а не данные.
Git: Только чтение. Операции commit, push или clone не предоставляются.
Fetch: Опциональный список разрешенных доменов предотвращает SSRF к внутренним сервисам.
Systemd-служба: Запускается от имени пользователя без прав root с параметрами PrivateTmp=true и NoNewPrivileges=true.

Требования

Node.js ≥ 18 (для нативного API fetch)
Git (для server-git)
Linux с systemd (для развертывания через Ansible)

mcp-tool-hub