Cách tạo máy chủ MCP bằng Gemini CLI và Go

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ tìm hiểu cách tạo và triển khai một máy chủ Giao thức ngữ cảnh mô hình (MCP) để mở rộng các chức năng của Gemini CLI. Bạn sẽ tạo godoctor, một máy chủ dựa trên Go cung cấp các công cụ tuỳ chỉnh để phát triển Go, chuyển đổi Gemini CLI từ một trợ lý lập trình đa năng thành một chuyên gia phát triển Go chuyên biệt.

Lớp học lập trình này sử dụng phương pháp "dựa trên câu lệnh". Bạn sẽ đóng vai trò là trưởng nhóm kỹ thuật, đưa ra câu lệnh cho trợ lý AI (Gemini CLI). Mục tiêu của bạn là tìm hiểu cách chuyển các yêu cầu của dự án thành câu lệnh hiệu quả và để AI xử lý các chi tiết triển khai.

Trọng tâm của dự án này là Giao thức ngữ cảnh mô hình (MCP). MCP là một giao thức nguồn mở giúp chuẩn hoá cách các mô hình ngôn ngữ lớn (LLM) như Gemini giao tiếp với các công cụ và dịch vụ bên ngoài. Công cụ này đóng vai trò là cầu nối, cho phép AI truy cập vào thông tin thực tế và thực hiện các hành động ngoài kiến thức được tích hợp sẵn. Bằng cách tạo một máy chủ MCP, bạn đang tạo một trình bổ trợ tuỳ chỉnh mà Gemini CLI có thể khám phá và sử dụng, nhờ đó dạy cho Gemini CLI các kỹ năng mới một cách hiệu quả.

Kiến thức bạn sẽ học được

Cách cài đặt và định cấu hình Gemini CLI
Cách xây dựng câu lệnh hiệu quả để hướng dẫn trợ lý AI trong quá trình phát triển phần mềm
Cách cung cấp bối cảnh và nguyên tắc cho trợ lý AI
Cách tạo và định cấu hình máy chủ MCP để tăng cường các chức năng của Gemini CLI
Cách tạo vùng chứa và triển khai một ứng dụng Go lên Google Cloud Run

Bạn cần có

Bạn có thể thực hiện toàn bộ hội thảo này trong Google Cloud Shell. Công cụ này đi kèm với tất cả các phần phụ thuộc cần thiết (giao diện dòng lệnh gcloud, Go, Docker, giao diện dòng lệnh Gemini) đã được cài đặt sẵn.

Ngoài ra, nếu muốn làm việc trên máy của riêng mình, bạn sẽ cần những thứ sau:

Node.js 20 trở lên
Google Cloud SDK (gcloud CLI) đã được cài đặt và khởi chạy
Go 1.24 trở lên đã được cài đặt trên hệ thống của bạn
Docker đã được cài đặt trên hệ thống của bạn

Công nghệ chính

Tại đây, bạn có thể tìm thêm thông tin về các công nghệ mà chúng tôi sẽ sử dụng:

Gemini CLI: Giao diện dòng lệnh dựa trên AI mà chúng tôi sẽ mở rộng
Giao thức ngữ cảnh mô hình (MCP): Giao thức nguồn mở cho phép Gemini CLI giao tiếp với công cụ tuỳ chỉnh của chúng tôi
Go SDK cho MCP: Thư viện Go mà chúng ta sẽ dùng để triển khai máy chủ MCP

Mẹo để có một lớp học lập trình thành công

Làm việc với trợ lý AI là một cách mới để phát triển phần mềm. Sau đây là một số mẹo giúp bạn có trải nghiệm suôn sẻ và thành công:

