FastMCP SonarQube 메트릭

개요

이 프로젝트는 FastMCP(Fast Model Context Protocol) 프레임워크를 사용하여 SonarQube 프로젝트에 대한 정보를 검색하기 위한 도구 세트를 제공합니다. 이 프로젝트는 SonarQube에 대한 인터페이스 역할을 하며, 사용자가 지정된 프로젝트에 대해 메트릭, 기록 데이터 및 구성 요소 트리 메트릭에 프로그래밍 방식으로 액세스할 수 있도록 합니다. 이러한 자동화된 액세스를 통해 SonarQube 데이터를 다른 시스템과 보고, 분석 및 통합할 수 있습니다.

이 프로젝트는 SonarQube API와 상호 작용하는 간소화된 메시지 기반 접근 방식을 제공하여 직접적인 API 호출 및 데이터 처리의 복잡성을 추상화함으로써 차별화됩니다. 이 프로젝트는 워크플로우에 SonarQube 데이터를 통합하거나 사용자 지정 보고 솔루션을 구축해야 하는 개발자, DevOps 엔지니어 및 분석가를 위해 설계되었습니다.

이 저장소는 통신 및 데이터 검색을 용이하게 하는 클라이언트 및 서버 구성 요소를 구체적으로 포함합니다. 서버는 SonarQube에서 데이터를 가져오는 도구를 노출하고, 클라이언트는 사용자가 이러한 도구를 호출하고 결과를 표시할 수 있는 명령줄 인터페이스를 제공합니다. 각 내부 모듈은 API 상호 작용, 데이터 처리 및 클라이언트-서버 통신과 같은 특정 기능을 캡슐화하여 이 목표에 기여합니다.

프로젝트에 포함된 클라이언트는 코드 작동 방식을 테스트하기 위한 용도일 뿐이며, Claude Desktop을 사용하거나 직접 사용자 지정 클라이언트를 개발하는 것을 권장합니다.

주의: 이 저장소는 작업 진행 중이며 일부 기능이 완벽하지 않을 수 있습니다.

Related MCP server: MCP QQ Music Test Server

호스팅 배포

Fronteir AI에서 호스팅 배포를 이용할 수 있습니다.

지원되는 MCP 도구

• get_status: 구성된 SonarQube 인스턴스에 대한 상태 확인을 수행합니다.

• create_sonarqube_project: 새로운 SonarQube 프로젝트를 생성합니다. 관리자 권한이 필요합니다.

• delete_sonarqube_project: SonarQube 프로젝트를 삭제합니다. 관리자 권한이 필요합니다. 주의해서 사용하세요!

• list_projects: 액세스 가능한 모든 SonarQube 프로젝트를 나열하며, 이름이나 키로 필터링할 수 있습니다.

• get_sonarqube_metrics: 지정된 SonarQube 프로젝트 키에 대해 지정된 메트릭(버그, 취약점, 코드 스멜, 커버리지, 중복 밀도)을 검색합니다.

• get_sonarqube_metrics_history: /api/measures/search_history를 사용하여 지정된 SonarQube 프로젝트에 대한 기록 메트릭(버그, 취약점, 코드 스멜, 커버리지, 중복 밀도)을 검색합니다. 선택적으로 날짜 필터를 적용할 수 있습니다.

• get_sonarqube_component_tree_metrics: /api/measures/component_tree를 사용하여 프로젝트의 모든 구성 요소(예: 파일 또는 디렉터리)에 대한 메트릭 값을 검색합니다. 모든 결과를 검색하기 위해 페이지 매김을 자동으로 처리합니다.

• get_project_issues: 지정된 프로젝트에 대한 SonarQube 이슈를 가져오며, 유형, 심각도 및 해결 상태별로 필터링할 수 있습니다. 최대 limit 결과(기본값: 10)를 반환합니다.

기술 스택

• 언어: Python

• 프레임워크: FastMCP

• 라이브러리: httpx, pydantic, dotenv, asyncio, json, pathlib, typing, base64

• 도구: SonarQube API

디렉터리 구조

├── client_test.py - Client application for testing and interacting with the server.
├── server.py - Server application exposing tools to retrieve SonarQube metrics.
├── client_tool.py - Client with a graphical interface to interact with the SonarQube server.
├── client_langchain.py - Command-line client to interact with the FastMCP server and SonarQube tools via LangChain
├── .env - Environment configuration file (stores SonarQube URL and token).
└── README.md - Project documentation.

시작하기

사전 요구 사항

• Python 3.7+

• API 액세스가 가능한 SonarQube 인스턴스

