Gemini CLI 및 Go로 MCP 서버를 빌드하는 방법

1. 소개

이 Codelab에서는 모델 컨텍스트 프로토콜 (MCP) 서버를 빌드하고 배포하여 Gemini CLI의 기능을 확장하는 방법을 알아봅니다. Go 개발용 커스텀 도구를 제공하는 Go 기반 서버인 godoctor를 빌드하여 Gemini CLI를 범용 코딩 어시스턴트에서 특화된 Go 개발 전문가로 탈바꿈시킵니다.

이 Codelab에서는 '프롬프트 기반' 접근 방식을 사용합니다. 여러분은 기술 책임자로서 AI 어시스턴트 (Gemini CLI)에 프롬프트를 제공합니다. 목표는 프로젝트 요구사항을 효과적인 프롬프트로 변환하고 AI가 구현 세부정보를 처리하도록 하는 방법을 알아보는 것입니다.

이 프로젝트의 핵심은 모델 컨텍스트 프로토콜 (MCP)입니다. MCP는 Gemini와 같은 대규모 언어 모델(LLM)이 외부 도구 및 서비스와 통신하는 방식을 표준화하는 오픈소스 프로토콜입니다. AI가 내장된 지식을 넘어 실제 정보에 액세스하고 작업을 수행할 수 있도록 지원하는 브리지 역할을 합니다. MCP 서버를 빌드하면 Gemini CLI가 발견하고 사용할 수 있는 커스텀 플러그인을 만들어 새로운 기술을 효과적으로 가르칠 수 있습니다.

학습할 내용

Gemini CLI를 설치하고 구성하는 방법
소프트웨어 개발에서 AI 어시스턴트를 안내하기 위한 효과적인 프롬프트를 작성하는 방법
AI 어시스턴트에 컨텍스트와 가이드라인을 제공하는 방법
MCP 서버를 만들어 Gemini CLI 기능을 보강하는 방법
Go 애플리케이션을 컨테이너화하여 Google Cloud Run에 배포하는 방법

필요한 항목

이 워크숍은 필요한 모든 종속 항목 (gcloud CLI, Go, Docker, Gemini CLI)이 사전 설치된 Google Cloud Shell 내에서 전부 진행할 수 있습니다.

또는 자체 머신에서 작업하려면 다음이 필요합니다.

Node.js 20 이상
Google Cloud SDK (gcloud CLI)가 설치되고 초기화됨
시스템에 설치된 Go 1.24 이상
시스템에 설치된 Docker

주요 기술

여기에서 활용할 기술에 대한 자세한 내용을 확인할 수 있습니다.

Gemini CLI: 확장할 AI 기반 명령줄 인터페이스
모델 컨텍스트 프로토콜 (MCP): Gemini CLI가 맞춤 도구와 통신할 수 있도록 지원하는 오픈소스 프로토콜
MCP용 Go SDK: MCP 서버를 구현하는 데 사용할 Go 라이브러리

성공적인 Codelab을 위한 도움말

AI 어시스턴트를 활용하면 새로운 방식으로 소프트웨어를 개발할 수 있습니다. 원활하고 성공적인 경험을 위한 몇 가지 도움말을 소개합니다.

ESC 키를 눌러도 됩니다. AI는 때로 동의할 수 없는 작업이나 코드를 제안할 수 있습니다. ESC 키를 사용하여 제안된 작업을 취소하고 새로운 프롬프트를 제공하여 올바른 방향으로 안내합니다. 여러분이 바로 조종사 역할을 하는 것입니다.
도구 사용을 권장합니다. AI가 길을 잃은 듯하거나 정보를 꾸며내고 있다면 제공되는 도구를 사용하도록 권장합니다. 'Google 검색을 사용해 확인할 수 있어?' 또는 'read_file 도구를 사용해 현재 코드를 이해하고 변경사항을 적용해'와 같은 프롬프트가 매우 효과적일 수 있습니다.
수동 변경을 최대한 자제합니다. AI가 모든 작업을 수행하도록 해 봅니다. 이것이 바로 여러분이 연습할 핵심 기술입니다. 하지만 수동으로 변경해야 한다면 나중에 AI에 알려 주세요. 'README.md 파일을 수동으로 업데이트했어. 다시 읽고 내용을 숙지해'와 같은 프롬프트를 사용하면 AI가 프로젝트와 동기화된 상태를 유지할 수 있습니다.
껐다가 다시 켜 보셨나요? 드물게 AI가 사용자의 명령어와 반대되는 특정 경로를 강제로 적용하려고 하는 경우가 있는데, 이는 컨텍스트 저하(때로는 '컨텍스트 로트'라고도 함) 때문일 수 있습니다. 이 경우 Gemini CLI 명령어 '/compress'를 사용하여 컨텍스트 노이즈를 줄이거나, 극단적인 경우에는 '/clear' 명령어를 사용하여 전체 세션 기록을 지울 수 있습니다.