Đừng ngại nhấn phím ESC. Đôi khi, AI sẽ đề xuất những hành động hoặc mã mà bạn không đồng ý. Sử dụng phím ESC để huỷ hành động được đề xuất và đưa ra một câu lệnh mới để hướng dẫn AI đi đúng hướng. Bạn là phi công.
Khuyến khích sử dụng công cụ. Nếu AI có vẻ không biết hoặc đang bịa đặt thông tin, hãy khuyến khích AI sử dụng các công cụ hiện có. Những câu lệnh như "Bạn có thể dùng Google Tìm kiếm để xác minh điều đó không?" hoặc "Hãy dùng công cụ read_file để hiểu mã hiện tại trước khi thực hiện thay đổi" có thể rất hiệu quả.
Chống lại các thay đổi thủ công. Hãy thử để AI thực hiện mọi việc. Đây là kỹ năng cốt lõi mà bạn đang luyện tập. Tuy nhiên, nếu bạn phải thực hiện thay đổi theo cách thủ công, hãy cho AI biết về thay đổi đó sau. Một câu lệnh như "Tôi đã cập nhật tệp README.md theo cách thủ công. Vui lòng đọc lại để củng cố kiến thức" sẽ đảm bảo AI luôn nắm bắt được thông tin mới nhất về dự án của bạn.
Bạn đã thử tắt rồi bật lại chưa? Trong trường hợp hiếm gặp khi AI cố gắng đi theo một đường dẫn nhất định trái với lệnh của bạn, có thể là do ngữ cảnh bị suy giảm (đôi khi còn gọi là "ngữ cảnh bị hỏng"). Trong trường hợp này, bạn có thể dùng lệnh "/compress" của Gemini CLI để giảm nhiễu trong bối cảnh hoặc trong trường hợp nghiêm trọng, bạn có thể dùng lệnh "/clear" để xoá toàn bộ nhật ký phiên.

2. Thiết lập môi trường

Chọn một trong các lựa chọn sau: Thiết lập môi trường tự học nếu bạn muốn chạy

lớp học lập trình trên máy của riêng bạn hoặc; Khởi động Cloud Shell nếu bạn muốn chạy lớp học lập trình này hoàn toàn trên đám mây.

Thiết lập môi trường theo tốc độ của riêng bạn

Đăng nhập vào Google Cloud Console rồi tạo một dự án mới hoặc sử dụng lại một dự án hiện có. Nếu chưa có tài khoản Gmail hoặc Google Workspace, bạn phải tạo một tài khoản.

Tên dự án là tên hiển thị của những người tham gia dự án này. Đây là một chuỗi ký tự mà các API của Google không sử dụng. Bạn luôn có thể cập nhật thông tin này.
Mã dự án là mã duy nhất trên tất cả các dự án trên Google Cloud và không thể thay đổi (bạn không thể thay đổi mã này sau khi đã đặt). Cloud Console sẽ tự động tạo một chuỗi duy nhất; thường thì bạn không cần quan tâm đến chuỗi này. Trong hầu hết các lớp học lập trình, bạn sẽ cần tham chiếu đến Mã dự án (thường được xác định là PROJECT_ID). Nếu không thích mã nhận dạng được tạo, bạn có thể tạo một mã nhận dạng ngẫu nhiên khác. Hoặc bạn có thể thử tên người dùng của riêng mình để xem tên đó có được chấp nhận hay không. Bạn không thể thay đổi chế độ này sau bước này và chế độ này sẽ duy trì trong suốt thời gian diễn ra dự án.
Để bạn nắm được thông tin, có một giá trị thứ ba là Số dự án mà một số API sử dụng. Tìm hiểu thêm về cả 3 giá trị này trong tài liệu.

Tiếp theo, bạn cần bật tính năng thanh toán trong Cloud Console để sử dụng các tài nguyên/API trên Cloud. Việc thực hiện lớp học lập trình này sẽ không tốn nhiều chi phí, nếu có. Để tắt các tài nguyên nhằm tránh bị tính phí ngoài phạm vi hướng dẫn này, bạn có thể xoá các tài nguyên đã tạo hoặc xoá dự án. Người dùng mới của Google Cloud đủ điều kiện tham gia chương trình Dùng thử miễn phí trị giá 300 USD.

Khởi động Cloud Shell

Mặc dù có thể vận hành Google Cloud từ xa trên máy tính xách tay, nhưng trong lớp học lập trình này, bạn sẽ sử dụng Google Cloud Shell, một môi trường dòng lệnh chạy trên Cloud.

Trên Bảng điều khiển Google Cloud, hãy nhấp vào biểu tượng Cloud Shell trên thanh công cụ ở trên cùng bên phải:

