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

1. 소개

이 Codelab에서는 모델 컨텍스트 프로토콜 (MCP) 서버를 빌드하고 배포하여 Gemini CLI의 기능을 확장하는 방법을 알아봅니다. Go 개발을 위한 맞춤 도구를 제공하는 Go 기반 서버인 godoctor를 빌드하여 Gemini CLI를 범용 코딩 어시스턴트에서 전문 Go 개발 전문가로 변환합니다.

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

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

학습할 내용

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

필요한 항목

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

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

• Node.js 20 이상
• 결제가 사용 설정된 Google Cloud 프로젝트
• Google Cloud SDK (gcloud CLI)가 설치되고 초기화됨
• 시스템에 Go 1.24 이상이 설치되어 있어야 합니다.
• 시스템에 설치된 Docker

주요 기술

여기에서 활용할 기술에 대해 자세히 알아보세요.

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

성공적인 Codelab을 위한 도움말

AI 어시스턴트를 활용한 작업은 새로운 소프트웨어 개발 방식입니다. 원활하고 성공적인 환경을 위한 몇 가지 팁을 소개합니다.

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

2. 환경 설정

자습형 환경 설정

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

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

주의: 프로젝트 ID는 전역적으로 고유하며 선택한 후에는 다른 사람이 사용할 수 없습니다. 해당 ID의 유일한 사용자입니다. 프로젝트가 삭제되더라도 ID는 다시 사용할 수 없습니다.

참고: Gmail 계정을 사용하는 경우 기본 위치를 조직 없음으로 설정된 그대로 둘 수 있습니다. Google Workspace 계정을 사용하는 경우 조직에 적합한 위치를 선택하세요.

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

Cloud Shell 시작

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

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

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

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

3. Gemini CLI 시작하기

이 섹션에서는 환경에 Gemini CLI를 설치하고 구성하는 방법을 비롯해 Gemini CLI에 대해 알아봅니다.

Gemini CLI란 무엇인가요?

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

설치

참고: Google Cloud Shell을 사용하는 경우 Gemini CLI가 이미 설치되어 있으므로 다음 섹션 (구성)으로 건너뛸 수 있습니다.

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 파일은 나중에 구성됩니다.

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

mkdir godoctor
cd godoctor
go mod init godoctor

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

Cloud Shell을 사용하는 경우 이 단계는 이미 완료된 것입니다. 다음 섹션 (개발 가이드라인)으로 건너뛰어도 됩니다.

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

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

gcloud auth application-default login

4. 개발 가이드라인

AI 어시스턴트가 고품질의 관용적인 Go 코드를 생성하도록 하려면 명확한 가이드라인을 제공해야 합니다. 이 작업은 GEMINI.md 파일에서 실행됩니다.

참고: GEMINI.md는 프로젝트 구조, 작업 방식, 테스트 등 CLI에 관한 정보를 제공하는 등 다양한 용도로 사용할 수 있습니다.

목표: 이 프로젝트 중에 AI 어시스턴트의 규칙 집합으로 사용될 GEMINI.md 파일을 만듭니다.

작업: 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*.

# Agent Guidelines
- **Reading URLs:** ALWAYS read URLs provided by the user. They are not optional.

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

5. 초기 빌드: godoc 서버

첫 번째 목표는 godoctor 서버의 초기 버전을 만드는 것입니다. 이 버전은 Go 문서를 조회하는 기능을 제공하는 godoc라는 단일 도구를 제공하는 최소한의 프로덕션 지원 애플리케이션이어야 합니다.

목표: LLM이 Go 문서를 쿼리할 수 있도록 go doc 명령어를 노출하는 프로덕션 지원 MCP 서버 만들기

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

gemini

참고: Cloud Shell에 Gemini CLI를 설치하거나 업데이트해야 하는 경우 sudo env PATH=$PATH npm install -g @google/gemini-cli 명령어를 사용하면 됩니다.

CLI를 처음 실행하면 인증 모드와 테마를 선택하라는 메시지가 표시됩니다. 인증 모드에서 개인 Google 계정으로 로그인하여 Gemini CLI의 넉넉한 무료 등급을 이용할 수 있도록 'Google로 로그인'을 선택합니다. 다음과 유사한 인증 모드를 선택하는 옵션이 표시됩니다.