2. 환경 설정

다음 옵션 중 하나를 선택합니다. 자체 학습 환경 설정: 이

자체 머신에서 Codelab을 실행하거나, 클라우드에서 Codelab을 완전히 실행하려면 Cloud Shell을 시작하세요.

자습형 환경 설정

Google Cloud Console에 로그인하여 새 프로젝트를 만들거나 기존 프로젝트를 재사용합니다. 아직 Gmail이나 Google Workspace 계정이 없는 경우 계정을 만들어야 합니다.

프로젝트 이름은 이 프로젝트 참가자의 표시 이름입니다. 이는 Google API에서 사용하지 않는 문자열이며 언제든지 업데이트할 수 있습니다.
프로젝트 ID는 모든 Google Cloud 프로젝트에서 고유하며, 변경할 수 없습니다(설정된 후에는 변경할 수 없음). Cloud 콘솔은 고유한 문자열을 자동으로 생성합니다. 일반적으로는 신경 쓰지 않아도 됩니다. 대부분의 Codelab에서는 프로젝트 ID (일반적으로 PROJECT_ID로 식별됨)를 참조해야 합니다. 생성된 ID가 마음에 들지 않으면 다른 임의 ID를 생성할 수 있습니다. 또는 직접 시도해 보고 사용 가능한지 확인할 수도 있습니다. 이 단계 이후에는 변경할 수 없으며 프로젝트 기간 동안 유지됩니다.
참고로 세 번째 값은 일부 API에서 사용하는 프로젝트 번호입니다. 이 세 가지 값에 대한 자세한 내용은 문서를 참고하세요.

다음으로 Cloud 리소스/API를 사용하려면 Cloud 콘솔에서 결제를 사용 설정해야 합니다. 이 Codelab 실행에는 많은 비용이 들지 않습니다. 이 튜토리얼이 끝난 후에 요금이 청구되지 않도록 리소스를 종료하려면 만든 리소스 또는 프로젝트를 삭제하면 됩니다. Google Cloud 신규 사용자는 300달러(USD) 상당의 무료 체험판 프로그램에 참여할 수 있습니다.

Cloud Shell 시작

Google Cloud를 노트북에서 원격으로 실행할 수 있지만, 이 Codelab에서는 Cloud에서 실행되는 명령줄 환경인 Google Cloud Shell을 사용합니다.

Google Cloud Console의 오른쪽 상단 툴바에 있는 Cloud Shell 아이콘을 클릭합니다.

Cloud Shell 활성화

환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 완료되면 다음과 같이 표시됩니다.

환경이 연결되었음을 보여주는 Google Cloud Shell 터미널 스크린샷

가상 머신에는 필요한 개발 도구가 모두 들어있습니다. 영구적인 5GB 홈 디렉터리를 제공하고 Google Cloud에서 실행되므로 네트워크 성능과 인증이 크게 개선됩니다. 이 Codelab의 모든 작업은 브라우저 내에서 수행할 수 있습니다. 아무것도 설치할 필요가 없습니다.

3. Gemini CLI 시작하기

이 섹션에서는 환경에 맞게 설치하고 구성하는 등 Gemini CLI에 대해 알아봅니다.

Gemini CLI란 무엇인가요?

Gemini CLI는 다양한 개발 작업을 지원하는 AI 기반 명령줄 인터페이스입니다. 프로젝트의 컨텍스트를 이해하고, 질문에 답하고, 코드를 생성하고, 외부 도구를 사용하여 기능을 확장할 수 있습니다.

설치

npm을 사용하여 Gemini CLI를 전역적으로 설치합니다.

npm install -g @google/gemini-cli

다음을 실행하여 CLI가 설치되었는지 확인할 수 있습니다.

gemini --version

구성

Gemini CLI의 동작은 구성 파일과 환경 변수로 제어됩니다. 주요 파일이 두 개 있습니다.

GEMINI.md: 이 파일은 AI에 가이드라인과 컨텍스트를 제공합니다. CLI는 이 파일을 읽고 프로젝트의 코딩 표준과 규칙을 이해합니다.
.gemini/settings.json: 이 파일은 CLI의 구성과 외부 도구에 연결하는 방식을 제어합니다. 이 파일은 나중에 이 실습에서 빌드하는 MCP 서버를 사용하도록 CLI를 구성하는 데 사용됩니다.

