Zig와 Gemini CLI를 사용한 로컬 MCP 개발

Source: Dev.to

위에 제공된 Source 링크만으로는 번역할 본문이 없습니다. 번역이 필요한 전체 텍스트(마크다운 형식 포함)를 제공해 주시면, 요청하신 대로 한국어로 번역해 드리겠습니다.

Source: …

개요

• Python은 전통적으로 ML/AI 도구를 장악해 왔지만, MCP 프로토콜은 언어에 구애받지 않습니다.
• 이 가이드는 Zig—현대적인 오픈소스 시스템 언어—를 MCP 개발 언어로 사용하는 방법을 보여줍니다.
• 여러분은 Gemini CLI와 stdio를 통해 통신하는 작은 “Hello World” 스타일의 Zig MCP 서버를 만들게 됩니다.

리소스

사전 요구 사항

1. Zig (최신 안정 버전) – OS 패키지 관리자를 통해 또는 위의 Debian 가이드를 참고하여 설치합니다.

2. Node.js – 최신 버전 중 최신 버전. nvm을 사용하여 관리합니다:

   # Install nvm (if not already present)
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
   # Load nvm and install Node LTS
   source ~/.bashrc   # or ~/.zshrc
   nvm install --lts

3. Gemini CLI – npm을 사용해 전역으로 설치합니다:

   npm install -g @google/gemini-cli

4. Authentication – gemini를 한 번 실행하여 Google 계정 또는 API 키로 로그인합니다.

개발 환경 설정

# 초기화 스크립트와 샘플 코드가 포함된 헬퍼 레포지토리 복제
cd ~
git clone https://github.com/xbill9/gemini-cli-codeassist
cd gemini-cli-codeassist

# 셸을 위한 환경 변수 초기화
source init.sh

세션이 만료되었거나 나중에 다시 인증이 필요한 경우:

source set_env.sh   # PROJECT_ID, 자격 증명 등을 재설정합니다.

Minimal MCP stdio 서버 구축

1. Zig 프로젝트 생성

샘플 프로젝트는 gemini-cli-codeassist/mcp-stdio-zig 아래에 있습니다.
해당 디렉터리로 이동한 뒤 기본 Make 타깃을 실행합니다:

cd mcp-stdio-zig
make          # runs `zig build`

다음과 같은 출력이 보일 것입니다:

Linked zig-out/bin/mcp-stdio-zig to server

2. 소스 코드 하이라이트

// src/main.zig
const std = @import("std");
const mcp = @import("mcp");

// Run the server using stdio transport
try server.run(.{ .stdio = {} });

서버는 표준 Zig 라이브러리(std)와 MCP 라이브러리(mcp)를 임포트한 뒤, stdio 기반 MCP 서버를 시작합니다.

3. Lint / format

make lint
# → zig fmt --check .
# → zig build -Doptimize=ReleaseFast

4. 서버 테스트

make test
# Output (truncated):
# Testing 'greet' tool...
# ✓ initialize successful
# ✓ notifications/initialized sent
# ✓ tools/list successful
# ✓ tools/call (greet) successful
# All tests passed!

테스트 하니스(python3 test_server.py)는 greet 도구를 검증합니다.

Gemini CLI에 서버 등록하기

~/.config/gemini-cli/settings.json (또는 기본 위치)에 항목을 추가합니다:

{
  "mcpServers": {
    "mcp-stdio-zig": {
      "command": "$HOME/gemini-cli-codeassist/mcp-stdio-zig/server"
    }
  }
}

Gemini CLI를 재시작하여 새로운 구성을 적용합니다.

MCP 서버 사용하기

# Start a Gemini CLI session
gemini

> /mcp schema

Configured MCP servers:

🟢 mcp-stdio-zig - Ready (1 tool)
  Tools:
  - greet
    Get a greeting from a local stdio server.
    Parameters:
    {
      "type": "object"
    }

이제 도구를 호출합니다:

> greet Carmen!

✦ I will read the src/main.zig file to understand how the greet tool is implemented and what parameters it expects.
╭─────────────────────────────────────────────────────────────────────╮
│ ✓ ReadFile src/main.zig                                            │
╰─────────────────────────────────────────────────────────────────────╯

서버가 인사말을 응답하여 MCP stdio 전송이 엔드‑투‑엔드로 정상 작동함을 확인합니다.

요약 및 다음 단계

1. 환경 – Zig, Node (nvm을 통해), Gemini CLI가 설치되고 인증됨.
2. 서버 – 최소 Zig MCP stdio 서버가 컴파일되고 테스트됨.
3. 통합 – Gemini CLI에 등록되었으며 /mcp schema와 툴 호출을 통해 확인됨.

여기서 할 수 있는 일:

• 더 많은 MCP 도구 추가 (예: summarize, translate).
• 동일한 고수준 MCP API를 사용하여 다른 전송 방식(TCP, WebSocket)으로 전환.
• 더 긴밀한 통합을 위해 Gemini LLM을 Zig 코드에 직접 임베드.

