Gausium OpenAPI MCP 서버

이 프로젝트는 Gausium OpenAPI에 대한 브리지 역할을 하는 MCP(Model Control Protocol) 서버를 구현하여 AI 모델이나 다른 클라이언트가 표준화된 인터페이스를 통해 Gausium 로봇과 상호 작용할 수 있도록 합니다.

건축학

서버는 관심사를 분리하고 유지 관리를 용이하게 하는 계층화된 아키텍처를 따릅니다.

아래 다이어그램은 AI 모델이 MCP 프로토콜을 통해 Gausium 로봇과 상호 작용하는 방식을 보여줍니다.

현재 서버는 MCP 도구로서 다음과 같은 기능을 지원합니다.

list_robots : API 키를 통해 접근 가능한 로봇을 나열합니다. (기반: List Robots API )
get_robot_status : 일련번호를 기준으로 특정 로봇의 자세한 상태를 가져옵니다. (기반: 로봇 상태 가져오기 API )
list_robot_task_reports : 특정 로봇의 청소 작업 보고서를 검색하며, 시간 필터링을 선택적으로 적용할 수 있습니다. ( List Robot Task Reports API 기반)
list_robot_maps : 특정 로봇과 관련된 지도를 나열합니다. ( List Robot Maps API 기반)

이 프로젝트는 Python 모범 사례를 기반으로 한 구조화된 레이아웃을 따릅니다.

지엑스피1

src/gs_openapi/config.py : 기본 URL, API 경로, 환경 변수 이름을 포함합니다.
src/gs_openapi/auth/token_manager.py : OAuth 토큰 획득 및 갱신을 관리합니다.
src/gs_openapi/api/ : httpx 사용하여 Gausium OpenAPI 엔드포인트를 직접 호출하는 기능이 있는 모듈( robots.py , maps.py )이 포함되어 있습니다.
src/gs_openapi/mcp/gausium_mcp.py : API 호출과 토큰 관리를 통합하는 GausiumMCP 클래스를 정의합니다.
main.py : GausiumMCP 초기화하고, @mcp.tool() 사용하여 API 기능을 MCP 도구로 등록하고, 기본 로깅을 구성하고, mcp.run() 사용하여 서버를 시작합니다.

저장소를 복제합니다.
git clone https://github.com/cfrs2005/mcp-gs-robot.git cd mcp-gs-robot
uv 사용하여 가상 환경을 만들고 활성화합니다.
uv venv source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
uv 사용하여 종속성을 설치합니다.
uv pip install -r requirements.txt # Or, if you prefer adding specific core packages: # uv add httpx "mcp[cli]"
자격 증명 구성: 애플리케이션은 Gausium API 자격 증명이 환경 변수로 설정되기를 기대합니다.
- GS_CLIENT_ID : Gausium 애플리케이션 클라이언트 ID입니다.
- GS_CLIENT_SECRET : Gausium 애플리케이션 클라이언트 비밀번호입니다.
- GS_OPEN_ACCESS_KEY : Gausium OpenAPI 액세스 키.
쉘에서 직접 설정할 수 있습니다:
export GS_CLIENT_ID="your_client_id" export GS_CLIENT_SECRET="your_client_secret" export GS_OPEN_ACCESS_KEY="your_access_key"
(또는 개발용으로 src/gs_openapi/config.py 수정하지만 자격 증명은 커밋하지 마세요 ).
서버를 실행합니다:
python main.py
기본적으로 이 명령은 http://0.0.0.0:8000 에서 SSE 전송을 사용하여 서버를 시작합니다. 필요한 경우 stdio 전송을 사용하도록 main.py 수정할 수 있습니다.

서버가 실행되면 MCP 클라이언트(Cursor나 다른 호환 도구)가 적절한 전송(SSE 또는 stdio)을 통해 서버에 연결하여 정의된 도구를 활용할 수 있습니다.

다음은 Cursor가 MCP 서버와 상호 작용하는 방식의 예입니다.

디버깅 정보를 확인하기 위해 서버 로그를 모니터링할 수 있습니다. main.py 의 기본 로깅 설정은 타임스탬프, 레벨, 소스 정보를 제공합니다.

다음은 운영 중 서버 로그 출력의 예입니다.