먼저 환경을 설정한 다음 GEMINI.md 파일을 만듭니다. settings.json 파일은 나중에 구성됩니다.

프로젝트 디렉터리를 만들고 초기화합니다.

mkdir godoctor && cd godoctor
go mod init godoctor

Google Cloud 애플리케이션 기본 사용자 인증 정보로 인증합니다.

이 Codelab에서 사용할 GCP 프로젝트에 액세스할 수 있는 계정에 로그인해야 합니다.

Google Cloud SDK가 설치 및 초기화되었는지 확인합니다.
다음 명령어를 실행하여 애플리케이션 기본 사용자 인증 정보를 설정합니다.

gcloud auth application-default login

4. 컨텍스트 파일 (GEMINI.md)

기본 이름 GEMINI.md를 사용하는 컨텍스트 파일은 Gemini 모델에 지시 컨텍스트를 제공하는 데 사용됩니다. 이러한 파일을 사용하여 프로젝트별 지침을 제공하거나, 페르소나를 정의하거나, 코딩 스타일 가이드를 제공하여 AI의 대답을 더 정확하게 맞춤설정할 수 있습니다.

AI 어시스턴트가 고품질의 관용적인 Go 코드를 생성하도록 Go 개발자를 위한 몇 가지 일반적인 권장사항이 포함된 GEMINI.md를 작성할 예정입니다.

목표: 이 프로젝트를 진행하는 동안 AI 어시스턴트의 규칙 집합 역할을 하는 GEMINI.md 파일을 만듭니다.

IDE를 열어 아래 콘텐츠로 GEMINI.md 파일을 만듭니다. Cloud Shell을 사용하는 경우 아래 명령어를 사용하여 편집기를 열 수 있습니다.

cloudshell edit .

작업: godoctor 디렉터리의 루트에 GEMINI.md라는 파일을 만들고 다음 콘텐츠를 붙여넣습니다.

# Go Development Guidelines
All code contributed to this project must adhere to the following principles.

## 1. Formatting
All Go code **must** be formatted with `gofmt` before being submitted.

## 2. Naming Conventions
- **Packages:** Use short, concise, all-lowercase names.
- **Variables, Functions, and Methods:** Use `camelCase` for unexported identifiers and `PascalCase` for exported identifiers.
- **Interfaces:** Name interfaces for what they do (e.g., `io.Reader`), not with a prefix like `I`.

## 3. Error Handling
- Errors are values. Do not discard them.
- Handle errors explicitly using the `if err != nil` pattern.
- Provide context to errors using `fmt.Errorf("context: %w", err)`.

## 4. Simplicity and Clarity
- "Clear is better than clever." Write code that is easy to understand.
- Avoid unnecessary complexity and abstractions.
- Prefer returning concrete types, not interfaces.

## 5. Documentation
- All exported identifiers (`PascalCase`) **must** have a doc comment.
- Comments should explain the *why*, not the *what*.

## 6. Project structure
- cmd/ contains source code for target binaries (e.g. server, client)
- internal/ contains source code for packages not meant to be exported (e.g. internal/tools/hello)
- bin/ contains the compiled binaries
- At the root place README.md, go.mod and go.sum

이제 개발 환경이 완전히 설정되었습니다.

5. 초기 빌드: 문서 서버

첫 번째 목표는 godoctor 서버의 초기 버전을 만드는 것입니다. 이 버전은 Go 문서 조회 기능을 제공하는 read_docs이라는 단일 도구가 포함된 최소한의 애플리케이션이어야 합니다.

목표: go doc 명령어를 노출하는 프로덕션 레디 MCP 서버를 만들어 LLM에서 Go 문서를 쿼리할 수 있도록 합니다.

셸에서 Gemini CLI 명령어를 실행합니다.

gemini

CLI를 처음 실행하면 인증 모드와 테마를 선택하라는 메시지가 표시됩니다.

Cloud Shell에서 이 Codelab을 실행하는 경우 Cloud Shell 사용자 인증 정보 사용 옵션을 선택합니다. 그렇지 않은 경우 Google로 로그인을 사용하여 개인 Google 계정으로 로그인하면 Gemini CLI의 넉넉한 무료 등급을 이용할 수 있습니다. 인증 선택 화면은 다음과 같이 표시됩니다.

