Pprof 분석기 MCP 서버

이는 Go로 구현된 MCP(Model Context Protocol) 서버로, Go pprof 성능 프로필을 분석하는 도구를 제공합니다.

특징

analyze_pprof 도구:
- 지정된 Go pprof 파일을 분석하고 직렬화된 분석 결과(예: Top N 목록 또는 플레임 그래프 JSON)를 반환합니다.
- 지원되는 프로필 유형:
  - cpu : 코드 실행 중 CPU 시간 소비를 분석하여 핫스팟을 찾습니다.
  - heap : 현재 메모리 사용량(힙 할당)을 분석하여 메모리 소모가 많은 객체와 함수를 찾습니다.
  - goroutine : 현재 모든 goroutine의 스택 추적을 표시하여 교착 상태, 누수 또는 과도한 goroutine 사용을 진단하는 데 사용됩니다.
  - allocs : 프로그램 실행 중 메모리 할당(해제된 메모리 포함)을 분석하여 빈번하게 할당되는 코드를 찾습니다. ( 아직 구현되지 않음 )
  - mutex : 뮤텍스에 대한 경합을 분석하여 블로킹을 유발하는 잠금을 찾습니다. ( 아직 구현되지 않음 )
  - block : 고루틴 차단을 유발하는 작업(예: 채널 대기, 시스템 호출)을 분석합니다. ( 아직 구현되지 않음 )
- 지원되는 출력 형식: text , markdown , json (상위 N 목록), flamegraph-json (계층적 플레임 그래프 데이터, 기본값).
  - text , markdown : 사람이 읽을 수 있는 텍스트 또는 마크다운 형식.
  - json : 구조화된 JSON 형식으로 상위 N개의 결과를 출력합니다( cpu , heap , goroutine 에 대해 구현됨).
  - flamegraph-json : d3-flame-graph( cpu , heap , 기본 형식)와 호환되는 JSON 형식의 계층적 플레임 그래프 데이터를 출력합니다. 출력은 간결합니다.
- 상위 N개 결과의 구성 가능한 개수( top_n , 기본값은 5, text , markdown , json 형식에 적용).
generate_flamegraph 도구:
- go tool pprof 사용하여 지정된 pprof 파일에 대한 플레임 그래프(SVG 형식)를 생성하고, 지정된 경로에 저장하고, 경로와 SVG 콘텐츠를 반환합니다.
- 지원되는 프로필 유형: cpu , heap , allocs , goroutine , mutex , block .
- 사용자가 출력 SVG 파일 경로를 지정해야 합니다.
- 중요: 이 기능을 사용하려면 Graphviz가 설치되어 있어야 합니다.
open_interactive_pprof 도구(macOS 전용):
- 지정된 pprof 파일에 대해 백그라운드에서 go tool pprof 대화형 웹 UI를 실행하려고 시도합니다. http_address 제공되지 않으면 기본적으로 :8081 포트를 사용합니다.
- 성공적으로 실행되면 백그라운드 pprof 프로세스의 프로세스 ID(PID)를 반환합니다.
- macOS 전용: 이 도구는 macOS에서만 작동합니다.
- 종속성: go 명령이 시스템 PATH에 있어야 합니다.
- 제한 사항: 백그라운드 pprof 프로세스의 오류는 서버에 의해 캡처되지 않습니다. 원격 URL에서 다운로드한 임시 파일은 프로세스가 종료될 때까지( disconnect_pprof_session 통해 수동으로 또는 MCP 서버가 종료될 때) 자동으로 정리되지 않습니다.
disconnect_pprof_session 도구:
- PID를 사용하여 open_interactive_pprof 에서 이전에 시작된 백그라운드 pprof 프로세스를 종료하려고 시도합니다.
- 먼저 인터럽트 신호를 보내고, 인터럽트가 실패하면 Kill 신호를 보냅니다.

설치(라이브러리/도구로서)

go install 사용하여 이 패키지를 직접 설치할 수 있습니다.

지엑스피1

이렇게 하면 pprof-analyzer-mcp 실행 파일이 $GOPATH/bin 또는 $HOME/go/bin 디렉터리에 설치됩니다. 명령을 직접 실행하려면 이 디렉터리가 시스템 PATH에 포함되어 있는지 확인하세요.

소스에서 빌드

Go 환경이 설치되어 있는지 확인하세요(Go 1.18 이상 권장).

프로젝트 루트 디렉토리( pprof-analyzer-mcp )에서 다음을 실행합니다.

