FastMCP SonarQube Metrics

FastMCP SonarQube 메트릭

개요

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

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

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

이 프로젝트에 포함된 클라이언트는 코드가 어떻게 작동하는지 테스트하기 위한 것일 뿐입니다. Claude Desktop을 사용하거나 사용자 정의 클라이언트를 직접 개발하는 것이 좋습니다.

이 저장소는 현재 작업 중이므로 일부 기능이 완벽하지 않을 수 있습니다.

지원되는 MCP 도구

• get_status : 구성된 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 이슈를 가져옵니다. 유형, 심각도 및 해결 상태별로 필터링하여 최대 10개까지 결과를 반환합니다.

기술 스택

• 언어: 파이썬
• 프레임워크: FastMCP
• 라이브러리: httpx, pydantic, dotenv, asyncio, json, pathlib, typing, base64
• 도구: SonarQube API

디렉토리 구조

지엑스피1

시작하기

필수 조건

• 파이썬 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> OPENAI_API_KEY=<your-openai-api_key>
   <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 프로젝트 키를 입력해야 합니다.

클라이언트 도구( client_tool.py )

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

클라이언트_랭체인( client_langchain.py )

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

예: 외부 프로젝트에 get_sonarqube_metrics 도구 통합

외부 프로젝트에서 get_sonarqube_metrics 도구를 사용하려면 FastMCP 서버에 연결하여 도구를 호출하는 클라이언트를 생성해야 합니다. 다음은 기본적인 예입니다.

이 예제는 클라이언트를 생성하고, 서버에 연결하고, 프로젝트 키를 사용하여 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. 사용 가능한 도구 찾아보기 도구 섹션에서 다음 사항을 확인할 수 있습니다.
   • 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을 구성합니다(VSCode를 사용하는 Windows): code $env:AppData\Claude\claude_desktop_config.json
3. 서버를 추가한 후 저장하세요.

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

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. 시스템 중심 기능

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

시스템 관련 기능은 server.py 에 정의된 서버 측 도구( get_sonarqube_metrics , get_sonarqube_metrics_history , get_sonarqube_component_tree_metrics )입니다. 이 도구들은 SonarQube API와의 상호작용, 데이터 처리 및 포맷팅을 담당합니다. 최종 사용자에게 직접 표시되지는 않지만 시스템의 핵심 기능을 제공하는 데 필수적입니다.

@mcp.tool() 데코레이터는 모든 도구 함수에 공통적인 동작을 체계적으로 적용하여 FastMCP 서버에 등록되고 클라이언트에서 접근할 수 있도록 보장합니다. 또한, Annotated 와 Field 사용하면 모든 도구에서 일관된 매개변수 정의 및 문서화가 보장됩니다.

적용된 아키텍처 패턴 및 디자인 원칙

• 클라이언트-서버 아키텍처: 이 프로젝트는 클라이언트가 서버에 서비스를 요청하는 클라이언트-서버 아키텍처를 따릅니다.
• 메시지 전달: FastMCP 프레임워크는 메시지 전달을 사용하여 클라이언트와 서버 간의 통신을 용이하게 합니다.
• 비동기 프로그래밍: asyncio 와 httpx 사용하면 비동기 작업이 가능해져 애플리케이션의 성능과 응답성이 향상됩니다.
• 환경 변수를 통한 구성: SonarQube URL과 토큰은 환경 변수를 사용하여 구성되므로 다양한 환경에서 애플리케이션을 보다 쉽게 배포하고 관리할 수 있습니다.
• 도구 기반 설계: 서버는 명확하게 정의된 도구를 통해 기능을 노출하므로 기능을 쉽게 추가하거나 수정할 수 있습니다.
• 오류 처리: 이 프로젝트에는 네트워크 오류, API 오류, 잘못된 데이터 등 잠재적인 문제를 원활하게 처리하기 위한 포괄적인 오류 처리 기능이 포함되어 있습니다.
• 로깅: logging 모듈을 사용하면 자세한 로그를 제공하여 디버깅과 모니터링에 도움이 됩니다.
• 종속성 주입: 프레임워크로 명시적으로 구현되지는 않았지만 환경 변수를 통해 SonarQube URL과 토큰을 구성하면 코드를 수정하지 않고도 다양한 SonarQube 인스턴스를 쉽게 대체할 수 있습니다.