선택 항목을 변경해야 하는 경우 /auth를 입력하고 Enter 키를 눌러 이 메뉴를 다시 열 수 있습니다.

다음으로 테마를 선택하라는 메시지가 표시됩니다.

/auth과 마찬가지로 /theme 명령어를 사용하면 나중에 테마를 변경할 수도 있습니다.

인증 방법과 선호하는 테마를 선택하면 명령 프롬프트로 이동합니다. 여기에 명령어를 입력하면 됩니다. 예를 들면 다음과 같습니다.

Write a hello world application in Go

CLI는 자체 추론(Gemini Flash 또는 Gemini Pro와 같은 Gemini 모델을 통해)과 도구를 결합하여 작업을 수행합니다. 파일 시스템이나 API, 데이터베이스 등의 외부 서비스와 상호작용해야 할 때마다 도구를 사용합니다. 기본 제공되는 도구에는 read_file, write_file, web_fetch, google_search 등이 있습니다. 빌드하는 MCP 서버는 CLI에서 사용할 수 있는 도구이기도 합니다.

도구를 처음 실행할 때 권한을 요청합니다. 일회성 권한 (한 번만 허용)을 부여하거나, 세션의 나머지 부분에 대해 포괄적인 승인 (항상 허용)을 제공하거나, 요청을 거부할 수 있습니다. 파일 수정 작업인 경우 필요에 따라 외부 편집기를 사용하여 파일을 수정하는 옵션도 있습니다. 예를 들어 위의 프롬프트로 hello world 프로그램을 만들면 다음과 같은 출력이 생성됩니다.

프롬프트 외에도 슬래시 명령어를 사용할 수 있습니다. '/'를 입력하면 CLI에 자동 완성 옵션이 자동으로 표시됩니다. 전체 명령어를 계속 입력하거나 옵션 중 하나를 선택할 수 있습니다. 위에 언급된 /auth 및 /theme 명령어가 이러한 명령어의 몇 가지 예입니다.

인터페이스에 익숙해지면 이 섹션의 주요 작업인 CLI에 MCP 서버를 작성해 달라고 요청할 수 있습니다.

Hello World MCP 서버 만들기

모델이 더 일관성 있게 빌드하도록 보장하는 가장 좋은 방법 중 하나는 복잡한 작업을 점진적인 단계로 나누는 것입니다. 모델이 복잡한 작업을 스스로 파악할 수 있더라도 올바른 설정이 없으면 올바른 구현을 발견하는 데 오랜 시간이 걸립니다.

더 일관된 접근 방식을 위해 원하는 기능 (Go 문서 읽기)을 구현하기 전에 먼저 'Hello World' MCP 서버를 빌드하도록 지시합니다.

프롬프트의 예는 다음과 같습니다.

Create a Model Context Protocol (MCP) server that exposes a "hello_world" tool. This tool, when called, should return the message "Hello, MCP world!"

For the MCP implementation, you should use the official Go SDK for MCP (github.com/modelcontextprotocol/go-sdk/mcp) and use the stdio transport.

TODO:
- Download the dependency: `go get github.com/modelcontextprotocol/go-sdk/mcp`
- Inspect the documentation of the SDK: `go doc github.com/modelcontextprotocol/go-sdk/mcp`
- Build a `server` command that supports stdio transport only
- Build a `client` command that connects to the server over command transport to test the server

Acceptance Criteria:
- `./bin/client --list-tools` returns the list of server tools including "hello_world"
- `./bin/client --call-tool` "hello_world" returns the output "Hello, MCP world!"

위 프롬프트는 세 가지 주요 세그먼트로 구성됩니다.

빌드하려는 항목과 제약 조건 (예: 아무 SDK 대신 공식 SDK 사용, http 대신 stdio 전송)을 포함한 문제 사양
실행할 작업 (할 일)의 분류
작업의 수락 기준입니다. 에이전트가 완료 시점을 알 수 있도록 테스트 절차로 작동합니다.

이 세 가지 구성요소를 갖추면 모델이 원하는 결과를 보다 일관된 방식으로 달성하는 데 도움이 됩니다.

`read_docs` 도구 구현

작동하는 구현이 있으면 실제 'read_docs' 도구를 구현할 수 있습니다.

Add a new tool to our MCP server called "read_docs" that invokes the "go doc" shell command. The tool will take a mandatory "package" argument and an optional "symbol" argument.

TODO:
- create a package `./internal/tools/docs`
- register the tool with the MCP server
- update the client to support the "read_docs" tool by providing arguments to the tool call