Kích hoạt Cloud Shell

Quá trình này chỉ mất vài phút để cung cấp và kết nối với môi trường. Khi quá trình này kết thúc, bạn sẽ thấy như sau:

Ảnh chụp màn hình cửa sổ dòng lệnh Google Cloud Shell cho thấy môi trường đã kết nối

Máy ảo này được trang bị tất cả các công cụ phát triển mà bạn cần. Nền tảng này cung cấp một thư mục chính có dung lượng 5 GB và chạy trên Google Cloud, giúp tăng cường đáng kể hiệu suất mạng và hoạt động xác thực. Bạn có thể thực hiện mọi thao tác trong lớp học lập trình này trong trình duyệt. Bạn không cần cài đặt bất cứ thứ gì.

3. Làm quen với Gemini CLI

Trong phần này, bạn sẽ tìm hiểu về Gemini CLI, bao gồm cả cách cài đặt và định cấu hình Gemini CLI cho môi trường của bạn.

Gemini CLI là gì?

Gemini CLI là một giao diện dòng lệnh dựa trên AI, có thể giúp bạn thực hiện nhiều tác vụ phát triển. Gemini có thể hiểu ngữ cảnh dự án của bạn, trả lời câu hỏi, tạo mã và sử dụng các công cụ bên ngoài để mở rộng khả năng của mình.

Cài đặt

Cài đặt Gemini CLI trên toàn cầu bằng npm.

npm install -g @google/gemini-cli

Bạn có thể xác nhận rằng CLI đã được cài đặt bằng cách chạy:

gemini --version

Cấu hình

Hành vi của Gemini CLI được kiểm soát bằng các tệp cấu hình và biến môi trường. Có hai tệp khoá:

GEMINI.md: Tệp này cung cấp hướng dẫn và bối cảnh cho AI. CLI sẽ đọc tệp này để hiểu các tiêu chuẩn và quy ước mã hoá của dự án.
.gemini/settings.json: Tệp này kiểm soát cấu hình của CLI, bao gồm cả cách kết nối với các công cụ bên ngoài. Chúng ta sẽ sử dụng tệp này sau để định cấu hình CLI nhằm sử dụng máy chủ MCP mà chúng ta đang tạo trong phòng thí nghiệm này.

Trước tiên, chúng ta sẽ thiết lập môi trường rồi tiến hành tạo tệp GEMINI.md. Tệp settings.json sẽ được định cấu hình ở bước sau.

Tạo và khởi chạy một thư mục dự án:

mkdir godoctor && cd godoctor
go mod init godoctor

Xác thực bằng thông tin xác thực mặc định của ứng dụng Google Cloud:

Chúng ta cần đăng nhập vào một tài khoản có quyền truy cập vào dự án GCP mà bạn sẽ sử dụng cho lớp học lập trình này:

Đảm bảo bạn đã cài đặt và khởi chạy Google Cloud SDK.
Chạy lệnh sau để thiết lập Thông tin xác thực mặc định của ứng dụng:

gcloud auth application-default login

4. Tệp ngữ cảnh (GEMINI.md)

Tệp ngữ cảnh (sử dụng tên mặc định GEMINI.md) được dùng để cung cấp ngữ cảnh hướng dẫn cho mô hình Gemini. Bạn có thể dùng những tệp này để đưa ra hướng dẫn cụ thể cho dự án, xác định một nhân vật hoặc cung cấp hướng dẫn về phong cách viết mã để câu trả lời của AI chính xác hơn và phù hợp với nhu cầu của bạn.

Để đảm bảo trợ lý AI tạo ra mã Go chất lượng cao và đúng chuẩn, chúng ta sẽ viết một tệp GEMINI.md với một số phương pháp hay nhất thường dùng cho nhà phát triển Go.

Mục tiêu: Tạo một tệp GEMINI.md đóng vai trò là bộ quy tắc cho trợ lý AI trong dự án này.

Mở IDE để tạo tệp GEMINI.md có nội dung bên dưới. Nếu đang sử dụng Cloud Shell, bạn có thể mở một trình chỉnh sửa bằng lệnh bên dưới:

cloudshell edit .