코드 품질 분석

SonarQube 보고서가 없기 때문에 포괄적인 코드 품질 분석을 수행할 수 없습니다. 그러나 코드 구조와 기능을 고려할 때, 다음과 같은 잠재적인 문제가 발생할 수 있습니다.

• 오류 처리 세부성: 오류 처리가 존재하지만, 사용자에게 더 유용한 정보를 제공하기 위해 특정 오류 메시지를 개선할 수 있습니다.
• 테스트 커버리지: 제공된 코드에는 단위 테스트가 포함되어 있지 않습니다. 코드의 신뢰성과 정확성을 보장하기 위해 테스트 커버리지를 추가해야 합니다.
• 코드 중복: 공통 논리를 재사용 가능한 함수나 클래스로 추출하여 코드 중복을 줄일 수 있는 방법이 있을 수 있습니다.

약점과 개선 영역

• 오류 메시지의 명확성 개선: 오류 메시지를 개선하여 사용자에게 문제 해결 방법에 대한 구체적인 지침을 제공합니다.
• 단위 테스트 추가: 서버 측 도구에 대한 단위 테스트를 구현하여 정확성과 안정성을 보장합니다.
• 공통 논리를 리팩토링합니다. 중복된 코드를 식별하여 재사용 가능한 함수나 클래스로 리팩토링합니다.
• 입력 유효성 검사 구현: 서버 측 도구에 입력 유효성 검사를 추가하여 잘못된 데이터가 처리되는 것을 방지합니다.
• 설명서 개선: 예제와 사용 지침을 포함하여 서버 측 도구에 대한 보다 자세한 설명서를 추가합니다.
• 더욱 강력한 구성 시스템 구현: 환경 변수에만 의존하는 대신, 구성 파일이나 전용 설정 클래스와 같은 더욱 강력한 구성 시스템을 사용하는 것을 고려하세요.
• 추가 SonarQube API 엔드포인트에 대한 지원 추가: 프로젝트, 규칙 또는 품질 프로필 관리를 위한 엔드포인트와 같은 추가 SonarQube API 엔드포인트를 지원하도록 시스템을 확장합니다.
• 더욱 사용자 친화적인 클라이언트 인터페이스 구현: 클라이언트 애플리케이션을 위한 그래픽 사용자 인터페이스(GUI)나 보다 정교한 명령줄 인터페이스(CLI)를 개발하는 것을 고려하세요.
• 잠재적인 보안 취약점을 해결합니다. 입력 검증이나 인증과 관련된 취약점 등 잠재적인 보안 취약점이 있는지 코드를 검토합니다.

추가 조사 영역

• 성능 병목 현상: API 요청 처리나 데이터 처리와 관련된 것과 같이 서버 측 도구에서 잠재적인 성능 병목 현상을 조사합니다.
• 확장성 고려 사항: 시스템의 확장성을 평가하고 메시지 큐나 분산 캐싱 시스템 사용과 같이 개선이 가능한 영역을 파악합니다.
• 외부 시스템과의 통합: CI/CD 시스템이나 이슈 추적기 등 다른 개발 도구와의 잠재적 통합을 살펴보세요.
• 고급 기능: 실시간 메트릭 모니터링이나 자동화된 코드 품질 분석과 같은 고급 기능을 연구하고 구현합니다.
• 코드 냄새와 낮은 테스트 범위: 코드베이스에 대한 철저한 분석을 수행하여 코드 냄새와 테스트 범위가 낮은 영역을 식별하고 해결합니다.

속성

자동화된 문서화 시스템인 ArchAI 의 지원을 받아 생성되었습니다.