go build

이렇게 하면 현재 디렉토리에 pprof-analyzer-mcp (또는 Windows에서는 pprof-analyzer-mcp.exe )라는 실행 파일이 생성됩니다.

`go install` 사용(권장)

go install 사용하여 실행 파일을 $GOPATH/bin 또는 $HOME/go/bin 디렉터리에 설치할 수도 있습니다. 이렇게 하면 명령줄에서 pprof-analyzer-mcp 직접 실행할 수 있습니다(디렉토리가 시스템의 PATH 환경 변수에 추가된 경우).

# Installs the executable using the module path defined in go.mod
go install .
# Or directly using the GitHub path (recommended after publishing)
# go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

Docker로 실행

Docker를 사용하면 Graphviz에 필요한 종속성이 포함되어 서버를 실행하는 편리한 방법입니다.

Docker 이미지 빌드: 프로젝트 루트 디렉토리( Dockerfile 이 있는 곳)에서 다음을 실행합니다.
docker build -t pprof-analyzer-mcp .
Docker 컨테이너를 실행합니다.
docker run -i --rm pprof-analyzer-mcp
- -i 플래그는 STDIN을 열어두는데, 이는 이 MCP 서버에서 사용하는 stdio 전송에 필요합니다.
- --rm 플래그는 컨테이너가 종료될 때 자동으로 컨테이너를 제거합니다.
Docker용 MCP 클라이언트 구성: MCP 클라이언트(예: Roo Cline)를 Docker 내부에서 실행되는 서버에 연결하려면 .roo/mcp.json 을 업데이트합니다.
{ "mcpServers": { "pprof-analyzer-docker": { "command": "docker run -i --rm pprof-analyzer-mcp" } } }
클라이언트가 이 명령을 실행하기 전에 pprof-analyzer-mcp 이미지가 로컬에 빌드되었는지 확인하세요.

릴리스(GitHub Actions를 통해 자동화됨)

이 프로젝트는 GoReleaser 와 GitHub Actions를 사용하여 릴리스 프로세스를 자동화합니다. v* 패턴(예: v0.1.0 , v1.2.3 )과 일치하는 Git 태그가 저장소에 푸시되면 릴리스가 자동으로 실행됩니다.

릴리스 단계:

변경 사항 만들기: 새로운 기능을 개발하거나 버그를 수정합니다.
변경 사항 커밋: 기존 커밋 형식(예: feat: ... , fix: ... )을 사용하여 변경 사항을 커밋하세요. 이는 자동 변경 로그 생성에 중요합니다.
git add . git commit -m "feat: Add awesome new feature" # or git commit -m "fix: Resolve issue #42"
변경 사항 푸시: GitHub의 메인 브랜치에 커밋을 푸시합니다.
git push origin main
태그 만들기 및 푸시: 릴리스할 준비가 되면 새로운 Git 태그를 만들어 GitHub에 푸시합니다.
# Example: Create tag v0.1.0 git tag v0.1.0 # Push the tag to GitHub git push origin v0.1.0
자동 릴리스: 태그를 푸시하면 .github/workflows/release.yml 에 정의된 GoReleaser GitHub Action이 트리거됩니다. 이 작업은 다음을 수행합니다.
- Linux, macOS, Windows(amd64 및 arm64)용 바이너리를 빌드합니다.
- 마지막 태그 이후의 기존 커밋을 기반으로 변경 로그를 생성합니다.
- 변경 로그를 사용하여 새로운 GitHub 릴리스를 만들고 빌드된 바이너리와 체크섬을 자산으로 첨부합니다.

GitHub 저장소의 "작업" 탭에서 릴리스 워크플로 진행 상황을 볼 수 있습니다.

MCP 클라이언트 구성

이 서버는 stdio 전송 프로토콜을 사용합니다. MCP 클라이언트(예: VS Code용 Roo Cline 확장 프로그램)에서 이를 구성해야 합니다.

일반적으로 여기에는 프로젝트 루트의 .roo/mcp.json 파일에 다음 구성을 추가하는 것이 포함됩니다.

{
  "mcpServers": {
    "pprof-analyzer": {
      "command": "pprof-analyzer-mcp"
    }
  }
}

참고: 빌드 방법( go build 또는 go install )과 실행 파일의 실제 위치에 따라 command 값을 조정하세요. MCP 클라이언트가 이 명령을 찾아 실행할 수 있는지 확인하세요.

