FastMCP SonarQube Metrics

Метрики FastMCP SonarQube

Обзор

Этот проект предоставляет набор инструментов для извлечения информации о проектах SonarQube с использованием фреймворка FastMCP (Fast Model Context Protocol). Он служит интерфейсом для SonarQube, позволяя пользователям программно получать доступ к метрикам, историческим данным и метрикам дерева компонентов для указанных проектов. Этот автоматизированный доступ позволяет создавать отчеты, анализировать и интегрировать данные SonarQube с другими системами.

Проект отличается тем, что предлагает упрощенный подход на основе сообщений для взаимодействия с API SonarQube, абстрагируясь от сложностей прямых вызовов API и обработки данных. Он предназначен для разработчиков, инженеров DevOps и аналитиков, которым необходимо включить данные SonarQube в свои рабочие процессы или создать индивидуальные решения для создания отчетов.

Этот репозиторий специально содержит клиентские и серверные компоненты, которые облегчают коммуникацию и извлечение данных. Сервер предоставляет инструменты для извлечения данных из SonarQube, в то время как клиент предоставляет интерфейс командной строки для пользователей, чтобы вызывать эти инструменты и отображать результаты. Каждый внутренний модуль вносит свой вклад в достижение этой цели, инкапсулируя определенные функции, такие как взаимодействие API, обработка данных и коммуникация клиент-сервер.

Клиент, включенный в проект, предназначен только для тестирования работы кода; мы рекомендуем использовать Claude Desktop или разработать собственный клиент.

ПОМНИТЕ, ЭТОТ РЕПО НАХОДИТСЯ В РАБОТЕ, НЕКОТОРЫЕ ФУНКЦИИ МОГУТ БЫТЬ НЕ ИДЕАЛЬНЫМИ.

Поддерживаемые инструменты MCP

• get_status : выполняет проверку работоспособности настроенного экземпляра SonarQube.
• list_projects : список всех доступных проектов SonarQube, опционально отфильтрованных по имени или ключу.
• get_sonarqube_metrics : извлекает указанные метрики (ошибки, уязвимости, запахи кода, покрытие, плотность дублирования) для заданного ключа проекта SonarQube.
• get_sonarqube_metrics_history : Извлекает исторические метрики (ошибки, уязвимости, запахи кода, покрытие, плотность дублирования) для данного проекта SonarQube с помощью /api/measures/search_history. Могут применяться дополнительные фильтры даты.
• get_sonarqube_component_tree_metrics : извлекает значения метрик для всех компонентов (например, файлов или каталогов) в проекте с помощью /api/measures/component_tree. Автоматически обрабатывает пагинацию для извлечения всех результатов.
• get_project_issues : Извлечь проблемы SonarQube для указанного проекта, опционально отфильтрованные по типу, серьезности и статусу разрешения. Возвращает до предела результатов (по умолчанию: 10).

Технологический стек

• Язык: Питон
• Фреймворки: FastMCP
• Библиотеки: httpx, pydantic, dotenv, asyncio, json, pathlib, typing, base64
• Инструменты: API SonarQube

Структура каталога

Начиная

Предпосылки

• Питон 3.7+
• Экземпляр SonarQube с доступом через API
• Токен API SonarQube с соответствующими разрешениями
• FastMCP установлен ( pip install fastmcp )
• httpx установлен ( pip install httpx )
• установлен pydantic ( pip install pydantic )
• установлен python-dotenv ( pip install python-dotenv )

Общие этапы сборки