• 적절한 권한이 있는 SonarQube API 토큰

• 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>
   GEMINI_MODEL=<your-gemini-model> (Optional)

   AzureOpenAI를 사용하려는 경우, OpenAI 및 Groq와 스키마가 동일합니다:

   SONARQUBE_URL=<your_sonarqube_url>
   SONARQUBE_TOKEN=<your_sonarqube_token>
   TRANSPORT=<stdio or sse>
   AZURE_OPENAI_API_KEY=<your-azureopenai-api_key>
   AZURE_OPENAI_ENDPOINT=<your-azureopenai-endpoint>
   AZURE_DEPLOYMENT=<your-azureopenai-deployment>
   AZURE_API_VERSION=<your-azureopenai-api_version>

   <your_sonarqube_url>을 SonarQube 인스턴스의 URL(예: http://localhost:9000)로, <your_sonarqube_token>을 SonarQube API 토큰으로 바꿉니다.

4. 서버 실행: python server.py

5. 클라이언트 실행: python client_test.py (선택 사항, 테스트 전용)

6. 클라이언트에 연결: 공식 문서를 따르세요.

모듈 사용법

서버 (server.py)

server.py 모듈은 SonarQube 메트릭을 검색하기 위한 도구를 노출하는 FastMCP 서버를 정의합니다. 서버를 초기화하고, 환경 변수를 로드하고, 사용 가능한 도구를 정의하며, SonarQube API와의 통신을 처리합니다. 서버를 사용하려면 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 프로젝트 키를 제공하고 .env 파일에서 전송 유형을 stdio로 설정해야 합니다.

Client_tool (client_tool.py)

client_tool.py 모듈은 SonarQube 서버와 상호 작용하기 위해 Tkinter 기반 그래픽 인터페이스를 갖춘 FastMCP 클라이언트를 구현합니다. 시작 시 필수적이지 않은 메시지를 억제하도록 로거를 구성하고, 환경 변수를 로드하고, 백그라운드에서 채팅 백엔드(ChatBackend)를 실행합니다. 이 백엔드는 LLM과 stdio를 통해 서버가 노출하는 MCP 도구를 사용합니다. 프론트엔드(ChatGUI)는 Tkinter 창을 관리하고, 스크롤 가능한 영역에 메시지 기록을 표시하며, 사용자가 서버에 명령을 보낼 수 있도록 합니다(필요 시 유효한 SonarQube 프로젝트 키를 요청함). 클라이언트를 사용하려면 client_tool.py 스크립트를 실행하고 GUI를 통해 상호 작용하면 됩니다.

Client_langchain (client_langchain.py)

client_langchain.py 모듈은 LangChain을 통해 FastMCP 서버 및 SonarQube 도구와 상호 작용하는 명령줄 클라이언트를 제공합니다. 시작 시 환경 변수를 로드하고 선택한 LLM을 구성합니다. 서버(server.py)에 대한 stdio 연결을 설정하고, MCP 세션을 초기화하고, 사용 가능한 도구(상태 확인, 현재 및 기록 메트릭, 프로젝트 목록, 이슈 검색)를 로드합니다. 자세한 시스템 프롬프트는 각 도구와 해당 매개변수를 설명합니다. 대화형 루프에서 콘솔로부터 사용자 입력을 읽고, 메시지 기록을 업데이트하고, React 에이전트를 호출하고, 서식이 지정된 응답을 출력합니다.

예시: 외부 프로젝트에서 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 스크립트 위치에 맞게 조정해야 합니다.

ArchAI-SonarQube 채팅 (GUI)

stdio를 통해 FastMCP 서버에 연결하고 SonarQube 메트릭 쿼리, 구성 요소 트리 탐색 및 LLM 기반 어시스턴트를 통한 상태 확인 실행을 위한 실시간 채팅 인터페이스를 노출하는 경량 Tkinter 클라이언트입니다.

TRANSPORT=SSE 사용

GUI를 시작하기 전에 TRANSPORT 환경 변수를 설정하여 클라이언트의 전송 계층을 SSE(Server-Sent Events)로 전환할 수 있습니다. 이를 통해 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. MCP Inspector에서 SSE 구성

   • 전송 유형으로 SSE 선택

   • URL 입력: http://localhost:8001/sse

4. 연결 시작

5. 사용 가능한 도구 탐색 Tools 섹션에서 다음을 확인할 수 있습니다:

   • 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. 실행 및 결과 검색 서버가 적절한 SonarQube API를 호출하고 서식이 지정된 JSON 응답을 반환합니다.

Claude Desktop 사용

fastmcp를 사용하여 이 서버를 Claude Desktop에 직접 설치할 수 있습니다:

1. FastMCP가 설치되어 있는지 확인합니다(pip install fastmcp 또는 uv pip install fastmcp).

2. 사용하려는 MCP 서버에 대해 Claude for Desktop을 구성합니다(Windows에서 VSCode 사용): code $env:AppData\Claude\claude_desktop_config.json

3. 서버를 추가하고 저장합니다:

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

4. 다음을 실행하여 시작합니다:

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

5. Claude Desktop이 실행 중이었다면 다시 시작합니다. 이제 "FastMCP SonarQube Metrics" 도구를 사용할 수 있습니다.

기능 분석

1. 시스템의 주요 책임

시스템의 주요 책임은 사용자와 SonarQube API 사이의 가교 역할을 하여 프로젝트 품질 메트릭을 검색하는 간소화된 방법을 제공하는 것입니다. SonarQube API의 복잡성을 캡슐화하여 쉽게 호출하고 자동화된 워크플로우에 통합할 수 있는 도구 세트를 제공합니다. 핵심 서비스에는 메트릭 가져오기, 기록 데이터 검색 및 SonarQube 프로젝트 내의 구성 요소 수준 메트릭 탐색이 포함됩니다. 기반 서비스는 도구 정의와 클라이언트-서버 통신을 관리하는 FastMCP 서버입니다.

2. 시스템이 해결하는 문제

이 시스템은 사용자가 SonarQube API와 직접 상호 작용할 필요 없이 프로그래밍 방식으로 SonarQube 데이터에 액세스하는 문제를 해결합니다. SonarQube 메트릭을 다른 시스템과 자동화된 보고, 분석 및 통합해야 하는 필요성을 해결합니다. 구체적으로 다음과 같은 작업을 간소화합니다:

• 코드 품질 메트릭에 대한 정기 보고서 생성.

• 시간 경과에 따른 코드 품질 추세 모니터링.

• 프로젝트 내 문제 구성 요소 식별.

• SonarQube 데이터를 다른 개발 도구와 통합.

아키텍처는 SonarQube API의 복잡성을 추상화하고 데이터 액세스를 위한 일관된 인터페이스를 제공하는 잘 정의된 도구 세트를 제공함으로써 이러한 문제를 해결합니다.

3. 모듈 및 구성 요소의 상호 작용

시스템은 클라이언트와 서버라는 두 가지 주요 구성 요소로 구성됩니다. 클라이언트는 실행할 도구와 입력 매개변수를 지정하여 서버에 요청을 시작합니다. 서버는 요청을 수신하고, SonarQube API와 상호 작용하고, 데이터를 처리하고, 결과를 클라이언트로 다시 보냅니다.

클라이언트와 서버 간의 상호 작용은 메시지 전달 및 직렬화를 처리하는 FastMCP 프레임워크에 의해 촉진됩니다. 서버는 함수를 호출 가능한 엔드포인트로 등록하는 @mcp.tool() 데코레이터를 사용하여 사용 가능한 도구를 정의합니다. 클라이언트는 도구 이름과 입력 매개변수가 포함된 메시지를 서버로 보내는 client.call_tool() 메서드를 사용하여 이러한 도구를 호출합니다.

서버는 httpx 라이브러리를 사용하여 SonarQube API에 비동기 HTTP 요청을 수행합니다. 실행 중인 도구와 클라이언트가 제공한 입력 매개변수를 기반으로 API URL 및 요청 매개변수를 구성합니다. 그런 다음 서버는 SonarQube API의 JSON 응답을 구문 분석하고 관련 메트릭 값을 추출합니다.

4. 사용자 대면 기능 vs 시스템 대면 기능

시스템의 사용자 대면 기능은 SonarQube 메트릭 검색 도구를 호출하기 위한 명령줄 인터페이스를 제공하는 클라이언트 애플리케이션(client_test.py)입니다. 사용자는 SonarQube 프로젝트 키와 선택적으로 날짜 범위나 메트릭 키와 같은 기타 매개변수를 제공하여 클라이언트와 상호 작용합니다. 그런 다음 클라이언트는 검색된 메트릭을 사람이 읽을 수 있는 형식으로 표시합니다.

시스템 대면 기능은 server.py에 정의된 서버 측 도구(get_sonarqube_metrics, get_sonarqube_metrics_history, get_sonarqube_component_tree_metrics)입니다. 이러한 도구는 SonarQube API와의 상호 작용, 데이터 처리 및 서식 지정을 처리합니다. 이러한 도구는 최종 사용자에게 직접 보이지 않