Việc cần làm: Tạo một tệp có tên GEMINI.md trong thư mục gốc của godoctor rồi dán nội dung sau vào tệp đó.

# 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

Môi trường phát triển của bạn hiện đã được thiết lập đầy đủ.

5. Bản dựng ban đầu: Máy chủ tài liệu

Mục tiêu đầu tiên của bạn là tạo phiên bản ban đầu của máy chủ godoctor. Phiên bản này phải là một ứng dụng tối thiểu cung cấp một công cụ duy nhất có tên là read_docs, cho phép tra cứu tài liệu Go.

Mục tiêu: Tạo một máy chủ MCP sẵn sàng cho hoạt động sản xuất, hiển thị lệnh go doc, cho phép một LLM truy vấn tài liệu Go.

Chạy lệnh Gemini CLI trên giao diện dòng lệnh:

gemini

Khi bạn chạy CLI lần đầu tiên, CLI sẽ yêu cầu bạn chọn một chế độ xác thực và một giao diện.

Nếu bạn đang chạy lớp học lập trình này trong Cloud Shell, hãy chọn mục Sử dụng thông tin đăng nhập của người dùng Cloud Shell. Nếu chưa, bạn có thể dùng tính năng đăng nhập bằng Google để đăng nhập bằng Tài khoản Google cá nhân. Nhờ đó, bạn có thể hưởng lợi từ bậc miễn phí hào phóng của Gemini CLI. Màn hình lựa chọn xác thực sẽ có dạng như sau:

Trong trường hợp cần thay đổi lựa chọn, bạn có thể nhập /auth rồi nhấn phím Enter để mở lại trình đơn này.

Tiếp theo, bạn sẽ được nhắc chọn một giao diện:

Tương tự như /auth, bạn cũng có thể thay đổi giao diện sau này bằng lệnh /theme.

Sau khi chọn phương thức xác thực và giao diện bạn muốn, bạn sẽ được chuyển đến dấu nhắc lệnh. Tại đây, bạn có thể nhập các lệnh, ví dụ:

Write a hello world application in Go

CLI sử dụng kết hợp khả năng suy luận của riêng mình (thông qua một mô hình Gemini như Gemini Flash hoặc Gemini Pro) và các công cụ để thực hiện các tác vụ. Nó sử dụng các công cụ bất cứ khi nào cần tương tác với hệ thống tệp hoặc các dịch vụ bên ngoài, chẳng hạn như API, cơ sở dữ liệu, v.v. Ví dụ về các công cụ có sẵn hoặc "công cụ nội bộ" là read_file, write_file, web_fetch và google_search. Máy chủ MCP mà chúng tôi đang xây dựng cũng sẽ trở thành một công cụ có sẵn cho CLI.

Vào lần đầu tiên chạy một công cụ, công cụ đó sẽ yêu cầu bạn cấp quyền. Bạn có thể cấp quyền một lần (cho phép một lần), phê duyệt chung cho phần còn lại của phiên (luôn cho phép) hoặc từ chối yêu cầu của ứng dụng. Nếu đó là thao tác chỉnh sửa tệp, bạn cũng sẽ thấy lựa chọn chỉnh sửa tệp bằng trình chỉnh sửa bên ngoài, phòng trường hợp bạn muốn điều chỉnh. Ví dụ: đây là kết quả của câu lệnh ở trên, để tạo một chương trình xin chào thế giới:

Ngoài câu lệnh, bạn cũng có thể dùng lệnh gạch chéo. Nếu bạn nhập "/", CLI sẽ tự động cho bạn thấy các lựa chọn tự động hoàn thành. Bạn có thể tiếp tục nhập toàn bộ lệnh hoặc chọn một lệnh trong số các lựa chọn. Lệnh /auth và /theme nêu trên là một vài lệnh như vậy.

Sau khi làm quen với giao diện này, bạn có thể bắt đầu nhiệm vụ chính của phần này, đó là yêu cầu CLI ghi máy chủ MCP cho chúng ta.

Tạo máy chủ MCP Hello World