1. Клонируйте репозиторий: git clone <repository_url>
2. Перейдите в каталог проекта: cd fastmcp-sonarqube-metrics
3. Настройте переменные среды: создайте файл .env в корневом каталоге проекта со следующим содержимым:
   SONARQUBE_URL=<your_sonarqube_url> SONARQUBE_TOKEN=<your_sonarqube_token> TRANSPORT=<stdio or sse> GEMINI_API_KEY=<your-gemini-api_key> OPENAI_API_KEY=<your-openai-api_key>
   Замените <your_sonarqube_url> на URL-адрес вашего экземпляра SonarQube (например, http://localhost:9000 ), а <your_sonarqube_token> на ваш токен API SonarQube.
4. Запускаем сервер: python server.py
5. Запустите клиент: python client_test.py(Необязательно, только для теста)
6. Подключитесь к своему клиенту: следуйте официальной документации

Использование модуля

Сервер ( server.py )

Модуль server.py определяет сервер FastMCP, который предоставляет инструменты для получения метрик SonarQube. Он инициализирует сервер, загружает переменные среды, определяет доступные инструменты и управляет связью с API SonarQube. Чтобы использовать сервер, вам необходимо задать переменные среды SONARQUBE_URL и SONARQUBE_TOKEN . Сервер запускается путем прямого запуска скрипта server.py .

Клиент ( client_test.py )

Модуль client_test.py определяет клиент FastMCP, который взаимодействует с сервером. Он запрашивает у пользователя ключ проекта SonarQube, подключается к серверу, вызывает инструменты get_sonarqube_metrics и get_sonarqube_component_tree_metrics и отображает результаты. Чтобы использовать клиент, вам необходимо напрямую запустить скрипт client_test.py и указать действительный ключ проекта SonarQube при запросе.

Клиентский_инструмент ( client_tool.py )

Модуль client_tool.py реализует клиент FastMCP с графическим интерфейсом на основе Tkinter для взаимодействия с сервером SonarQube. При запуске он настраивает регистраторы для подавления несущественных сообщений, загружает переменные среды и запускает бэкэнд чата (ChatBackend) в фоновом режиме, который использует LLM и инструменты MCP, предоставляемые сервером через stdio. Фронтенд (ChatGUI) управляет окном Tkinter, отображает историю сообщений в прокручиваемой области и позволяет пользователю отправлять команды на сервер, запрашивая действительный ключ проекта SonarQube при необходимости. Чтобы использовать клиент, просто запустите скрипт client_tool.py и взаимодействуйте через GUI.

Client_langchain ( client_langchain.py )

Модуль client_langchain.py предоставляет клиент командной строки для взаимодействия с сервером FastMCP и инструментами SonarQube через LangChain. При запуске он загружает переменные среды и настраивает выбранный LLM. Он устанавливает stdio-соединение с сервером ( server.py ), инициализирует сеанс MCP и загружает доступные инструменты (проверка работоспособности, текущие и исторические метрики, список проектов, поиск проблем). Подробная системная подсказка описывает каждый инструмент и его параметры. В интерактивном цикле он считывает пользовательский ввод с консоли, обновляет историю сообщений, вызывает агент React и печатает отформатированный ответ.

Пример: Интеграция инструмента get_sonarqube_metrics во внешний проект

Чтобы использовать инструмент get_sonarqube_metrics во внешнем проекте, вы можете создать клиент, который подключается к серверу FastMCP и вызывает инструмент. Вот простой пример:

В этом примере показано, как создать клиента, подключиться к серверу, вызвать инструмент get_sonarqube_metrics с ключом проекта и обработать результаты. Вам нужно будет адаптировать переменную server_path к фактическому местоположению скрипта server.py в вашей среде.

Чат ArchAI-SonarQube (графический интерфейс)

Легкий клиент Tkinter, который подключается через stdio к серверу FastMCP и предоставляет интерфейс чата в реальном времени для запроса метрик SonarQube, просмотра деревьев компонентов и запуска проверок работоспособности с помощью помощника на основе LLM.

Использование с TRANSPORT=SSE

Вы можете переключить транспортный уровень клиента на Server-Sent Events (SSE), установив переменную среды TRANSPORT перед запуском GUI. Это позволяет получать однонаправленные обновления в реальном времени с сервера FastMCP. Когда сервер запускается в режиме SSE, на порту 8001 открывается постоянное HTTP-соединение. Это позволяет подключаться через совместимые интерфейсы, такие как MCP Inspector.*

1. Запустите сервер в режиме SSE
   uv run mcp dev "<server_name>"
2. Открыть MCP Inspector . Для запуска MCP Inspector в вашем браузере будет предоставлена ссылка (например, http://127.0.0.1:6274 ).
3. Настройка SSE в MCP Inspector
   • Выберите SSE в качестве типа транспорта.
   • Введите URL-адрес: http://localhost:8001/sse
4. Инициировать соединение
5. Просмотрите доступные инструменты. В разделе «Инструменты» вы увидите:
   • get_status
   • get_sonarqube_metrics
   • get_sonarqube_metrics_history
   • get_sonarqube_component_tree_metrics
   • list_projects
   • get_project_issues
6. Выберите и вызовите инструмент. Например, выберите get_project_issues и укажите:
   • project_key : ключ проекта SonarQube
   • issue_type (необязательно): например, BUG , CODE_SMELL
   • severity (необязательно): например, MAJOR , CRITICAL
   • resolved (необязательно): true или false
   • limit (необязательно): максимальное количество возвращаемых вопросов
7. Выполнение и получение результатов Сервер вызовет соответствующий API SonarQube и вернет отформатированный ответ JSON.

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

Вы можете установить этот сервер непосредственно в Claude Desktop с помощью fastmcp:

1. Убедитесь, что FastMCP установлен (pip install fastmcp или uv pip install fastmcp).
2. Настройте Claude for Desktop для любых серверов MCP, которые вы хотите использовать (в Windows с помощью VSCode): code $env:AppData\Claude\claude_desktop_config.json
3. Добавьте свой сервер и сохраните:

4. Чтобы запустить его, выполните:

5. Перезапустите Claude Desktop, если он был запущен. Инструмент "FastMCP SonarQube Metrics" теперь должен быть доступен.

Функциональный анализ

1. Основные обязанности системы

Основная обязанность системы — выступать в качестве моста между пользователем и API SonarQube, предоставляя упрощенный способ получения метрик качества проекта. Он инкапсулирует сложности API SonarQube, предлагая набор инструментов, которые можно легко вызывать и интегрировать в автоматизированные рабочие процессы. Основные службы включают в себя выборку метрик, получение исторических данных и исследование метрик на уровне компонентов в проекте SonarQube. Основополагающей службой является сервер FastMCP, который управляет определениями инструментов и клиент-серверной связью.

2. Проблемы, которые решает система

Система решает проблему программного доступа к данным SonarQube, не требуя от пользователей прямого взаимодействия с API SonarQube. Она решает потребность в автоматизированной отчетности, анализе и интеграции метрик SonarQube с другими системами. В частности, она упрощает такие задачи, как:

• Формирование регулярных отчетов по показателям качества кода.
• Мониторинг тенденций качества кода с течением времени.
• Выявление проблемных компонентов в проекте.
• Интеграция данных SonarQube с другими инструментами разработки.

Архитектура решает эти проблемы, предоставляя набор четко определенных инструментов, которые абстрагируются от сложностей API SonarQube и обеспечивают единый интерфейс для доступа к данным.

3. Взаимодействие модулей и компонентов

Система состоит из двух основных компонентов: клиента и сервера. Клиент инициирует запросы к серверу, указывая инструмент для выполнения и любые входные параметры. Сервер получает запрос, взаимодействует с API SonarQube, обрабатывает данные и отправляет результаты обратно клиенту.

Взаимодействие между клиентом и сервером облегчается фреймворком FastMCP, который обрабатывает передачу сообщений и сериализацию. Сервер определяет доступные инструменты с помощью декоратора @mcp.tool() , который регистрирует функции как вызываемые конечные точки. Клиент вызывает эти инструменты с помощью метода client.call_tool() , который отправляет сообщение на сервер с именем инструмента и входными параметрами.

Сервер использует библиотеку httpx для выполнения асинхронных HTTP-запросов к API SonarQube. Он создает URL-адреса API и параметры запроса на основе исполняемого инструмента и входных параметров, предоставленных клиентом. Затем сервер анализирует ответы JSON от API SonarQube и извлекает соответствующие значения метрик.

4. Функциональность, ориентированная на пользователя и на систему

Функциональность системы, ориентированная на пользователя, — это клиентское приложение ( client_test.py ), которое предоставляет интерфейс командной строки для вызова инструментов извлечения метрик SonarQube. Пользователи взаимодействуют с клиентом, предоставляя ключ проекта SonarQube и, опционально, другие параметры, такие как диапазоны дат или ключи метрик. Затем клиент отображает извлеченные метрики в удобном для восприятия человеком формате.

Системные функции — это серверные инструменты ( get_sonarqube_metrics , get_sonarqube_metrics_history , get_sonarqube_component_tree_metrics ), определенные в server.py . Эти инструменты управляют взаимодействием с API SonarQube, обработкой данных и форматированием. Они не видны напрямую конечным пользователям, но необходимы для обеспечения основных функций системы.

Декоратор @mcp.tool() систематически применяет общие поведения во всех функциях инструмента, гарантируя, что они зарегистрированы на сервере FastMCP и доступны для клиентов. Кроме того, использование Annotated и Field обеспечивает единообразное определение параметров и документирование во всех инструментах.

Архитектурные модели и принципы дизайна, применяемые

• Архитектура клиент-сервер: проект следует архитектуре клиент-сервер, где клиент запрашивает услуги у сервера.
• Передача сообщений: фреймворк FastMCP упрощает взаимодействие между клиентом и сервером с помощью передачи сообщений.
• Асинхронное программирование: использование asyncio и httpx позволяет выполнять асинхронные операции, повышая производительность и скорость реагирования приложения.
• Конфигурация через переменные среды: URL-адрес и токен SonarQube настраиваются с помощью переменных среды, что упрощает развертывание и управление приложением в различных средах.
• Проектирование на основе инструментов: сервер реализует функциональность с помощью четко определенных инструментов, что упрощает добавление или изменение функций.
• Обработка ошибок: проект включает в себя комплексную обработку ошибок для корректного устранения потенциальных проблем, таких как сетевые ошибки, ошибки API и недействительные данные.
• Ведение журнала: использование модуля logging обеспечивает ведение подробных журналов, облегчающих отладку и мониторинг.
• Внедрение зависимостей: хотя это явно не реализовано в виде фреймворка, конфигурация URL-адреса и токена SonarQube через переменные среды позволяет легко заменять различные экземпляры SonarQube без изменения кода.

Анализ качества кода

Из-за отсутствия отчета SonarQube невозможно провести комплексный анализ качества кода. Однако, исходя из структуры и функциональности кода, к потенциальным областям беспокойства относятся:

• Детализация обработки ошибок: хотя обработка ошибок присутствует, конкретные сообщения об ошибках можно было бы улучшить, чтобы предоставить пользователю более полезную информацию.
• Тестовое покрытие: Предоставленный код не включает модульные тесты. Тестовое покрытие должно быть добавлено для обеспечения надежности и корректности кода.
• Дублирование кода: существуют возможности сократить дублирование кода путем извлечения общей логики в повторно используемые функции или классы.

Слабые стороны и области для улучшения

• Повышение ясности сообщений об ошибках: улучшение сообщений об ошибках для предоставления пользователям более конкретных рекомендаций по решению проблем.
• Добавьте модульные тесты: реализуйте модульные тесты для серверных инструментов, чтобы убедиться в их корректности и надежности.
• Реорганизуйте общую логику: определите и реорганизуйте дублирующийся код в повторно используемые функции или классы.
• Реализуйте проверку входных данных: добавьте проверку входных данных в серверные инструменты, чтобы предотвратить обработку недействительных данных.
• Улучшить документацию: добавить более подробную документацию для серверных инструментов, включая примеры и инструкции по использованию.
• Реализуйте более надежную систему конфигурации: рассмотрите возможность использования более надежной системы конфигурации, например файла конфигурации или специального класса настроек, вместо того, чтобы полагаться исключительно на переменные среды.
• Добавьте поддержку дополнительных конечных точек API SonarQube: расширьте систему для поддержки дополнительных конечных точек API SonarQube, например, для управления проектами, правилами или профилями качества.
• Реализуйте более удобный клиентский интерфейс: рассмотрите возможность разработки графического пользовательского интерфейса (GUI) или более сложного интерфейса командной строки (CLI) для клиентского приложения.
• Устраните потенциальные уязвимости безопасности: проверьте код на наличие потенциальных уязвимостей безопасности, например, связанных с проверкой входных данных или аутентификацией.

Дальнейшие направления исследований

• Узкие места производительности: исследуйте потенциальные узкие места производительности в серверных инструментах, например, связанных с обработкой запросов API или обработкой данных.
• Вопросы масштабируемости: оцените масштабируемость системы и определите потенциальные области для улучшения, например, использование очереди сообщений или распределенной системы кэширования.
• Интеграция с внешними системами: изучите потенциальные возможности интеграции с другими инструментами разработки, такими как системы CI/CD или системы отслеживания ошибок.
• Расширенные функции: исследуйте и внедряйте расширенные функции, такие как мониторинг показателей в реальном времени или автоматизированный анализ качества кода.
• Негативные коды и низкое тестовое покрытие: проведите тщательный анализ кодовой базы, чтобы выявить и устранить негативные коды и области с низким тестовым покрытием.

Атрибуция

Создано при поддержке ArchAI , автоматизированной системы документирования.