구성 후 MCP 클라이언트를 다시 로드하거나 재시작하면 PprofAnalyzer 서버에 자동으로 연결됩니다.

종속성

Graphviz : generate_flamegraph 도구를 사용하려면 Graphviz에서 SVG 플레임 그래프를 생성해야 합니다( go tool pprof 명령은 SVG 생성 시 dot 명령을 호출합니다). Graphviz가 시스템에 설치되어 있고 dot 명령이 시스템의 PATH 환경 변수에 있는지 확인하세요.Graphviz 설치:
- macOS(Homebrew 사용):
  brew install graphviz
- 데비안/우분투:
  sudo apt-get update && sudo apt-get install graphviz
- 센트OS/페도라:
  sudo yum install graphviz # or sudo dnf install graphviz
- Windows(Chocolatey 사용):
  choco install graphviz
- 기타 시스템: Graphviz 공식 다운로드 페이지 를 참조하세요.

사용 예(MCP 클라이언트를 통해)

서버가 연결되면 프로필 파일에 file:// , http:// 또는 https:// URI를 사용하여 analyze_pprof 및 generate_flamegraph 도구를 호출할 수 있습니다.

예: CPU 프로필 분석(텍스트 형식, 상위 5개)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
  }
}

예: 힙 프로필 분석(마크다운 형식, 상위 10개)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "top_n": 10,
    "output_format": "markdown"
  }
}

예: 고루틴 프로필 분석(텍스트 형식, 상위 5개)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/goroutine.pprof",
    "profile_type": "goroutine"
  }
}

예: CPU 프로필에 대한 Flame Graph 생성

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "output_svg_path": "/path/to/save/cpu_flamegraph.svg"
  }
}

예: 힙 프로필(inuse_space)에 대한 Flame Graph 생성

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_svg_path": "/path/to/save/heap_flamegraph.svg"
  }
}

예: CPU 프로필 분석(JSON 형식, 상위 3개)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "top_n": 3,
    "output_format": "json"
  }
}

예: CPU 프로필 분석(기본 Flame Graph JSON 형식)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
    // output_format defaults to "flamegraph-json"
  }
}

예: 힙 프로필 분석(명시적 Flame Graph JSON 형식)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_format": "flamegraph-json"
  }
}

예: 원격 CPU 프로필 분석(HTTP URL에서)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://example.com/profiles/cpu.pprof",
    "profile_type": "cpu"
  }
}

예: 온라인 CPU 프로필 분석(GitHub 원시 URL에서)

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu",
    "profile_type": "cpu",
    "top_n": 5
  }
}

예: 온라인 힙 프로필에 대한 플레임 그래프 생성(GitHub 원시 URL에서)

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.heap",
    "profile_type": "heap",
    "output_svg_path": "./online_heap_flamegraph.svg"
  }
}

예: 온라인 CPU 프로필을 위한 대화형 Pprof UI 열기(macOS 전용)

{
  "tool_name": "open_interactive_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu"
    // Optional: "http_address": ":8082" // Example of overriding the default port
  }
}

예: Pprof 세션 연결 해제

{
  "tool_name": "disconnect_pprof_session",
  "arguments": {
    "pid": 12345 // Replace 12345 with the actual PID returned by open_interactive_pprof
  }
}

향후 개선 사항(TODO)

allocs , mutex , block 프로필에 대한 전체 분석 논리를 구현합니다.
allocs , mutex , block 프로필 유형에 대한 json 출력 형식을 구현합니다.
output_format 에 따라 MCP 결과에 적절한 MIME 유형을 설정합니다.
더욱 강력한 오류 처리 및 로깅 수준 제어를 추가합니다.
~~원격 pprof 파일 URI(예: http:// , https:// ) 지원을 고려하세요.~~(완료)

mcp-pprof-anaylzer

Integrations

Pprof 분석기 MCP 서버

특징

설치(라이브러리/도구로서)

소스에서 빌드

`go install` 사용(권장)

Docker로 실행

릴리스(GitHub Actions를 통해 자동화됨)

MCP 클라이언트 구성

종속성

사용 예(MCP 클라이언트를 통해)

향후 개선 사항(TODO)

Integrations

Pprof 분석기 MCP 서버

특징

설치(라이브러리/도구로서)

소스에서 빌드

go install 사용(권장)

Docker로 실행

릴리스(GitHub Actions를 통해 자동화됨)

MCP 클라이언트 구성

종속성

사용 예(MCP 클라이언트를 통해)

향후 개선 사항(TODO)

`go install` 사용(권장)