선택사항을 변경해야 하는 경우 /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 서버를 빌드하도록 안내합니다.

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

Your task is to create a Model Context Protocol (MCP) server to expose a "hello world" tool. For the MCP implementation, you should use the official Go SDK for MCP and use the stdio transport.

Read these references to gather information about the technology and project structure before writing any code:
- https://github.com/modelcontextprotocol/go-sdk/blob/main/README.md
- https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle
- https://go.dev/doc/modules/layout

To test the server, use shell commands like these:
(
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}';
  echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}';
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}';
) | ./bin/godoctor

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

1. 빌드하려는 항목과 제약 조건 (예: SDK 대신 공식 SDK 사용)을 포함한 문제 사양
2. 모델이 요청을 명확하게 구분하는 데 도움이 되는 참고 문서
3. 작업의 승인 기준으로 작동하는 테스트 절차

이 세 가지 구성요소를 사용하면 모델이 원하는 결과를 더 일관되게 달성할 수 있습니다.

주의: Google에서는 매우 정확한 안내를 제공하지만 모델이 안내된 내용을 벗어나는 경우가 있으므로 모델의 작업을 확인하고 잠재적인 오류 루프와 환각에 주의하는 것이 중요합니다. 모델이 멈추면 이 챕터의 유용한 리소스 섹션을 확인하세요.

Go 문서 도구 구현

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

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

Read the reference for the go doc command to understand its API: https://pkg.go.dev/golang.org/x/tools/cmd/godoc

Test it by executing the call with:
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name": "godoc", "arguments": {"package": "fmt"} } }'
 | ./bin/godoctor

Test it using both a standard library package and an external package like "github.com/modelcontextprotocol/go-sdk/mcp", both with and without symbols.

이 프롬프트를 사용해 보거나 직접 프롬프트를 만들어 보세요.

참고: 표준 라이브러리를 사용하여 문서를 가져오는 코드는 사소하지 않으며 모델이 스스로 파악하는 데 시간이 걸릴 수 있으므로 위의 프롬프트는 모델이 go doc 셸 명령어를 사용하도록 명시적으로 권장합니다. 컴파일러 내장 go doc 도구를 사용하면 시간을 많이 절약할 수 있고 MCP 구현이라는 중요한 부분에 집중할 수 있습니다.

유용한 명령줄 인터페이스

좋은 구현이 정해지면 모델에 MCP 클라이언트를 사용하여 godoctor CLI를 만들라고 지시할 수 있습니다. 이렇게 하면 JSON-RPC 호출을 수동으로 빌드할 필요가 없어 기능 테스트를 간소화할 수 있습니다.

프롬프트 예:

Now create a godoctor-cli component that will call the MCP server using command transport. This CLI will expose all tools using subcommands and allow us to test the MCP server implementation without needing to build the JSON-RPC calls manually.

Use the reference implementation at https://github.com/modelcontextprotocol/go-sdk/blob/main/README.md to build the client.

Test it by calling from the command line:
- the hello_world tool 
- the godoc tool with a local package
- the godoc tool with a local package and symbol
- the godoc tool with an external package
- the godoc tool with an external package and symbol

이제 작동하는 클라이언트 및 서버가 있으므로 다음 섹션에서는 방금 만든 MCP 서버로 Gemini CLI를 구성하여 다음 코딩 작업에서 이점을 활용합니다.

유용한 리소스

참고: LLM을 사용한 코딩은 비결정적 환경이므로 동일한 환경에서 동일한 프롬프트를 두 번 실행하더라도 항상 정확히 동일한 결과가 보장되지는 않습니다. 따라서 LLM이 루프에 갇혀 있거나 컨텍스트가 저하된 시점을 파악하는 것이 중요한 기술입니다. 사용자는 언제든지 ESC 키를 눌러 중단할 수 있습니다.

MCP는 아직 새로운 개념이고 MCP용 Go SDK는 새로운 라이브러리이므로 이 단계에서 Gemini가 올바른 구현을 스스로 발견하는 데 시간이 오래 걸릴 수 있습니다. 모델이 올바른 해결책을 제시하도록 하려면 다음 참조를 제공하는 것이 좋습니다.