Acceptance Criteria:
- `./bin/client --tools-list` show both hello_world and read_docs
- `./bin/client --tool-call read_docs fmt` returns the documentation for the `fmt` package
- `./bin/client --tool-call read_docs fmt.Println` returns the documentation for the `fmt.Println` function
- `./bin/client --tool-call read_docs github.com/modelcontextprotocol/go-sdk/mcp` returns documentation for the `mcp` package

참고: 이 프롬프트를 사용해 보거나 직접 프롬프트를 작성해 보세요.

유용한 도움말

MCP는 아직 새로운 개념이고 MCP용 Go SDK는 새로운 라이브러리이므로 이 단계에서 Gemini가 적절한 구현을 스스로 발견하는 데 오랜 시간이 걸릴 수 있습니다. 모델이 올바른 솔루션을 도출하도록 돕기 위해 다음을 시도해 보세요.

모델이 어느 단계에서든 문서를 읽지 않았다면 ESC 키를 눌러 문서를 읽도록 상기시켜 주세요. Go에 익숙하지 않다면 'go doc'과 패키지 이름 'go doc github.com/modelcontextprotocol/go-sdk/mcp'을 실행하면 올바른 문서가 반환됩니다.
최상위 모듈 'github.com/modelcontextprotocol/go-sdk'에는 문서가 없습니다 (Go 코드가 없기 때문). 모델에 전체 경로를 찾도록 지시해야 합니다.
반대로 모델이 존재하지 않는 패키지를 할루시네이션하는 경우(예: 'go doc github.com/modelcontextprotocol/go-sdk/mcp/server'를 입력하면 최상위 패키지로 안내됩니다.

6. godoctor를 Gemini CLI의 MCP 서버로 구성

AI 어시스턴트가 클라이언트와 서버 모두에 대한 코드를 생성한 후 몇 가지 수동 테스트를 실행하도록 지시할 수 있습니다. 예를 들면 다음과 같습니다.

retrieve the documentation for the package net/http

또한 외부 종속 항목 (표준 라이브러리에 없음)으로도 테스트해야 합니다.

retrieve the documentation for the github.com/modelcontextprotocol/go-sdk/mcp package

결과가 만족스러우면 이 프로젝트를 사용하고 개발하는 방법에 관한 안내가 포함된 README.md를 작성하라고 지시합니다.

Now write a detailed README.md file explaining both from a user and a developer perspective how to use and to build this project.

이제 다음 개발 단계에서 Gemini CLI가 사용할 수 있도록 서버를 구성합니다.

CLI에 GEMINI.md를 업데이트하여 read_docs을 문서를 읽는 기본 방법으로 사용하도록 요청합니다.

update the GEMINI.md file to include instructions to always use the read_docs tool to retrieve documentation about Go packages or symbols. This should be done whenever seeing an import for the first time in a session or after a new dependency is installed to the project (e.g. via `go get`)

이제 MCP 서버를 구성하려면 Gemini CLI를 다시 시작해야 합니다. 먼저 채팅 세션을 저장하여 다시 시작한 후 중단한 지점부터 재개할 수 있도록 하겠습니다.

/chat save godoctor-workshop

Ctrl+D를 두 번 누르거나 /quit 명령어를 입력하여 CLI를 종료합니다.
이전 단계에서 에이전트가 서버 바이너리를 컴파일했지만 소스 코드를 수정할 때 영향을 받지 않도록 다른 이름으로 서버를 다시 컴파일합니다.

mkdir -p bin && go build -o ./bin/godoctor ./cmd/server

로컬 도구에 맞게 Gemini CLI 구성: 프로젝트 루트에 .gemini/settings.json 파일을 만들고 mcpServers 섹션을 추가하여 컴파일된 서버를 실행하는 방법을 Gemini CLI에 알려줍니다.

mkdir -p .gemini && touch .gemini/settings.json

이제 Cloud Shell 편집기 또는 즐겨찾는 IDE를 사용하여 새 파일에 다음 콘텐츠를 추가합니다.

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor"
    }
  }
}

gemini 명령어로 Gemini CLI 실행
/mcp 명령어를 입력하면 도구가 로드된 것을 확인할 수 있습니다. /mcp desc를 사용하여 도구의 전체 설명을 표시할 수도 있습니다.

'net/http 패키지의 문서를 보여 줘'와 같은 프롬프트로 Gemini CLI에 도구를 사용해 달라고 요청하여 통합을 테스트합니다.

다음과 같은 결과를 확인할 수 있습니다.

도구가 올바르게 작동하면 도구 호출을 통해 검색된 문서가 표시됩니다.