Một trong những cách tốt nhất để đảm bảo mô hình sẽ tạo ra các nội dung nhất quán hơn là chia nhỏ các nhiệm vụ phức tạp thành các bước gia tăng. Mặc dù mô hình có thể tự mình tìm ra một tác vụ phức tạp, nhưng nếu không được thiết lập đúng cách, mô hình sẽ mất nhiều thời gian để khám phá ra cách triển khai phù hợp.

Để có một phương pháp nhất quán hơn, trước tiên, chúng ta sẽ hướng dẫn nó tạo một máy chủ MCP "Hello World" trước khi triển khai chức năng mà chúng ta muốn (đọc tài liệu về Go).

Sau đây là ví dụ về câu lệnh:

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!"

Xin lưu ý rằng câu lệnh trên bao gồm 3 đoạn chính:

Quy cách vấn đề, bao gồm những gì chúng ta muốn xây dựng và các ràng buộc (ví dụ: sử dụng SDK chính thức thay vì bất kỳ SDK nào, truyền tải stdio thay vì http)
Phân tích các việc cần làm (TODO)
Tiêu chí chấp nhận cho tác vụ, hoạt động như một quy trình kiểm thử để nhân viên biết khi nào tác vụ hoàn tất

Việc có 3 thành phần này sẽ giúp mô hình đạt được kết quả mong muốn một cách nhất quán hơn.

Triển khai công cụ `read_docs`

Sau khi bạn triển khai thành công, chúng ta có thể chuyển sang triển khai công cụ "read_docs" thực:

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

Lưu ý: bạn có thể tuỳ ý thử nghiệm câu lệnh này hoặc tự nghĩ ra câu lệnh của riêng mình.

Mẹo hữu ích

Vì MCP vẫn là một khái niệm mới và Go SDK cho MCP là một thư viện mới, nên ở bước này, Gemini có thể mất nhiều thời gian để tự tìm ra cách triển khai phù hợp. Để giúp mô hình đưa ra giải pháp phù hợp, bạn có thể thử những cách sau:

Nếu mô hình bỏ qua việc đọc tài liệu ở bất kỳ bước nào, hãy nhấn ESC và nhắc mô hình làm như vậy. Nếu bạn không quen thuộc với go, hãy chạy "go doc" cùng với tên của gói "go doc github.com/modelcontextprotocol/go-sdk/mcp" để trả về tài liệu phù hợp.
Mô-đun cấp cao nhất " github.com/modelcontextprotocol/go-sdk" không có tài liệu nào (vì không có mã Go), bạn cần yêu cầu mô hình tìm đường dẫn đầy đủ
Ngược lại, nếu mô hình tạo ra một gói không tồn tại, chẳng hạn như "go doc github.com/modelcontextprotocol/go-sdk/mcp/server", chỉ cần hướng dẫn nó đến gói cấp cao nhất.

6. Định cấu hình godoctor làm Máy chủ MCP cho Gemini CLI

Sau khi trợ lý AI tạo mã cho cả máy khách và máy chủ, bạn có thể hướng dẫn trợ lý này chạy một số kiểm thử thủ công. Ví dụ:

retrieve the documentation for the package net/http

Đảm bảo bạn cũng kiểm thử bằng một phần phụ thuộc bên ngoài (không có trong thư viện chuẩn):

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

Khi bạn hài lòng với kết quả, hãy hướng dẫn AI viết một tệp README.md có hướng dẫn về cách sử dụng và phát triển dự án này.

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

Giờ đây, chúng ta sẽ định cấu hình máy chủ để Gemini CLI có thể sử dụng máy chủ này trong giai đoạn phát triển tiếp theo.

