시스템 정보·패키지 도구
이 도구는 AI 어시스턴트가 서버의 하드웨어, OS, 사용자, 그룹, 네트워크, 디스크, 설치된 소프트웨어를 조회하고 OS 패키지·Python 패키지를 설치하거나 제거할 수 있게 합니다. “web-01은 어떤 OS를 쓰고 있어”, “db-03에 nginx가 설치되어 있어”, “web-01에 requests 패키지를 설치해줘” 같은 요청에 이 도구가 사용됩니다.
모든 도구는 workspace(필수)와 region(선택, 미지정 시 설정된 리전 사용)을 공통으로 받습니다. 아래 표에서는 이 두 파라미터를 생략합니다.
요약
| 도구 | 설명 | 접근 수준 |
|---|---|---|
get_system_info | 하드웨어 사양: CPU 모델, 코어 수, RAM, 아키텍처 | 읽기 전용 |
get_os_version | OS 이름, 버전, 커널 버전, 배포판 | 읽기 전용 |
list_system_users | OS 수준 사용자 계정(passwd 항목) | 읽기 전용 |
list_system_groups | OS 수준 그룹 | 읽기 전용 |
list_system_packages | 설치된 OS 패키지(rpm/deb) | 읽기 전용 |
get_network_interfaces | 네트워크 인터페이스 설정 | 읽기 전용 |
get_disk_info | 디스크 장치 및 파티션 구성 | 읽기 전용 |
get_system_time | 시스템 시각, 타임존, 업타임 | 읽기 전용 |
get_server_overview | 하드웨어·OS·시각·네트워크·디스크를 한 번에 조회 | 읽기 전용 |
list_system_package_entries | 서버의 패키지 관리 항목 | 읽기 전용 |
install_system_package | 패키지 매니저로 OS 패키지 설치 | 추가적 |
remove_system_package | 시스템 패키지 항목 제거 | 파괴적 |
list_python_packages | 설치된 Python 패키지 | 읽기 전용 |
install_python_package | pip로 Python 패키지 설치 | 추가적 |
remove_python_package | Python 패키지 항목 제거 | 파괴적 |
시스템 정보
get_system_info
서버의 하드웨어 및 시스템 사양(CPU 모델, 코어 수, 총 RAM, 아키텍처)을 반환합니다. 워크로드를 배포하기 전에 서버가 하드웨어 요구사항을 충족하는지 확인할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 시스템 정보를 조회할 서버 ID(UUID) |
예시
“web-01의 CPU와 RAM 사양이 어떻게 돼?”
어시스턴트가 get_system_info를 호출해 CPU 모델, 코어 수, RAM 크기, 아키텍처를 알려줍니다.
get_os_version
서버의 OS 이름, 버전, 커널 버전, Linux 배포판 정보를 반환합니다. OS 호환성을 확인하거나 업그레이드를 계획할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | OS 정보를 조회할 서버 ID(UUID) |
예시
“db-03은 어떤 OS와 커널 버전을 쓰고 있어?”
어시스턴트가 get_os_version을 호출해 배포판, 버전, 커널 정보를 반환합니다.
list_system_users
서버의 OS 수준 사용자 계정(passwd 항목)을 나열합니다. UID, 홈 디렉터리, 셸, 그룹 소속 정보를 포함하며 사용자 이름 검색이나 로그인 가능 여부로 필터링할 수 있습니다.
워크스페이스 수준 IAM 사용자를 조회하는 list_iam_users와는 다릅니다. 이 도구는 서버의 OS 계정을 조회합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 사용자 목록을 조회할 서버 ID(UUID) |
username_filter | string | 아니오 | 사용자 이름으로 검색 |
login_enabled_only | boolean | 아니오 | 로그인 가능한 사용자만 반환. 기본값 false |
예시
“web-01에서 로그인 가능한 사용자 목록을 보여줘”
어시스턴트가 login_enabled_only를 true로 설정해 list_system_users를 호출하고 해당하는 계정을 반환합니다.
list_system_groups
서버의 OS 수준 그룹을 나열합니다. GID와 각 그룹의 멤버 목록을 포함하며 그룹 이름 검색으로 필터링할 수 있습니다.
워크스페이스 수준 IAM 그룹을 조회하는 list_iam_groups와는 다릅니다. 이 도구는 서버의 OS 그룹을 조회합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 그룹 목록을 조회할 서버 ID(UUID) |
groupname_filter | string | 아니오 | 그룹 이름으로 검색 |
예시
“db-03에 어떤 그룹이 있고, docker 그룹 멤버는 누구야?”
어시스턴트가 list_system_groups를 호출해(필요하면 이름으로 필터링) 해당하는 그룹의 멤버를 나열합니다.
list_system_packages
서버에 설치된 OS 패키지(rpm/deb)를 나열합니다. 패키지 이름, 버전, 아키텍처를 반환하며 패키지 이름 검색이나 아키텍처로 필터링할 수 있습니다.
이 도구는 서버의 실시간 패키지 목록을 조회합니다. install_system_package로 생성되는 패키지 관리 항목은 아래 list_system_package_entries를 참고하세요.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 패키지 목록을 조회할 서버 ID(UUID) |
package_name | string | 아니오 | 패키지 이름으로 검색 |
architecture | string | 아니오 | 아키텍처로 필터링(예: x86_64, aarch64) |
limit | integer | 아니오 | 반환할 최대 패키지 수. 기본값 100 |
예시
“web-01에 nginx가 설치되어 있어? 버전은 뭐야?”
어시스턴트가 package_name을 nginx로 설정해 list_system_packages를 호출하고 해당 항목을 반환합니다.
get_network_interfaces
서버의 네트워크 인터페이스 설정(인터페이스 이름, IP 주소, MAC 주소, MTU, 링크 상태)을 반환합니다. 네트워크 구성을 파악하거나 연결 문제를 진단할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 네트워크 인터페이스를 조회할 서버 ID(UUID) |
예시
“web-01의 네트워크 인터페이스를 보여줘”
어시스턴트가 get_network_interfaces를 호출해 각 인터페이스의 IP, MAC 주소, 상태를 나열합니다.
get_disk_info
서버의 물리 디스크 장치와 파티션 구성(디스크 모델, 크기, 파티션 마운트 지점, 파일시스템 유형, 용량)을 반환합니다. 디스크와 파티션 데이터를 동시에 조회합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 디스크 정보를 조회할 서버 ID(UUID) |
예시
“db-03은 디스크가 어떻게 파티셔닝되어 있어?”
어시스턴트가 get_disk_info를 호출해 각 디스크의 파티션, 마운트 지점, 파일시스템 유형을 설명합니다.
get_system_time
서버의 현재 시스템 시각, 타임존 설정, 업타임을 반환합니다. 시간 동기화 상태를 확인하거나 서버가 얼마나 오래 실행 중인지 확인할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 시간 정보를 조회할 서버 ID(UUID) |
예시
“web-01의 현재 시각과 업타임이 어떻게 돼?”
어시스턴트가 get_system_time을 호출해 시각, 타임존, 업타임을 알려줍니다.
get_server_overview
get_system_info, get_os_version, get_system_time, get_network_interfaces, get_disk_info를 한 번의 호출로 동시에 조회해 서버의 종합 스냅샷을 반환합니다. 개별 시스템 정보 도구를 여러 번 호출하는 대신 서버의 전체 상태를 한 번에 파악할 때 사용합니다. 내부 조회 중 하나가 실패해도 해당 항목만 오류로 표시되고 나머지 결과는 정상적으로 반환됩니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 개요를 조회할 서버 ID(UUID) |
예시
“web-01 전체 개요를 보여줘”
어시스턴트가 get_server_overview를 호출해 하드웨어, OS, 업타임, 네트워크, 디스크 정보를 한 번에 요약합니다.
패키지 관리
패키지 상태를 조회하는 도구는 두 가지입니다. 위에서 다룬 list_system_packages는 서버의 실시간 패키지 목록을 조회하고, 아래의 list_system_package_entries는 install_system_package와 remove_system_package로 생성되는 패키지 관리 항목을 조회합니다. 패키지를 제거하려면 entry ID가 필요하므로 entries 계열 도구를 사용하세요.
list_system_package_entries
서버의 시스템 패키지 관리 항목(패키지 이름, 버전, OS 패키지 매니저의 설치 정보)을 나열합니다. 설치된 OS 수준 패키지를 감사하거나 remove_system_package에 필요한 entry ID를 찾을 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 패키지 목록을 조회할 서버 ID(UUID) |
page | integer | 아니오 | 페이지네이션 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“web-01의 패키지 항목을 보여줘”
어시스턴트가 list_system_package_entries를 호출해 각 항목의 이름, 버전, 상태를 나열합니다.
install_system_package
OS 패키지 매니저를 통해 서버에 시스템 패키지를 설치합니다. 특정 버전을 지정할 수 있습니다. 설치는 대상 서버에서 비동기로 실행되므로, 호출이 성공적으로 완료됐다는 것은 요청이 접수됐다는 의미이지 설치가 끝났다는 의미가 아닙니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 패키지를 설치할 서버 ID(UUID) |
package_name | string | 예 | 설치할 패키지 이름 |
version | string | 아니오 | 설치할 특정 버전 |
예시
“web-01에 nginx를 설치해줘”
어시스턴트가 package_name을 nginx로 설정해 install_system_package를 호출하고 설치 요청이 접수됐음을 알려줍니다.
remove_system_package
entry ID로 시스템 패키지 항목을 제거하며, 이는 대상 서버에서 패키지 제거를 트리거합니다. 패키지 이름을 직접 받지 않으므로, 먼저 list_system_package_entries로 entry ID를 찾아야 합니다.
이 작업은 파괴적이며 MCP 도구 자체에서는 되돌릴 수 없습니다. entry ID가 의도한 패키지와 일치하는지 확인한 뒤 제거하세요.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
entry_id | string | 예 | 제거할 패키지 항목 ID(list_system_package_entries에서 확인) |
예시
“web-01에서 nginx 패키지를 제거해줘”
어시스턴트가 list_system_package_entries로 nginx의 entry ID를 찾아 사용자에게 확인받은 뒤, 해당 ID로 remove_system_package를 호출합니다.
list_python_packages
서버에 설치된 Python 패키지(이름, 버전, 설치 정보)를 나열합니다. Python 의존성을 감사하거나 특정 라이브러리를 확인할 때 사용합니다.
접근 수준: 읽기 전용
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | Python 패키지 목록을 조회할 서버 ID(UUID) |
page | integer | 아니오 | 페이지네이션 페이지 번호 |
page_size | integer | 아니오 | 페이지당 항목 수 |
예시
“web-01에 어떤 Python 패키지가 설치되어 있어?”
어시스턴트가 list_python_packages를 호출해 설치된 패키지와 버전을 나열합니다.
install_python_package
pip를 통해 서버에 Python 패키지를 설치합니다. 특정 버전을 지정할 수 있습니다. 설치는 대상 서버에서 비동기로 실행됩니다.
접근 수준: 추가적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
server_id | string | 예 | 패키지를 설치할 서버 ID(UUID) |
package_name | string | 예 | 설치할 Python 패키지 이름 |
version | string | 아니오 | 설치할 특정 버전 |
예시
“web-01에 requests 2.31.0을 설치해줘”
어시스턴트가 package_name을 requests, version을 2.31.0으로 설정해 install_python_package를 호출합니다.
remove_python_package
entry ID로 Python 패키지 항목을 제거하며, 이는 대상 서버에서 패키지 제거를 트리거합니다. 패키지 이름을 직접 받지 않으므로, 먼저 list_python_packages로 entry ID를 찾아야 합니다.
이 작업은 파괴적이며 MCP 도구 자체에서는 되돌릴 수 없습니다. entry ID가 의도한 패키지와 일치하는지 확인한 뒤 제거하세요.
접근 수준: 파괴적
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
entry_id | string | 예 | 제거할 Python 패키지 항목 ID(list_python_packages에서 확인) |
예시
“web-01에서 requests 패키지를 제거해줘”
어시스턴트가 list_python_packages로 requests의 entry ID를 찾아 사용자에게 확인받은 뒤, 해당 ID로 remove_python_package를 호출합니다.
관련 문서
- 서버 관리 도구 - 이 도구를 호출하기 전에 서버 목록과 서버 ID를 조회합니다
- 모니터링·알림 도구 - 시간에 따른 CPU, 메모리, 디스크 사용량 지표
- 시작하기 - AI 어시스턴트를 MCP로 Alpacon에 연결하기