1. 모델이 SDK API를 더 일관되게 검색하도록 하려면 'go doc shell 명령어를 사용하여 go-sdk 라이브러리의 API를 검색해'라는 프롬프트를 제공하면 됩니다.
2. 모델이 read_file 도구를 사용하여 SDK의 소스 코드를 검사하려고 하면 Gemini CLI가 현재 범위 외부의 파일을 읽을 수 없으므로 실패합니다. run_shell_command 도구를 통해 cat 및 ls 명령어를 대신 사용하도록 지시할 수 있습니다.
3. 모델이 애플리케이션을 디버깅하는 데 문제가 있는 경우 더 자세한 로깅을 추가하고 오류 메시지의 컨텍스트 정보를 개선하도록 안내합니다.
4. 다른 모든 방법이 실패하면 참조 구현을 제공하세요. https://github.com/danicat/godoctor

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가 사용할 수 있도록 서버를 구성합니다.

1. 문서를 읽는 기본 방법으로 godoc를 사용하도록 GEMINI.md를 업데이트해 달라고 CLI에 요청합니다.

update the GEMINI.md file to use the godoc tool to retrieve documentation about Go packages or symbols. Always prefer to use godoc over WebFetch and GoogleSearch, and only use those when godoc doesn't give a clear answer.

2. 이제 Gemini CLI를 다시 시작하여 구성해야 합니다. 먼저 채팅 세션을 저장하여 다시 시작한 후 중단한 부분부터 이어서 진행할 수 있도록 하겠습니다.

/chat save workshop001

3. Ctrl+D를 두 번 누르거나 /quit 명령어를 입력하여 CLI를 종료합니다.
4. 서버 바이너리 컴파일: bin 디렉터리를 만들고 godoctor 서버를 컴파일합니다.

mkdir -p bin
go build -o ./bin/godoctor ./cmd/godoctor # adjust paths as needed

참고: 다음 단계에서 이 바이너리가 안정적이고 CLI에서 사용할 수 있도록 개발 중에 서버를 빌드하는 데 사용한 폴더와 다른 폴더를 사용하는 것이 좋습니다.

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

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

6. 이제 vim 또는 nano와 같은 명령줄 편집기를 사용하여 새 파일에 다음 콘텐츠를 추가합니다.

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

7. 이제 Gemini CLI를 실행하고 채팅 세션을 복원합니다.

/chat resume workshop001

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

9. 'net/http의 문서를 가져와'와 같은 프롬프트로 Gemini CLI에 도구를 사용하도록 요청하여 통합을 테스트합니다.

다음과 같이 표시됩니다.

참고: 모델이 셸 명령어를 통해 도구를 호출하려고 할 수 있습니다. 이 문제가 발생하면 이전 세션의 컨텍스트 없이 세션을 시작해 보세요 (예: /chat resume를 호출하지 않음).

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

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

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

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

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

프롬프트 예시:

I want to add a new tool to my project called code_review. This tool should use the Gemini API on Vertex AI (with gemini-2.5-flash) to analyze Go code and provide a list of improvements in json format 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". Please update the server to include this new tool and modify the CLI client to add a review command to use it.

Use this SDK to call Gemini: https://github.com/googleapis/go-genai

유용한 도움말

모델이 작업을 시작하면 genai 패키지의 문서를 탐색하기 위해 godoc 도구를 호출하도록 요청하는 메시지가 자동으로 표시될 수 있습니다. 그렇지 않은 경우 언제든지 Esc 키로 프로세스를 중단하고 이제 godoc 도구를 사용할 수 있다고 알려주면 됩니다.

코드 검토 도구 테스트

1. /chat save workshop002로 채팅 세션을 저장한 다음 Ctrl+D를 두 번 눌러 CLI를 종료합니다.
2. code_review 도구는 Vertex AI에 액세스해야 하므로 먼저 API를 사용 설정해야 합니다.

gcloud services enable aiplatform.googleapis.com