즐거운 코딩 되세요! 🚀

MCP Tools Extension – 요약

1️⃣ Greeting Test

Command

✦ I will call the greet tool with the parameter param set to "Carmen!".

Tool Invocation

✓ greet (mcp-stdio-zig MCP Server) {"param":"Carmen!"}

Result

Carmen!

Note: 도구가 “Carmen!”을 반환했으며, 기본 MCP 기능이 정상 작동함을 확인했습니다.

2️⃣ 새로운 MCP 도구 추가

Zig 프로젝트에 세 개의 새로운 도구가 추가되었습니다:

Code Diff (src/main.zig에 추가)

+ fn serverInfoHandler(allocator: std.mem.Allocator, _: ?std.json.Value) mcp.tools.ToolError!mcp.tools.ToolResult {
+     logInfo("Executed server-info tool");
+
+     const info = "Server: mcp-stdio-zig, Version: 0.1.0";
+     var items = allocator.alloc(mcp.types.ContentItem, 1) catch return mcp.tools.ToolError.OutOfMemory;
+     items[0] = .{ .text = .{ .text = try allocator.dupe(u8, info) } };
+
+     return mcp.tools.ToolResult{
+         .content = items,
+         .is_error = false,
+     };
+ }

변경 사항이 커밋되었으며, 새로운 도구들이 검증되었습니다.

3️⃣ Build & List Tools

xbill@penguin:~/gemini-cli-codeassist/mcp-stdio-zig$ make
zig build
Linked zig-out/bin/mcp-stdio-zig to server

List Available MCP Tools

/mcp list

Configured MCP servers:

🟢 mcp-stdio-zig - Ready (4 tools)
  Tools:
  - current-time
  - greet
  - server-info
  - zig-info

4️⃣ 새로운 도구 실행

current-time

✓ current-time (mcp-stdio-zig MCP Server) {}
Timestamp: 1769875173

zig-info

✓ zig-info (mcp-stdio-zig MCP Server) {}
Zig Version: 0.15.2, OS: linux, Arch: x86_64

Result: Linux x86_64 환경에서 Zig 0.15.2가 실행 중임을 확인했습니다.

server-info

✓ server-info (mcp-stdio-zig MCP Server) {}
Server: mcp-stdio-zig, Version: 0.1.0

Result: 서버 이름과 버전을 확인했습니다.

5️⃣ Zig 환경 요약

MCP 도구와 코드베이스를 이용해:

✓ ReadFile src/main.zig
✓ ReadFile build.zig
✓ ReadFile build.zig.zon

Summary (요약)

• Zig Version (Zig 버전): 0.15.2
• Operating System (운영 체제): Linux (x86_64)
• MCP Server: mcp-stdio-zig (v0.1.0)
• Primary Dependency (주요 의존성): mcp.zig (v0.0.1) – Zig용 Model Context Protocol 구현.
• Communication (통신): 표준 입출력 (stdio)과 구조화된 JSON 로깅을 stderr에 출력.
• Exposed Tools (제공 도구):
  • greet – 인사말 반환 (매개변수 가능).
  • zig-info – Zig 버전, OS, 아키텍처 보고.
  • server-info – 서버 이름 및 버전 반환.
  • current-time – 현재 시스템 타임스탬프 제공.

6️⃣ 궁극의 대결: Ferris vs. Carmen

Google Search (맥락 파악용)

✓ GoogleSearch Searching the web for: "who is carmen programming language mascot"
Search results for "who is carmen programming language mascot" returned.

Result

가상의 대결에서 **Rust의 Ferris (게 crab)**와 Zig Allocgator인 Carmen이 맞붙으면 Safety vs. Control(안전성 vs. 제어)이라는 전투가 펼쳐집니다.

Tale of the Tape

Bottom line: Ferris는 철벽 같은 안전성을, Carmen은 직접적인 제어력을 제공합니다.

ety, while Carmen offers fine‑grained control.
승자는 보장된 안전성(Rust)을 중시하는지 혹은 결정론적이며 낮은 오버헤드 제어(Zig)를 중시하는지에 따라 달라집니다.

Zig와 MCP 개발에 Gemini CLI 사용하기

MCP 개발에 Zig를 Gemini CLI와 함께 사용하는 전략은 단계별 점진적 접근 방식으로 검증되었습니다:

1. 최소한의 stdio 전송 MCP 서버를 Zig 소스 코드에서 시작하고, 동일한 로컬 환경에서 MCP 클라이언트 역할을 하는 Gemini CLI로 검증했습니다.
2. 이후 Gemini CLI를 사용해 샘플 Zig 코드에 여러 MCP 도구를 추가하고, 이러한 도구들을 기본 LLM 컨텍스트 내에서 활용했습니다.