Yêu cầu CLI cập nhật GEMINI.md để sử dụng read_docs làm phương thức ưu tiên để đọc tài liệu:

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`)

Bây giờ, chúng ta cần khởi động lại Gemini CLI để định cấu hình máy chủ MCP. Trước tiên, hãy lưu phiên trò chuyện để bạn có thể tiếp tục từ điểm dừng khi phiên trò chuyện được khởi động lại.

/chat save godoctor-workshop

Thoát khỏi CLI bằng cách nhấn tổ hợp phím Ctrl+D hai lần hoặc nhập lệnh /quit.
Trong các bước trước, tác nhân sẽ biên dịch một tệp nhị phân máy chủ cho bạn, nhưng chúng ta sẽ biên dịch lại máy chủ bằng một tên khác để không bị ảnh hưởng khi sửa đổi mã nguồn của máy chủ:

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

Định cấu hình Gemini CLI cho công cụ cục bộ: Tạo tệp .gemini/settings.json trong thư mục gốc của dự án và thêm một phần mcpServers để cho Gemini CLI biết cách chạy máy chủ đã biên dịch.

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

Bây giờ, hãy thêm nội dung sau vào tệp mới bằng trình chỉnh sửa cloudshell hoặc IDE mà bạn yêu thích.

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

Khởi chạy Gemini CLI bằng lệnh gemini
Bạn có thể thấy rằng công cụ này được tải bằng cách nhập lệnh /mcp. Bạn cũng có thể hiện nội dung mô tả đầy đủ về các công cụ bằng cách sử dụng /mcp desc:

Kiểm thử quy trình tích hợp bằng cách yêu cầu Gemini CLI sử dụng công cụ của bạn với một câu lệnh như "Cho tôi xem tài liệu về gói net/http"

Bạn sẽ thấy như sau:

Nếu công cụ hoạt động bình thường, bạn sẽ thấy tài liệu được truy xuất thông qua lệnh gọi công cụ:

Xin chúc mừng, bạn đã tạo một công cụ MCP! Nhưng đây chưa phải là kết thúc, chúng ta vẫn có thể làm cho máy chủ này hữu ích hơn một chút.

7. Thêm một công cụ đánh giá mã dựa trên AI

Hãy thêm một tính năng tinh vi hơn, dựa trên AI: một trình đánh giá mã sử dụng Gemini API.

Giờ đây, bạn có thể khôi phục phiên trò chuyện trước đó bằng lệnh /chat resume godoctor-workshop. Lệnh này sẽ tải ngữ cảnh của phiên cho đến thời điểm chúng ta hoàn tất việc phát triển read_docs, vì vậy, mô hình sẽ có kiến thức cần thiết để tạo công cụ mới.

Công cụ này sẽ cần quyền truy cập vào Vertex AI, vì vậy, trước tiên chúng ta cần bật API này. Bạn có thể chạy các lệnh shell mà không cần rời khỏi Gemini CLI bằng cách nhập dấu chấm than (!) vào một câu lệnh trống. Thao tác này sẽ chuyển Gemini CLI sang chế độ shell.

Chạy lệnh sau ở chế độ shell để bật Vertex AI API:

gcloud services enable aiplatform.googleapis.com

Sau khi hoàn tất lệnh, bạn có thể chuyển về chế độ lời nhắc bằng cách nhập phím thoát (Esc).

Mục tiêu: Thêm một công cụ mới có tên là code_review vào dự án hiện có. Công cụ này sẽ sử dụng Gemini API để phân tích mã Go và đưa ra ý kiến phản hồi.

Câu lệnh mẫu:

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

Mẹo hữu ích

Sau khi mô hình bắt đầu hoạt động, bạn có thể thấy mô hình tự động yêu cầu gọi công cụ read_docs để duyệt xem tài liệu cho gói genai. Nếu không, bạn luôn có thể nhấn phím thoát để dừng quy trình và nhắc AI rằng giờ đây AI đã có công cụ read_docs theo ý mình.
Nếu bạn thấy mô hình đang cố gắng sử dụng GenAI SDK không chính xác (mặc dù có danh sách "không được phép" rõ ràng trong câu lệnh), hãy hướng dẫn mô hình quay lại sử dụng GenAI SDK chính xác.

Kiểm thử Trình đánh giá mã

Lưu phiên trò chuyện bằng /chat save godoctor-workshop rồi thoát CLI bằng cách nhấn Ctrl+D hai lần.
Biên dịch lại máy chủ bằng định nghĩa công cụ mới:.

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

Sử dụng IDE của bạn, hãy cập nhật tệp .gemini/settings.json để thêm cấu hình môi trường cho Vertex AI:

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

Khởi chạy lại Gemini CLI. Khôi phục phiên trò chuyện với /chat resume godoctor-workshop
Xác nhận rằng công cụ này đã được bật bằng cách nhập lệnh /mcp. Bạn sẽ thấy như sau:

Bây giờ, hãy kiểm thử công cụ code_review bằng cách xem xét một trong các tệp nguồn của công cụ này:

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

    You should see something like this:

Khi công cụ đánh giá mã hoạt động, giờ đây, bạn có thể đề xuất mô hình áp dụng một số điểm cải tiến mà mô hình tìm thấy, để có một quy trình "tự cải thiện" hoàn chỉnh!

Giờ đây, bạn đã xác nhận rằng công cụ code-review hoạt động. Trong phần tiếp theo, bạn sẽ tìm hiểu cách triển khai ứng dụng này lên đám mây. Lưu phiên hiện tại bằng /chat save godoctor-workshop và thoát khỏi CLI.

8. Chuẩn bị máy chủ cho đám mây

Máy chủ MCP mà chúng ta đã phát triển cho đến nay chỉ chạy trên máy cục bộ. Điều này không sao nếu bạn đang phát triển các công cụ để sử dụng cho riêng mình. Tuy nhiên, trong môi trường doanh nghiệp, chúng ta thường cần triển khai các công cụ để hàng trăm hoặc thậm chí hàng nghìn nhà phát triển có thể sử dụng rộng rãi.

Để mở rộng quy mô máy chủ MCP, chúng ta cần chuyển đổi máy chủ này từ một máy chủ chỉ nói I/O tiêu chuẩn sang một máy chủ có thể nói HTTP và triển khai máy chủ đó ở nơi mà nhiều nhà phát triển có thể truy cập. Để đạt được mục tiêu này, chúng ta sẽ sử dụng một chế độ truyền tải được xác định trong quy cách MCP dưới dạng HTTP có thể truyền trực tuyến và sử dụng Cloud Run làm mục tiêu triển khai.

Mục tiêu: Tái cấu trúc máy chủ godoctor để sử dụng phương thức truyền HTTP có thể truyền trực tuyến.

Câu lệnh mẫu:

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

Mẹo hữu ích

Mô hình có thể cố gắng sử dụng HTTP+SSE (đã ngừng hoạt động). Nếu bạn thấy yêu cầu đi theo đường dẫn này, hãy chuyển hướng yêu cầu đó trở lại HTTP có thể truyền phát.
Phiên bản hiện tại của Gemini CLI (0.26.0) không hỗ trợ chạy các quy trình ở chế độ nền (mọi quy trình được khởi chạy bằng run_shell_command sẽ bị huỷ khi lệnh gọi công cụ trả về), vì vậy, chúng tôi yêu cầu Gemini tự động hoá quy trình kiểm thử bằng một tập lệnh. Tính năng này đang được lên kế hoạch và sẽ được thêm vào trong tương lai gần, giúp đơn giản hoá quy trình kiểm thử.

Không bắt buộc: Kiểm thử Máy chủ MCP bằng HTTP

Nếu bạn muốn định cấu hình Gemini CLI để sử dụng máy chủ thông qua HTTP, hãy làm như sau:

Lưu phiên và thoát khỏi CLI
Chỉnh sửa tệp .gemini/settings.json và thay đổi cấu hình để trỏ đến máy chủ đang chạy cục bộ.

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

Trong một thiết bị đầu cuối thứ hai, hãy chạy máy chủ đã bật HTTP cục bộ:

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

Khởi động lại Gemini CLI và đưa ra một câu lệnh để kiểm tra kết nối, ví dụ: "Sử dụng công cụ godoctor để xem tài liệu về fmt.Println."
Dừng máy chủ bằng tổ hợp phím Ctrl+C khi bạn hoàn tất kiểm thử.

9. Đóng gói ứng dụng bằng Docker

Giờ đây, khi máy chủ của chúng ta đang sử dụng giao thức truyền tải chính xác, chúng ta có thể chứa nó để triển khai.

Mục tiêu: Tạo một Dockerfile để đóng gói máy chủ godoctor vào một hình ảnh vùng chứa di động, sẵn sàng cho sản xuất.

Câu lệnh mẫu:

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

Không bắt buộc: Kiểm thử thủ công hình ảnh Docker

Sau khi tạo Dockerfile, hãy tạo hình ảnh và chạy hình ảnh đó để đảm bảo hình ảnh hoạt động đúng cách.

Tạo vùng chứa:

docker build -t godoctor:latest .

Chạy vùng chứa cục bộ:

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

Kiểm thử vùng chứa đang chạy: Trong một thiết bị đầu cuối khác, hãy khởi động Gemini CLI và yêu cầu công cụ này tìm nạp tài liệu.
Dừng máy chủ bằng tổ hợp phím Ctrl+C khi bạn hoàn tất kiểm thử.

10. Triển khai lên Cloud Run

Giờ là lúc triển khai vùng chứa lên đám mây.

Mục tiêu: Triển khai máy chủ godoctor được chứa trong vùng chứa đến Google Cloud Run.

Câu lệnh mẫu:

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

Sau khi quá trình triển khai hoàn tất, chúng ta sẽ định cấu hình Gemini CLI để sử dụng công cụ mà bạn vừa triển khai.

Cập nhật tệp .gemini/settings.json để thay đổi cấu hình công cụ MCP nhằm trỏ đến dịch vụ đã triển khai của bạn hoặc yêu cầu Gemini CLI thực hiện việc này cho bạn:

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

Phần mcpServers cuối cùng sẽ có dạng như sau (hãy nhớ thay thế trình giữ chỗ bằng URL thực tế của ứng dụng Cloud Run):

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

Kiểm thử việc triển khai Cloud Run

Giờ đây, bạn đã sẵn sàng cho quy trình kiểm thử toàn diện cuối cùng.

Khởi động lại Gemini CLI lần cuối (bằng cách sử dụng /chat save và /chat resume nếu bạn muốn giữ lại bối cảnh). Giờ đây, CLI có thể gọi máy chủ MCP từ xa. Hãy thử yêu cầu tài liệu cho mọi gói.

Bạn cũng có thể kiểm thử công cụ đánh giá mã:

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

Dọn dẹp

Sau khi kiểm thử xong, hãy nhớ dọn dẹp môi trường. Bạn có thể yêu cầu Gemini xoá dự án hoặc chỉ xoá việc triển khai CloudRun. Câu lệnh mẫu:

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. Xin chúc mừng!

Bạn đã hướng dẫn thành công một trợ lý AI xây dựng, đóng gói và triển khai một công cụ tinh vi dựa trên AI. Quan trọng hơn, bạn đã thực hành kỹ năng thiết yếu của hoạt động phát triển phần mềm hiện đại: chuyển đổi các yêu cầu thành câu lệnh hiệu quả. Bạn đã mở rộng thành công Gemini CLI bằng một công cụ MCP tuỳ chỉnh, giúp công cụ này trở thành một trợ lý phát triển Go mạnh mẽ và chuyên biệt hơn.

Cách tạo máy chủ MCP bằng Gemini CLI và Go

1. Giới thiệu

Kiến thức bạn sẽ học được

Bạn cần có

Công nghệ chính

Mẹo để có một lớp học lập trình thành công

2. Thiết lập môi trường

Thiết lập môi trường theo tốc độ của riêng bạn

Khởi động Cloud Shell

3. Làm quen với Gemini CLI

Gemini CLI là gì?

Cài đặt

Cấu hình

4. Tệp ngữ cảnh (GEMINI.md)

5. Bản dựng ban đầu: Máy chủ tài liệu

Tạo máy chủ MCP Hello World

Triển khai công cụ read_docs

Mẹo hữu ích

6. Định cấu hình godoctor làm Máy chủ MCP cho Gemini CLI

7. Thêm một công cụ đánh giá mã dựa trên AI

Mẹo hữu ích

Kiểm thử Trình đánh giá mã

8. Chuẩn bị máy chủ cho đám mây

Mẹo hữu ích

Không bắt buộc: Kiểm thử Máy chủ MCP bằng HTTP

9. Đóng gói ứng dụng bằng Docker

Không bắt buộc: Kiểm thử thủ công hình ảnh Docker

10. Triển khai lên Cloud Run

Kiểm thử việc triển khai Cloud Run

Dọn dẹp

11. Xin chúc mừng!

Tài liệu tham khảo

Triển khai công cụ `read_docs`