축하합니다. MCP 도구를 만들었습니다. 하지만 아직 끝이 아닙니다. 이 서버를 좀 더 유용하게 만들 수 있습니다.

7. AI 기반 코드 검토자 추가

Gemini API를 사용하는 코드 검토기와 같은 더 정교한 AI 기반 기능을 추가해 보겠습니다.

이제 /chat resume godoctor-workshop. 명령어를 사용하여 이전 채팅 세션을 복원할 수 있습니다. 이렇게 하면 read_docs 개발을 완료한 시점까지의 세션 컨텍스트가 로드되므로 모델에 새 도구를 빌드하는 데 필요한 지식이 제공됩니다.

이 도구는 Vertex AI에 액세스해야 하므로 먼저 API를 사용 설정해야 합니다. 빈 프롬프트에 느낌표 (!)를 입력하면 Gemini CLI를 종료하지 않고도 셸 명령어를 실행할 수 있습니다. 그러면 Gemini CLI가 셸 모드로 변경됩니다.

셸 모드에서 다음 명령어를 실행하여 Vertex AI API를 사용 설정합니다.

gcloud services enable aiplatform.googleapis.com

명령어가 완료되면 Esc 키를 입력하여 프롬프트 모드로 다시 전환할 수 있습니다.

목표: 기존 프로젝트에 code_review라는 새 도구를 추가합니다. 이 도구는 Gemini API를 사용하여 Go 코드를 분석하고 의견을 제공합니다.

프롬프트 예시:

Add a new tool to my project called code_review. This tool should use the Gemini API on Vertex AI (with model id gemini-2.5-pro) to analyze Go code and provide a list of improvements according to the best practices accepted by the Go community.

The tool should take the Go code content and an optional hint as input. The hint will be used to provide additional guidance for the AI reviewer, like "focus on security" or "help me simplify this code".

The tool output should be text in Markdown format.

TODO:
- add the genai SDK dependency with `go get import google.golang.org/genai`
- create the tool code in ./internal/tools/code/review.go
- create a code review prompt to be used by the tool
- use go-genai with Vertex AI authentication to call gemini-2.5-pro
- register the tool with the server
- add a flag to the server to set the Google Cloud Project ID: --project
- add a flag to the server to set the Google Cloud Location: --location
- add support to the review tool in the client CLI

NOT TO DO:
- DO NOT use the package github.com/google/generative-ai-go/genai as it is DEPRECATED
- DO NOT use the package cloud.google.com/go/vertexai/genai as it has been superseded by google.golang.org/genai

Acceptance Criteria:
- `./bin/client --tools-list` show all tools including `code_review`
- `./bin/client --tool-call code_review internal/tools/code/review.go` returns the code review for the "review.go" file

유용한 도움말

모델이 작업을 시작하면 genai 패키지의 문서를 탐색하기 위해 read_docs 도구를 호출하도록 요청하는 메시지가 자동으로 표시될 수 있습니다. 그렇지 않은 경우 언제든지 Esc 키로 프로세스를 중단하고 이제 read_docs 도구를 사용할 수 있다고 알려주세요.
프롬프트에 명확한 '허용되지 않음' 목록이 있음에도 불구하고 잘못된 생성형 AI SDK를 사용하려고 하는 경우 올바른 SDK로 다시 안내합니다.

코드 검토 도구 테스트

/chat save godoctor-workshop로 채팅 세션을 저장한 다음 Ctrl+D를 두 번 눌러 CLI를 종료합니다.
새 도구 정의로 서버를 다시 컴파일합니다.

go build -o ./bin/godoctor ./cmd/server

IDE를 사용하여 Vertex AI의 환경 구성을 포함하도록 .gemini/settings.json 파일을 업데이트합니다.

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor",
      "env": {
        "GOOGLE_CLOUD_USE_VERTEXAI": "true",
        "GOOGLE_CLOUD_PROJECT": "<your-project-id>",
        "GOOGLE_CLOUD_LOCATION": "<your-preferred-region>"
      }
    }
  }
}

Gemini CLI를 다시 실행합니다. /chat resume godoctor-workshop와의 채팅 세션 복원
/mcp 명령어를 입력하여 도구가 사용 설정되었는지 확인합니다. 다음과 같은 결과를 확인할 수 있습니다.

이제 도구의 소스 파일 중 하나를 검토하여 code_review 도구를 테스트해 보겠습니다.

Use the code_review tool to review cmd/server/main.go

    You should see something like this:

