Метрики 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

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

├── client_test.py - Client application for testing and interacting with the server.
├── server.py - Server application exposing tools to retrieve SonarQube metrics.
├── .env - Environment configuration file (stores SonarQube URL and token).
└── README.md - Project documentation.

Начиная

Предпосылки

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

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

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

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

Сервер ( `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 при запросе.

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

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

import asyncio
from fastmcp import Client
from fastmcp.types import TextContent

async def get_metrics(project_key: str):
    server_path = "server.py" # Adjust if necessary
    client = Client(server_path)
    try:
        async with client:
            result = await client.call_tool(
                "get_sonarqube_metrics", {"project_key": project_key}
            )
            if result:
                content = result[0]
                if isinstance(content, TextContent):
                    metrics = json.loads(content.text)
                    print(metrics)
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    asyncio.run(get_metrics("your-project-key")) # Replace with your project key

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

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

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

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

{
    "mcpServers": {
        "fastmcp-sonarqube-metrics": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/fastmcp-sonarqube-metrics",
                "run",
                "server.py"
            ]
        }
    }
}

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

 uv --directory  /ABSOLUTE/PATH/TO/PARENT/FOLDER/fastmcp-sonarqube-metrics run server.py

Перезапустите 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 , автоматизированной системы документирования.

FastMCP SonarQube Metrics

Integrations