Argo CD MCP Server

Реализация сервера Model Context Protocol (MCP) для Argo CD, позволяющая ИИ-ассистентам взаимодействовать с вашими приложениями Argo CD с помощью естественного языка. Этот сервер обеспечивает бесшовную интеграцию с Visual Studio Code и другими MCP-клиентами через протоколы передачи stdio и HTTP stream.

Функциональные возможности

• Транспортные протоколы: Поддерживает режимы передачи stdio и HTTP stream для гибкой интеграции с различными клиентами

• Полная интеграция с API Argo CD: Предоставляет всесторонний доступ к ресурсам и операциям Argo CD

• Готовность к работе с ИИ-ассистентами: Предварительно настроенные инструменты для взаимодействия ИИ-ассистентов с Argo CD на естественном языке

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

Сервер предоставляет следующие инструменты управления ArgoCD:

Управление кластерами

• list_clusters: Список всех кластеров, зарегистрированных в ArgoCD

Управление приложениями

• list_applications: Список и фильтрация всех приложений

• get_application: Получение подробной информации о конкретном приложении

• create_application: Создание нового приложения

• update_application: Обновление существующего приложения

• delete_application: Удаление приложения

• sync_application: Запуск операции синхронизации приложения

Управление ресурсами

• get_application_resource_tree: Получение дерева ресурсов для конкретного приложения

• get_application_managed_resources: Получение управляемых ресурсов для конкретного приложения

• get_application_workload_logs: Получение логов рабочих нагрузок приложения (подов, развертываний и т.д.)

• get_resource_events: Получение событий для ресурсов, управляемых приложением

• get_resource_actions: Получение доступных действий для ресурсов

• run_resource_action: Выполнение действия над ресурсом

Установка

Предварительные требования

• Node.js (рекомендуется v18 или выше)

• Менеджер пакетов pnpm (для разработки)

• Экземпляр Argo CD с доступом к API

• Токен API Argo CD (см. инструкции в документации)

Использование с Cursor

1. Следуйте документации Cursor по поддержке MCP и создайте файл .cursor/mcp.json в вашем проекте:

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

2. Начните диалог в режиме Agent, чтобы использовать MCP.

Использование с VSCode

1. Следуйте документации по использованию MCP-серверов в VS Code и создайте файл .vscode/mcp.json в вашем проекте:

{
  "servers": {
    "argocd-mcp-stdio": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

2. Начните диалог с ИИ-ассистентом в VS Code, который поддерживает MCP.

Использование с Claude Desktop

1. Следуйте документации по MCP в Claude Desktop и создайте файл конфигурации claude_desktop_config.json:

{
  "mcpServers": {
    "argocd-mcp": {
      "command": "npx",
      "args": [
        "argocd-mcp@latest",
        "stdio"
      ],
      "env": {
        "ARGOCD_BASE_URL": "<argocd_url>",
        "ARGOCD_API_TOKEN": "<argocd_token>"
      }
    }
  }
}

2. Настройте Claude Desktop на использование этого файла конфигурации в настройках.

Самоподписанные сертификаты

Если ваш экземпляр Argo CD использует самоподписанные сертификаты или сертификаты от частного центра сертификации (CA), вам может потребоваться добавить следующую переменную окружения в вашу конфигурацию:

"NODE_TLS_REJECT_UNAUTHORIZED": "0"

Это отключает проверку TLS-сертификатов для Node.js при подключении к экземплярам Argo CD, использующим самоподписанные сертификаты или сертификаты от частных CA, которые не доверены хранилищем сертификатов вашей системы.

Внимание: Отключение проверки SSL снижает безопасность. Используйте эту настройку только в средах разработки или если вы понимаете последствия для безопасности.

Режим «Только чтение» (Read Only)

Если вы хотите запустить MCP-сервер в режиме «Только чтение», чтобы избежать изменения ресурсов или приложений, вам следует установить переменную окружения:

"MCP_READ_ONLY": "true"

Это отключит следующие инструменты:

• create_application

• update_application

• delete_application

• sync_application

• run_resource_action

По умолчанию все инструменты будут доступны.

Stateless-режим

По умолчанию HTTP-транспорт назначает идентификатор сессии каждому клиентскому подключению и хранит карту активных сессий в памяти. Это хорошо работает для развертываний с одним экземпляром, но вызывает ошибки 400, когда запущено несколько реплик без «липких» сессий (sticky sessions), так как запрос, направленный на другой под, не найдет сессию, созданную на исходном поде.

Чтобы запустить сервер без требований к аффинити сессий, используйте флаг --stateless:

node dist/index.js http --stateless

Или с помощью Docker:

docker run -e ARGOCD_BASE_URL=<argocd_url> -e ARGOCD_API_TOKEN=<argocd_token> \
  argoprojlabs/mcp-for-argocd http --stateless

В stateless-режиме:

• Идентификатор Mcp-Session-Id не возвращается и не требуется — любая реплика может обработать любой запрос

• Учетные данные ArgoCD должны предоставляться с каждым запросом через переменные окружения или заголовки x-argocd-base-url / x-argocd-api-token

• GET /mcp и DELETE /mcp возвращают 405 Method Not Allowed (SSE на уровне сессии и завершение сессии не поддерживаются)

Этот режим рекомендуется для развертываний в Kubernetes с горизонтальным автомасштабированием подов (HPA), где «липкие» сессии на сетевом уровне недоступны.

Для разработки

1. Клонируйте репозиторий:

git clone https://github.com/argoproj-labs/mcp-for-argocd.git
cd mcp-for-argocd

2. Установите зависимости проекта:

pnpm install

3. Запустите сервер разработки с включенной горячей перезагрузкой:

pnpm run dev

Как только сервер запущен, вы можете использовать MCP-сервер в Visual Studio Code или другом MCP-клиенте.

Обновление типов ArgoCD

Чтобы обновить определения типов TypeScript на основе последней спецификации API Argo CD:

1. Скачайте файл swagger.json со страницы релизов ArgoCD, например, вот ссылка на swagger.json для ArgoCD v2.14.11.

2. Поместите скачанный файл swagger.json в корневой каталог проекта argocd-mcp.

3. Сгенерируйте типы TypeScript из определения Swagger, выполнив следующую команду. Это создаст или перезапишет файл src/types/argocd.d.ts:

   pnpm run generate-types

4. Обновите файл src/types/argocd-types.ts, чтобы экспортировать необходимые типы из только что созданного src/types/argocd.d.ts. Этот шаг часто требует ручной проверки, чтобы убедиться, что экспортируются только необходимые типы.

Авторы

Проект был первоначально создан и передан сообществу @jiachengxu, @imwithye, @hwwn и @alexmt из Akuity.