코드 검토 도구가 작동하므로 이제 모델이 찾은 개선사항을 적용하도록 제안하여 완전한 '자체 개선' 워크플로를 만들 수 있습니다.

이제 code-review 도구가 작동하는지 확인했습니다. 다음 섹션에서는 클라우드에 배포하는 작업을 진행합니다. /chat save godoctor-workshop로 현재 세션을 저장하고 CLI를 종료합니다.

8. 클라우드용 서버 준비

지금까지 개발한 MCP 서버는 로컬 머신에서만 실행되므로, 자체적으로 사용할 도구를 개발하는 경우에는 문제가 없습니다. 하지만 기업 환경에서는 수백 또는 수천 명의 개발자가 더 광범위하게 사용할 수 있는 도구를 배포해야 하는 경우가 많습니다.

MCP 서버를 확장하려면 표준 I/O만 사용하는 서버에서 HTTP를 사용할 수 있는 서버로 변환하고 여러 개발자가 액세스할 수 있는 곳에 배포해야 합니다. 이 목표를 위해 MCP 사양에 스트리밍 가능한 HTTP로 정의된 전송 모드를 사용하고 Cloud Run을 배포 대상으로 사용합니다.

목표: 스트리밍 가능한 HTTP 전송을 사용하도록 godoctor 서버를 리팩터링합니다.

프롬프트 예시:

The godoctor server is currently using the stdio transport. I want to prepare it to be deployed to Cloud Run, so we need to add support to use the Streamable HTTP transport.

TODO:
- Update server to enable Streamable HTTP via the -http flag.
- An optional -listen flag can be specified to set the port to listen
- If no -http flag is specified, the server defaults to stdio transport and -listen is ignored
- Update client to use Streamable HTTP via the -addr flag
- If no flag is specified, the client defaults to command transport
- Create a shell script test_server.sh to support testing

NOT TO DO:
- DO NOT use the HTTP+SSE protocol as it has been deprecated by the MCP specification

Acceptance Criteria
- Create a shell script that:
  - Runs the server in the background;
  - Runs the client connecting over HTTP and call list tools
  - Kills the background process
- The shell script should run without failures

유용한 도움말

모델이 지원 중단된 HTTP+SSE를 대신 사용하려고 시도할 수 있습니다. 이 경로를 사용하려고 하는 것을 확인했다면 스트리밍 가능한 HTTP로 다시 유도하세요.
현재 버전의 Gemini CLI (0.26.0)는 백그라운드에서 프로세스를 실행하는 것을 지원하지 않으므로 (run_shell_command로 실행된 프로세스는 도구 호출이 반환되면 종료됨) 스크립트를 사용하여 테스트 프로세스를 자동화하도록 Gemini에 요청합니다. 이 기능은 계획되어 있으며 조만간 추가될 예정이므로 테스트 프로세스를 간소화할 수 있습니다.

선택사항: HTTP를 사용하여 MCP 서버 테스트

HTTP를 통해 서버를 사용하도록 Gemini CLI를 구성하려면 다음 단계를 따르세요.

세션을 저장하고 CLI를 종료합니다.
.gemini/settings.json 파일을 수정하고 로컬에서 실행 중인 서버를 가리키도록 구성을 변경합니다.

"mcpServers": {
  "godoctor": {
    "httpUrl": "http://localhost:8080"
  }
}

두 번째 터미널에서 HTTP 지원 서버를 로컬로 실행합니다.

go build -o ./bin/godoctor ./cmd/server && ./bin/godoctor -listen=:8080