3. 다음 콘텐츠로 .env 파일을 만듭니다. GOOGLE_CLOUD_PROJECT 변수를 이 실습 시작 시 만든 프로젝트의 실제 프로젝트 ID로 바꾸고 GOOGLE_CLOUD_LOCATION을 원하는 위치 (예: 'us-central1')로 바꾸세요.

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='your-location'

4. source 명령어를 사용하여 .env 파일을 로드합니다.

source .env

5. 새 도구 정의로 서버를 다시 컴파일합니다.

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

6. Gemini CLI를 다시 실행합니다. /chat resume workshop002로 채팅 세션을 복원합니다.
7. /mcp 명령어를 입력하여 도구가 사용 설정되었는지 확인합니다. 다음과 같이 표시됩니다.

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

'godoctor 도구를 사용하여 cmd/godoctor/main.go 파일을 검토하세요.'

    You should see something like this:

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

이제 code-review 도구가 작동하는지 확인했습니다. 다음 섹션에서는 클라우드에 배포하는 작업을 진행합니다. /chat save workshop003로 현재 세션을 저장하고 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 deploy it to Cloud Run, so I need to refactor it to use the streamable HTTP transport instead. Please modify the server to comply with the streamable HTTP specification.

유용한 리소스

1. 모델이 스트림 가능한 HTTP 전송을 구현하는 데 어려움을 겪는 경우 https://github.com/modelcontextprotocol/go-sdk/blob/main/design/design.md를 참고하도록 안내할 수 있습니다.
2. 모델이 지원 중단된 HTTP+SSE를 대신 사용하려고 할 수 있습니다. 이 경로를 통과하는 것을 확인하면 스트리밍 가능한 HTTP로 다시 안내하세요.

HTTP를 사용하여 서버 테스트

모델에 스트림 가능한 HTTP도 사용하도록 godoctor 클라이언트를 업데이트하여 여전히 작동하는지 테스트해 달라고 요청합니다.

Now update the client to use streamable HTTP and run a test by retrieving documentation from one package

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

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

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

3. 리팩터링된 서버를 로컬에서 실행합니다.

go run ./cmd/godoctor/main.go

4. 위 작업이 차단되므로 새 터미널에서 Gemini CLI를 시작하고 연결을 테스트하는 프롬프트를 제공합니다 (예: 'godoctor 도구를 사용하여 fmt.Println의 문서를 가져와'
5. 테스트가 끝나면 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.24-alpine.

Docker 이미지 테스트

Dockerfile가 생성된 후 이미지를 빌드하고 실행하여 제대로 작동하는지 확인합니다. Gemini에게 다음 작업을 요청할 수 있습니다.

build the image and test the connectivity to the server using the godoctor client

선택사항: 테스트를 수동으로 진행하려면 다음 단계를 따르세요.

1. 컨테이너를 빌드합니다.

docker build -t godoctor:latest .

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

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

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

10. Cloud Run에 배포

이제 컨테이너를 클라우드에 배포할 차례입니다.

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

프롬프트 안내: AI 어시스턴트에게 컨테이너를 배포하는 gcloud 명령어를 제공해 달라고 요청합니다.

프롬프트 예시:

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 environment variables in the .env file.

주의: 이 프로젝트에서 Cloud Run을 처음 사용하는 경우 Artifact Registry 및 Cloud Run API를 사용 설정하라는 메시지가 표시됩니다.

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

배포된 서비스를 가리키도록 MCP 도구 구성을 변경하려면 .gemini/settings.json 파일을 업데이트하거나 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 배포 테스트

이제 최종 엔드 투 엔드 테스트를 실행할 준비가 되었습니다.

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

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

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

삭제

주의: 특히 인증되지 않은 Cloud Run 인스턴스를 사용하는 경우 GCP 결제 계정에 예기치 않은 요금이 청구되지 않도록 이 세션을 종료하기 전에 Cloud Run 배포를 삭제해야 합니다.

테스트가 완료되면 환경을 정리해야 합니다. 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 발표 블로그
• Gemini CLI 홈페이지
• Gemini CLI 문서
• 모델 컨텍스트 프로토콜 사양
• MCP용 Go SDK
• Google Gen AI Go SDK