Gemini CLI를 다시 시작하고 연결을 테스트하라는 프롬프트를 입력합니다(예: 'godoctor 도구를 사용하여 fmt.Println의 문서를 가져와'
테스트가 끝나면 Ctrl+C를 눌러 서버를 중지합니다.

9. Docker로 애플리케이션 컨테이너화

이제 서버가 올바른 전송 프로토콜을 사용하므로 배포를 위해 컨테이너화할 수 있습니다.

목표: godoctor 서버를 휴대 가능한 프로덕션 레디 컨테이너 이미지로 패키징하는 Dockerfile 만들기

프롬프트 예시:

Please create a multi-stage Dockerfile that compiles the Go binary and copies it into a minimal golang image like golang:1.25.6-alpine. The image should support the following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI
- GOOGLE_CLOUD_PROJECT
- GOOGLE_CLOUD_LOCATION

Acceptance Criteria:
- The image builds successfully
- Create a script test_docker.sh to launch the docker image in background and test the connectivity with the client:
    - Call list_tools on the client pointing to the server running on Docker
    - Call read_docs for fmt.Println
    - Stop the server
- The script should run without failures

선택사항: Docker 이미지 수동 테스트

Dockerfile이 생성되면 이미지를 빌드하고 실행하여 제대로 작동하는지 확인합니다.

컨테이너를 빌드합니다.

docker build -t godoctor:latest .

로컬에서 컨테이너를 실행합니다.

docker run -p 8080:8080 -e PORT=8080 godoctor:latest

실행 중인 컨테이너 테스트: 다른 터미널에서 Gemini CLI를 시작하고 문서를 가져오도록 요청합니다.
테스트가 끝나면 Ctrl+C를 눌러 서버를 중지합니다.

10. Cloud Run에 배포

이제 컨테이너를 클라우드에 배포해 보겠습니다.

목표: 컨테이너화된 godoctor 서버를 Google Cloud Run에 배포합니다.

프롬프트 예시:

Now please deploy this image to Cloud Run and return me an URL I can use to call the MCP tool. Configure Cloud Run to use the following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI: true,
- GOOGLE_CLOUD_PROJECT: <your-project-id>
- GOOGLE_CLOUD_LOCATION: <your-preferred-region>

TODO:
- Run `docker build -t gcr.io/daniela-genai-sandbox/godoctor .`
- Run `gcloud run deploy godoctor --image` with the image created above

Acceptance Criteria:
- Call list-tools with the client pointing to the CloudRun endpoint

배포가 완료되면 방금 배포한 도구를 사용하도록 Gemini CLI를 구성합니다.

.gemini/settings.json 파일을 업데이트하여 배포된 서비스를 가리키도록 MCP 도구 구성을 변경하거나 Gemini CLI에 이를 요청합니다.

now update the .gemini/settings.json file to use this URL for the godoctor server

최종 mcpServers 섹션은 다음과 같이 표시됩니다 (자리표시자를 실제 Cloud Run 앱 URL로 바꿔야 함).

"mcpServers": {
  "godoctor": {
    "httpUrl": "https://<your-cloud-run-id>.us-central1.run.app"
  }
}

Cloud Run 배포 테스트

이제 최종 엔드 투 엔드 테스트를 진행할 수 있습니다.

마지막으로 Gemini CLI를 다시 시작합니다 (컨텍스트를 보존하려면 /chat save 및 /chat resume 사용). 이제 CLI가 원격 MCP 서버를 호출할 수 있습니다. 패키지에 대한 문서를 요청해 보세요.

코드 검토 도구를 테스트할 수도 있습니다.

Use the godoctor tool to review the cmd/godoctor/main.go file

삭제

테스트가 완료되면 환경을 정리해야 합니다. Gemini에게 프로젝트를 삭제하거나 CloudRun 배포만 삭제하도록 요청할 수 있습니다. 프롬프트 예:

I'm done with my tests on the CloudRun server, please delete this deployment for me and revert my .gemini/settings.json to use the local version.

11. 축하합니다.

AI 어시스턴트에게 지시하여 정교한 AI 기반 도구를 빌드, 컨테이너화, 배포했습니다. 무엇보다도 요구사항을 효과적인 프롬프트로 변환하는 최신 소프트웨어 개발의 필수 기술을 연습했습니다. 커스텀 MCP 도구로 Gemini CLI를 확장하여 더욱 강력하고 전문화된 Go 개발 어시스턴트로 만들었습니다.

Gemini CLI 및 Go로 MCP 서버를 빌드하는 방법

1. 소개

학습할 내용

필요한 항목

주요 기술

성공적인 Codelab을 위한 도움말

2. 환경 설정

자습형 환경 설정

Cloud Shell 시작

3. Gemini CLI 시작하기

Gemini CLI란 무엇인가요?

설치

구성

4. 컨텍스트 파일 (GEMINI.md)

5. 초기 빌드: 문서 서버

Hello World MCP 서버 만들기

read_docs 도구 구현

유용한 도움말

6. godoctor를 Gemini CLI의 MCP 서버로 구성

7. AI 기반 코드 검토자 추가

유용한 도움말

코드 검토 도구 테스트

8. 클라우드용 서버 준비

유용한 도움말

선택사항: HTTP를 사용하여 MCP 서버 테스트

9. Docker로 애플리케이션 컨테이너화

선택사항: Docker 이미지 수동 테스트

10. Cloud Run에 배포

Cloud Run 배포 테스트

삭제

11. 축하합니다.

참조 문서

`read_docs` 도구 구현