Mcp on Yarang's Tech Lair

MCP 통합 가이드: ZeroClaw 런타임에서 Discord MCP 연동하기

Sun, 28 Jun 2026 09:00:35 +0900

최근 고성능 Rust 에이전트 런타임인 ZeroClaw를 발표하며, 멀티 에이전트 시스템의 효율성을 극대화하는 방안에 대한 고민이 깊어졌습니다. 특히 [Discord Decision MCP] 아키텍처 설계를 진행하면서 겪었던 통신 프로토콜의 복잡성은 MCP(Model Context Protocol)를 표준 인터페이스로 채택하게 된 결정적인 계기가 되었습니다.

이번 포스트에서는 ZeroClaw의 환경에서 Discord MCP를 실제로 통합하여, 에이전트가 Discord 메시지를 수신하고 처리하는 과정을 구체적인 코드와 함께 설명하겠습니다.

1. 아키텍처 설계: 단일 채널에서의 이중 통신

기존 [Discord MCP] Gateway 아키텍처에서는 게이트웨이가 이벤트를 필터링하고 에이전트에게 전달하는 역할을 했습니다. 하지만 ZeroClaw 내부적으로 MCP 클라이언트를 직접 구현함으로써 중간 계층을 제거하고 지연 시간을 줄이는 방향으로 설계를 변경했습니다.

핵심은 **MCP Client**가 Discord 이벤트를 stdio를 통해 ZeroClaw 프로세스로 전달하고, 에이전트의 응답을 다시 Discord로 보내는 흐름입니다.

2. 필수 의존성 및 설정 (Rust)

ZeroClaw는 Rust로 작성되었으므로, 높은 동시성 처리를 위해 비동기 런타임인 tokio와 JSON 처리를 위한 serde를 사용합니다. MCP 서버와의 통신은 JSON-RPC 메시지를 표준 입출력(stdio)으로 주고받는 방식을 가정합니다.

# Cargo.toml
[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
async-trait = "0.1"

3. MCP 클라이언트 구현

ZeroClaw 내부에서 Discord MCP 서버를 제어하기 위한 간단한 클라이언트 구조를 정의합니다. 이 클라이언트는 MCP 표준을 따르는 tools/call 메서드를 사용하여 Discord 봇의 기능을 실행합니다.

use serde::{Deserialize, Serialize};
use std::process::{Command, Stdio};
use std::io::{BufReader, BufWriter, Write};

#[derive(Debug, Serialize, Deserialize)]
struct MCPRequest {
 jsonrpc: String,
 id: u64,
 method: String,
 params: serde_json::Value,
}

#[derive(Debug, Serialize, Deserialize)]
struct MCPResponse {
 jsonrpc: String,
 id: u64,
 result: Option<serde_json::Value>,
}

pub struct DiscordMCPClient {
 id: u64,
}

impl DiscordMCPClient {
 pub fn new() -> Self {
 Self { id: 0 }
 }

 /// Discord 채널에 메시지를 전송하는 MCP 툴 실행
 pub async fn send_message(&mut self, channel_id: &str, content: &str) -> Result<(), Box<dyn std::error::Error>> {
 self.id += 1;
 
 // MCP 서버 프로세스 실행 (예: Python 기반 Discord MCP 서버)
 let mut child = Command::new("python3")
 .arg("discord_mcp_server.py")
 .stdin(Stdio::piped())
 .stdout(Stdio::piped())
 .spawn()?;

 let stdin = child.stdin.as_mut().ok("Failed to open stdin")?;
 let mut stdout = BufReader::new(child.stdout.as_mut().ok("Failed to open stdout")?);

 let request = MCPRequest {
 jsonrpc: "2.0".to_string(),
 id: self.id,
 method: "tools/call".to_string(),
 params: serde_json::json!({
 "name": "send_message",
 "arguments": {
 "channel_id": channel_id,
 "content": content
 }
 }),
 };

 // 요청 전송
 let request_json = serde_json::to_string(&request)?;
 writeln!(stdin, "{}", request_json)?;

 // (실제 구현 시에는 비동기 리더에서 응답을 파싱하는 로직 필요)
 // 여기서는 간단한 예시를 위해 생략합니다.
 
 Ok(())
 }
}

4. ZeroClaw 에이전트와의 통합

이제 위에서 만든 DiscordMCPClient를 ZeroClaw의 에이전트 루프 내에서 사용해봅시다. 에이전트가 특정 작업을 완료했을 때, 이를 Discord에 알리는 시나리오입니다.

struct ZeroClawAgent {
 discord_client: DiscordMCPClient,
}

impl ZeroClawAgent {
 async fn run_task(&mut self, task: &str) {
 println!("[Agent] 작업 시작: {}", task);
 
 // 복잡한 추론 또는 파일 처리 로직 (생략)
 // ...

 let result = format!("작업 '{}' 완료됨.", task);

 // 결과를 Discord로 전송
 match self.discord_client.send_message("123456789", &result).await {
 Ok(_) => println!("[Agent] Discord 알림 전송 성공"),
 Err(e) => eprintln!("[Agent] 전송 실패: {}", e),
 }
 }
}

#[tokio::main]
async fn main() {
 let mut agent = ZeroClawAgent {
 discord_client: DiscordMCPClient::new(),
 };

 agent.run_task("서버 로그 분석").await;
}

5. 효율성 및 보안 고려사항 (Architecture Insights)

리소스 관리: [Hacker News]의 최신 트렌드인 ‘Adrafinil’처럼, 에이전트가 유휴 상태일 때는 Discord MCP 연결을 끊고 작업이 활성화되었을 때만 연결을 맺는 speculative decoding 방식을 적용하면 리소스를 아낄 수 있습니다.
보안: [Anonymous GitHub account] 관련 이슈처럼, MCP 서버에 전달되는 파라미터(예: API 토큰)는 환경 변수로 관리하거나 별도의 보안 저장소(Vault)에서 가져오도록 설계해야 합니다. 코드 내에 하드코딩된 시크릿은 치명적입니다.
에러 처리: 통신 플랫폼 설계 고찰에서 언급된 바와 같이, Discord API의 Rate Limit을 고려하여 MCP 클라이언트에 재시도 로직(Retry Logic)을 포함하는 것이 중요합니다.

마무리하며

ZeroClaw와 Discord MCP의 통합은 단순히 봇을 만드는 것을 넘어, 에이전트가 외부 세계와 상호작용하는 표준화된 인터페이스를 구축하는 과정입니다. 앞으로도 [MCP] 블로그 자동화 시스템 구축 경험을 살려, 더욱 정교한 멀티 에이전트 협업 시스템을 발전시켜 나갈 계획입니다.

MCP 서버 메타데이터 동기화: 개발자 생산성을 위한 컨텍스트 관리 전략

Mon, 22 Jun 2026 09:01:11 +0900

MCP 서버 메타데이터 동기화: 개발자 생산성을 위한 컨텍스트 관리 전략

최근 AI 에이전트와 개발 툴링의 통합이 깊어지면서, 우리는 **Model Context Protocol (MCP)**를 통해 블로그 시스템을 자동화하고 있지만, 여전히 하나의 성가신 문제가 남아 있습니다. 바로 AI와의 세션마다 프로젝트의 구조와 맥락을 반복해서 설명해야 하는 ‘토큰 낭비(Token Waste)’ 현상입니다.

Hacker News의 최신 글인 *Stop wasting tokens and re explaining your project between sessions*에서 언급된 것처럼, 프로젝트의 맥락을 일관되게 유지하는 것은 단순한 편의를 넘어 비용 효율과 직결됩니다.

이번 포스트에서는 MCP 서버가 제공하는 정적 리소스(Tools, Resources, Prompts)를 넘어, 동적 메타데이터(컨텍스트)를 어떻게 에이전트에게 효율적으로 공유할 수 있는지에 대한 실용적인 설계안을 제안합니다.

문제 정의: 매번 반복되는 ‘내 프로젝트 소개’

기존 MCP 클라이언트는 서버가 제공하는 tools 리스트를 통해 기능을 파악합니다. 예를 들어, write_post라는 툴이 있으면 Claude는 이를 호출하여 글을 씁니다. 하지만 Claude는 ‘이 블로그의 글쓰기 스타일은 어떤지?’, ‘최근 트렌드는 무엇인지?’ 와 같은 맥락(Context)을 알지 못합니다.

결국 사용자는 다음과 같은 프롬프트를 매번 달아줘야 합니다.

“블로그에 글을 써줘. 단, 스타일은 기술적이고 구체적이어야 하며, 최신 Hacker News 트렌드를 참고해야 해.”

이는 불필요한 토큰 소모를 유발합니다. 이를 해결하기 위해 MCP 서버 내에 프로젝트의 ‘아키텍처 설계서’나 ‘개발 가이드’를 리소스(Resource)로 통합하는 방법을 고려해볼 수 있습니다.

솔루션: 리소스 기반 메타데이터 제공

MCP 규격에서 Resources는 서버가 제공하는 데이터 조각입니다. 우리는 이를 단순한 파일 조회용이 아닌, **‘프로젝트 상태 머신(State Machine)’**으로 활용할 수 있습니다.

1. 아키텍처 문서 자동화

이전에 작성한 [ZeroClaw] 코드베이스 아키텍처 분석이나 [Multi-Agent] 파일 기반 아키텍처 설계와 같은 문서는 정적 파일로 존재하거나 Confluence 등에 흩어져 있을 수 있습니다. 이를 MCP 서버가 시작될 때 메모리에 로드하거나, 동적으로 생성하여 제공할 수 있도록 만듭니다.

2. Rust 구현 예제

Rust로 작성된 MCP 서버(예: blog-api-server)에 architecture_guide라는 리소스를 추가하는 코드를 작성해보겠습니다.

use jsonrpc_core::{Result, Params};
use std::collections::HashMap;
use serde_json::Value;

// 가상의 MCP 핸들러 구조체
pub struct BlogMcpServer {
 // 캐싱된 메타데이터
 cached_context: String,
}

impl BlogMcpServer {
 pub fn new() -> Self {
 // 서버 초기화 시 핵심 컨텍스트(아키텍처, 규칙)를 로드
 let context = r#"
 프로젝트: ZeroClaw Multi-Agent Runtime
 아키텍처: 파일 기반 이벤트 버스를 사용하는 비동기 멀티 에이전트 시스템.
 주요 규칙:
 1. 모든 에이전트는 독립된 스레드에서 실행됨.
 2. 통신은 JSON-RPC over MCP 프로토콜을 따름.
 3. 로그는 구조화된 JSON 형식으로 출력해야 함.
 "#;
 
 Self { cached_context: context.to_string() }
 }

 // MCP 리소스 조회 핸들러 (resources/read)
 pub fn handle_read_resource(&self, params: Params) -> Result<Value> {
 let params_obj: HashMap<String, Value> = params.parse()?;
 let uri = params_obj.get("uri").and_then(|v| v.as_str()).unwrap_or("");

 match uri {
 "context://architecture/guide" => {
 // 클라이언트가 요청할 때 캐싱된 컨텍스트 반환
 Ok(json!({
 "contents": [
 {
 "uri": uri,
 "mimeType": "text/plain",
 "text": self.cached_context.clone()
 }
 ]
 }))
 },
 "context://trends/latest" => {
 // 외부 RSS(Hacker News 등)를 실시간으로 페칭하여 제공 (동적 리소스)
 let trends = fetch_latest_hn_trends().await.unwrap_or_default();
 Ok(json!({
 "contents": [{
 "uri": uri,
 "mimeType": "application/json",
 "text": trends
 }]
 }))
 },
 _ => Err(Error::invalid_params("Unknown resource URI"))
 }
 }
}

async fn fetch_latest_hn_trends() -> Option<String> {
 // 실제로는 reqwest 등을 사용하여 RSS를 파싱
 // 예시를 위해 간단한 JSON 문자열 반환
 Some(r#"[{"title": "JSON-LD Explained", "link": "..."}]"#.to_string())
}

이 코드는 MCP 클라이언트가 context://architecture/guide URI를 통해 리소스를 요청하면, 사전에 정의된 프로젝트의 아키텍처 규칙을 즉시 반환합니다.

3. 프롬프트 자동 주입 (Prompt Injection)

이제 클라이언트(Claude 등)가 복잡한 설정을 하지 않도록, MCP 서버의 Prompts 기능을 활용하여 시스템 프롬프트를 자동으로 완성해주는 템플릿을 제공할 수 있습니다.

MCP 서버는 다음과 같은 프롬프트 템플릿을 노출할 수 있습니다.

Prompt Name: generate_blog_post Arguments: topic, tone

{
 "name": "generate_blog_post",
 "description": "Creates a technical blog post based on architecture context and latest trends.",
 "arguments": [
 { "name": "topic", "description": "Main topic", "required": true },
 { "name": "tone", "description": "Writing style", "required": false }
 ]
}

실제 구현 로직(Rust)은 다음과 같이 작동합니다.

pub fn handle_get_prompt(&self, params: Params) -> Result<Value> {
 let name = params.get("name").and_then(|v| v.as_str()).unwrap_or("");
 let args = params.get("arguments").and_then(|v| v.as_object()).unwrap_or(&json!(null));

 if name == "generate_blog_post" {
 let topic = args.get("topic").unwrap_or(&json!("general"));
 
 // 리소스에서 가져온 아키텍처 가이드를 프롬프트에 내장
 let system_instruction = format!(
 "You are writing for a blog defined by the following architecture:\n{}\n\nPlease write a post about: {}",
 self.cached_context, // 앞서 로드한 아키텍처 정보
 topic
 );

 Ok(json!({
 "messages": [
 {
 "role": "user",
 "content": {
 "type": "text",
 "text": system_instruction
 }
 }
 ]
 }))
 } else {
 Err(Error::invalid_params("Unknown prompt"))
 }
}

효과 및 기대 효과

이 접근 방식의 핵심은 **‘중복 제거(Duplication)’**입니다. Hacker News의 *Prefer duplication over the wrong abstraction*라는 글과 같이, 우리는 프로젝트의 본질을 단순화하기 위해 복잡한 추상화를 피하고, 대신 **필요한 정보(Context)를 필요한 곳(Prompt)에 통째로 복사(Duplication)**하여 넣습니다.

일관성 유지: 문서가 업데이트되면 MCP 서버만 재시작하거나 리소스를 갱신하면, 모든 세션에 최신 정보가 반영됩니다.
토큰 절약: 사용자가 매번 “내 프로젝트는 러스트로 짜여진 멀티 에이전트 시스템이야…“라고 설명할 필요가 없어집니다.
자동화 친화적: CI/CD 파이프라인에서 문서가 자동으로 생성되어 MCP 리소스로 등록되면, AI는 항상 최신 문서를 기반으로 코드를 생성하거나 리뷰할 수 있습니다.

결론

우리는 [ZeroClaw] 멀티 에이전트 아키텍처 설계안과 같은 문서를 단순히 ‘읽기용’으로 남겨두지 않고, 실행 가능한 AI의 뇌(Context)로 활용해야 합니다. MCP 서버에 이러한 메타데이터 동기화 계층을 추가하는 것은 복잡한 LLM 애플리케이션을 구축하기 위한 첫걸음이며, 개발자가 토큰을 낭비하지 않고 본질적인 로직에 집중하게 만드는 기반입니다.

다음 포스트에서는 이러한 메타데이터가 실제로 어떻게 Claude Code와 같은 팀 에이전트 통신 아키텍처에서 활용되는지 다루어보겠습니다.

Zero-Touch OAuth 구현을 위한 MCP 인증 아키텍처 설계

Fri, 19 Jun 2026 09:00:58 +0900

최근 ‘Zero-Touch OAuth for MCP’라는 흥미로운 기술 트렌드를 접했습니다. 우리가 개발 중인 ZeroClaw 런타임과 blog-api-server의 MCP(Model Context Protocol) 통합 과정에서, 사용자 경험을 저해하지 않으면서도 보안성을 확보하는 것은 필수적인 과제입니다. 이번 포스트에서는 별도의 복잡한 설정 없이 사용자가 MCP 클라이언트를 연결할 수 있도록 돕는 ‘Zero-Touch’ 인증 흐름을 설계하고, 이를 실제 코드로 구현하는 방법을 살펴보겠습니다.

왜 Zero-Touch인가?

기존의 OAuth 2.0 흐름은 사용자에게 ‘Client ID’와 ‘Client Secret’을 발급받아 설정 파일에 입력하도록 요구하곤 했습니다. 하지만 일반 사용자나 개발자에게 이는 큰 진입 장벽입니다. Zero-Touch OAuth는 클라이언트가 사전에 등록된 정보(Pre-registered metadata)를 통해 자동으로 인증을 시도하고, 사용자는 단순히 ‘허용’ 버튼만 누르면 되는 흐름을 지향합니다.

아키텍처 설계

우리는 blog-api-server를 MCP Provider로, Claude Code나 커스텀 클라이언트를 MCP Consumer로 구성합니다. 핵심은 PKCE (Proof Key for Code Exchange) 확장을 사용하여 Secret을 저장하지 않는 Public Client 환경을 구축하는 것입니다.

핵심 구성 요소:

MCP Client (Consumer): 사용자의 로컬 환경에서 실행되는 에이전트입니다.
Auth Server: blog-api-server 내에 구현된 OAuth2 인증 서버입니다.
Resource Server: 실제 블로그 API입니다.

구현 단계 1: 서버 사이드 (blog-api-server)

먼저, Rust 기반의 blog-api-server에 간단한 인증 엔드포인트를 추가해야 합니다. 이전 글인 *’[blog-api-server] MCP 블로그 클라이언트 언어 파라미터 추가’*에서 언급된 아키텍처를 확장하여 Auth 모듈을 독립시킵니다.

여기서는 핵심 로직인 코드 검증(Verification) 로직을 보여드리겠습니다. 클라이언트로부터 받은 code_verifier를 검증하는 과정입니다.

// blog-api-server/src/auth/handler.rs
use axum::{extract::State, Json};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use base64::Engine as _;

#[derive(Deserialize)]
pub struct TokenRequest {
 pub code: String,
 pub code_verifier: String, // PKCE를 통해 클라이언트가 생성한 난수
 pub redirect_uri: String,
}

#[derive(Serialize)]
pub struct TokenResponse {
 pub access_token: String,
 pub token_type: String,
 pub expires_in: u64,
}

pub async fn exchange_token(
 State(state): State<AppState>,
 Json(payload): Json<TokenRequest>,
) -> Result<Json<TokenResponse>, String> {
 // 1. DB에서 Authorization Code 조회
 let auth_record = state.db.get_auth_code(&payload.code)
 .await
 .map_err(|_| "Invalid code".to_string())?;

 // 2. PKCE Challenge 검증 (핵심 보안 로직)
 let mut hasher = Sha256::new();
 hasher.update(payload.code_verifier.as_bytes());
 let hashed_verifier = hasher.finalize();
 let encoded_verifier = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(hashed_verifier);

 if encoded_verifier != auth_record.code_challenge {
 return Err("Code verifier mismatch".to_string());
 }

 // 3. Access Token 발급
 let access_token = generate_jwt(&state.secrets, &auth_record.user_id);

 Ok(Json(TokenResponse {
 access_token,
 token_type: "Bearer".to_string(),
 expires_in: 3600,
 }))
}

이 코드는 클라이언트가 보내온 code_verifier를 해싱하여, 처음 인증 요청을 보낼 때 생성된 code_challenge와 일치하는지 확인합니다. 이 과정이 ‘Zero-Touch’를 보안적으로 가능하게 만드는 핵심입니다.

구현 단계 2: 클라이언트 사이드 (MCP Client)

이제 클라이언트는 사용자 개입 없이(혹은 최소한의 개입으로) 토큰을 발급받을 수 있습니다. Python을 사용한 MCP 클라이언트 예제를 작성해보겠습니다.

import hashlib
import base64
import requests
from urllib.parse import urlencode

# Zero-Touch 설정 (하드코딩 혹은 환경 변수)
CLIENT_ID = "zeroclaw-mcp-client"
AUTH_URL = "https://api.myblog.com/oauth/authorize"
TOKEN_URL = "https://api.myblog.com/oauth/token"
REDIRECT_URI = "http://localhost:3000/callback"

# PKCE Code Verifier 생성
random_bytes = os.urandom(32)
code_verifier = base64.urlsafe_b64encode(random_bytes).rstrip(b'=').decode('utf-8')

# Code Challenge 생성
challenge_digest = hashlib.sha256(code_verifier.encode('utf-8')).digest()
code_challenge = base64.urlsafe_b64encode(challenge_digest).rstrip(b'=').decode('utf-8')

def get_auth_url():
 params = {
 "response_type": "code",
 "client_id": CLIENT_ID,
 "redirect_uri": REDIRECT_URI,
 "scope": "mcp:read mcp:write",
 "code_challenge": code_challenge,
 "code_challenge_method": "S256"
 }
 return f"{AUTH_URL}?{urlencode(params)}"

def exchange_code_for_token(auth_code):
 data = {
 "grant_type": "authorization_code",
 "code": auth_code,
 "redirect_uri": REDIRECT_URI,
 "client_id": CLIENT_ID,
 "code_verifier": code_verifier # 서버로 전송하여 검증받음
 }
 response = requests.post(TOKEN_URL, data=data)
 return response.json()

# 사용 예시
# 1. 사용자가 get_auth_url()를 통해 브라우저에서 인증 (최초 1회)
# 2. 리다이렉션된 쿼리 파라미터에서 'code' 추출
# 3. token = exchange_code_for_token(code)

ZeroClaw 런타임 통합 고찰

지난 회고록인 *’[ZeroClaw] 2026 상반기 발전방향 회의록’*에서 언급했듯, 우리의 에이전트 런타임은 보안과 확장성을 최우선으로 고려해야 합니다. 위에서 구현한 OAuth 흐름을 ZeroClaw의 Multi-Agent 아키텍처에 통합한다면, 각 에이전트는 독립된 Identity를 가질 수 있습니다.

특히 *’[ZeroClaw] 멀티 에이전트 통신 프로토콜 설계’*에서 논의된 바와 같이, Agent 간 통신 시 이 Access Token을 사용하여 다른 에이전트의 리소스(API)에 안전하게 접근할 수 있는 기반을 마련하게 됩니다. 이는 단순한 블로그 자동화를 넘어, 에이전트가 에이전트를 신뢰하고 작업을 위임하는 분산 시스템의 첫걸음이 됩니다.

마치며

Zero-Touch OAuth는 사용자의 편의성과 보안이라는 두 마리 토끼를 잡는 훌륭한 접근 방식입니다. blog-api-server와 같은 작은 프로젝트부터 시작하여, 점차 ZeroClaw의 핵심 인증 모듈로 발전시켜 나갈 계획입니다. 위 코드는 기본적인 골격이므로, 실제 운영 환경에서는 State 검증, Refresh Token Rotation 등의 로직을 추가해야 합니다.

다음 포스트에서는 이렇게 확보된 토큰을 활용하여 MCP 서버와 실제로 데이터를 주고받는 ‘핸드셰이크(Handshake)’ 과정을 디버깅해보겠습니다.

MCP 기반 멀티 에이전트 시스템의 통신 프로토콜 설계와 Rust 구현

Mon, 15 Jun 2026 09:00:53 +0900

최근 ‘ZeroClaw’ 프로젝트와 MCP(Model Context Protocol) 관련 작업을 진행하며, 단일 에이전트를 넘어선 **멀티 에이전트 시스템(Multi-Agent System)**의 필요성을 절실히 느꼈습니다. 단순히 LLM에 프롬프트를 던지는 방식을 넘어, 에이전트 간에 의미 있는 데이터를 주고받고 협업하는 구조를 만들기 위해서는 견고한 **통신 프로토콜(Communication Protocol)**이 필수적입니다.

이번 포스트에서는 MCP 아키텍처를 기반으로 한 멀티 에이전트 통신 설계 과정과, 이를 고성능 런타임인 ZeroClaw(Rust) 위에 구현하는 방법을 살펴보겠습니다.

1. 문제 정의: 왜 통신 프로토콜인가?

기존의 [blog-api-server]나 [Discord MCP] 구현에서는 주로 ‘요청-응답(Request-Response)’ 구조를 따랐습니다. 클라이언트가 요청을 보내면 서버가 처리하고 응답하는 단방향 흐름이 주를 이루었습니다. 하지만 멀티 에이전트 환경에서는 다음과 같은 이유로 이 구조만으로는 부족합니다.

비동기성(Asynchrony): 에이전트 A가 에이전트 B에게 작업을 위임하고, B가 완료될 때까지 A가 멈춰 있으면 시스템 전체의 처리량이 떨어집니다.
이벤트 기반 상호작용: 어떤 에이전트는 시스템의 상태 변화(예: 파일 생성, 로그 업데이트)를 감시하다가 특정 조건에서 다른 에이전트에게 신호를 보내야 합니다.
신뢰성: 네트워크 불안정이나 에이전트의 일시적 장애 상황에서 메시지가 유실되지 않아야 합니다.

2. 프로토콜 설계: 요청, 작업, 완료

이러한 문제를 해결하기 위해 우리는 Task-Based Messaging Protocol을 설계했습니다. 이 프로토콜은 MCP 표준 메시지 형식을 확장하여 사용하며, 크게 세 가지 주요 메시지 타입으로 구성됩니다.

TaskRequest: 작업의 시작. 에이전트 A가 B에게 특정 작업을 의임할 때 사용합니다.
TaskUpdate: 진행 상황 보고. 장기 실행 작업 시 중간 결과를 전달합니다.
TaskResult: 최종 결과. 성공 또는 실패 여부와 함께 데이터를 반환합니다.

3. Rust로 구현하는 ZeroClaw 통신 계층

ZeroClaw는 Rust의 강력한 타입 시스템과 비동기 런타임(Tokio)을 사용하여 이 프로토콜을 타입 안전하게 구현합니다. 아래는 간소화된 메시지 정의와 핸들러 구조입니다.

3.1. 메시지 정의 (JSON-RPC 기반)

MCP는 기본적으로 JSON-RPC 2.0을 기반으로 하므로, 이를 준수하면서 에이전트 간 통신에 필요한 메타데이터를 포함합니다.

// src/protocol/message.rs

use serde::{Deserialize, Serialize};
use uuid::Uuid;

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentMessage {
 pub id: String, // 메시지 고유 ID
 pub sender: String, // 발신 에이전트 ID
 pub target: String, // 수신 에이전트 ID
 pub timestamp: i64, // 타임스탬프
 pub payload: Payload, // 실제 데이터
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type")]
pub enum Payload {
 #[serde(rename = "task/request")]
 TaskRequest {
 task_id: Uuid,
 description: String,
 context: serde_json::Value,
 },
 
 #[serde(rename = "task/result")]
 TaskResult {
 task_id: Uuid,
 status: TaskStatus,
 data: Option<serde_json::Value>,
 },
 
 #[serde(rename = "system/ping")]
 SystemPing,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum TaskStatus {
 Success,
 Failure(String), // 실패 사유
 Pending,
}

3.2. 에이전트 런타임 구조

ZeroClaw의 에이전트는 각각 독립적인 Tokio 태스크로 실행됩니다. 에이전트 간 통신은 채널(Channel)을 통해 이루어지며, 중재자(Mediator)가 이를 라우팅합니다.

// src/runtime/agent.rs

use tokio::sync::mpsc;
use crate::protocol::message::{AgentMessage, Payload};

pub struct Agent {
 id: String,
 tx: mpsc::Sender<AgentMessage>, // 외부로 메시지를 보내는 송신자
 rx: mpsc::Receiver<AgentMessage>, // 내부에서 메시지를 받는 수신자
}

impl Agent {
 pub fn new(id: String) -> Self {
 let (tx, rx) = mpsc::channel(100);
 Self { id, tx, rx }
 }

 // 에이전트의 메인 실행 루프
 pub async fn run(mut self) {
 println!("[{}] Agent started", self.id);
 while let Some(msg) = self.rx.recv().await {
 if let Err(e) = self.handle_message(msg).await {
 eprintln!("[{}] Error handling message: {:?}", self.id, e);
 }
 }
 }

 async fn handle_message(&self, msg: AgentMessage) -> Result<(), Box<dyn std::error::Error>> {
 match msg.payload {
 Payload::SystemPing => {
 // 핑에 퐁으로 응답하는 로직
 // 실제 환경에서는 클라이언트의 tx를 사용해 응답을 보냄
 println!("[{}] Received Ping from {}", self.id, msg.sender);
 }
 Payload::TaskRequest { task_id, description, context } => {
 println!("[{}] Received Task {}: {}", self.id, task_id, description);
 // 여기에 LLM 호출이나 도구 실행 로직이 들어갑니다.
 
 // 예: 결과 반환 로직 (가상)
 // self.send_result(task_id, ...).await;
 }
 _ => {
 println!("[{}] Received unhandled message type", self.id);
 }
 }
 Ok(())
 }
}

4. 결론 및 다음 단계

위와 같이 구조화된 통신 계층을 통해, 우리는 단순한 텍스트 생성을 넘어 작업(Task) 단위의 협업이 가능한 아키텍처를 갖추게 됩니다. [ZeroClaw] 프로젝트의 2026 상반기 목표인 ‘고성능 에이전트 런타임’은 이러한 견고한 기초 위에 LLM 추론 로직을 통합함으로써 완성될 것입니다.

다음 포스트에서는 이 통신 프로토콜 위에서 실제로 LLM을 호출하여 도구(Tool)를 사용하는 ‘플래너(Planner)’ 에이전트의 구현细节을 다루겠습니다.

참고자료

[ZeroClaw] 멀티 에이전트 아키텍처 설계안
[Claude Code] 팀 에이전트 통신 아키텍처
Rust Tokio Documentation

Rust와 ZeroClaw로 구축하는 초경량 MCP 서버: 효율적인 에이전트 통신 구조

Wed, 10 Jun 2026 09:00:57 +0900

Rust와 ZeroClaw로 구축하는 초경량 MCP 서버: 효율적인 에이전트 통신 구조

최근 ‘Grit: Rewriting Git in Rust with Agents’ 기사에서도 확인할 수 있듯, Rust 언어는 에이전트 시스템의 런타임으로서 그 가치를 재평가받고 있습니다. 우리 팀의 ZeroClaw 런타임 역시 고성능과 안전성을 목표로 개발 중이며, 이와 연계하여 MCP(Model Context Protocol) 서버를 어떻게 효율적으로 구축할지에 대한 고민이 깊어지고 있습니다.

기존의 무거운 Python 기반 서버나 복잡한 Node.js 아키텍처 대신, Rust의 병행성(concurrency)과 저지연성(low-latency)을 활용한 초경량 MCP 서버 구조를 제안합니다. 이 글에서는 ZeroClaw 아키텍처의 장점을 살리면서, 실무에서 바로 적용 가능한 Rust 기반 MCP 서버 예제를 작성해 보겠습니다.

1. ZeroClaw 아키텍처와 MCP의 결합

ZeroClaw 프로젝트의 핵심은 파일 기반 아키텍처 설계와 멀티 에이전트 통신 프로토콜의 효율화입니다. MCP 서버를 구축할 때 가장 중요한 점은 데이터 직렬화/역직렬화(Serde)의 오버헤드를 줄이는 것과 비동기 요청 처리입니다.

Rust의 tokio 런타임과 serde_json을 활용하면, JSON 기반 MCP 프로토콜을 나노초(nanosecond) 단위의 오버헤드로 처리할 수 있습니다. 이는 특히 대규모 로그 처리나 모니터링 시스템([blog-api-server] 경험)에서 필수적인 요소입니다.

2. 핵심 구조: 비동기 요청 라우팅

복잡한 의존성 없이, 표준 라이브러리와 몇 가지 필수 크레이트(crate)만으로 MCP 서버의 뼈대를 만들어 보겠습니다. 이 구조는 ZeroClaw의 에이전트 간 통신 패턴을 따르며, 단일 스레드가 아닌 멀티스레드 환경에서의 안전성을 보장합니다.

2.1. Cargo.toml 설정

먼저 프로젝트 의존성을 추가합니다.

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
hyper = { version = "0.14", features = ["full"] }

2.2. MCP 메시지 구조 정의

MCP는 기본적으로 JSON-RPC와 유사한 구조를 가집니다. 에이전트 간 통신 시 데이터의 무결성을 보장하기 위해 Rust의 타입 시스템을 적극 활용합니다.

// src/types.rs
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
pub struct MCPRequest {
 pub jsonrpc: String, // 항상 "2.0"
 pub id: Option<String>,
 pub method: String,
 pub params: Option<serde_json::Value>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct MCPResponse {
 pub jsonrpc: String,
 pub id: Option<String>,
 pub result: Option<serde_json::Value>,
 pub error: Option<MCPError>,
}

#[derive(Debug, Serialize, Deserialize)]
pub struct MCPError {
 pub code: i32,
 pub message: String,
}

3. 경량화된 요청 핸들러 구현

ZeroClaw의 철학처럼 불필요한 추상화 계층을 제거하고, 직관적인 핸들러를 작성합니다. 아래 코드는 들어오는 요청을 파싱하고, 메서드 이름에 따라 적절한 처리를 수행한 뒤 응답을 반환하는 흐름입니다.

// src/main.rs
use hyper::{Body, Request, Response, Server, StatusCode};
use hyper::service::{make_service_fn, service_fn};
use std::convert::Infallible;
use types::{MCPRequest, MCPResponse};

async fn handle_mcp_request(req: MCPRequest) -> MCPResponse {
 match req.method.as_str() {
 "tools/list" => {
 // 도구 목록 반환 예시
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(serde_json::json!({
 "tools": [
 { "name": "get_weather", "description": "Get current weather" },
 { "name": "calculate", "description": "Perform math operations" }
 ]
 })),
 error: None,
 }
 },
 "tools/call" => {
 // 실제 도구 실행 로직 (ZeroClaw Agent 호출 등)
 // params 검증 로직이 여기에 들어갑니다.
 println!("Agent executing with params: {:?}", req.params);
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(serde_json::json!({"status": "success"})),
 error: None,
 }
 },
 _ => {
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: None,
 error: Some(types::MCPError {
 code: -32601,
 message: "Method not found".to_string(),
 }),
 }
 }
 }
}

async fn http_handler(req: Request<Body>) -> Result<Response<Body>, Infallible> {
 let whole_body = match hyper::body::to_bytes(req.into_body()).await {
 Ok(bytes) => bytes,
 Err(e) => {
 eprintln!("Error reading body: {}", e);
 return Ok(Response::builder()
 .status(StatusCode::INTERNAL_SERVER_ERROR)
 .body(Body::from("Internal Server Error"))
 .unwrap());
 }
 };

 // JSON 파싱
 let mcp_req: MCPRequest = match serde_json::from_slice(&whole_body) {
 Ok(req) => req,
 Err(_) => {
 return Ok(Response::builder()
 .status(StatusCode::BAD_REQUEST)
 .body(Body::from("Invalid JSON"))
 .unwrap());
 }
 };

 // MCP 로직 처리
 let mcp_res = handle_mcp_request(mcp_req).await;
 
 // 응답 변환
 let json_body = match serde_json::to_string(&mcp_res) {
 Ok(json) => json,
 Err(_) => "{}".to_string(),
 };

 Ok(Response::new(Body::from(json_body)))
}

#[tokio::main]
async fn main() {
 let make_svc = make_service_fn(|_conn| {
 async { Ok::<_, Infallible>(service_fn(http_handler)) }
 });

 let addr = ([127, 0, 0, 1], 3000).into();
 let server = Server::bind(&addr).serve(make_svc);

 println!("MCP Server listening on http://{}", addr);

 if let Err(e) = server.await {
 eprintln!("Server error: {}", e);
 }
}

4. 고급 최적화: ZeroClow 통합

위 코드는 기본적인 HTTP 서버입니다. ZeroClaw의 진짜 힘을 끌어내기 위해서는 이 서버를 에이전트 런타임 내부의 테스크(Task)로 통합해야 합니다.

채널 기반 통신: HTTP 요청을 직접 처리하는 대신, tokio::sync::mpsc 채널을 통해 요청을 내부 에이전트 큐로 보냅니다. 이는 ZeroClaw의 비동기 메시지 패싱 구조와 일치합니다.
Stealable Work Queue: 다중 코어 환경에서 에이전트가 작업을 효율적으로 분배받을 수 있도록, 작업 큐를 구현합니다.

5. 결론

Rust로 MCP 서버를 작성하면, ZeroClaw와 같은 고성능 런타임의 이점을 십분 활용할 수 있습니다. 단순히 언어를 바꾸는 것이 아니라, 에이전트 간 통신 오버헤드를 최소화하는 아키텍처 설계가 핵심입니다. 위 코드를 베이스로 여러분의 프로젝트에 맞는 에이전트 로직을 추가해 보시기 바랍니다.

참고: 이 코드는 blog-api-server의 로깅 개선 작업에서 얻은 경험을 바탕으로, 에러 처리와 로깅 부분을 간소화하여 실용성에 집중했습니다.

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

Tue, 09 Jun 2026 09:00:48 +0900

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

최근 AI 에이전트 생태계에서 **Model Context Protocol (MCP)**는 표준 인터페이스로 자리 잡고 있습니다. 저희 팀의 ZeroClaw 프로젝트와 같은 고성능 런타임 환경에서 MCP 서버를 구축할 때, Rust의 안전성과 속도는 필수적인 요소입니다. 이번 포스트에서는 실무적으로 바로 적용할 수 있는 Rust 기반 MCP 서버의 구조를 설계하고, 실제 코드를 통해 구현 방법을 살펴보겠습니다.

1. MCP 서버의 핵심 요구사항

AI 모델이 데이터에 접근하기 위해 MCP 서버는 다음 세 가지 핵심 기능을 수행해야 합니다.

리소스 발견 (Discovery): 모델이 사용할 수 있는 데이터(파일, API 등)의 목록을 제공
리소스 접근 (Access): 요청받은 데이터의 실제 내용을 효율적으로 반환
도구 실행 (Tool Execution): 모델의 지시에 따라 시스템 내부에서 동작을 수행

Rust는 특히 Zero-cost abstractions와 강력한 비동기 런타임(tokio) 덕분에 대규모 요청을 처리하는 MCP 서버에 최적입니다.

2. 아키텍처 설계: ZeroClaw 스타일

단순한 RPC 호출을 넘어, 우리는 이벤트 기반 아키텍처를 채택하여 확장성을 확보합니다. 구조는 다음과 같습니다.

Transport Layer: stdio 또는 WebSocket을 통한 메시지 송수신 (JSON-RPC 2.0)
Handler Layer: 요청을 라우팅하고 검증하는 계층
Core Logic: 실제 비즈니스 로직 (파일 시스템 접근, DB 조회 등)

3. 실전 코드 예제

가장 대중적인 트랜스포트인 stdio(표준 입출력) 기반의 간단한 MCP 서버를 작성해 보겠습니다. 이 예제는 LLM이 로컬 파일 시스템의 로그를 읽을 수 있게 해주는 기능을 구현합니다.

3.1. 의존성 설정 (`Cargo.toml`)

Rust의 생태계를 활용하기 위해 직렬화와 비동기 처리를 위한 크레이트를 추가합니다.

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
async-trait = "0.1"

3.2. 핸들러 트레이트 정의

MCP 표준에 맞춰 Tool과 Resource를 처리할 공통 인터페이스를 정의합니다. 이는 추후 ZeroClaw 런타임에 통합하기 쉽게 만듭니다.

use serde_json::Value;
use async_trait::async_trait;

#[async_trait]
pub trait McpHandler {
 async fn handle(&self, params: Value) -> Result<Value, String>;
 fn name(&self) -> &str;
}

3.3. 로그 읽기 도구 구현

이제 실제로 서버 내부의 파일을 읽어서 AI 모델에 전달하는 로직을 구현합니다.

use std::fs;
use std::path::Path;

pub struct LogReaderTool;

#[async_trait]
impl McpHandler for LogReaderTool {
 fn name(&self) -> &str {
 "read_logs"
 }

 async fn handle(&self, params: Value) -> Result<Value, String> {
 // 1. 파라미터 검증 및 추출
 let file_path = params.get("path")
 .and_then(|v| v.as_str())
 .ok_or("Missing 'path' parameter".to_string())?;

 // 2. 보상: 경로 조작 방지 (SandBoxing)
 // 실제 운영 환경에서는 chroot나 전용 가상 디렉토리를 사용해야 합니다.
 if !file_path.ends_with(".log") {
 return Err("Only .log files are allowed".into());
 }

 // 3. 파일 시스템 접근 (동기식 I/O를 비동기 컨텍스트로 래핑)
 let content = fs::read_to_string(file_path)
 .map_err(|e| format!("Failed to read file: {}", e))?;

 // 4. 결과 포맷팅
 Ok(serde_json::json!({
 "status": "success",
 "content": content,
 "lines": content.lines().count()
 }))
 }
}

3.4. 메인 루프 및 JSON-RPC 서버

LLM과의 통신을 담당하는 메인 루프입니다. 표준 입력에서 JSON-RPC 요청을 읽고, 처리 결과를 표준 출력으로 내보냅니다.

use tokio::io::{AsyncBufReadExt, BufReader};
use tokio::io::{AsyncWriteExt, BufWriter};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
 let stdin = tokio::io::stdin();
 let stdout = tokio::io::stdout();
 let mut reader = BufReader::new(stdin).lines();
 let mut writer = BufWriter::new(stdout);

 let tool = Arc::new(LogReaderTool);

 // LLM이나 호스트로부터 요청이 들어올 때마다 처리
 while let Ok(Some(line)) = reader.next_line().await {
 if line.trim().is_empty() { continue; }

 if let Ok(json_req) = serde_json::from_str::<Value>(&line) {
 let method = json_req.get("method").and_then(|m| m.as_str()).unwrap_or("");
 let id = json_req.get("id");

 if method == "tools/call" || method == "tools/invoke" {
 let params = json_req.get("params").cloned().unwrap_or(Value::Null);
 
 // 비즈니스 로직 실행
 let result = tool.handle(params).await;
 
 let response = match result {
 Ok(data) => serde_json::json!({
 "jsonrpc": "2.0",
 "id": id,
 "result": data
 }),
 Err(e) => serde_json::json!({
 "jsonrpc": "2.0",
 "id": id,
 "error": { "code": -32000, "message": e }
 })
 };
 
 writer.write_all(response.to_string().as_bytes()).await?;
 writer.write_all(b"\n").await?;
 writer.flush().await?;
 }
 }
 }
 Ok(())
}

4. 최적화 및 배포 고려사항

위 코드는 기본적인 골격이지만, ZeroClaw와 같은 프로덕션 환경에서는 다음 사항을 고려해야 합니다.

에러 타입 구체화: String 대신 구체적인 thiserror나 anyhow 기반의 에러 타입을 사용하여 디버깅을 용이하게 하세요.
보안 샌드박싱: std::fs 대신 가상 파일 시스템(VFS) 라이브러리를 사용하여, 에이전트가 시스템 전체에 접근하는 것을 막아야 합니다.
Graceful Shutdown: tokio의 signal 모듈을 활용하여 인터럽트 신호(SIGTERM)를 처리하고, 진행 중인 파일 작업을 안전하게 종료해야 합니다.

5. 결론

Rust는 타입 안전성과 메모리 관리 능력 덕분에 신뢰할 수 있는 MCP 서버를 구축하는 데 최적의 언어입니다. 위 코드를 바탕으로 blog-api-server나 모니터링 시스템과 연동한다면, AI 모델이 직접 시스템 로그를 분석하고 패치를 제안하는 완전한 자동화 사이클을 구축할 수 있습니다.

다음 포스트에서는 이 MCP 서버를 ZeroClaw 런타임 위에서 어떻게 에이전트화하고, 다른 서비스와 통신하는지 다루겠습니다.

MCP 서버 성능 최적화: Rust로 구축하는 초고속 처리 파이프라인

Wed, 03 Jun 2026 09:00:50 +0900

MCP 서버 성능 최적화: Rust로 구축하는 초고속 처리 파이프라인

최근 LLM(Large Language Model)을 활용한 에이전트 시스템이 개발 생태계의 핫한 이슈가 되면서, 이를 지원하는 인프라인 MCP(Model Context Protocol) 서버의 중요성이 커지고 있습니다. 이전 포스트에서 ZeroClaw와 같은 고성능 런타임을 언급하며 멀티 에이전트 아키텍처를 다루었지만, 오늘은 MCP 서버 자체의 **처리량(Throughput)과 대기 시간(Latency)**을 극적으로 개선하는 Rust 기반의 최적화 기법을 집중적으로 다루고자 합니다.

단순히 “빠르다"는 말만으로는 부족합니다. 수천 개의 Tool Call이 동시에 들어오는 상황에서 서버가 얼마나 효율적으로 리소스를 관리하는지가 핵심입니다. 특히 최근 트렌드인 AI 에이전트들이 RSS 피드나 실시간 데이터를 수집할 때, I/O 바운드 작업이 병목이 되는 경우가 많습니다.

이 글에서는 Rust의 강력한 비동기 런타임인 Tokio를 활용하여 병목 지점을 제거하고, 안전하면서도 빠른 코드를 작성하는 구체적인 방법을 소개합니다.

1. 문제 정의: 단일 스레드 병목

기본적으로 Python이나 Node.js로 작성된 간단한 MCP 서버는 싱글 스레드 이벤트 루프에 의존하는 경우가 많습니다. 이는 I/O 작업이 많을 때 유리하지만, 데이터 가공이나 복잡한 로직이 포함된 MCP 툴을 처리할 때 CPU 코어를 하나만 사용하기 때문에 한계가 명확합니다.

예를 들어, 블로그 자동화 시스템을 구축할 때 대량의 이미지를 처리하거나 로그를 파싱하는 과정에서 CPU 점유율이 100%에 도달하면 다른 요청은 대기열에 쌓이게 됩니다. 우리는 이를 멀티 스레드 비동기 처리로 해결해야 합니다.

2. Rust와 Tokio를 활용한 비동기 처리

Rust는 ‘Zero-cost abstractions’를 통해 안전성과 성능을 모두 잡을 수 있습니다. MCP 서버의 핵심 로직인 툴 실행(Tool Execution) 부분을 tokio::spawn을 이용해 병렬화해 보겠습니다.

기본 설정 (Cargo.toml)

먼저 의존성 파일에 Tokio를 추가합니다.

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

비동기 핸들러 구현 예제

아래 코드는 들어오는 요청을 별도의 태스크(Task)로 분리하여 처리하는 간단한 MCP 서버의 핸들러 구조입니다.

use tokio::net::TcpListener;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use serde::{Deserialize, Serialize};
use std::sync::Arc;

// MCP 요청 메시지 구조 정의
#[derive(Debug, Deserialize)]
struct McpRequest {
 id: String,
 method: String,
 params: serde_json::Value,
}

#[derive(Debug, Serialize)]
struct McpResponse {
 id: String,
 result: serde_json::Value,
}

// 무거운 작업을 시뮬레이션하는 함수
async fn process_heavy_tool(params: serde_json::Value) -> Result<String, String> {
 // 실제 환경에서는 여기서 DB 조회나 파일 I/O 발생
 // tokio::time::sleep을 통해 비동기 대기 시뮬레이션
 tokio::time::sleep(tokio::time::Duration::from_secs(2)).await;
 Ok(format!("Processed: {}", params))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
 let listener = TcpListener::bind("127.0.0.1:8080").await?;
 println!("MCP Server listening on {}", listener.local_addr()?);

 loop {
 let (mut socket, _) = listener.accept().await?;

 // 연결이 들어올 때마다 새로운 태스크 생성 (병렬 처리)
 tokio::spawn(async move {
 let mut buf = [0; 1024];

 loop {
 let n = match socket.read(&mut buf).await {
 Ok(n) if n == 0 => return, // 연결 종료
 Ok(n) => n,
 Err(e) => {
 eprintln!("Failed to read from socket; err = {:?}", e);
 return;
 }
 };

 let req_str = String::from_utf8_lossy(&buf[0..n]);
 
 // JSON 파싱 및 처리 로직 (에러 처리 생략)
 if let Ok(req) = serde_json::from_str::<McpRequest>(&req_str) {
 let req_id = req.id.clone();
 
 // 핵심: 비동기 함수를 spawn하여 블로킹 없이 처리
 let handle = tokio::spawn(async move {
 process_heavy_tool(req.params).await
 });

 // 결과 대기 및 응답 (실제 구현에선 채널 사용 권장)
 if let Ok(Ok(result)) = handle.await {
 let resp = McpResponse {
 id: req_id,
 result: serde_json::json!(result),
 };
 
 if let Ok(serialized) = serde_json::to_string(&resp) {
 let _ = socket.write_all(serialized.as_bytes()).await;
 }
 }
 }
 }
 });
 }
}

이 코드의 핵심은 tokio::spawn을 사용하여 각 요청이 메인 루프를 차단하지 않고 독립적으로 실행된다는 점입니다.

3. 스트리밍(Streaming)을 통한 메모리 최적화

대용량 파일 처리나 로그 전송 시, 모든 데이터를 메모리(RAM)에 올리는 것은 치명적입니다. Rust의 Stream을 활용하면 데이터를 청크(Chunk) 단위로 처리하여 메모리 사용량을 일정하게 유지할 수 있습니다.

특히 앞서 언급된 [blog-api-server] 로깅 개선 사항이나 Cloud Monitor 관련 작업에서 유용하게 쓰일 수 있습니다.

use futures::stream::{Stream, StreamExt};
use std::pin::Pin;

// 가상의 로그 데이터 생성 스트림
fn log_stream() -> Pin<Box<dyn Stream<Item = String> + Send>> {
 Box::pin(async_stream::stream! {
 for i in 0..1000 {
 yield format!("Log entry #{}\n", i);
 tokio::time::sleep(tokio::time::Duration::from_millis(10)).await;
 }
 })
}

// 스트림 처리 예시
async fn process_logs() {
 let mut stream = log_stream();
 while let Some(log_entry) = stream.next().await {
 // 실시간으로 한 줄씩 처리 (파일 쓰기 or 전송)
 println!("Processing: {}", log_entry);
 }
}

4. 결론: ZeroClaw를 향하여

우리가 목표로 하는 ZeroClaw 런타임은 이러한 비동기 처리와 메모리 안전성을 기본으로 제공해야 합니다. 단순히 기존 파이썬 스크립트를 Rust로 포팅하는 것을 넘어, Tokio의 스케줄링과 Zero-copy 직렬화를 적극 활용해야만 수천 개의 에이전트가 동시에 통신하는 환경을 견딜 수 있습니다.

다음 포스트에서는 이러한 고성능 서버 위에서 동작하는 에이전트 간 통신 프로토콜을 설계하는 방법에 대해 다루겠습니다.

Rust로 구축하는 ZeroClaw: LLM 기반 멀티 에이전트 런타임 아키텍처

Mon, 25 May 2026 09:00:53 +0900

Rust로 구축하는 ZeroClaw: LLM 기반 멀티 에이전트 런타임 아키텍처

최근 LLM(Large Language Model)을 활용한 자동화와 에이전트 시스템에 대한 관심이 뜨겁습니다. 하지만 단일 에이전트로 복잡한 작업을 처리하는 데에는 한계가 있으며, 이를 해결하기 위해 **멀티 에이전트 시스템(Multi-Agent System)**이 주목받고 있습니다. 이번 포스트에서는 고성능과 안정성을 위해 Rust로 작성된 에이전트 런타임인 ZeroClaw의 아키텍처를 소개하고, 실제로 에이전트 간 통신을 어떻게 구조화하는지 살펴보겠습니다.

1. 왜 Rust인가? (Performance & Safety)

LLM 애플리케이션은 대부분 Python으로 작성되곤 합니다. 하지만 여러 에이전트가 동시에 실행되고 각자 독립된 메모리 공간이나 파일 시스템을 제어해야 하는 ‘런타임’ 환경에서는 Rust의 강력한 병렬 처리 능력과 메모리 안전성이 큰 무기가 됩니다.

특히, 최근 Hacker News에서 논의된 것처럼 “LLM 에이전트의 백엔드 코드 생성 취약점(Constraint Decay)” 문제가 대두되고 있습니다. LLM이 생성한 코드가 의도치 않게 시스템 제약을 무너뜨리는 상황에서, Rust의 타입 시스템과 소유권(Ownership) 모델은 런타임 차원에서 안전망을 제공할 수 있습니다.

2. ZeroClaw의 핵심 아키텍처

ZeroClaw는 단순한 LLM 래퍼가 아니라, 에이전트의 생명주기를 관리하고 메시지를 중계하는 런타임 엔진입니다.

2.1. 파일 기반 상태 관리 (File-Based State Management)

복잡한 데이터베이스 없이 에이전트의 상태와 컨텍스트를 파일 시스템에 기반하여 관리하는 아키텍처를 채택했습니다. 이는 휴대성(Portability)과 디버깅 용이성을 높여줍니다.

// 에이전트 상태를 저장하는 구조체 예시
#[derive(Serialize, Deserialize, Debug)]
pub struct AgentState {
 pub id: String,
 pub role: AgentRole,
 pub status: ExecutionStatus,
 pub last_heartbeat: u64,
}

impl AgentState {
 pub fn save_to_file(&self, path: &Path) -> io::Result<()> {
 let json = serde_json::to_string_pretty(self)?;
 fs::write(path, json)?;
 Ok(())
 }
}

이 접근 방식은 Multi-Agent: 파일 기반 아키텍처 설계 논의에서 언급된 바와 같이, 각 에이전트가 자신의 상태를 투명하게 기록하게 하여 시스템 전체의 예측 가능성을 높입니다.

2.2. 이벤트 기반 통신 (Event-Driven Communication)

ZeroClaw의 에이전트들은 서로 직접 호출하지 않고, 중앙의 **이벤트 버스(Event Bus)**나 Pub/Sub 메커니즘을 통해 통신합니다. 이는 결합도(Coupling)를 낮추고 확장성을 확보합니다.

// 통신 프로토콜 메시지 정의
#[derive(Debug, Clone)]
pub enum AgentMessage {
 TaskRequest { task_id: String, payload: String },
 TaskResponse { task_id: String, result: String },
 StatusUpdate { agent_id: String, status: String },
}

// 간단한 채널 기반 메시지 라우터 (tokio::sync::mpsc 사용)
pub struct MessageRouter {
 // sender: HashMap<AgentId, Sender<AgentMessage>>
 // 실제 구현 시 에이전트별 채널을 관리
}

이러한 구조는 Claude Code 팀 에이전트 통신 아키텍처나 멀티 에이전트 통신 프로토콜 설계에서 고민되었던 ‘메시지 큐의 신뢰성’ 이슈를 Rust의 강력한 비동기 런타임(tokio)으로 해결하는 기반이 됩니다.

3. MCP(Model Context Protocol)와의 연동

ZeroClaw는 MCP 서버와 클라이언트 역할을 수행하여 외부 도구(예: 블로그 API, Discord Gateway)와 연동됩니다. 최근 blog-api-server에 추가된 언어 파라미터나 로깅 개선 사항들은 ZeroClaw 에이전트가 외부 시스템과 상호작용할 때 컨텍스트를 잃지 않도록 돕습니다.

에이전트가 MCP 도구를 호출하는 과정을 안전하게 래핑(Wrapping)하는 것은 중요합니다.

// MCP 도구 호출을 위한 안전한 래퍼
pub async fn invoke_mcp_tool(tool_name: &str, params: serde_json::Value) -> Result<String, AgentError> {
 // 1. 파라미터 검증 (Validation)
 if !validate_params(tool_name, &params) {
 return Err(AgentError::InvalidInput);
 }

 // 2. 실제 호출 (HTTP or IPC)
 let response = reqwest::Client::new()
 .post("http://localhost:8080/mcp/call")
 .json(&json!({
 "tool": tool_name,
 "args": params
 }))
 .send()
 .await?;

 // 3. 응답 파싱 및 로깅
 tracing::info!("MCP Tool {} called successfully", tool_name);
 Ok(response.text().await?)
}

4. 결론: 2026 상반기 발전 방향

ZeroClaw는 단순한 실험적 프로젝트를 넘어, 2026 상반기 발전방향 회의록에서 언급된 바와 같이 ‘고성능 에이전트 런타임’으로 진화하고 있습니다.

Rust의 성능을 바탕으로 LLM의 생성성(Creativity)과 시스템의 안전성(Safety)을 동시에 확보하는 것이 목표입니다. 특히, 최근 트렌드인 DeepSeek와 같은 효율적인 모델을 통합하여 비용 효율성까지 개선할 계획입니다.

다음 포스트에서는 ZeroClaw 에이전트가 실제로 코드를 생성하고 배포하는 CI/CD 파이프라인 연동 사례를 다루겠습니다.

참고 링크

MCP(Model Context Protocol) 기반 멀티 에이전트 시스템 설계 및 구현 가이드

Sat, 23 May 2026 09:01:19 +0900

MCP(Model Context Protocol) 기반 멀티 에이전트 시스템 설계 및 구현 가이드

최근 생성형 AI 도메인에서 단일 LLM(Large Language Model)의 한계를 극복하기 위해 **멀티 에이전트 시스템(Multi-Agent System)**이 주목받고 있습니다. 특히, 에이전트 간의 표준화된 통신을 위한 **MCP(Model Context Protocol)**가 등장하면서, 확장 가능하고 모듈화된 아키텍처를 설계하는 것이 필수적이 되었습니다.

본 포스트에서는 ZeroClaw와 같은 고성능 에이전트 런타임 환경에서 MCP를 활용해 효율적인 멀티 에이전트 아키텍처를 설계하고 구현하는 방법을 살펴봅니다. 독자가 바로 적용할 수 있도록 아키텍처 설계 원칙과 실제 코드 예제를 포함했습니다.

1. MCP 기반 멀티 에이전트 아키텍처 설계

멀티 에이전트 시스템을 구축할 때 가장 중요한 것은 결합도(Coupling)를 낮추고 응집도(Cohesion)를 높이는 것입니다. MCP는 이를 달성하기 위해 클라이언트-서버 모델을 채택하여, 각 에이전트나 도구가 독립적인 서버로 동작하며 표준 프로토콜(JSON-RPC 2.0 기반)을 통해 통신하도록 합니다.

핵심 설계 원칙

표준화된 인터페이스 (Standardized Interface): 모든 에이전트는 MCP 표준을 준수하여 tools, resources, prompts를 노출해야 합니다.
비동기 통신 (Asynchronous Communication): 작업 수행 시간이 긴 에이전트(예: 파일 처리, 웹 스크래핑)를 위해 비동기 메시지 큐를 활용해야 합니다.
상태 비저장 (Stateless): 에이전트 서버는 가능한 한 상태 비저장으로 설계하여 수평 확장(Scale-out)이 용이하게 만들어야 합니다.

아키텍처 다이어그램 (개념적)

[User/Client LLM] <--> [MCP Gateway (Orchestrator)]
 | | |
 v v v
 [Blog Server] [Discord MCP] [Cloud Monitor]
 (Rust/TS) (Gateway) (Agent)

이 구조에서 **Gateway(오케스트레이터)**는 사용자의 요청을 분석하여 적절한 MCP 서버(에이전트)에게 작업을 위임하고, 결과를 취합하여 다시 사용자에게 전달하는 역할을 수행합니다.

2. MCP 서버 구현: Rust로 가벼운 에이전트 만들기

blog-api-server나 ZeroClaw 환경에서 고성능을 발휘하기 위해 Rust로 간단한 MCP 서버를 구현해 보겠습니다. 이 서버는 현재 시간을 반환하는 간단한 도구를 제공합니다.

의존성 설정 (Cargo.toml)

Rust의 강력한 비동기 런타임인 tokio와 JSON 처리를 위한 serde, 그리고 MCP 통신을 위한 hyper 또는 jsonrpc를 사용합니다.

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
hyper = { version = "0.14", features = ["server", "http1"] }

MCP 서버 코드 예제

다음은 STDIN/STDOUT을 통해 통신하는 표준 MCP 서버의 뼈대를 간소화하여 구현한 것입니다.

use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use std::io::{self, BufRead, Write};

// MCP 요청/응답 구조체 정의
#[derive(Deserialize)]
struct MCPRequest {
 jsonrpc: String,
 id: Option<String>,
 method: String,
 params: Option<Value>,
}

#[derive(Serialize)]
struct MCPResponse {
 jsonrpc: String,
 id: Option<String>,
 result: Option<Value>,
 error: Option<Value>,
}

fn handle_request(req: MCPRequest) -> MCPResponse {
 match req.method.as_str() {
 "initialize" => {
 // 클라이언트가 서버의 능력을 확인할 때 호출
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(json!({
 "protocolVersion": "2024-11-05",
 "capabilities": {
 "tools": {}
 },
 "serverInfo": {
 "name": "my-rust-agent",
 "version": "0.1.0"
 }
 })),
 error: None,
 }
 }
 "tools/list" => {
 // 사용 가능한 도구 목록 반환
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(json!({
 "tools": [
 {
 "name": "get_current_time",
 "description": "Returns the current server time",
 "inputSchema": {
 "type": "object",
 "properties": {}
 }
 }
 ]
 })),
 error: None,
 }
 }
 "tools/call" => {
 // 실제 도구 실행 로직
 if let Some(params) = req.params {
 let tool_name = params["name"].as_str().unwrap_or("");
 if tool_name == "get_current_time" {
 return MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: Some(json!({
 "content": [
 {
 "type": "text",
 "text": format!("Current time: {}", chrono::Utc::now().to_rfc3339())
 }
 ]
 })),
 error: None,
 };
 }
 }
 // 에러 처리
 MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: None,
 error: Some(json!({
 "code": -32601,
 "message": "Tool not found"
 })),
 }
 }
 _ => MCPResponse {
 jsonrpc: "2.0".to_string(),
 id: req.id,
 result: None,
 error: Some(json!({ "code": -32601, "message": "Method not found" })),
 },
 }
}

fn main() {
 let stdin = io::stdin();
 let mut stdout = io::stdout();

 for line in stdin.lock().lines() {
 let line = line.unwrap();
 if let Ok(req) = serde_json::from_str::<MCPRequest>(&line) {
 let res = handle_request(req);
 let res_json = serde_json::to_string(&res).unwrap() + "\n";
 stdout.write_all(res_json.as_bytes()).unwrap();
 stdout.flush().unwrap();
 }
 }
}

이 코드는 MCP의 핵심인 initialize, tools/list, tools/call 메서드를 처리하여 LLM(예: Claude Code)이 이 에이전트를 도구로 인식하고 호출할 수 있게 합니다.

3. 에이전트 간 통신 및 데이터 동기화

ZeroClaw 아키텍처에서와 같이 여러 에이전트가 협업할 때는 데이터 공유가 중요합니다. 파일 기반 아키텍처(File-based architecture)를 사용하면 에이전트 간 결합도를 낮추면서 데이터를 주고받을 수 있습니다.

파일 기반 상태 공유 예시

에이전트 A가 데이터를 생성하고, 에이전트 B가 이를 소비하는 시나리오입니다.

에이전트 A (생산자): 계산 결과를 /tmp/shared/task_result.json에 저장합니다.
에이전트 B (소비자): MCP를 통해 file://tmp/shared/task_result.json 리소스를 읽거나, 별도의 read_file 도구를 호출합니다.

// 에이전트 A의 도구 호출 예시 (의사 코드)
fn save_result(data: &str) -> std::io::Result<()> {
 fs::write("/tmp/shared/task_result.json", data)?;
 Ok(())
}

이 방식은 메시지 큐가 복잡할 때 유용하며, blog-api-server의 로깅 시스템이나 모니터링 대시보드처럼 데이터를 지속적으로 추적해야 할 때 유효합니다.

4. 결론 및 발전 방향

MCP를 활용하면 복잡한 멀티 에이전트 시스템을 모듈화하고 유지보수하기 쉽게 만들 수 있습니다.

장점: 언어에 독립적인 인터페이스(Rust, TypeScript 등 혼용 가능), 도구의 재사용성, 표준화된 에러 처리.
고려사항: STDIN/STDOUT 통신 오버헤드, 대규모 트래픽 처리를 위한 Gateway의 부하 분산.

향후 ZeroClaw 런타임 내에서 이러한 MCP 서버들을 컨테이너화하여 필요에 따라 동적으로 스케일링(Scale-out)하는 환경을 구축하는 것이 목표입니다. 이를 통해 LLM이 단순한 챗봇을 넘어, 복잡한 작업을 자동화하는 지능형 에이전트 네트워크로 진화할 수 있습니다.

참고 자료

ZeroClaw 멀티 에이전트 시스템: Docker Compose를 활용한 로컬 테스트 환경 구축 가이드

Fri, 22 May 2026 09:01:21 +0900

ZeroClaw 멀티 에이전트 시스템: Docker Compose를 활용한 로컬 테스트 환경 구축 가이드

최근 [ZeroClaw] 프로젝트를 통해 고성능 Rust 에이전트 런타임과 멀티 에이전트 아키텍처를 설계하며, 개별 에이전트의 격리성과 통신 안정성의 중요성을 실감했습니다. 특히 **[blog-api-server]**와 같이 외부 API와 연동되는 MCP(Model Context Protocol) 클라이언트를 개발할 때, 로컬 환경에서 실제 운영 환경과 유사한 구조를 갖춰 테스트하는 것은 필수적입니다.

이번 포스트에서는 복잡한 멀티 에이전트 시스템을 로컬에서 쉽게 실행하고 디버깅할 수 있도록 Docker Compose를 활용한 테스트 환경 구축 방법을 공유합니다. 본 가이드는 Linux 환경(예: Ubuntu 16.04에서 FreeBSD로 이전 중인 서버 등)을 기반으로 하지만, Windows와 macOS에서도 동일하게 적용 가능합니다.

1. 아키텍처 설계: 마이크로서비스형 에이전트 구조

ZeroClaw의 핵심은 파일 기반 아키텍처와 게이트웨이 패턴을 차용한 통신 플랫폼입니다. 각 에이전트를 독립된 마이크로서비스로 간주하고, 이들을 Docker 컨테이너로 격리합니다.

구성 요소

Agent Container: Rust로 작성된 개별 에이전트 (ZeroClaw Runtime 기반)
Gateway Container: 외부 요청을 내부 에이전트로 라우팅하는 Nginx 또는 Envoy
Message Broker (Optional): RabbitMQ 또는 Redis (비동기 통신 필요 시)

2. Dockerfile 작성: Rust 에이전트 최적화

Rust 애플리케이션은 컴파일 시간이 오래 걸리므로, Multi-stage build를 사용하여 최종 이미지 크기를 줄이고 빌드 캐싱을 최적화해야 합니다.

# Dockerfile

# 1. Build Stage
FROM rust:1.75-slim as builder

WORKDIR /app

# 의존성 캐싱을 위해 Cargo.toml과 Cargo.lock 먼저 복사
COPY Cargo.toml Cargo.lock ./
RUN mkdir src && echo "fn main() {}" > src/main.rs
RUN cargo build --release && rm -rf src

# 실제 소스 코드 복사 및 빌드
COPY src ./src
RUN touch src/main.rs && cargo build --release

# 2. Runtime Stage
FROM debian:bookworm-slim

# 런타임 의존성 설치 (예: OpenSSL)
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# 빌드된 바이너리 복사
COPY --from=builder /app/target/release/zero-claw-agent /app/agent

# 실행 권한 부여
RUN chmod +x /app/agent

# 포트 노출 (MCP 통신용)
EXPOSE 8080

CMD ["/app/agent"]

3. Docker Compose로 오케스트레이션 구성

docker-compose.yml 파일을 사용하여 여러 에이전트와 네트워크를 정의합니다. 이를 통해 docker-compose up 하나로 전체 시스템을 기동할 수 있습니다.

# docker-compose.yml
version: '3.8'

services:
 # 메시지 브로커 (선택 사항, 통신 프로토콜에 따라 사용)
 redis:
 image: redis:7-alpine
 container_name: zero-claw-redis
 ports:
 - "6379:6379"
 networks:
 - zero-claw-net

 # Agent 1: Blog Handler (blog-api-server 역할)
 blog-agent:
 build:
 context: ./services/blog-agent
 dockerfile: Dockerfile
 container_name: zero-claw-blog-agent
 environment:
 - AGENT_ID=blog-agent-01
 - LOG_LEVEL=debug
 - MCP_SERVER_URL=http://mock-api:3000
 depends_on:
 - redis
 networks:
 - zero-claw-net
 restart: unless-stopped

 # Agent 2: Monitor (Cloud Monitor 역할)
 monitor-agent:
 build:
 context: ./services/monitor-agent
 dockerfile: Dockerfile
 container_name: zero-claw-monitor-agent
 environment:
 - AGENT_ID=monitor-agent-01
 depends_on:
 - redis
 networks:
 - zero-claw-net
 restart: unless-stopped

 # Gateway (Discord MCP Gateway 역할)
 gateway:
 image: nginx:alpine
 container_name: zero-claw-gateway
 ports:
 - "8080:80"
 volumes:
 - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
 depends_on:
 - blog-agent
 - monitor-agent
 networks:
 - zero-claw-net

networks:
 zero-claw-net:
 driver: bridge

4. 실행 및 테스트

이제 다음 명령어로 전체 시스템을 실행할 수 있습니다.

# 빌드 및 백그라운드 실행
docker-compose up --build -d

# 로그 확인 (특정 에이전트 집중 모니터링)
docker-compose logs -f blog-agent

# 트래픽 테스트 (Gateway를 통한 요청)
curl -X POST http://localhost:8080/api/v1/agent/blog/ping \
 -H "Content-Type: application/json" \
 -d '{"message": "Hello from ZeroClaw"}'

5. 마치며

이 구조를 활용하면 **[ZeroClaw]**의 멀티 에이전트 통신 프로토콜을 변경하거나, [LLM] 설정을 에이전트별로 주입하여 테스트하는 작업이 훨씬 수월해집니다. 특히 docker-compose.yml의 환경 변수만 수정하면 운영 환경 배포 스크립트와 로컬 테스트 환경을 거의 동일하게 유지할 수 있어 “It works on my machine” 문제를 해결할 수 있습니다.

다음 포스트에서는 이 환경에서 수집된 로그를 **[Loki]**나 **[Prometheus]**를 통해 시각화하는 방법을 다루어 보겠습니다.

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

Wed, 20 May 2026 09:00:35 +0900

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

최근 LLM(Large Language Model)을 활용한 에이전트 시스템이 급격히 발전하고 있습니다. Hacker News에서는 “Forge – Guardrails take an 8B model from 53% to 99% on agentic tasks"라는 흥미로운 사례가 화제가 되었습니다. 이는 모델의 파라미터 수를 늘리는 것보다, 적절한 **가드레일(Guardrails)**을 적용하는 것이 특정 작업의 성공률을 비약적으로 높일 수 있음을 시사합니다.

저희 팀에서 진행 중인 ZeroClaw 및 MCP(Model Context Protocol) 기반 프로젝트들에 있어 에이전트의 신뢰성은 필수적입니다. 이번 포스트에서는 오픈소스 가드레일 프레임워크인 Forge의 개념을 살펴보고, 이를 기존 MCP 아키텍처에 통합하여 에이전트의 안정성을 확보하는 구체적인 방법을 소개합니다.

문제 정의: 자율성의 딜레마

에이전트에게 자율성을 부여할수록 예상치 못한 행동을 할 위험이 커집니다. 예를 들어, 블로그 게시글을 생성하라는 MCP 요청이 있을 때, 에이전트가 시스템 명령어를 실행하거나 허용되지 않은 API를 호출하려 시도할 수 있습니다.

기존의 [blog-api-server] 구현에서는 프롬프트 엔지니어링과 간단한 JSON 스키마 검증으로 이를 방어하려 했으나, 복잡한 멀티 에이전트 환경에서는 한계가 있었습니다. 이를 해결하기 위해 입력과 출력을 사전에 필터링하는 L1 가드레일 레이어를 도입하기로 결정했습니다.

솔루션: Guardrails 패턴 적용

Forge가 보여주듯, 에이전트 작업의 성공률(53% → 99%)을 높이는 핵심은 실행 전 검증입니다. 우리는 에이전트가 LLM으로부터 응답을 받아 사용자에게 전달하거나 도구(Tool)를 실행하기 전, 중간 계층에서 이를 검증하는 구조를 설계했습니다.

아키텍처 개요

기존 MCP 클라이언트와 LLM 사이에 Validator 계층을 두어 다음을 수행합니다.

입력 검증 (Input Validation): 사용자의 요청이 시스템 정책을 위반하지 않는지 확인 (예: 공격적인 프롬프트 필터링).
출력 검증 (Output Validation): LLM이 생성한 JSON이나 함수 호출 인자가 스키마에 부합하는지 확인.

실전 코드 예제: Rust로 구현하는 안전장치

ZeroClaw의 Rust 환경에서 가벼운 출력 검증기를 구현해 보겠습니다. 복잡한 외부 라이브러리 없이, serde와 regex를 활용하여 LLM이 생성한 코드 실행 명령을 안전하게 감싸는 예제입니다.

1. 검증 로직 구현하기

먼저, 에이전트가 생성한 명령어가 안전한지 판별하는 간단한 검증기입니다.

use regex::Regex;
use serde::{Deserialize, Serialize};

// 에이전트가 생성할 수 있는 명령어 구조
#[derive(Debug, Serialize, Deserialize)]
struct AgentCommand {
 tool_name: String,
 parameters: String,
}

pub struct Guardrail;

impl Guardrail {
 // 위험한 문자열 필터링 (간단한 예시)
 fn is_dangerous(input: &str) -> bool {
 let dangerous_patterns = vec!["rm -rf", "sudo", "eval", "__import__"];
 dangerous_patterns.iter().any(|&pat| input.contains(pat))
 }

 // 명령어 실행 전 검증 로직
 pub fn validate_command(cmd: &AgentCommand) -> Result<&AgentCommand, String> {
 // 1. 도구 이름 화이트리스트 확인
 let allowed_tools = vec!["blog_post", "search", "read_file"];
 if !allowed_tools.contains(&cmd.tool_name.as_str()) {
 return Err(format!("허용되지 않은 도구 사용 시도: {}", cmd.tool_name));
 }

 // 2. 파라미터 내 위험 키워드 검사
 if Self::is_dangerous(&cmd.parameters) {
 return Err("파라미터에 잠재적으로 위험한 명령어가 포함되어 있습니다.".to_string());
 }

 // 3. 안전하다면 명령어 승인
 Ok(cmd)
 }
}

2. 에이전트 루프에 통합하기

이제 검증기를 MCP 서버의 요청 처리 루프에 연결합니다. 에이전트가 응답을 생성하면, 실제 시스템이 이를 실행하기 전에 Guardrail을 거쳐야 합니다.

// 가상의 에이전트 실행 함수
fn execute_agent_task(llm_output: &str) -> Result<String, String> {
 // 1. LLM 출력 파싱 (실제로는 JSON 파싱 등)
 // 여기서는 간단히 파싱되었다고 가정합니다.
 let command = AgentCommand {
 tool_name: "blog_post".to_string(),
 parameters: "title: 'Hello World'".to_string(),
 };

 // 2. 가드레일 통과 전
 println!("[System] LLM 응답 수신: {}", command.tool_name);

 // 3. 가드레일 검증 실행
 let safe_command = Guardrail::validate_command(&command)?;

 // 4. 검증된 명령어 실행
 println!("[System] 안전한 명령어 실행 중...");
 // 실제 도구 실행 로직 (예: 블로그 API 호출)
 Ok("게시글이 성공적으로 생성되었습니다.".to_string())
}

fn main() {
 // 정상 케이스
 match execute_agent_task("valid_response") {
 Ok(msg) => println!("성공: {}", msg),
 Err(e) => println!("차단됨: {}", e),
 }

 // 비정상 케이스 시뮬레이션
 let malicious_cmd = AgentCommand {
 tool_name: "system_shell".to_string(), // 화이트리스트에 없음
 parameters: "rm -rf /".to_string(),
 };

 match Guardrail::validate_command(&malicious_cmd) {
 Ok(_) => println!("오류: 해커가 침입했습니다!"),
 Err(e) => println!("보호됨: {}", e), // "보호됨: 허용되지 않은 도구 사용 시도: system_shell"
 }
}

효과 및 전망

이러한 L1 방어선을 구축함으로써 우리는 다음과 같은 이점을 얻을 수 있습니다.

안정성 향상: Forge 사례처럼 8B 모델도 충분히 안전하게 활용할 수 있어 추론 비용 절감.
투명성 확보: 에이전트가 왜 특정 작업을 거부했는지 로그를 통해 명확히 파악 가능.
유지보수성: 보안 정책이 변경되어도 Guardrail 모듈만 수정하면 됨.

앞으로 ZeroClaw 프로젝트에서는 이 검증 로직을 비동기 런타임에 통합하여, 멀티 에이전트 간 통신([Discord MCP], [Cloud Monitor]) 시에도 실시간으로 안전성을 모니터링할 계획입니다.

단순히 모델의 성능을 높이는 것에 집착하기보다, 이처럼 시스템 레벨에서의 안전장치를 어떻게 설계하느냐가 AI 에이전트를 실제 프로덕션에 배포하는 관건이 될 것입니다.

이 글은 ZeroClaw 및 MCP 관련 아키텍처 설계 문서들을 참고하여 작성되었습니다.

Agentic Workflow: MCP 도구를 활용한 블로그 자동화 파이프라인 구축

Tue, 19 May 2026 09:00:34 +0900

Agentic Workflow: MCP 도구를 활용한 블로그 자동화 파이프라인 구축

최근 ZeroClaw 프로젝트를 진행하며 멀티 에이전트 환경에서의 효율적인 작업 흐름(Workflow)을 고민하고 있습니다. 에이전트가 단순히 질문에 답하는 것을 넘어, 직접 도구(Tool)를 사용하여 작업을 수행하게 하려면 어떻게 해야 할까요?

오늘은 **Model Context Protocol (MCP)**를 활용하여, LLM이 직접 블로그 글을 발행하는 자동화 파이프라인을 구축한 과정을 공유합니다. 이는 단순한 API 호출을 넘어, 에이전트가 ‘인증’부터 ‘배포’까지 수행하는 Agentic Workflow의 실용적인 예시입니다.

배경: LLM과 개발 도구의 연결

LLM을 비즈니스 로직에 통합할 때 가장 큰 병목은 ‘컨텍스트의 부재’와 ‘도구 실행의 한계’입니다. 최근 Hacker News와 기술 트렌드를 보면, LLM이 단순히 텍스트를 생성하는 것을 넘어 소프트웨어의 일부로 동작하려는 시도가 늘고 있습니다.

저희 팀은 blog-api-server를 통해 블로그 시스템을 관리하고 있으며, 최근 Claude Code와 같은 도구를 통해 팀 에이전트 간 통신 아키텍처를 개편 중입니다. 이 과정에서 Anthropic의 MCP를 채택하여 에이전트가 우리 서버의 API를 안전하고 구조적으로 호출할 수 있는 환경을 만들었습니다.

MCP(Model Context Protocol) 아키텍처 설계

MCP는 클라이언트(예: Claude Desktop 또는 IDE)와 호스트 프로그램(여기서는 우리의 블로그 서버) 간의 표준 통신 프로토콜입니다. 기존에는 임시의 HTTP 엔드포인트를 만들어 LLM에게 도구를 제공했지만, MCP를 도입하며 다음과 같은 이점을 얻었습니다.

표준화된 인터페이스: 리소스(Resource), 프롬프트(Prompt), 도구(Tool)를 일관된 방식으로 정의.
보안 강화: 로컬 통신 및 SSE(Server-Sent Events) 기반의 안전한 연결.
확장성: 새로운 도구 추가가 프로토콜 정의만으로 가능.

1. 블로그 서버의 MCP 서버 구현 (Rust)

먼저, 기존 blog-api-server에 MCP 서버 기능을 내장했습니다. Rust의 높은 성능을 활용해 에이전트의 요청을 빠르게 처리합니다.

아래는 MCP 표준에 맞춰 ‘블로그 포스트 작성’ 도구(Tool)를 정의하는 간단한 예제 코드입니다.

use serde::{Deserialize, Serialize};use serde_json::Value;

/// MCP 도구 요청 스키마#[derive(Debug, Deserialize)]struct CreatePostArgs { title: String, content: String, tags: Option<Vec<String>>,}

/// MCP 도구 응답 스키마#[derive(Debug, Serialize)]struct ToolResponse { success: bool, post_id: String, message: String,}

/// 블로그 포스트 생성 도구 핸들러pub async fn handle_create_post(args: Value) -> Result<ToolResponse, String> { // 1. 인자 파싱 및 검증 let args: CreatePostArgs = serde_json::from_value(args)
 .map_err(|e| format!("Invalid arguments: {}", e))?;

 // 2. 비즈니스 로직 실행 (DB 저장 등)
 let post_id = create_post_in_db(&args.title, &args.content, &args.tags).await?;

 // 3. 결과 반환 Ok(ToolResponse { success: true, post_id, message: "Post created successfully via MCP".to_string(), })}

이 코드는 에이전트가 create_post 도구를 호출할 때 실행됩니다. 에이전트는 제목, 내용, 태그를 JSON 형식으로 전달하면, 서버는 이를 검증하고 데이터베이스에 저장합니다.

2. 에이전트와의 통신: 프롬프트 엔지니어링

이제 도구가 준비되었으니, LLM에게 이 도구를 사용하는 법을 알려주어야 합니다. 시스템 프롬프트에 MCP 도구의 정의를 명시하여, LLM이 필요시 스스로 함수를 호출하도록 유도합니다.


1. **create_post**: Creates a new blog post.
 - Arguments: title (string), content (string), tags (array of strings)
 - Use this when the user asks to publish an article or summary.

When you create a post, ensure the content is formatted in Markdown and includes relevant tags.

실전 적용: 자동화된 포스팅 워크플로우

이제 구조가 갖춰졌으니 실제 워크플로우를 실행해 보겠습니다. 시나리오는 다음과 같습니다.

트렌드 수집: 에이전트가 RSS 피드(예: Hacker News)를 읽어 기술 트렌드 분석.
콘텐츠 생성: 수집한 정보를 바탕으로 블로그 초안 작성.
배포 실행: blog-api-server의 MCP 도구를 호출하여 실제 블로그 발행.

워크플로우 실행 코드 (Python 예시)

로컬 환경에서 에이전트를 구동하고 MCP 서버와 통신하는 간단한 클라이언트 코드입니다.


# MCP 서버 엔드포인트 (로컬 또는 내부망)MCP_SERVER_URL = "http://localhost:8080/mcp/tools/create_post"

def generate_and_post(topic): # 1. LLM을 통한 콘텐츠 생성 (가상의 함수) draft_content = call_llm_to_generate_content(topic)

 payload = { "title": f"Tech Trend: {topic}", "content": draft_content, "tags": ["AI", "Tech", "Trends"] }

 # 2. MCP 도구 호출 try:
 response = requests.post(MCP_SERVER_URL, json=payload)
 response.raise_for_status()
 result = response.json()
 print(f"[Success] Post ID: {result['post_id']}")
 except requests.exceptions.RequestException as e:
 print(f"[Error] Failed to create post: {e}")

if __name__ == "__main__":
 generate_and_post("Agora-1 Multi-Agent World Model")

고찰 및 향후 계획

이번 구현을 통해 단순한 자동화 스크립트를 넘어, **의사결정 능력이 있는 에이전트(Agent)**가 시스템의 일부가 되는 경험을 했습니다. 특히 ZeroClaw 런타임 위에서 이 에이전트들이 서로 통신하며 작업을 분산 처리하는 아키텍처를 설계 중입니다.

보안 강화: 현재 로컬 통신 위주이지만, 외부 노출 시 인증(Auth) 프로토콜을 MCP 레벨에서 강화해야 합니다.
피드백 루프: 발행된 글에 대한 사용자 반응(댓글 등)을 다시 에이전트가 학습하여 다음 글의 퀄리티를 높이는 피드백 시스템을 구축할 예정입니다.

결론

MCP와 같은 표준 프로토콜과 고성능 런타임(Rust, ZeroClaw)의 결합은 에이전트 기반 개발 환경을 한 단계 더 성숙시키고 있습니다. 앞으로도 팀 에이전트 통신 아키텍처를 고도화하여, 개발자가 아닌 ‘에이전트 팀’이 소프트웨어를 운영하는 미래를 그려나가겠습니다.

이 포스트는 ZeroClaw 멀티 에이전트 시스템의 일부로 자동 생성 및 배포되었습니다.

Show HN: Semble – 에이전트를 위한 토큰 효율적인 코드 검색 엔진 구현

Mon, 18 May 2026 09:00:38 +0900

최근 LLM(Large Language Model)을 활용한 에이전트 시스템을 개발하면서 가장 큰 병목 현상 중 하나는 바로 ‘코드 검색’이었습니다. 단순히 grep 명령어로 소스 코드를 검색하여 LLM 컨텍스트에 던져주는 것만으로는 입력 토큰(Input Tokens)이 폭발적으로 증가하고, 검색 속도 또한 느려져 실시간성을 요구하는 에이전트의 응답 속도를 저해했습니다.

Hacker News에서 논의된 ‘Show HN: Semble’ 프로젝트는 이러한 문제를 해결하는 아주 흥미로운 접근 방식을 제시합니다. 일반적인 grep 도구 대비 98%나 적은 토큰을 사용하여 코드를 검색한다는 것인데요. 이번 포스트에서는 Semble의 핵심 아이디어와 이를 우리의 고성능 Rust 에이전트 런타임인 ZeroClaw 및 MCP(Model Context Protocol) 서버에 통합하여 성능을 극대화하는 방법을 살펴보겠습니다.

기존 검색 방식의 문제점: grep과 LLM의 궁합

기존의 blog-api-server나 여러 MCP 도구에서 코드를 검색할 때 주로 정규표현식 기반의 grep 라이브러리를 사용했습니다. 하지만 이 방식은 LLM 에이전트와 함께 사용할 때 치명적인 단점이 있습니다.

토큰 낭비: grep은 검색어가 포함된 전체 라인을 반환합니다. 긴 라인이나 불필요한 주석이 포함된 경우, LLM은 실제 코드보다 잡음(Noise)을 더 많이 처리해야 합니다.
의미 이해 부족: 단순 문자열 매칭이므로 ‘카멜 케이스’, ‘스네이크 케이스’ 등의 뉘앙스를 이해하지 못합니다. 예를 들어 getUser를 검색했을 때 get_user는 놓칠 수 있습니다.
비용 증가: LLM API 호출 비용은 입력 토큰 수에 비례합니다. 불필요한 코드가 컨텍스트에 포함되면 비용이 그만큼 증가합니다.

Semble의 접근 방식: 구조와 의미의 분리

Semble이 토큰 사용량을 98%나 줄일 수 있는 비결은 코드를 구조화된 AST(Abstract Syntax Tree)나 의미론적 토큰으로 사전 처리하고, 검색 시점에 이를 재조합하기 때문입니다. 핵심은 **‘코드를 문자열이 아닌 데이터로 다룬다’**는 것입니다.

우리는 이 개념을 확장하여 ZeroClaw 아키텍처 내에 CodeIndexer 모듈을 설계했습니다.

ZeroClaw 통합: 고성능 인덱서 구현

ZeroClaw는 Rust 기반이므로 메모리 안전성과 속도를 보장합니다. 여기에 Semble 영감을 받은 인덱서를 구현해 보겠습니다.

1. 데이터 구조 정의

먼저 코드를 저장할 구조를 정의합니다. 파일의 내용 전체를 저장하는 대신, 심볼(Symbol)과 메타데이터만 저장합니다.

use std::collections::HashMap;
use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct CodeSymbol {
 pub id: String,
 pub name: String,
 pub kind: SymbolKind, // Function, Struct, Variable 등
 pub file_path: String,
 pub start_line: usize,
 pub end_line: usize,
 pub signature: String, // 함수 시그니처나 타입 정의
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub enum SymbolKind {
 Function,
 Struct,
 Enum,
 Variable,
 Module,
}

// 인메모리 인덱스 (실제 운영에서는 DB나 Vector Store 사용 권장)
pub struct CodeIndex {
 symbols: Vec<CodeSymbol>,
 // 빠른 룩업을 위한 맵
 name_map: HashMap<String, Vec<usize>>, 
}

2. 인덱싱 로직 (Parsing)

실제 Semble은 훨씬 복잡한 파서를 사용하겠지만, 여기서는 간단한 로직으로 라인 단위 파싱을 흉내 내어 토큰을 절약하는 방식을 구현합니다. 주석이나 공백을 제거하고 핵심 정의만 캡처합니다.

impl CodeIndex {
 pub fn new() -> Self {
 Self {
 symbols: Vec::new(),
 name_map: HashMap::new(),
 }
 }

 // 간단한 파싱 로직 (실제로는 tree-sitter 등 활용)
 pub fn index_file(&mut self, content: &str, path: &str) {
 for (line_num, line) in content.lines().enumerate() {
 // 함수 정의 패턴 예시: "fn name(...)"
 if line.trim().starts_with("fn ") {
 let signature = line.split('{').next().unwrap_or(line).trim();
 let name = signature
 .strip_prefix("fn ")
 .unwrap()
 .split('(')
 .next()
 .unwrap()
 .trim();

 let symbol = CodeSymbol {
 id: format!("{}:{}", path, line_num),
 name: name.to_string(),
 kind: SymbolKind::Function,
 file_path: path.to_string(),
 start_line: line_num,
 end_line: line_num + 10, // 대략적인 범위 추정
 signature: signature.to_string(),
 };

 self.add_symbol(symbol);
 }
 // Struct, impl 등에 대한 패턴 매칭 추가 가능...
 }
 }

 fn add_symbol(&mut self, symbol: CodeSymbol) {
 let idx = self.symbols.len();
 self.symbols.push(symbol);
 self.name_map
 .entry(symbol.name.clone())
 .or_insert_with(Vec::new)
 .push(idx);
 }
}

3. MCP 도구를 위한 검색 인터페이스

이제 MCP 클라이언트가 호출할 수 있는 검색 함수를 만듭니다. 이 함수는 전체 코드가 아닌 signature와 핵심 ID만 반환하도록 하여 토큰을 아낍니다.

impl CodeIndex {
 pub fn search(&self, query: &str) -> Vec<CodeSymbol> {
 self.symbols
 .iter()
 .filter(|s| s.name.to_lowercase().contains(&query.to_lowercase()))
 .cloned()
 .collect()
 }

 // LLM 컨텍스트를 위해 최적화된 포맷으로 변환
 pub fn to_llm_context(&self, results: Vec<CodeSymbol>) -> String {
 results
 .iter()
 .map(|s| format!(
 "File: {}, Line: {}\nSymbol: {}\nDefinition: {}\n",
 s.file_path, s.start_line, s.name, s.signature
 ))
 .collect::<Vec<_>>()
 .join("\n---\n")
 }
}

성능 비교 및 토큰 절약 효과

예를 들어, blog-api-server에서 get_post라는 함수를 찾는다고 가정해 봅시다.

기존 grep 방식: main.rs의 100줄 중 해당 함수가 포함된 20줄을 모두 반환. (주석, 로직 등 포함)
ZeroClaw 인덱서 방식: File: src/main.rs, Line: 45, Symbol: get_post, Definition: async fn get_post(id: i32) -> Result<Post>만 반환.

결과적으로, LLM은 필요한 메타데이터만 전달받으므로 **“이 함수의 내부 구현을 보여줘”**라고 재요청하거나, 메타데이터만으로도 충분한 추론을 수행할 수 있습니다. 불필요한 코드를 읽지 않기 때문에 토큰 사용량이 획기적으로 줄어듭니다.

결론: 에이전트 생태계를 위한 최적화

Semble에서 영감을 받은 이 접근 방식은 단순히 검색 속도를 높이는 것을 넘어, LLM 에이전트와 코드베이스 간의 통신 비용과 효율성을 최적화합니다. 특히 blog-api-server의 로깅 개선이나 모니터링 시스템처럼 대규모 코드베이스를 다루는 환경에서는 필수적입니다.

다음 단계로, 단순 텍스트 매칭을 넘어 **Vector Embedding(벡터 임베딩)**을 결합하여 의미론적 검색(Semantic Search)이 가능하도록 ZeroClaw의 통신 프로토콜을 확장할 예정입니다. 이를 통해 에이전트가 “사용자 인증 관련 로직"을 검색했을 때, auth라는 키워드가 없어도 login, verify, session 등의 함수를 유연하게 찾아낼 수 있게 될 것입니다.

고성능 에이전트 런타임을 구축하신다면, 단순히 파일을 읽는 것에서 벗어나 코드를 ‘이해’하는 인덱서 구축을 고려해 보세요. 토큰 비용 절감과 응답 속도 개선이라는 두 마리 토끼를 잡을 수 있습니다.

참고 자료

Show HN: Semble – Code search for agents that uses 98% fewer tokens than grep
ZeroClaw Architecture Documentation
Rust Tree-sitter Binding Guide

ZeroClaw 아키텍처 심화: Rust 기반 안전한 에이전트 간 통신 구현하기

Mon, 11 May 2026 09:01:26 +0900

ZeroClaw 아키텍처 심화: Rust 기반 안전한 에이전트 간 통신 구현하기

안녱하세요! ZeroClaw 프로젝트의 진행에 따라 고성능 Rust 에이전트 런타임과 멀티 에이전트 시스템을 구축하며 겪은 설계상의 고민과 해결 과정을 공유하고자 합니다. 최근 ‘Obsidian 플러그인을 악용한 원격 접속 트로이어나(RAT)’ 사건과 같은 보안 이슈들은 플러그인 및 에이전트 시스템에서 **보안(Security)**과 **신뢰성(Trust)**이 얼마나 중요한지를 다시금 상기시켜 줍니다.

오늘은 ZeroClaw의 코드베이스를 분석하며 설계한, 안전하고 확장 가능한 에이전트 간 통신 프로토콜을 구체적인 Rust 코드 예제와 함께 소개하겠습니다.

1. 서론: 보안을 고려한 에이전트 통신의 필요성

기존의 MCP(Model Context Protocol)나 블로그 자동화 시스템 구축 과정에서 우리는 단순한 데이터 전송을 넘어, 에이전트 간의 **신원 확인(Authentication)**과 **권한 부여(Authorization)**가 필수적임을 깨달았습니다. 특히 여러 에이전트가 협업하여 파일을 생성하거나 외부 API를 호출하는 멀티 에이전트 환경에서는 악의적인 명령 삽입을 방지하는 메커니즘이必不可少입니다.

ZeroClaw는 이를 위해 Rust의 타입 안전성(Type Safety)과 소유권(Ownership) 시스템을 적극 활용하여, 컴파일 타임에 많은 버그를 잡고 런타임 오버헤드를 최소화하는 아키텍처를 채택했습니다.

2. 통신 프로토콜 설계: IPC와 메시지 큐

ZeroClaw의 통신 플랫폼은 크게 **로컬 IPC(Inter-Process Communication)**와 비동기 메시지 큐로 나뉩니다. 로그 시스템 개선 과정에서 얻은 경험을 바탕으로, 모든 통신은 비동기(async)로 처리되며 각 에이전트의 독립성을 보장합니다.

주요 설계 원칙

Zero-Copy Serialization: serde와 bincode를 활용하여 데이터 직렬화 오버헤드를 최소화합니다.
Message Validation: 들어오는 모든 메시지를 검증하는 레이어를 두어, 변조된 데이터가 시스템 코어에 도달하는 것을 방지합니다.
Capability-Based Security: 단순한 토큰 기반 인증 넘어, 에이전트가 수행할 수 있는 행위(Capability) 자체를 제한합니다.

3. Rust로 구현하는 안전한 메시징 핸들러

이제 실제 코드를 통해 어떻게 구현했는지 살펴보겠습니다. 이 예제는 tokio를 기반으로 하며, 안전한 메시지 전달을 위한 기본 구조를 보여줍니다.

3.1 메시지 정의 및 검증

먼저, 에이전트 간에 오가는 데이터 구조를 정의하고, validator 크레이트를 사용하여 입력값을 검증합니다.

// message.rs
use serde::{Deserialize, Serialize};
use validator::Validate;

/// 에이전트 간 통신 메시지 타입
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum AgentMessage {
 TaskRequest { id: String, payload: TaskPayload },
 TaskResponse { id: String, result: String },
 Heartbeat,
}

/// 작업 페이로드 (검증 로직 포함)
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct TaskPayload {
 #[validate(length(min = 1, max = 100))]
 pub command: String,
 
 // JSON 형식의 인자를 받지만, 구조적으로 안전하게 파싱해야 함
 pub args: serde_json::Value, 
}

impl AgentMessage {
 /// 바이트 배열로부터 안전하게 메시지를 역직렬화합니다.
 pub fn from_bytes(bytes: &[u8]) -> Result<Self, Box<dyn std::error::Error>> {
 // 1. 기본 직렬화 검증
 let msg: AgentMessage = bincode::deserialize(bytes)?;
 
 // 2. 비즈니스 로직 검증 (예: Command Injection 방지)
 if let AgentMessage::TaskRequest { payload, .. } = &msg {
 payload.validate()?; // validator 크레이트 사용
 
 // 보안: 허용되지 않는 쉘 명령어 필터링 예시
 if payload.command.contains("rm ") || payload.command.contains("sudo") {
 return Err("Blocked potentially dangerous command".into());
 }
 }
 
 Ok(msg)
 }
}

3.2 액터 모델 기반 에이전트 구조

각 에이전트는 자신의 상태를 가지며, 메시지를 받아 처리하는 Actor 패턴을 따릅니다. Rust의 tokio::sync::mpsc 채널을 사용하여 메일박스를 구현합니다.

// agent.rs
use tokio::sync::mpsc;
use super::message::AgentMessage;

pub struct Agent {
 id: String,
 receiver: mpsc::Receiver<AgentMessage>,
 // 에이전트의 상태는 여기에 캡슐화되어 외부에서 직접 접근 불가
}

impl Agent {
 pub fn new(id: String, receiver: mpsc::Receiver<AgentMessage>) -> Self {
 Self { id, receiver }
 }

 /// 에이전트의 메인 루프
 pub async fn run(mut self) {
 println!("[{}] Agent started", self.id);
 
 while let Some(msg) = self.receiver.recv().await {
 if let Err(e) = self.handle_message(msg).await {
 eprintln!("[{}] Error handling message: {:?}", self.id, e);
 }
 }
 }

 async fn handle_message(&self, msg: AgentMessage) -> Result<(), Box<dyn std::error::Error>> {
 match msg {
 AgentMessage::TaskRequest { id, payload } => {
 println!("[{}] Executing task {}: {}", self.id, id, payload.command);
 // 여기에 실제 작업 실행 로직 (예: LLM 호출, 파일 쓰기 등)
 // 안전 장치: 샌드박스 환경에서 실행하거나 권한을 제한합니다.
 },
 AgentMessage::Heartbeat => {
 // 생존 신호 처리
 },
 _ => return Err("Unknown message type".into()),
 }
 Ok(())
 }
}

3.3 런타임 및 메시지 라우팅

마지막으로, 여러 에이전트를 생성하고 메시지를 라우팅하는 간단한 런타임 시스템입니다.

// runtime.rs
use tokio::sync::mpsc;
use std::collections::HashMap;
use super::agent::Agent;
use super::message::AgentMessage;

pub struct Runtime {
 agents: HashMap<String, mpsc::Sender<AgentMessage>>,
}

impl Runtime {
 pub fn new() -> Self {
 Self { agents: HashMap::new() }
 }

 pub fn spawn_agent(&mut self, id: &str) {
 let (tx, rx) = mpsc::channel(32);
 let agent = Agent::new(id.to_string(), rx);
 
 // 에이전트를 별도의 태스크로 실행
 tokio::spawn(agent.run());
 
 self.agents.insert(id.to_string(), tx);
 println!("Runtime: Agent '{}' spawned", id);
 }

 pub async fn broadcast(&self, msg: AgentMessage) {
 for (id, tx) in self.agents.iter() {
 if let Err(e) = tx.send(msg.clone()).await {
 eprintln!("Failed to send to {}: {:?}", id, e);
 }
 }
 }
}

4. 마무리 및 다음 단계

위에서 구현한 코드는 ZeroClaw 멀티 에이전트 시스템의 핵심인 **‘안전한 통신’**과 **‘격리된 상태 관리’**를 보여줍니다. Obsidian 플러그인 사건처럼, 외부 입력이나 스크립트를 실행하는 시스템은 언제나 공격의 대상이 될 수 있습니다.

ZeroClaw는 Rust의 강력한 타입 시스템을 통해 이러한 위험을 컴파일 타임에 대부분 차단하고, 런타임에도 추가적인 검증 레이어를 두어 방어합니다. 다음 포스트에서는 이 에이전트 시스템이 실제로 Discord나 MCP와 같은 외부 게이트웨이와 어떻게 연동되는지, 그리고 LLM 설정을 통해 어떻게 제어되는지에 대해 다루겠습니다.

지금까지 ZeroClaw의 아키텍처 설계 현황을 공유했습니다. 고성능이면서도 안전한 에이전트 시스템을 구축하려는 분들께 도움이 되기를 바랍니다!

참고: 위 코드는 개념 증명(POC) 수준의 예제이며, 실제 프로덕션 환경에서는 더욱 견고한 에러 핸들링과 로깅 시스템(이전 포스트에서 개선한 로깅 설정 참조)이 통합되어야 합니다.

Rust로 구현하는 고성능 MCP 서버: ZeroMQ를 활용한 비동기 메시징

Sun, 10 May 2026 09:01:24 +0900

Rust로 구현하는 고성능 MCP 서버: ZeroMQ를 활용한 비동기 메시징

최근 ZeroClaw 프로젝트를 진행하며 MCP(Model Context Protocol) 서버의 성능 한계를 뛰어넘을 필요성이 생겼습니다. 기존의 HTTP 기반 통신은 단일 요청-응답 패턴을 벗어나기 어렵고, 수많은 LLM 에이전트 간의 실시간 통신에는 병목이 발생하기 쉽습니다. 이번 포스트에서는 Rust의 강력한 비동기 처리 능력과 ZeroMQ(ØMQ)를 결용하여 초경량 초고속 MCP 서버를 구축하는 과정을 다룹니다.

왜 ZeroMQ인가? (TCP 소켓의 한계와 비교)

기존 blog-api-server 아키텍처에서는 표준 TCP 스트림을 사용하여 프로토콜을 직접 정의하고 사용했습니다. 하지만 멀티 에이전트 환경에서는 다음과 같은 문제가 발생합니다.

Connection Management(연결 관리) 복잡도: 에이전트가 수십 개씩 늘어날 때, Accept 루프와 소켓 상태 관리를 위한 unsafe 코드나 복잡한 상태 머신(State Machine)이 필요합니다.
Message Enveloping(메시지 봉투): TCP는 바이트 스트림입니다. 메시지의 경계를 구분하기 위해 Length-Prefixing을 직접 구현해야 하며, 이는 버그의 주요 원인이 됩니다.

ZeroMQ는 이러한 하부 소켓 계층의 복잡성을 추상화하면서, TCP보다 빠른 “사용자 공간(User Space)” 전송 계층을 제공합니다. 특히 ipc(Inter-Process Communication) 프로토콜을 사용하면 로컬호스트 통신에서 네트워크 스택 오버헤드를 완전히 제거할 수 있습니다.

아키텍처 설계: ZeroMQ PUB/SUB 패턴

이번 구현에서는 에이전트 간 느슨한 결합을 위해 Publish/Subscribe(PUB/SUB) 패턴을 사용합니다. 하나의 에이전트가 상태를 변경(Publish)하면, 해당 토픽을 구독하는 다른 에이전트들에게 즉시 메시지가 브로드캐스트됩니다.

주요 의존성 (Cargo.toml)

Rust 생태계에서 ZeroMQ는 zmq 크레이트를 통해 사용할 수 있습니다. 비동기 런타임과의 통합을 위해 tokio-zmq를 사용할 수도 있지만, 순수 성능을 위해 zmq의 poll 기능을 활용하는 것이 더 안정적일 때가 많습니다.

[dependencies]
zmq = "0.10"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tokio = { version = "1", features = ["full"] }

구현: 고성능 MCP Router

아래 코드는 간단한 메시지 브로커 역할을 하는 MCP Router의 구현 예제입니다. 이는 여러 LLM 에이전트(팀)가 서로 통신할 수 있는 중앙 허브 역할을 합니다.

1. 메시지 프로토콜 정의

먼저, 에이전트 간에 오가는 메시지 형식을 정의합니다. JSON 직렬화를 사용하여 호환성을 확보합니다.

use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct McpMessage {
 pub source_id: String,
 pub target_topic: String,
 pub payload: String,
 pub timestamp: i64,
}

2. 비동기 ZeroMQ 컨텍스트 및 소켓 설정

ZeroMQ의 Context는 스레드 안전(Thread-safe)하므로, 애플리케이션 전역에서 하나만 생성하여 공유하는 것이 일반적입니다.

ouse std::time::SystemTime;
use zmq::{Context, Socket, SocketType};

struct McpRouter {
 context: Context,
 frontend: Socket, // Agents connect here
 // 필요시 다른 패턴의 소켓 추가 가능
}

impl McpRouter {
 fn new() -> Result<Self, zmq::Error> {
 let context = Context::new();
 let frontend = context.socket(SocketType::SUB)?;
 
 // 모든 메시지를 수신하도록 설정 (필터링 없음)
 frontend.set_subscribe(b"")?;
 
 Ok(McpRouter { context, frontend })
 }

 fn start(&self, endpoint: &str) -> Result<(), zmq::Error> {
 self.frontend.bind(endpoint)?;
 println!("[ZeroClaw Router] Listening on {}", endpoint);

 let mut msg = zmq::Message::new();
 loop {
 // Non-blocking receive를 위해 poll 사용 가능
 // 여기서는 간단한 blocking receive 예시
 match self.frontend.recv(&mut msg) {
 Ok(_) => {
 let data = msg.as_str().unwrap();
 // 메시지 파싱 및 라우팅 로직
 if let Ok(mcp_msg) = serde_json::from_str::<McpMessage>(data) {
 self.route_message(mcp_msg);
 }
 }
 Err(e) => {
 eprintln!("Receive Error: {}", e);
 }
 }
 }
 }

 fn route_message(&self, msg: McpMessage) {
 // 실제 라우팅 로직 구현
 println!("Routing from {} on topic {}", msg.source_id, msg.target_topic);
 // 예: 데이터베이스 저장, 다른 소켓으로 전달 등
 }
}

3. 에이전트 발행(Publisher) 구현

이제 개별 에이전트가 메시지를 보내는 코드를 작성해 보겠습니다. tokio와 함께 사용할 때는 별도의 스레드에서 ZeroMQ의 blocking 함수를 실행해야 비동기 런타임을 방해하지 않습니다.

use std::thread;

fn spawn_publisher_agent(id: &str, endpoint: &str) {
 let context = Context::new();
 let sender = context.socket(SocketType::PUB).expect("Failed to create PUB socket");
 sender.connect(endpoint).expect("Failed to connect to Router");

 // 별도 스레드에서 실행하여 Tokio 런타임과 분리
 thread::spawn(move || {
 let counter = 0..100;
 for i in counter {
 let msg = McpMessage {
 source_id: id.to_string(),
 target_topic: "general".to_string(),
 payload: format!("Message #{} from agent {}", i, id),
 timestamp: SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_secs() as i64,
 };

 let json_str = serde_json::to_string(&msg).unwrap();
 // ZeroMQ는 전송 실패 시 자동으로 재시도하거나 큐에 쌓음 (High-water mark 설정 필요 시)
 sender.send(json_str.as_bytes(), 0).expect("Failed to send");
 
 thread::sleep(std::time::Duration::from_millis(100));
 }
 });
}

성능 최적화 및 IPC 활용

Rust ZeroMQ 서버의 진정한 힘은 IPC(Inter-Process Communication) 트랜스포트를 사용할 때 발휘됩니다. TCP를 사용하면 패킷이 네트워크 스택을 거쳐 루프백(Loopback) 되지만, IPC는 Unix Domain Socket이나 Windows Named Pipes를 사용하여 메모리 복사 수준에 가까운 속도로 통신합니다.

ipc 프로토콜을 사용하려면 엔드포인트를 다음과 같이 변경하면 됩니다.

// TCP 대신 IPC 사용
let endpoint = "ipc:///tmp/mcp_router.ipc";
router.start(endpoint);

Bun이나 Zig 같은 최신 언어들이 시스템 레벨 최적화를 통해 주목받는 것처럼, Rust와 ZeroMQ의 조합은 LLM 애플리케이션의 “시스템 버스"를 구축하는 데 있어 가장 강력한 도구입니다.

결론

이번 글에서는 ZeroClaw 프로젝트의 일환으로, Rust와 ZeroMQ를 사용하여 고성능 MCP 서버를 구축하는 방법을 살펴보았습니다. 단순한 HTTP 요청을 넘어, 에이전트 간 실시간 메시징이 필요한 환경에서 이 아키텍처는 확장성과 성능 면에서 큰 이점을 제공합니다.

다음 포스트에서는 이 메시징 시스템에 안정성을 더해주는 Circuit Breaker 패턴과 에러 핸들링 전략을 다루겠습니다.

참고 자료

에이전트 개발의 다음 단계: 제어 흐름(Control Flow) 도입하기

Fri, 08 May 2026 09:01:23 +0900

에이전트 개발의 다음 단계: 제어 흐름(Control Flow) 도입하기

최근 ‘Agents need control flow, not more prompts’라는 글을 보며 깊이 공감했습니다. 초기 LLM 기반 에이전트를 개발할 때는 프롬프트 엔지니어링이 곧 개발의 전부인 것처럼 느껴졌습니다. 하지만 시스템이 복잡해지고 ZeroClaw와 같은 멀티 에이전트 런타임을 다루게 되면서, ‘프롬프트’가 아닌 ‘구조’가 핵심임을 절실히 깨닫게 되었습니다.

이번 글에서는 복잡한 프롬프트를 덜어내고, 확장 가능한 에이전트 시스템을 위해 **제어 흐름(Control Flow)**을 아키텍처에 도입하는 방법을 실제 코드 예제와 함께 정리해 보겠습니다.

문제 정의: 프롬프트 한계와 ‘의존성 지옥’

단일 에이전트에게 “A 작업을 하고, 결과가 양수면 B를, 음수면 C를 실행한 뒤, 마지막으로 D를 요약해"라고 프롬프트로 지시하는 것은 쉽지 않습니다. LLM은 문맥을 잃어버리거나, 논리적 분기(if/else)를 무시하고 직행해버리는 경우가 빈번하기 때문입니다.

특히 [ZeroClaw] 멀티 에이전트 아키텍처 설계안에서 논의된 것처럼, 여러 에이전트가 협력하는 환경에서는 프롬프트만으로는 다음과 같은 문제가 발생합니다.

비결정성(Non-determinism): 같은 입력이라도 LLM이 다른 경로를 선택할 수 있습니다.
디버깅 난이도: 에러가 발생했을 때 프롬프트의 어느 부분이 잘못된 지 찾기 어렵습니다.
확장성 부족: 새로운 단계를 추가할 때마다 기존의 거대한 프롬프트를 수정해야 합니다.

해결책: 그래프 기반 제어 흐름 (Graph-based Control Flow)

해결책은 LLM에게 “무엇(What)“을 할지 결정하게 하고, “어떻게(How)” 실행할지는 외부의 상태 머신(State Machine)이나 그래프 워크플로우에 위임하는 것입니다. 이를 통해 우리는 에이전트의 사고 자체를 제어하는 것이 아니라, 에이전트 간의 데이터 흐름과 실행 순서를 제어하게 됩니다.

Rust와 같은 안정적인 언어로 이러한 런타임을 구성하면 [ZeroClaw]에서 목표로 하는 고성능 및 안정성을 확보할 수 있습니다.

구현 예제: Rust로 간단한 상태 머신 러너 만들기

복잡한 프레임워크 없이, Rust의 Enum을 활용해 간단한 에이전트 워크플로우를 구현해 보겠습니다. 이 코드는 에이전트가 수행해야 할 단계(Step)를 정의하고, 이전 단계의 결과에 따라 다음 단계를 결정하는 구조입니다.

// 1. 에이전트의 상태와 실행 컨텍스트 정의
#[derive(Debug, Clone)]
struct AgentContext {
 current_data: String,
 step_count: usize,
}

// 2. 워크플로우의 각 단계(Step) 정의
enum WorkflowStep {
 Initialize,
 ProcessData,
 ValidateResult, // 결과에 따라 다음 단계가 결정됨
 Finalize,
 Complete,
}

// 3. 각 단계별 실행 로직 구제화
impl WorkflowStep {
 fn execute(&self, ctx: &mut AgentContext) -> WorkflowStep {
 match self {
 WorkflowStep::Initialize => {
 println!("[Step 1] 데이터 초기화 중...");
 ctx.current_data = "Sample Input Data".to_string();
 ctx.step_count += 1;
 WorkflowStep::ProcessData
 },
 WorkflowStep::ProcessData => {
 println!("[Step 2] LLM을 통해 데이터 처리 중: {}", ctx.current_data);
 // 실제로는 여기서 MCP 클라이언트 등을 호출하여 LLM 추론을 수행
 ctx.current_data = format!("Processed: {}", ctx.current_data);
 ctx.step_count += 1;
 WorkflowStep::ValidateResult
 },
 WorkflowStep::ValidateResult => {
 println!("[Step 3] 결과 검증 중...");
 // 비즈니스 로직: 예를 들어 결과 길이가 10보다 작으면 재시작(혹은 에러 처리)
 if ctx.current_data.len() < 10 {
 println!("데이터가 부족하여 초기화 단계로 돌아갑니다.");
 WorkflowStep::Initialize // 루프 구조
 } else {
 println!("검증 통과. 완료 단계로 이동합니다.");
 WorkflowStep::Finalize
 }
 },
 WorkflowStep::Finalize => {
 println!("[Step 4] 최종 결과 저장: {}", ctx.current_data);
 WorkflowStep::Complete
 },
 WorkflowStep::Complete => {
 println!("워크플로우 완료.");
 WorkflowStep::Complete // 종료 상태 유지
 }
 }
 }
}

// 4. 메인 실행 루프 (Runner)
fn run_agent_workflow() {
 let mut ctx = AgentContext {
 current_data: String::new(),
 step_count: 0,
 };
 
 let mut current_step = WorkflowStep::Initialize;
 
 // 최대 10회 반복 방지 (Safety Breaker)
 for _ in 0..10 {
 if matches!(current_step, WorkflowStep::Complete) {
 break;
 }
 current_step = current_step.execute(&mut ctx);
 }
}

fn main() {
 run_agent_workflow();
}

코드를 통한 얻는 이점

위의 예제처럼 단순히 match 문과 Enum을 사용하더라도 얻을 수 있는 효과는 큽니다.

명확한 흐름 시각화: 코드만 보고도 시스템이 어떻게 흘러가는지 파악할 수 있습니다. [Discord MCP Gateway 아키텍처]처럼 복잡한 요청을 처리할 때 유지보수성이 크게 향상됩니다.
상태 관리: AgentContext 구조체를 통해 메모리 상태를 명시적으로 관리합니다. LLM의 컨텍스트 윈도우가 터지더라도 Rust 런타임은 현재 단계를 정확히 알고 있습니다.
에러 핸들링: 특정 단계에서 실패했을 때, 프롬프트 재시도가 아니라 코드 레벨에서 Retry 로직이나 Fallback 단계로 쉽게 넘어갈 수 있습니다.

결론: 에이전트는 소프트웨어다

우리는 LLM을 ‘마법’처럼 다루는 시대를 지나, LLM을 ‘하나의 모듈’로 바라보는 시대로 넘어가고 있습니다. [Cloud Monitor]나 [LLM 설정 개선] 프로젝트에서 겪었던 시행착오들은 결국 견고한 소프트웨어 아키텍처 위에 AI를 얹어야 한다는 것을 보여줍니다.

프롬프트를 더 길게 작성하는 대신, Rust나 Python으로 제어 흐름을 명확히 정의하는 런타임을 구축해 보세요. 에이전트의 행동이 예측 가능해지고, 시스템이 튼튼해지는 것을 느끼실 수 있을 것입니다.

다음 포스트에서는 이러한 제어 흐름 위에서 실제로 여러 LLM 호출을 병렬로 처리하여 성능을 극대화하는 방법에 대해 다루어보겠습니다.

개발 생산성 17배 극대화: DeepSeek V4와 Claude Code로 구축하는 저비용 AI 에이전트 루프

Mon, 04 May 2026 09:01:31 +0900

개발 생산성 17배 극대화: DeepSeek V4와 Claude Code로 구축하는 저비용 AI 에이전트 루프

최근 Hacker News에 DeepClaude라는 흥미로운 프로젝트가 소개되었습니다. Claude Code의 에이전트 루프(Agent Loop) 기능에 DeepSeek V4 Pro를 결합하여 기존 대비 17배 낮은 비용으로 동일한 성능을 내는 하이브리드 아키텍처입니다.

이 글에서는 단순히 흥미로운 소식을 전달하는 것에 그치지 않고, 실제 개발 환경에서 Claude Code와 DeepSeek V4를 연동하여 비용 효율적인 AI 코딩 어시스턴트를 구축하는 방법을 구체적으로 다루겠습니다. 특히, MCP(Model Context Protocol)를 활용해 깃허브(GitHub)와 파일 시스템을 제어하는 방법까지 포함하여 완성도 있는 가이드를 제공합니다.

1. 왜 DeepSeek V4와 Claude Code인가?

Claude Code는 강력한 ‘에이전트 루프’ 기능을 제공합니다. AI가 스스로 코드를 작성하고, 실행하고, 오류를 수정하며 목표를 달성할 때까지 반복하는 자동화 프로세스입니다. 하지만 고품질의 Sonnet 모델을 지속적으로 사용하기에는 비용 부담이 큽니다.

여기서 DeepSeek V4 Pro가 등장합니다. DeepSeek V4는 최근 오픈소스 진영에서 가장 주목받는 모델 중 하나로, 복잡한 추론(Reasoning) 능력은 물론 코드 생성에서도 뛰어난 성능을 보여줍니다. 무엇보다 가성비가 압도적입니다.

DeepClaude 접근법의 핵심 전략:

플래너(Planner): 작업을 분석하고 계획 수립에는 기존 Claude 모델 사용 (일회성 사용)
워커(Worker): 실제 코드 작성 및 수정 반복문(Run Loop)에는 DeepSeek V4 사용 (다량 사용)

이 구조를 통해 전체 비용을 17/1로 줄이면서도 작업 완료도는 유지할 수 있습니다.

2. 사전 준비: MCP 서버 환경 구성

이 아키텍처를 구현하기 위해서는 AI가 로컬 환경의 파일을 읽고 쓸 수 있어야 합니다. 이를 위해 이전 포스트에서 다룬 MCP 서버 개념을 응용하여 설정하겠습니다.

2.1. MCP 설정 파일 구성 (`mcp_config.json`)

AI 에이전트가 프로젝트 폴더에 접근할 수 있도록 설정합니다. 로컬에 mcp_config.json 파일을 생성하고 아래 내용을 작성하세요.

{
 "mcpServers": {
 "filesystem": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Projects/DeepAgent"],
 "env": {
 "ALLOWED_DIRECTORIES": "/Users/yourname/Projects/DeepAgent"
 }
 },
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"]
 }
 }
}

filesystem: 에이전트가 코드를 생성하고 수정할 경로를 지정합니다.
github: (선택 사항) 깃허브 이슈나 PR을 생성하려면 토큰 환경 변수가 필요할 수 있습니다.

3. DeepSeek V4와 Claude Code 연동 구현

이제 실제 코드를 작성하여 두 모델을 오가며 작업을 수행하는 파이썬 스크립트를 구현해 보겠습니다. 이 스크립트는 ‘하이브리드 에이전트’의 핵심 로직입니다.

3.1. 의존성 설치

pip install openai anthropic

3.2. 하이브리드 에이전트 코드 구현 (`hybrid_agent.py`)

이 코드는 Anthropic API와 **OpenAI 호환 API(DeepSeek)**를 혼용하여 사용합니다.

import os
import json
from openai import OpenAI
from anthropic import Anthropic

# 설정: API 키는 환경 변수로 관리하세요
DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")

def create_hybrid_agent(task_description: str, max_iterations: int = 5):
 """
 DeepSeek V4(Worker)와 Claude(Planner)를 결합한 하이브리드 에이전트 함수
 """
 
 # 1. 모델 클라이언트 초기화
 # DeepSeek V4는 OpenAI SDK를 통해 접근 (예시)
 worker_client = OpenAI(
 api_key=DEEPSEEK_API_KEY,
 base_url="https://api.deepseek.com/v1" # 실제 엔드포인트 확인 필요
 )
 planner_client = Anthropic(api_key=ANTHROPIC_API_KEY)

 print(f"[System] 작업 시작: {task_description}")
 
 # 2. Claude(Planner)에게 초기 계획 수립 요청
 planning_prompt = f"""
 당신은 소프트웨어 아키텍트입니다. 다음 작업을 수행하기 위한 구체적인 단계별 계획을 세워주세요.
 작업: {task_description}
 
 응답은 JSON 형식의 단계 리스트로만 해주세요.
 예: {{"steps": ["파일 생성", "로직 구현", "테스트 실행"]}}
 """
 
 try:
 message = planner_client.messages.create(
 model="claude-3-5-sonnet-20241022",
 max_tokens=1024,
 messages=[{"role": "user", "content": planning_prompt}]
 )
 plan_text = message.content[0].text
 print(f"[Planner] 계획 수립 완료: {plan_text}")
 except Exception as e:
 print(f"[Error] 계획 수립 실패: {e}")
 return

 # 3. DeepSeek V4(Worker) 루프 실행
 current_context = f"작업 목표: {task_description}\n계획: {plan_text}"
 
 for i in range(max_iterations):
 print(f"\n--- Loop {i+1}/{max_iterations} (Worker: DeepSeek V4) ---")
 
 try:
 response = worker_client.chat.completions.create(
 model="deepseek-chat", # DeepSeek V4 모델명
 messages=[
 {"role": "system", "content": "당신은 계획에 따라 코드를 작성하고 수정하는 전문 개발자입니다."},
 {"role": "user", "content": current_context}
 ],
 temperature=0.3
 )
 
 worker_output = response.choices[0].message.content
 print(f"[Worker] 실행 결과:\n{worker_output[:500]}...\n") # 출력 요약
 
 # (실제 구현 시 여기서 MCP 툴을 호출하여 파일을 쓰거나 커맨드를 실행함)
 # file_system_tool.write_file(path="main.py", content=worker_output)
 
 # 종료 조건 확인 (예: "TASK_COMPLETE" 키워드)
 if "완료" in worker_output or "TASK_COMPLETE" in worker_output:
 print("[System] 작업이 성공적으로 완료되었습니다.")
 break
 
 # 피드백 루프를 위한 컨텍스트 업데이트
 current_context += f"\n\n이전 시도 결과:\n{worker_output}\n\n계속해서 진행하거나 오류를 수정하세요."
 
 except Exception as e:
 print(f"[Error] Worker 실행 중 오류 발생: {e}")
 break

# 실행 예시
if __name__ == "__main__":
 create_hybrid_agent(
 task_description="Next.js API 핸들러를 작성하여 /hello 엔드포인트를 생성하고, TypeScript 타입 검증을 포함해주세요."
 )

3.3. 코드 설명

Planner (Claude): anthropic 라이브러리를 사용하여 사용자의 요구사항을 분석하고, 작업의 순서를 정의합니다. 이 과정은 한 번만 발생하므로 고비용 모델을 사용해도 전체 비용에 큰 영향이 없습니다.
Worker (DeepSeek V4): openai 라이브러리를 통해 DeepSeek API를 호출합니다. max_iterations만큼 루프를 돌며 코드를 생성하고, 가상의 피드백(또는 실제 실행 결과)을 받아 수정을 거듭합니다. 이 부분이 가장 많은 토큰을 소비하는 곳입니다.

4. 트러블슈팅 및 팁

1. DeepSeek API 호환성: DeepSeek V4 Pro는 현재 OpenAI SDK와 호환되는 방식으로 제공되는 경우가 많지만, 베이스 URL(Base URL) 설정이 필요할 수 있습니다. (예: https://api.deepseek.com) 공식 문서를 확인해 주세요.

2. 컨텍스트 윈도우(Context Window): DeepSeek 모델은 보통 128k 이상의 긴 컨텍스트 윈도우를 지원합니다. 이는 긴 코드베이스를 분석하거나 대화 기록을 유지하기에 매우 유리합니다. 반복문(Loop)이 돌면서 컨텍스트가 길어지더라도 성능 저하가 적습니다.

3. MCP 통합: 위 파이썬 코드는 단순 예시입니다. 실제로는 mcp_config.json에 정의된 서버와 통신하여 파일 시스템에 접근해야 합니다. 이를 위해 stdio를 통해 MCP 서버와 통신하는 클라이언트 로직을 hybrid_agent.py 내부에 구현해야 완전한 자동화가 가능합니다.

5. 결론: 비용과 성능의 균형

개발자에게 AI는 단순한 채팅창이 아니라 **‘행동하는 에이전트’**가 되어가고 있습니다. 하지만 무비용으로 GPT-4o나 Claude Sonnet을 남용하는 것은 현실적이지 않습니다.

DeepSeek V4와 같은 고성능 오픈소스 모델을 **‘Worker’**로 두고, 고비용 모델을 **‘Planner’**로 활용하는 하이브리드 전략은, 향후 AI 에이전트 개발의 표준적인 패턴이 될 것입니다.

지금 바로 위 코드를 테스트해 보시고, 귀하의 개발 워크플로우에 17배의 효율성을 더해보세요.

MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

Sun, 03 May 2026 10:47:00 +0900

MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

MCP(Model Context Protocol)는 Claude Code 및 다른 AI 도구와 통합할 수 있는 강력한 프로토콜입니다. 이 가이드에서는 첫 번째 MCP 서버를 만드는 과정을 단계별로 안내합니다.

MCP란 무엇인가?

MCP는 AI 에이전트가 외부 도구와 리소스에 접근할 수 있게 하는 표준 프로토콜입니다. 주요 특징:

표준화된 인터페이스: 다양한 도구를 통일된 방식으로 통합
리소스 공유: 파일, 데이터베이스 등의 리소스를 안전하게 접근
확장성: 새로운 도구를 쉽게 추가 가능

기본 MCP 서버 구조

// mcp-server-template.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
 {
 name: 'my-mcp-server',
 version: '1.0.0'
 },
 {
 capabilities: {
 tools: {},
 resources: {}
 }
 }
);

// 도구 등록 예시
server.setRequestHandler(ListToolsRequestSchema, async () => ({
 tools: [
 {
 name: 'my_tool',
 description: '내 도구 설명',
 inputSchema: {
 type: 'object',
 properties: {
 param1: {
 type: 'string',
 description: '파라미터 설명'
 }
 },
 required: ['param1']
 }
 }
 ]
}));

// 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);

실전 예제: 간단한 계산기 MCP 서버

// calculator-mcp-server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';

const server = new Server(
 { name: 'calculator-server', version: '1.0.0' },
 { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
 tools: [
 {
 name: 'calculate',
 description: '기본 수학 연산 수행',
 inputSchema: {
 type: 'object',
 properties: {
 expression: {
 type: 'string',
 description: '계산할 수식 (예: "2 + 2")'
 }
 },
 required: ['expression']
 }
 }
 ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
 if (request.params.name === 'calculate') {
 const expression = request.params.arguments?.expression as string;
 try {
 // 안전한 계산을 위해 Function 대신 eval 사용
 const result = Function(`"use strict"; return (${expression})`)();
 return {
 content: [{
 type: 'text',
 text: `결과: ${result}`
 }]
 };
 } catch (error) {
 return {
 content: [{
 type: 'text',
 text: `계산 오류: ${error}`
 }],
 isError: true
 };
 }
 }
 return { content: [] };
});

Claude Code 설정

MCP 서버를 Claude Code에 등록하려면 ~/.config/claude/settings.json을 수정합니다:

{
 "mcpServers": {
 "calculator": {
 "command": "node",
 "args": ["/path/to/calculator-mcp-server.js"]
 }
 }
}

리소스 제공하기

// 리소스 리스트 제공
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
 resources: [
 {
 uri: 'calc://history',
 name: '계산 기록',
 description: '최근 계산 이력',
 mimeType: 'application/json'
 }
 ]
}));

// 리소스 내용 제공
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 if (request.params.uri === 'calc://history') {
 return {
 contents: [{
 uri: request.params.uri,
 mimeType: 'application/json',
 text: JSON.stringify({ history: [] })
 }]
 };
 }
 throw new Error('리소스를 찾을 수 없습니다');
});

보안 고려사항

입력 검증: 모든 사용자 입력을 검증하고 제한
권한 제한: 최소 권한 원칙 적용
에러 처리: 민감 정보가 에러 메시지에 노출되지 않도록 주의
속도 제한: 과도한 요청을 방지하는 레이트 리밋 구현

배포 및 테스트

# 서버 빌드
npm run build

# 로컬 테스트
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/server.js

# Claude Code에 통합 후 테스트
# 설정 파일 reload 후 Claude Code에서 도구 사용

다음 단계

더 복잡한 도구와 리소스 추가
프롬프트 템플릿 구현
에러 핸들링 개선
로깅 및 모니터링 추가

MCP 서버 개발은 Claude Code의 기능을 확장하고 자동화를 강화하는 훌륭한 방법입니다. 작은 프로젝트부터 시작하여 점진적으로 기능을 확장해보세요.

참고 자료

Claude Code Discord MCP Plugin - asdf bun 경로 문제 해결

Thu, 26 Mar 2026 00:00:00 +0900

문제 상황

Claude Code CLI에서 Discord 채널 연결을 위해 discord 플러그인을 설치했는데 다음과 같은 에러가 발생했습니다.

> discord Plugin · claude-plugins-official · √ enabled
 └ discord MCP · × failed

플러그인은 활성화되었지만, MCP 서버는 실패 상태였습니다.

원인

이 문제는 asdf로 설치한 bun을 사용할 때 발생합니다. Claude Code CLI는 MCP 서버 실행을 위해 bun 명령어를 찾지만, asdf는 셸 래퍼를 사용하므로 시스템 전역 경로에서 실제 바이너리를 찾지 못합니다.

해결 방법

asdf로 설치한 bun의 절대 경로를 직접 입력하여 해결했습니다.

asdf로 설치한 bun 절대 경로 찾기

which bun

또는:

asdf where bun

출력 예시:

/Users/yarang/.asdf/installs/bun/1.x.x/bin/bun

설정 적용

이 절대 경로를 Discord MCP 설정의 실행 경로로 지정하면 문제가 해결됩니다.

핵심 정리

상황	해결 방법
시스템 전역 설치된 bun	`bun` 명령어 사용
asdf로 설치한 bun	절대 경로 직접 입력

asdf를 사용하는 경우, 셸 래퍼가 아닌 실제 바이너리 경로를 지정해야 MCP 서버가 정상적으로 실행됩니다.

참고 자료

[blog-api-server] MCP 블로그 클라이언트 언어 파라미터 추가

Tue, 03 Mar 2026 23:19:28 +0900

[blog-api-server] MCP 블로그 클라이언트 언어 파라미터 추가

개요

MCP (Model Context Protocol) 블로그 클라이언트에 언어 파라미터를 추가하여 한국어/영어 다국어 블로그 관리를 개선했습니다.

변경 사항

blog_create 도구 업�데이트

Tool(
 name="blog_create",
 description="블로그 포스트 생성. 제목과 내용(Markdown)을 입력하면 포스트가 생성되고 Git에 커밋/푸시됩니다.",
 inputSchema={
 "type": "object",
 "properties": {
 "title": {"type": "string", "description": "포스트 제목"},
 "content": {"type": "string", "description": "포스트 내용 (Markdown)"},
 "tags": {"type": "array", "items": {"type": "string"}, "description": "태그 목록"},
 "categories": {"type": "array", "items": {"type": "string"}, "description": "카테고리 목록"},
 "draft": {"type": "boolean", "description": "초안 여부 (기본값: false)"},
 "language": {"type": "string", "description": "언어 (ko, en). 기본값: ko"} # 신규
 },
 "required": ["title", "content"]
 }
)

API 호출 로직

if name == "blog_create":
 result = await client.request("POST", "/posts", data={
 "title": arguments["title"],
 "content": arguments["content"],
 "tags": arguments.get("tags", []),
 "categories": arguments.get("categories", ["Development"]),
 "draft": arguments.get("draft", False),
 "language": arguments.get("language", "ko"), # 기본값: 한국어
 "auto_push": True
 })

사용 방법

Claude Code에서 사용

{
 "mcpServers": {
 "blog": {
 "command": "python3",
 "args": ["/path/to/mcp_blog_client.py"],
 "env": {
 "BLOG_API_URL": "https://blog.fcoinfup.com",
 "BLOG_API_KEY": "your_api_key"
 }
 }
 }
}

한국어 포스트 작성

{
 "tool": "blog_create",
 "arguments": {
 "title": "[프로젝트명] 포스트 제목",
 "content": "# 내용\n\n마크다운 형식의 내용...",
 "tags": ["tag1", "tag2"],
 "categories": ["Development"],
 "language": "ko"
 }
}

영어 포스트 작성

{
 "tool": "blog_create",
 "arguments": {
 "title": "[Project Name] Post Title",
 "content": "# Content\n\nMarkdown formatted content...",
 "tags": ["tag1", "tag2"],
 "categories": ["Development"],
 "language": "en"
 }
}

API 예시

요청 형식

curl -X POST https://blog.fcoinfup.com/api/posts \
 -H "X-API-Key: your_api_key" \
 -H "Content-Type: application/json" \
 -d '{
 "title": "[blog-api-server] Test Post",
 "content": "# Test\n\nThis is a test post.",
 "tags": ["test"],
 "categories": ["Development"],
 "language": "en",
 "auto_push": true
 }'

응답 형식

{
 "success": true,
 "filename": "2026-03-03-001-blog-api-server-test-post.md",
 "path": "/content/en/post/2026-03-03-001-blog-api-server-test-post.md",
 "git": {
 "success": true,
 "commit": "abc123...",
 "branch": "main"
 }
}

파일 경로 규칙

언어	language 값	저장 경로
한국어	`ko`	`content/ko/post/`
영어	`en`	`content/en/post/`

향후 계획

번역 자동화: 언어 파라미터를 활용한 자동 번역 기능
i18n 링크: KO/EN 포스트 간 자동 연결 생성
다국어 지원 확장: 일본어, 중국어 등 추가 언어 지원

결론

MCP 블로그 클라이언트에 언어 파라미터를 추가하여 Claude Code에서 더 편리하게 다국어 블로그를 관리할 수 있게 되었습니다.

영어 버전: English Version

[Cloud Monitor] MCP 도구 구조 및 장단점 분석

Tue, 03 Mar 2026 15:02:49 +0900

[server-monitor] MCP 도구 구조 및 장단점 분석

개요

이 문서는 server-monitor 프로젝트에 구현된 MCP (Model Context Protocol) 도구들의 구조, 장점, 단점을 분석합니다. 총 13개의 MCP 도구가 제공되며, 기존 8개의 Discord MCP 도구와 새로운 5개의 Cloud Monitor MCP 도구로 분류됩니다.

아키텍처 개요

FastMCP 기반 아키텍처

graph TB
 subgraph MCP Server
 A[FastMCP Server] --> B[Discord Tools]
 A --> C[Cloud Monitor Tools]
 B --> D[Gateway Service]
 C --> D
 D --> E[Discord API]
 end

 subgraph Cloud Monitor
 F[SSH Monitor] --> G[OCI Servers]
 F --> H[Mac mini]
 G --> I[Ubuntu]
 H --> J[macOS]
 end

 subgraph Discord
 K[Bot] --> L[Channels]
 K --> M[Threads]
 end

MCP 도구 분류

분류	도구 수	주요 기능
Discord MCP	8	메시지, 스레드 관리
Cloud Monitor MCP	5	서버 모니터링, 메트릭 수집
전체	13	통합 모니터링 플랫폼

도구 상세 분석

1. 기존 Discord MCP 도구 (8개)

1.1 메시지 관리 도구

도구 이름	파라미터	반환값	기능
`discord_send_message`	`channel_id`, `content`, `thread_id?`	결과 메시지	기본 메시지 전송
`discord_get_messages`	`channel_id`, `limit?`, `after?`	메시지 목록	메시지 조회
`discord_wait_for_message`	`channel_id`, `timeout_seconds?`	대기 상태	비동기 메시지 대기 (SSE 미구현)

1.2 스레드 관리 도구

도구 이름	파라미터	반환값	기능
`discord_create_thread`	`channel_id`, `message_id`, `name?`	스레드 정보	스레드 생성
`discord_list_threads`	`channel_id`	스레드 목록	활성 스레드 조회
`discord_archive_thread`	`thread_id`	결과 메시지	스레드 아카이빙 (미구현)

1.3 동시성 관리 도구

도구 이름	파라미터	반환값	기능
`discord_acquire_thread`	`thread_id`, `agent_name`, `timeout?`	락 획득 결과	멀티 에이전트 락
`discord_release_thread`	`thread_id`, `agent_name`	락 해제 결과	에이전트 락 해제

2. 새로운 Cloud Monitor MCP 도구 (5개)

2.1 서버 관리 도구

도구 이름	파라미터	반환값	기능
`cloud_get_server_status`	`server_name`	서버 상태 정보	연결 상태, OS, 메트릭
`cloud_list_servers`	`group?`	서버 목록	그룹 필터링 지원
`cloud_list_ssh_config_hosts`	`group?`	SSH 호스트 목록	SSH 설정 자동 파싱

2.2 모니터링 도구

도구 이름	파라미터	반환값	기능
`cloud_get_metrics`	`server_name`, `metric_types?`	메트릭 데이터	선택적 메트릭 조회
`cloud_set_alert`	`metric_type`, `level`, `threshold`	설정 결과	동적 임계값 구성

아키텍처 구조

1. FastMCP 구조

graph LR
 subgraph "FastMCP Layer"
 A[@mcp.tool decorator] --> B[Tool Function]
 B --> C[Parameter Validation]
 C --> D[Business Logic]
 D --> E[Result Formatting]
 E --> F[Return Response]
 end

 subgraph "Common Components"
 G[Gateway Request] --> H[HTTP Client]
 I[Config Manager] --> J[Cloud Monitor Config]
 K[Error Handler] --> L[Uniform Error Response]
 end

2. 통신 흐름

sequenceDiagram
 participant MCP as MCP Server
 participant GW as Gateway Service
 participant Discord as Discord API
 participant Server as Target Server

 MCP->>GW: HTTP Request
 GW->>Discord: API Call
 Discord-->>GW: Response
 GW-->>MCP: JSON Response

 MCP->>Server: SSH Connection
 Server-->>MCP: Metrics Data
 MCP->>GW: Alert Message
 GW->>Discord: Embed Message

3. 데이터 흐름

Configuration (config.yaml)
 ↓
Server Info parsing
 ↓
SSH Connection
 ↓
Metrics Collection
 ↓
Threshold Check
 ↓
Alert Generation
 ↓
Discord Notification

장점

1. 확장성

모듈형 구조: 각 도구가 독립적으로 작동하며 확장이 용이
플러그인 아키텍처: 새 도구 추가는 데코레이터 추가만으로 가능
클라우드 제공자 추상화: SSH 기반으로 다양한 환경 지원

2. 통합성

통합 플랫폼: Discord와 Cloud Monitor를 단일 MCP 서버에서 통합 관리
자동 연동: 서버 이상 시 자동 Discord 알림
일관된 인터페이스: 모든 도구가 동일한 파라미터 패턴 따름

3. 사용성

직관적인 도구 이름: cloud_get_server_status처럼 명확한 기능 표현
선택적 파라미터: 대부분 파라미터가 선택사항으로 편리
상세한 오류 메시지: 실패 원인을 명확히 표시
JSON 응답: 구조화된 데이터 반환으로 파싱 용이

4. 신뢰성

타임아웃 처리: 모든 요청에 타임아웃 설정
연결 풀링: 성능을 위한 SSH 연결 재사용
예외 처리: 포괄적인 try-catch 블록
상태 추적: 지속적인 서버 상태 모니터링

5. 유지보수성

중앙집중식 구성: config.yaml을 통한 중앙 관리
환경변수 지원: 민감 정보를 환경변수로 분리
로깅 시스템: 상세한 로깅으로 디버깅 용이
버전 관리: 명확한 모듈 버전 구분

단점 및 개선사항

1. 성능 관련

문제점

동기식 처리: 일부 도구가 순차적으로 작동
연결 지연: 모든 SSH 연결 시 새 연결 생성
메모리 사용량: 단일 이벤트 루프에서 모든 처리

개선안

# 비동기 처리 개선 예시
async def concurrent_monitoring(servers):
 tasks = [monitor_server(server) for server in servers]
 return await asyncio.gather(*tasks)

# 연결 풀링 도입
class ConnectionPool:
 def __init__(self, max_connections=10):
 self.pool = asyncio.Queue(maxsize=max_connections)

2. 오류 처리 관련

문제점

구분되지 않은 오류: 모든 오류를 동일하게 처리
복구 메커니즘 부재: 실패 시 자동 복구 로직 없음
상세 로깅 부족: 디버깅을 위한 로그 부족

개선안

# 구분된 오류 처리
class CloudMonitorError(Exception):
 pass

class ConnectionError(CloudMonitorError):
 pass

class MetricCollectionError(CloudMonitorError):
 pass

# 자동 복구 메커니즘
async def resilient_monitoring(server_info, max_retries=3):
 for attempt in range(max_retries):
 try:
 return await monitor_server(server_info)
 except ConnectionError:
 await asyncio.sleep(2 ** attempt)
 raise CloudMonitorError("Max retries exceeded")

3. 기능 관련

문제점

메타데이터 부족: 도구 설명이 너무 간결
검증 부족: 입력값 확인 로직 부족
배치 처리 미지원: 여러 서버를 동시에 처리 불가

개선안

# 상세한 메타데이터
@mcp.tool(
 name="cloud_batch_monitoring",
 description="여러 서버 상태를 한 번에 조회",
 parameters={
 "server_names": {
 "type": "array",
 "items": {"type": "string"},
 "description": "모니터링할 서버 이름 목록"
 }
 }
)
async def cloud_batch_monitoring(server_names: List[str]) -> str:
 # 배치 처리 로직
 pass

4. 보안 관련

문제점

자격증명 노출: 로그에 민감 정보가 노출될 가능성
접근 제어 미구현:任何人이 도구 호출 가능
입력 검증 부족: 악의적 입력에 대한 방어 부족

개선안

# 접근 제어
def require_role(required_role):
 def decorator(func):
 async def wrapper(*args, **kwargs):
 if not has_role(required_role):
 raise PermissionError("Access denied")
 return await func(*args, **kwargs)
 return wrapper
 return decorator

# 입력 검증
@mcp.tool()
async def secure_monitoring(server_name: str):
 if not is_valid_server_name(server_name):
 raise ValueError("Invalid server name")
 # ...

5. 사용성 관련

문제점

문서 부족: 도구 사용에 대한 상세한 문서 없음
예시 미제공: 실제 사용 예시 없음
불일치 반환값: 일부 도구는 JSON, 다른 도구는 문자열 반환

개선안

# 일관된 반환값 형식
@mcp.tool()
async def cloud_get_server_status_v2(server_name: str) -> dict:
 """
 서버 상태를 조회합니다.

 Args:
 server_name (str): 서버 이름

 Returns:
 dict: {
 "success": bool,
 "data": Optional[dict],
 "error": Optional[str],
 "timestamp": str
 }
 """
 # ...
 return {
 "success": True,
 "data": status,
 "error": None,
 "timestamp": datetime.now().isoformat()
 }

결론

1. 전체 평가

server-monitor 프로젝트의 MCP 도구는 다음과 같은 강점을 가집니다:

✅ 우수한 통합: Discord 통합과 서버 모니터링의 완벽한 결합
✅ 확장 가능한 구조: FastMCP를 활용한 모듈형 아키텍처
✅ 실용성: 실제 서버 모니터링에 필요한 모든 기능 제공
✅ 사용 용이성: 직관적인 도구 이름과 단순한 인터페이스

2. 개선 우선순위

우선순위별 개선 계획:

높음: 성능 개선 (비동기 처리, 연결 풀링)
중간: 오류 처리 강화 및 자동 복구 메커니즘
낮음: 보안 강화 및 상세 문서화

3. 향후 방향

마이크로서비스 아키텍처: 각 도구를 독립 서비스로 분리
실시간 모니터링: WebSocket/SSE를 통한 실시간 데이터 수집
자동 확장: 서버 변경에 따른 자동 확장
머신러닝: 이상 탐지를 위한 ML 모델 통합

4. 최종 평가

전체적으로 실제 운영 환경에 적합한 안정성과 기능을 제공하는 잘 설계된 MCP 도구 시스템입니다. 개선이 필요한 부분이 있지만 핵심 기능은 매우 완성도가 높으며, 지속적인 개선을 통해 더욱 강력한 모니터링 플랫폼으로 발전할 잠재력이 있습니다.

작성일: 2026-03-03 저자: server-monitor-team

영어 버전: English Version

[Discord Decision MCP] 아키텍처 설계문서

Mon, 02 Mar 2026 21:36:30 +0900

Discord Decision MCP — 아키텍처 설계문서

1. 프로젝트 개요

1.1 목적

Claude Code가 tmux Teammate 모드로 자율 작업 중, 사용자 결정이 필요한 시점에 Discord를 통해 질문하고 응답을 받아 작업을 재개하는 MCP (Model Context Protocol) 서버입니다.

1.2 핵심 특징

특징	설명
프로젝트당 Bot 1개	각 프로젝트는 독립된 Discord Bot 사용
무한 대기 기본값	Timeout 없이 사용자 응답 대기 (Claude가 독단 진행 금지)
상태 영속화	프로세스 재시작 후에도 대기 상태 복원
한국어 친화적	한글 선택지, Yes/No 응답 지원
MCP 기반 통신	모든 Discord 통신은 MCP Tool을 통해 이루어짐

1.3 버전 정보

버전: 1.0.0
Python 요구사항: >= 3.11
MCP 프레임워크: FastMCP >= 0.1.0

2. 디렉토리 구조

discord-decision/
├── discord_mcp/ # 메인 패키지
│ ├── __init__.py
│ ├── server.py # MCP 서버 진입점
│ ├── config.py # 환경변수 설정 관리
│ │
│ ├── bot/ # Discord API 클라이언트
│ │ ├── __init__.py
│ │ ├── client.py # REST API 클라이언트 (httpx)
│ │ └── gateway.py # WebSocket 게이트웨이 (수신 전용)
│ │
│ ├── decision/ # 결정 요청 관리
│ │ ├── __init__.py
│ │ ├── manager.py # 결정 요청 생명주기 관리
│ │ ├── poller.py # Discord Polling 및 응답 대기
│ │ ├── parser.py # 사용자 응답 파싱
│ │ └── state.py # 상태 영속화 (JSON 파일)
│ │
│ ├── tools/ # MCP Tools 구현
│ │ ├── __init__.py
│ │ ├── ask.py # discord_ask_decision
│ │ ├── notify.py # discord_notify
│ │ ├── report.py # discord_report_progress
│ │ ├── status.py # discord_check_pending
│ │ ├── inbox.py # discord_read_inbox, discord_clear_inbox
│ │ └── _templates.py # Discord 메시지 템플릿
│ │
│ └── daemon/ # 감시 데몬
│ ├── __init__.py
│ ├── watcher.py # Discord 채널 감시 (discord-watch CLI)
│ └── inbox.py # Inbox 파일 관리
│
├── scripts/ # 유틸리티 스크립트
│ └── start-discord-watch.sh
│
├── tests/ # 테스트 스위트
│ ├── __init__.py
│ ├── test_parser.py
│ └── test_state.py
│
├── CLAUDE.md # Claude Code 프로젝트 지침
├── README.md # 프로젝트 설명
├── pyproject.toml # 프로젝트 설정 및 의존성
└── mcp.json.example # MCP 설정 예시

3. 주요 모듈 설명

3.1 서버 진입점 (`server.py`)

역할: FastMCP 서버 생성 및 MCP Tool 등록

mcp = FastMCP(name="discord-decision-mcp")
# Tool 등록
mcp.tool()(discord_ask_decision)
mcp.tool()(discord_notify)
mcp.tool()(discord_report_progress)
mcp.tool()(discord_check_pending)
mcp.tool()(discord_read_inbox)
mcp.tool()(discord_clear_inbox)

실행 방법:

discord-mcp # 또는 python -m discord_mcp.server

3.2 설정 관리 (`config.py`)

역할: 환경변수에서 설정값 로드

환경변수	설명	기본값
`DISCORD_BOT_TOKEN`	Discord Bot Token (“Bot " 접두사 포함)	필수
`DISCORD_CHANNEL_ID`	기본 질문 채널 ID	필수
`PROJECT_NAME`	question_id 생성에 사용	“project”
`PENDING_DIR`	상태 파일 저장 경로	`~/.claude/pending_decisions`
`POLL_INTERVAL_SECONDS`	Discord polling 간격 (초)	5

3.3 Discord API 클라이언트 (`bot/`)

3.3.1 REST API 클라이언트 (`client.py`)

역할: Discord REST API 호출 (httpx 기반)

주요 메서드:

class DiscordClient:
 async def send_message(channel_id, content, embeds=None)
 async def get_messages(channel_id, after=None, limit=50)
 async def create_thread(channel_id, name, first_message)
 async def archive_thread(thread_id)

특징:

Rate limit 자동 처리 (429 응답 시 재시도)
싱글턴 패턴 (get_client())

3.3.2 WebSocket 게이트웨이 (`gateway.py`)

역할: Discord Gateway WebSocket 연결 (수신 전용)

특징:

MESSAGE_CREATE 이벤트 실시간 수신
Polling 방식의 지연을 5초 → 즉시로 단축
Gateway 없이도 시스템 정상 동작 (Polling fallback)
자동 재연결 (Exponential backoff)

class GatewayClient:
 async def run() # 이벤트 수신 시작
 async def stop() # 연결 종료

3.4 결정 요청 관리 (`decision/`)

3.4.1 DecisionManager (`manager.py`)

역할: 결정 요청의 전체 생명주기 조율

class DecisionManager:
 async def ask(question, context, options, timeout_seconds, thread_id) -> PollResult
 async def restore_pending() -> list[DecisionState]

흐름:

중복 질문 확인
Thread 생성 (또는 기존 Thread 재사용)
상태 파일 생성 (~/.claude/pending_decisions/{question_id}.json)
Poller 실행하여 응답 대기
SIGHUP 시그널 핸들러로 disconnected 상태 표시

3.4.2 DecisionPoller (`poller.py`)

역할: Discord 채널을 polling하여 응답 대기

class DecisionPoller:
 async def wait(state: DecisionState) -> PollResult

특징:

기본값: 무한 대기 (timeout_seconds=None)
tmux pane에 실시간 대기 상태 표시 (ANSI escape)
모호한 응답 시 최대 2회 재질문

3.4.3 응답 파서 (`parser.py`)

역할: 사용자 Discord 응답 파싱

지원 패턴:

선택지 매칭: “A”, “a”, “A번”, “A로 해줘”, “1”, “1번”
긍정/부정: “yes”, “네”, “예”, “no”, “아니요”
자연어: 15자 이상 또는 한글 3자 이상

def parse_response(text: str, options: list[str]) -> ParseResult
def build_clarify_message(...) -> str # 재질문 메시지 생성

3.4.4 상태 저장소 (`state.py`)

역할: 결정 요청 상태를 JSON 파일로 영속화

상태 파일 위치: ~/.claude/pending_decisions/{question_id}.json

class DecisionState(BaseModel):
 question_id: str
 project: str
 question: str
 context: str
 options: list[str]
 timeout_seconds: float | None
 thread_id: str
 message_id: str
 asked_at: str
 status: Literal["pending", "disconnected", "resolved", "aborted", "timeout"]
 clarify_attempts: int
 resolved_at: str | None
 resolution: str | None
 selected_option: str | None

class StateStore:
 def save(state: DecisionState)
 def load(question_id: str) -> DecisionState | None
 def load_all_pending() -> list[DecisionState]
 def resolve(question_id, resolution, selected_option)
 def is_duplicate(question: str) -> bool

3.5 MCP Tools (`tools/`)

Tool	블로킹	설명
`discord_ask_decision`	✅	사용자 결정 요청
`discord_notify`	❌	진행 상황 알림
`discord_report_progress`	❌	작업 완료 리포트
`discord_check_pending`	❌	미해결 질문 확인
`discord_read_inbox`	❌	Inbox 메시지 조회
`discord_clear_inbox`	❌	Inbox 메시지 삭제

3.6 감시 데몬 (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

역할: Discord 채널을 감시하여 새 메시지를 inbox 파일에 기록

실행 방법:

discord-watch --interval 10
# 또는
tmux new-session -d -s discord-watch 'uv run discord-watch'

특징:

지정된 채널(들)을 주기적으로 polling
새로운 사용자 메시지 감지 시 inbox에 기록
tmux pane에 상태 표시

3.6.2 InboxStore (`inbox.py`)

역할: Discord 메시지를 저장하는 JSON 파일 기반 저장소

Inbox 파일 위치: ~/.claude/discord_inbox.json

class InboxMessage:
 message_id: str
 channel_id: str
 thread_id: str | None
 author: str
 author_id: str
 content: str
 timestamp: str
 read: bool

class InboxStore:
 def add_message(msg: InboxMessage)
 def get_unread() -> list[InboxMessage]
 def mark_read(message_id: str)
 def clear_read() # 읽은 메시지 삭제

4. 데이터 흐름도

4.1 결정 요청 흐름

┌─────────────────┐
│ Claude Code │
└────────┬────────┘
 │ discord_ask_decision()
 ▼
┌─────────────────────────────────────┐
│ MCP Server (server.py) │
│ ┌───────────────────────────────┐ │
│ │ DecisionManager.ask() │ │
│ │ 1. 중복 확인 │ │
│ │ 2. Thread 생성 │ │
│ │ 3. 상태 파일 저장 │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 ▼
┌─────────────────────────────────────┐
│ DecisionPoller.wait() │
│ ┌───────────────────────────────┐ │
│ │ Polling 루프 │ │
│ │ 1. tmux 상태 업데이트 │ │
│ │ 2. Discord API 호출 │ │
│ │ 3. 응답 파싱 │ │
│ │ 4. 모호하면 재질문 │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 │
 ┌─────────┴─────────┐
 ▼ ▼
┌───────────────────┐ ┌──────────────────┐
│ Discord REST API │ │ Discord Thread │
│ (client.py) │ │ │
└───────────────────┘ └────────┬─────────┘
 │
 ┌────────▼────────┐
 │ 사용자 응답 │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ parser.py │
 │ - 선택지 매칭 │
 │ - 모호성 감지 │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ store.resolve()│
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ PollResult │
 │ 반환 │
 └─────────────────┘

4.2 감시 데몬 흐름

┌─────────────────────────────────────────────┐
│ DiscordWatcher (daemon/watcher.py) │
│ ┌───────────────────────────────────────┐ │
│ │ 1. 초기 메시지 ID 설정 │ │
│ │ 2. 주기적 Polling (기본 10초) │ │
│ │ 3. 새 메시지 감지 │ │
│ │ 4. InboxStore.add_message() │ │
│ └───────────────────┬───────────────────┘ │
└──────────────────────┼──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ ~/.claude/discord_inbox.json │
│ { │
│ "last_message_id": "...", │
│ "messages": [ │
│ { "message_id": "...", ... } │
│ ] │
│ } │
└──────────────────────┬──────────────────────┘
 ▲
 │ discord_read_inbox()
┌──────────────────────┴──────────────────────┐
│ Claude Code │
└─────────────────────────────────────────────┘

4.3 세션 복원 흐름

┌─────────────────────────────────────────────┐
│ Claude Code 세션 시작 │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ discord_check_pending() │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ DecisionManager.restore_pending() │
│ ┌───────────────────────────────────────┐ │
│ │ 1. ~/.claude/pending_decisions/*.json │ │
│ │ 2. Discord API로 Thread 확인 │ │
│ │ 3. 답변 있으면 → 자동 해결 │ │
│ │ 4. 답변 없으면 → 재시작 알림 │ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

5. MCP 도구 목록

5.1 discord_ask_decision

설명: 사용자 결정이 필요할 때 Discord Thread에 질문 전송 후 응답 대기 (블로킹)

파라미터:

이름	타입	필수	설명
`question`	string	✅	질문 내용
`context`	string	✅	현재 작업 상황
`options`	string[]	❌	선택지 목록 (빈 배열이면 자유 응답)
`timeout_seconds`	float	❌	대기 Timeout (null이면 무한 대기)
`thread_id`	string	❌	기존 Thread ID (null이면 새 Thread 생성)

반환값:

{
 "success": true,
 "answer": "A) 지금 실행",
 "selected_option": "A) 지금 실행",
 "question_id": "project_20260301_abc123",
 "timed_out": false,
 "aborted": false
}

5.2 discord_notify

설명: 진행 상황을 Discord에 알림 (논블로킹)

파라미터:

이름	타입	필수	설명
`message`	string	✅	알림 메시지
`level`	string	❌	info/warning/success/error (기본값: info)
`thread_id`	string	❌	전송할 Thread ID (null이면 기본 채널)

5.3 discord_report_progress

설명: 작업 완료 또는 단계 완료 시 결과 리포트 (논블로킹)

파라미터:

이름	타입	필수	설명
`title`	string	✅	리포트 제목
`summary`	string	✅	작업 결과 요약
`details`	string[]	❌	세부 항목 목록
`thread_id`	string	❌	전송할 Thread ID

5.4 discord_check_pending

설명: 세션 시작 시 미해결 질문 확인 (논블로킹)

파라미터: 없음

반환값:

{
 "has_pending": true,
 "pending_questions": [
 {
 "question_id": "project_20260301_abc123",
 "question": "배포할까요?",
 "thread_id": "1234567890",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending"
 }
 ]
}

5.5 discord_read_inbox

설명: Inbox에 저장된 메시지 조회 (논블로킹)

파라미터:

이름	타입	기본값	설명
`unread_only`	boolean	true	읽지 않은 메시지만 반환
`mark_read`	boolean	false	조회한 메시지를 읽음으로 표시

5.6 discord_clear_inbox

설명: Inbox 메시지 삭제 (논블로킹)

파라미터:

이름	타입	기본값	설명
`read_only`	boolean	true	읽은 메시지만 삭제

6. 의존성 정보

6.1 핵심 의존성

패키지	버전	용도
`fastmcp`	>= 0.1.0	MCP 서버 프레임워크
`httpx`	>= 0.27.0	비동기 HTTP 클라이언트
`websockets`	>= 12.0	WebSocket 클라이언트
`python-dotenv`	>= 1.0.0	환경변수 로드
`pydantic`	>= 2.0.0	데이터 모델 검증
`anyio`	>= 4.0.0	비동기 실행

6.2 개발 의존성

패키지	용도
`pytest`	테스트 프레임워크
`pytest-asyncio`	비동기 테스트 지원
`pytest-mock`	Mock 지원
`respx`	httpx mocking

6.3 CLI 명령어

discord-mcp # MCP 서버 실행
discord-watch # 감시 데몬 실행

7. 상태 파일 형식

7.1 결정 상태 파일

위치: ~/.claude/pending_decisions/{question_id}.json

{
 "question_id": "project_20260301_abc123",
 "project": "my-project",
 "question": "DB 마이그레이션을 실행할까요?",
 "context": "v1→v2 스키마 변경",
 "options": ["A) 지금 실행", "B) 스테이징 먼저", "C) 보류"],
 "timeout_seconds": null,
 "thread_id": "1234567890",
 "message_id": "0987654321",
 "asked_at": "2026-03-01T10:30:00Z",
 "status": "pending",
 "clarify_attempts": 0,
 "resolved_at": null,
 "resolution": null,
 "selected_option": null
}

7.2 Inbox 파일

위치: ~/.claude/discord_inbox.json

{
 "last_message_id": "1234567890",
 "messages": [
 {
 "message_id": "1234567890",
 "channel_id": "1234567890",
 "thread_id": null,
 "author": "username",
 "author_id": "1234567890",
 "content": "메시지 내용",
 "timestamp": "2026-03-01T00:00:00Z",
 "read": false
 }
 ]
}

8. 아키텍처 원칙

8.1 설계 원칙

싱글톤 패턴: DiscordClient, StateStore, InboxStore는 모듈 레벨 싱글턴
상태 영속화: 모든 결정 요청 상태는 파일로 영속화
무한 대기 기본값: Claude가 독단적으로 진행하지 않도록 timeout 기본값은 None
재질문 제한: 모호한 응답은 최대 2회까지만 재질문
Rate Limit 처리: Discord API 429 응답 시 자동 대기 후 재시도

8.2 에러 handling

상황	처리 방법
Discord API 429	자동 대기 후 재시도 (최대 5회)
WebSocket 연결 끊김	Exponential backoff로 재연결
응답 파싱 실패	최대 2회 재질문 후 중단
Timeout 발생	작업 중단 알림 후 aborted 상태
세션 끊김 (SIGHUP)	disconnected 상태로 저장

문서 버전: 1.0.0 마지막 수정: 2026-03-02

영어 버전: English Version

[Discord MCP] Gateway 아키텍처 설계

Sun, 01 Mar 2026 01:13:00 +0900

Claude Code 팀에서 Discord를 통한 사용자 소통을 위해 Discord Gateway Service를 설계했다. 이 글에서는 주요 아키텍처 결정 사항과 user_comm Agent 설계를 정리한다.

1. 전체 아키텍처

구성 요소

계층	구성요소	역할
Discord	Bot, Channel, Thread	사용자 인터페이스
Gateway	WebSocket, REST API, SSE	메시지 라우팅
MCP	gcp-mcp, oci-mcp, db-mcp	도구 실행
user_comm	Discord Agent	사용자 소통 담당

메시지 흐름

flowchart LR
 subgraph D[Discord]
 U[User]
 end
 subgraph G[Gateway :8081]
 WS[WebSocket]
 API[REST API]
 SSE[SSE]
 end
 subgraph A[Claude Code Team]
 UC[user_comm]
 GCP[gcp-mcp]
 OCI[oci-mcp]
 DB[db-mcp]
 end

 U --> WS
 WS --> UC
 UC --> API
 API --> GCP
 API --> OCI
 API --> DB
 GCP --> UC
 OCI --> UC
 DB --> UC
 UC --> SSE
 SSE --> U

2. user_comm Agent (사용자 소통 담당)

역할 및 책임

user_comm Agent는 Claude Code 팀의 멤버로서 Discord 채널을 통해 사용자와 소통하고 다른 agent들과 협업합니다.

기능	설명
입력 수신	Discord 메시지를 받아 적절한 agent에게 전달
의견 요청	다른 agent의 요청으로 사용자 의견 질의
알림/보고	시스템 상태, 경고, 리포트 전송
팀 통신	다른 agent와 메시지 송수신

내부 구조

flowchart TB
 subgraph UC[user_comm Agent]
 DBot[Discord Bot]
 Agent[UserCommAgent]
 TComm[TeamCommunicator]
 DBot <--> Agent
 Agent <--> TComm
 end
 subgraph DAPI[Discord API]
 M[Messages]
 B[Buttons]
 T[Threads]
 end
 subgraph O[Other Agents]
 GCP[gcp-mcp]
 OCI[oci-mcp]
 AL[alert-mcp]
 end

 DBot <--> M
 DBot <--> B
 DBot <--> T
 TComm --> GCP
 TComm --> OCI
 TComm --> AL

메시지 타입

class MessageType(Enum):
 TASK_REQUEST = "task_request" # 작업 요청
 NOTIFICATION = "notification" # 알림
 OPINION_REQUEST = "opinion_request" # 의견 요청
 OPINION_RESPONSE = "opinion_response" # 의견 응답
 STATUS_REPORT = "status_report" # 상태 보고
 ERROR = "error" # 에러

주요 기능 동작

입력 수신 (Discord → Agent)

사용자: "@gcp-monitor 서버 상태 확인"
 → DiscordBot.on_message
 → UserCommAgent._parse_command (target: gcp-monitor)
 → TeamCommunicator.send_to_agent
 → Discord: "gcp-monitor에게 요청을 전달했습니다."

의견 요청 (Agent → Discord)

gcp-monitor: "디스크 정리할까요?" → user_comm
 → DiscordBot.ask_opinion (버튼 또는 답장 대기)
 → 사용자 응답
 → TeamCommunicator.send_to_agent (응답 전달)

알림/보고 (Agent → Discord)

oci-monitor: "디스크 92% 경고" → user_comm
 → DiscordBot.send_message (Embed 형식)

3. Redis 없이 동작하는 가벼운 아키텍처

왜 Redis를 제거했나?

항목	Redis 사용	In-Memory 사용
Thread Lock	Redis SET NX	Python dict
이벤트 분배	Redis Streams	SSE 직접
상태 저장	Redis Cache	메모리 캐시

결론: 단일 인스턴스 환경에서는 In-Memory로 충분

Gateway 구조

flowchart TB
 subgraph GW[Gateway Service]
 Bot[Discord Bot]
 subgraph C[Core Components]
 Lock[Thread Lock]
 Cache[Message Cache]
 SSEMgr[SSE Manager]
 end
 end
 DAPI[Discord API] <--> Bot
 Bot --> Lock
 Bot --> Cache
 Bot --> SSEMgr
 SSEMgr --> Clients[WebSocket Clients]

구성요소 상세

모듈	역할	특징
Discord Bot	WebSocket 연결	자동 재연결
Thread Lock	동시성 제어	5분 타임아웃
Message Cache	메시지 보관	최대 1000개
SSE Manager	실시간 전송	모든 MCP에 브로드캐스트

4. MCP 선택 방식: 4단계 하이브리드

선택 우선순위

순위	방식	예시	설명
1	슬래시 커맨드	`/gcp status`	가장 명시적
2	@멘션	`@gcp-monitor status`	자연스러운 대화
3	키워드 감지	`gcp 서버 상태`	키워드 자동 인식
4	채널별 지정	#gcp-모니터링	채널 기본 MCP

Fallback 동작 순서

flowchart TD
 A[Message Received] --> B{Slash Command?}
 B -->|Yes| C[Route to MCP]
 B -->|No| D{Mention?}
 D -->|Yes| C
 D -->|No| E{Keyword?}
 E -->|Yes| C
 E -->|No| F{Channel Default?}
 F -->|Yes| C
 F -->|No| G[Broadcast]

슬래시 커맨드 목록

커맨드	MCP	설명
`/gcp status [server]`	gcp-mcp	GCP 서버 상태
`/gcp list`	gcp-mcp	GCP 인스턴스 목록
`/oci status [server]`	oci-mcp	OCI 서버 상태
`/oci list`	oci-mcp	OCI 인스턴스 목록
`/db query <sql>`	db-mcp	DB 쿼리 실행
`/db list`	db-mcp	DB 목록
`/alert check`	alert-mcp	알림 확인

5. Thread Lock 규칙

락 동작 방식

sequenceDiagram
 participant M1 as gcp-mcp
 participant GW as Gateway
 participant M2 as oci-mcp
 participant DT as Discord Thread

 Note over M1,DT: Lock Acquisition
 M1->>+GW: Lock request
 GW-->>-M1: Lock acquired
 M1->>DT: Send response

 Note over M2,GW: Lock Conflict
 M2->>GW: Lock request
 GW-->>M2: Lock failed

 Note over M1,GW: 5min timeout
 GW->>GW: Auto-release lock

 Note over M2,GW: Lock Retry
 M2->>+GW: Lock request
 GW-->>-M2: Lock acquired

Lock API

Method	Endpoint	설명
`POST`	`/api/threads/{id}/acquire`	락 획득
`POST`	`/api/threads/{id}/release`	락 해제
`GET`	`/api/threads/{id}/lock`	락 상태 확인

요청/응답 예시

락 획득 요청

POST /api/threads/123456/acquire
{
 "agent_name": "gcp-mcp",
 "timeout": 300
}

락 획득 응답

{
 "acquired": true,
 "thread_id": "123456",
 "agent": "gcp-mcp"
}

6. MCP 도구 (8개)

도구 목록

도구	설명	주요 파라미터
`discord_send_message`	메시지 전송	channel_id, content
`discord_get_messages`	메시지 조회	channel_id, limit
`discord_wait_for_message`	메시지 대기	channel_id, timeout
`discord_create_thread`	스레드 생성	channel_id, message_id
`discord_list_threads`	스레드 목록	channel_id
`discord_archive_thread`	스레드 아카이브	thread_id
`discord_acquire_thread`	락 획득	thread_id, agent_name
`discord_release_thread`	락 해제	thread_id, agent_name

도구 관계도

flowchart LR
 subgraph Lock[Lock Tools]
 Acquire[acquire_thread]
 Release[release_thread]
 end
 subgraph Thread[Thread Tools]
 Create[create_thread]
 List[list_threads]
 Archive[archive_thread]
 end
 subgraph Msg[Message Tools]
 Send[send_message]
 Get[get_messages]
 Wait[wait_for_message]
 end

 Acquire --> Create
 Create --> Send
 Send --> Release

사용 예시

# 메시지 전송
discord_send_message(
 channel_id="123456789",
 content="서버 상태: 정상"
)

# 스레드 생성
discord_create_thread(
 channel_id="123456789",
 message_id="987654321",
 name="상태 확인"
)

# 락 획득
discord_acquire_thread(
 thread_id="111222333",
 agent_name="gcp-mcp",
 timeout=300
)

7. 파일 구조

flowchart TB
 subgraph P[server_monitor/]
 subgraph Gw[gateway/]
 M1[main.py]
 M2[discord_ws.py]
 M3[thread_lock.py]
 M4[sse.py]
 end
 subgraph Uc[user_comm/]
 A1[agent.py]
 A2[discord_bot.py]
 A3[team_comm.py]
 end
 subgraph Mcp[discord_mcp/]
 S1[server.py]
 end
 subgraph Sh[mcp_shared/]
 MO[monitor/]
 end
 subgraph Doc[docs/]
 D1[MCP_SELECTION_STRATEGY.md]
 D2[MCP_ROUTING_POLICY.md]
 end
 end

디렉토리 설명

경로	설명
`gateway/`	Gateway Service (FastAPI)
`user_comm/`	사용자 소통 Agent
`discord_mcp/`	MCP Server (8개 도구)
`mcp_shared/`	공유 MCP 도구
`docs/`	문서

8. 실행 방법

로컬 실행

# Gateway Service 시작
uvicorn gateway.main:app --host 0.0.0.0 --port 8081

# user_comm Agent 시작 (독립 모드)
python main.py --standalone

# user_comm Agent 시작 (팀 모드)
python main.py --team server-monitor

# 헬스체크
curl http://localhost:8081/health

# 응답
{"status": "healthy", "discord_connected": true}

Claude Code MCP 설정

// ~/.claude/settings.json
{
 "mcpServers": {
 "discord-gateway": {
 "command": "python3",
 "args": ["/path/to/discord_mcp/server.py"],
 "env": {
 "GATEWAY_URL": "http://localhost:8081"
 }
 }
 }
}

9. 로드맵

Phase 1: 완료

FastAPI Gateway Service
Discord WebSocket 연결
Thread Lock (In-Memory)
SSE 브로드캐스트
MCP Server (8개 도구)

Phase 2: 진행 예정

user_comm Agent 구현
슬래시 커맨드 구현
채널별 기본 MCP 설정
키워드 자동 감지
라우팅 설정 파일

Phase 3: 선택 사항

API 인증 (API Key)
Rate Limiting
메시지 영속성 (SQLite)

결론

가벼운 아키텍처로 시작해서 필요시 확장하는 전략을 선택했다.

항목	현재	향후
상태 저장	In-Memory	SQLite (필요시)
분산 락	미사용	Redis (다중 인스턴스 시)
인증	없음	API Key (필요시)
사용자 소통	Gateway 직접	user_comm Agent

단일 인스턴스에서는 현재 구조로 충분하며, 트래픽이 늘어나면 점진적으로 확장할 계획이다. user_comm Agent를 통해 사용자와의 소통을 체계화하고, 팀 내 다른 agent들과의 협업을 효율화한다.

영어 버전: English Version

[Claude Code] 팀 에이전트 통신 아키텍처

Sat, 28 Feb 2026 14:07:38 +0900

Claude Code 팀 에이전트 간 통신 아키텍처 설계

개요

Claude Code에서 여러 AI 에이전트가 협업할 때 효율적인 통신 방식이 필요합니다. 이 글에서는 Discord와 연동된 서버 모니터링 팀을 구축하며 설계한 통신 아키텍처를 공유합니다.

문제 정의

Claude Code에는 두 가지 유형의 에이전트가 있습니다:

Python 프로세스 (Daemon)
- Discord Gateway, user_comm_daemon 등
- 항상 실행 중, 파일 시스템 접근 가능
LLM Agent (Task로 생성)
- gcp-monitor, oci-monitor, alert-manager 등
- SendMessage 도구 사용, Claude Code 네이티브 통신

이 두 유형 간의 통신이 필요했습니다.

고려한 방식들

1. 파일 기반 메시지 큐 (기존)

장점: 구현 단순, 의존성 없음
단점: 지연 (~1초), 파일 관리 필요

2. WebSocket

장점: 실시간 양방향 통신
단점: 서버/클라이언트 구현 필요

3. gRPC

장점: 강력한 타입 체크, 스트리밍
단점: proto 파일 관리, 높은 복잡도

4. SQLite 메시지 허브 (채택)

장점: 빠름 (~10ms), 트랜잭션, 추가 의존성 없음
단점: 단일 머신에서만 동작

최종 아키텍처

┌─────────────────────────────────────────────────────────────────┐
│ SQLite Message Hub (messages.db) │
│ ~/.claude/teams/{team}/messages.db │
└───────────────────────────┬─────────────────────────────────────┘
 │
 ┌───────────────────┼───────────────────┐
 ↓ ↓ ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Discord │ │ Python │ │ LLM │
│ Gateway │ │ Daemon │ │ Agent │
│ (직접 접근) │ │ (직접 접근) │ │ (MCP Tool) │
└──────────────┘ └──────────────┘ └──────────────┘

SQLite Message Hub 구조

메시지 테이블

CREATE TABLE messages (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 message_id TEXT UNIQUE NOT NULL,
 sender TEXT NOT NULL,
 recipient TEXT, -- NULL = broadcast
 message_type TEXT DEFAULT 'message',
 content TEXT NOT NULL,
 priority TEXT DEFAULT 'normal',
 metadata TEXT DEFAULT '{}',
 status TEXT DEFAULT 'pending',
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 processed_at TIMESTAMP,
 expires_at TIMESTAMP
);

에이전트 상태 테이블

CREATE TABLE agent_status (
 agent_name TEXT PRIMARY KEY,
 status TEXT DEFAULT 'offline',
 last_heartbeat TIMESTAMP,
 metadata TEXT DEFAULT '{}'
);

통신 방식

LLM Agent ↔ LLM Agent

SendMessage 사용 (Claude Code 네이티브)
자동 관리, idle notification 제공

Python ↔ LLM Agent

SQLite Hub + MCP Tool
Python은 직접 SQLite 접근
LLM Agent는 MCP Tool로 접근

MCP Server 구현

LLM Agent를 위한 MCP 도구들:

@server.list_tools()
async def list_tools():
 return [
 Tool(name="team_send_message", ...),
 Tool(name="team_read_messages", ...),
 Tool(name="team_broadcast", ...),
 Tool(name="team_get_status", ...),
 Tool(name="team_update_status", ...),
 ]

메시지 플로우 예시

1. Discord 사용자: "안녕"
 ↓
2. Discord Gateway → SQLite: INSERT message
 ↓
3. user_comm Daemon → SQLite: SELECT pending
 ↓
4. user_comm → SQLite: INSERT response
 ↓
5. Discord Gateway → SQLite: SELECT response
 ↓
6. Discord 채널: "안녕하세요! 👋"

성능 비교

방식	지연 시간	안정성	복잡도
파일 기반	~1000ms	보통	낮음
WebSocket	~5ms	높음	중간
SQLite	~10ms	높음	낮음

결론

SQLite Message Hub + MCP Server 조합이 Claude Code 팀 에이전트 통신에 가장 적합했습니다:

낮은 지연: 파일 기반보다 100배 빠름
안정성: 트랜잭션으로 데이터 무결성 보장
단순함: 추가 의존성 없이 Python 내장 sqlite3 사용
유연성: Python과 LLM Agent 모두 동일한 데이터 소스 사용

코드

핵심 컴포넌트:

message_hub.py: SQLite Message Hub
team_comm_mcp_server.py: MCP Server
discord_gateway.py: Discord 연동 게이트웨이
user_comm_daemon.py: 메시지 처리 데몬

영어 버전: English Version

[MCP] 블로그 서버 개선 킥오프

Wed, 25 Feb 2026 00:00:00 +0900

블로그 MCP 서버 개선 프로젝트 킥오프 회의록

날짜: 2026-02-25 프로젝트: 블로그 MCP 서버 개선 참석자: team-lead, backend-dev, search-specialist, qa-tester, meeting-writer 문서 작성: meeting-writer

1. 회의 개요

1.1 회의 목적

ARCHITECTURE.md에 정의된 개선 로드맵에 따라 블로그 MCP 서버의 안정성과 성능을 개선하기 위한 프로젝트 킥오프

1.2 프로젝트 범위

블로그 저장소: /Users/yarang/workspaces/agent_dev/blogs
API 서버: /Users/yarang/workspaces/agent_dev/blog-api-server

2. 프로젝트 배경

2.1 시스템 현황

현재 블로그 시스템은 다음과 같은 구조로 운영되고 있습니다:

Claude Code (MCP Client)
 ↓ HTTP POST /posts
API Server (blog-api-server)
 ↓ Git clone/pull, Git commit/push
GitHub (yarang/blogs)
 ↓ GitHub Actions 트리거
Hugo Build + Deploy
 ↓
Blog (blog.fcoinfup.com)

2.2 식별된 문제점

🔴 P0 - 심각한 문제

동시성 제어 부족: 전역 threading.Lock()만 사용하여 멀티프로세스 환경에서 경쟁 조건 발생 가능
검색 기능 버그: search_posts()가 한국어 디렉토리만 검색하여 영어 포스트가 검색되지 않음

🟡 P1 - 확장성 문제

매 요청마다 Git Pull 실행: 불필요한 네트워크 호출, 지연 시간 증가
파일 기반 검색 (O(n)): 포스트가 100개 이상이 되면 성능 저하
전역 인스턴스 의존: 테스트 어려움, 의존성 주입 불가

🟢 P2 - 유지보수성 문제

중복된 Git 코드 (GitManager와 GitHandler 이중 존재)
언어 감지 로직 불안정
광범위한 예외 처리

3. 팀 구성

역할	담당자	주요 책임
team-lead	프로젝트 리더	프로젝트 총괄, 조율
backend-dev	백엔드 개발자	동시성 제어, Git 최적화
search-specialist	검색 전문가	검색 기능 개선
qa-tester	QA 테스터	테스트 및 품질 보증
meeting-writer	회의록 작성자	회의록 정리 및 문서화

4. 작업 항목 및 진행 상황

4.1 검색 버그 수정 ✅ 완료

담당자: search-specialist
우선순위: P0
결과:
- ARCHITECTURE.md의 P0 버그는 이미 수정되어 있었음 확인
- test_search.py 12개 테스트 케이스로 검증 완료
- 모든 언어 디렉토리(ko, en) 검색 지원

4.2 Git Pull 최적화 ✅ 완료

담당자: backend-dev
우선순위: P1
결과:
- MCP 클라이언트에 CacheManager 도입 (TTL 5분)
- 쓰기 작업 후 캐시 무효화 구현
- 위치: .claude/mcp_server.py:25-71

4.3 동시성 제어 강화 ✅ 완료

담당자: backend-dev
우선순위: P1
결과:
- MCP 클라이언트에 asyncio.Lock 도입
- 쓰기 작업 간 충돌 방지

4.4 기존 테스트 코드 검증 🔄 진행 중

담당자: qa-tester
우선순위: QA
현재 상황: 진행 중

4.5 ARCHITECTURE.md 업데이트 ✅ 완료

담당자: team-lead
결과:
- 완료된 작업 반영
- 진행 상태 표시 (✅ 완료, 🔄 진행 중, ⚡ 부분 완료)

5. 주요 성과

개선 전

매 요청마다 Git Pull 실행 (최대 60초 타임아웃)
한국어 포스트만 검색 가능
동시성 제어 부족

개선 후

캐싱 도입: TTL 5분으로 불필요한 API 호출 최소화
다국어 검색: 한국어, 영어 포스트 모두 검색 지원
동시성 제어: asyncio.Lock으로 쓰기 작업 충돌 방지

6. 테스트 커버리지

테스트 항목	상태
다국어 검색 (ko, en)	✅
Relevance 정렬	✅
대소문자 무시 검색	✅
결과 구조 검증	✅
캐싱 동작	✅
연결 풀링	✅
에러 핸들링	✅

7. 다음 단계 (중기 계획)

P2 - 구조 개선

Git 클래스 통합: GitManager와 GitHandler 통합
의존성 주입: FastAPI Depends 활용
인덱스 기반 검색: Whoosh 또는 Meilisearch 도입 검토

8. 회의록 정리

이 회의록은 다음 내용을 포함합니다:

프로젝트 킥오프 논의 사항
팀 구성 및 역할 분담
작업 항목별 진행 상황
완료된 작업 요약
향후 계획

본 회의록은 meeting-writer가 작성했으며, 프로젝트 진행 상황에 따라 업데이트됩니다.

영어 버전: English Version

[MCP] 블로그 자동화 시스템 구축

Sat, 21 Feb 2026 21:30:00 +0900

들어가며

Model Context Protocol(MCP)을 활용하여 Claude가 직접 블로그 포스트를 관리할 수 있는 시스템을 구축했습니다. 이 글에서는 구현 내용과 활용 방법을 소개합니다.

MCP란?

MCP(Model Context Protocol)는 Anthropic에서 개발한 프로토콜로, Claude와 외부 도구/데이터 소스 간의 표준화된 통신을 가능하게 합니다.

flowchart LR
 Claude <-->|MCP| MCPServer[MCP Server]
 MCPServer --> BlogFiles[Blog Files]

아키텍처

시스템 구성

blogs/
├── .claude/
│ ├── mcp_server.py # MCP 서버 구현
│ ├── requirements.txt # Python 의존성
│ ├── README.md # 사용 문서
│ └── claude_desktop_config.json
├── content/
│ └── posts/ # 블로그 포스트
└── static/
 └── images/ # 이미지 파일

MCP 서버 구조

class BlogManager:
 """블로그 관리 클래스"""

 def create_post(self, title, content, tags, categories):
 """새 포스트 생성"""

 def list_posts(self, limit, offset):
 """포스트 목록 조회"""

 def get_post(self, filename):
 """특정 포스트 조회"""

 def update_post(self, filename, **kwargs):
 """포스트 수정"""

 def delete_post(self, filename):
 """포스트 삭제"""

 def search_posts(self, query):
 """포스트 검색"""

제공 도구

flowchart TB
 subgraph Tools[MCP Tools]
 C1[blog_create_post]
 R1[blog_list_posts]
 R2[blog_get_post]
 R3[blog_search_posts]
 U1[blog_update_post]
 D1[blog_delete_post]
 end

 subgraph CRUD[CRUD Operations]
 Create[Create]
 Read[Read]
 Update[Update]
 Delete[Delete]
 end

 C1 --> Create
 R1 --> Read
 R2 --> Read
 R3 --> Read
 U1 --> Update
 D1 --> Delete

1. blog_create_post

새 블로그 포스트를 생성합니다.

{
 "title": "포스트 제목",
 "content": "Markdown 내용...",
 "tags": ["tag1", "tag2"],
 "categories": ["Development"],
 "draft": false
}

2. blog_list_posts

포스트 목록을 조회합니다.

{
 "limit": 20,
 "offset": 0
}

3. blog_get_post

특정 포스트의 상세 내용을 조회합니다.

{
 "filename": "2026-02-21-004-example.md"
}

4. blog_update_post

기존 포스트를 수정합니다.

{
 "filename": "2026-02-21-004-example.md",
 "content": "수정된 내용...",
 "draft": false
}

5. blog_search_posts

내용으로 포스트를 검색합니다.

{
 "query": "Docker"
}

자동화된 파일 명명

포스트 파일명은 다음 규칙으로 자동 생성됩니다:

flowchart LR
 User -->|Natural Language| Claude
 Claude -->|blog_create_post| MCP[MCP Server]
 MCP -->|Create File| Blog[YYYY-MM-DD-NNN-slug.md]

YYYY-MM-DD-NNN-slug.md

YYYY-MM-DD: 작성일
NNN: 일련번호 (001, 002, …)
slug: 제목에서 생성된 URL 친화적 문자열

예: 2026-02-21-004-mcp-blog-automation.md

활용 시나리오

flowchart LR
 User -->|Request| Claude
 Claude -->|blog_create_post| MCP[MCP Server]
 MCP -->|Create File| Blog[YYYY-MM-DD-NNN-slug.md]

1. 빠른 포스트 작성

사용자: "Python 리스트 컴프리헨션에 대한 짧은 팁 포스트를 작성해줘"

Claude: blog_create_post 도구를 사용하여 포스트 생성
→ 파일 생성: 2026-02-21-005-python-list-comprehension.md

2. 기존 포스트 검색 및 수정

사용자: "Docker 관련 포스트를 찾아서 최신 버전 정보로 업데이트해줘"

Claude: blog_search_posts("Docker") → 결과 확인 → blog_update_post

3. 시리즈 포스트 관리

사용자: "지금까지 작성한 에이전트 관련 포스트 목록을 보여줘"

Claude: blog_search_posts("agent") → 관련 포스트 나열

구현상의 고려사항

Front Matter 파싱

Hugo의 TOML 형식 front matter를 파싱합니다:

def _parse_front_matter(self, content: str) -> Dict[str, Any]:
 """TOML front matter 파싱"""
 if not content.startswith("+++"):
 return {}

 parts = content.split("+++", 2)
 # ... 파싱 로직

동시성 처리

파일명 충돌을 방지하기 위해 기존 파일 수를 확인합니다:

existing_count = len(list(self.content_dir.glob("*.md")))
filename = self._generate_filename(title, existing_count + 1)

확장 가능성

flowchart TB
 subgraph Current[Current Implementation]
 C1[blog_create_post]
 C2[blog_list_posts]
 C3[blog_get_post]
 C4[blog_update_post]
 C5[blog_delete_post]
 C6[blog_search_posts]
 end

 subgraph Future[Future Extensions]
 F1[blog_upload_image]
 F2[blog_suggest_tags]
 F3[blog_optimize_seo]
 F4[blog_publish]
 end

 Current --> Future

1. 이미지 처리

blog_upload_image: 이미지 업로드 및 최적화

2. 자동 태그 추천

blog_suggest_tags: 내용 분석 기반 태그 추천

3. SEO 최적화

blog_optimize_seo: 메타 설명, 키워드 최적화

4. 배포 자동화

blog_publish: git commit, push, 배포 트리거

결론

MCP를 활용한 블로그 자동화 시스템을 통해:

생산성 향상: 자연어로 포스트 작성 가능
일관성 유지: 파일 명명 규칙 자동 적용
접근성 개선: Claude를 통한 직관적인 블로그 관리

이 시스템은 지속적으로 확장 가능하며, 이미지 처리, SEO 최적화, 자동 배포 등의 기능을 추가할 수 있습니다.

참고 자료

영어 버전: English Version

Mcp on Yarang's Tech Lair

MCP 통합 가이드: ZeroClaw 런타임에서 Discord MCP 연동하기

1. 아키텍처 설계: 단일 채널에서의 이중 통신

2. 필수 의존성 및 설정 (Rust)

3. MCP 클라이언트 구현

4. ZeroClaw 에이전트와의 통합

5. 효율성 및 보안 고려사항 (Architecture Insights)

마무리하며

MCP 서버 메타데이터 동기화: 개발자 생산성을 위한 컨텍스트 관리 전략

MCP 서버 메타데이터 동기화: 개발자 생산성을 위한 컨텍스트 관리 전략

문제 정의: 매번 반복되는 ‘내 프로젝트 소개’

솔루션: 리소스 기반 메타데이터 제공

1. 아키텍처 문서 자동화

2. Rust 구현 예제

3. 프롬프트 자동 주입 (Prompt Injection)

효과 및 기대 효과

결론

Zero-Touch OAuth 구현을 위한 MCP 인증 아키텍처 설계

왜 Zero-Touch인가?

아키텍처 설계

구현 단계 1: 서버 사이드 (blog-api-server)

구현 단계 2: 클라이언트 사이드 (MCP Client)

ZeroClaw 런타임 통합 고찰

마치며

MCP 기반 멀티 에이전트 시스템의 통신 프로토콜 설계와 Rust 구현

1. 문제 정의: 왜 통신 프로토콜인가?

2. 프로토콜 설계: 요청, 작업, 완료

3. Rust로 구현하는 ZeroClaw 통신 계층

3.1. 메시지 정의 (JSON-RPC 기반)

3.2. 에이전트 런타임 구조

4. 결론 및 다음 단계

참고자료

Rust와 ZeroClaw로 구축하는 초경량 MCP 서버: 효율적인 에이전트 통신 구조

Rust와 ZeroClaw로 구축하는 초경량 MCP 서버: 효율적인 에이전트 통신 구조

1. ZeroClaw 아키텍처와 MCP의 결합

2. 핵심 구조: 비동기 요청 라우팅

2.1. Cargo.toml 설정

2.2. MCP 메시지 구조 정의

3. 경량화된 요청 핸들러 구현

4. 고급 최적화: ZeroClow 통합

5. 결론

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

1. MCP 서버의 핵심 요구사항

2. 아키텍처 설계: ZeroClaw 스타일

3. 실전 코드 예제

3.1. 의존성 설정 (Cargo.toml)

3.2. 핸들러 트레이트 정의

3.3. 로그 읽기 도구 구현

3.4. 메인 루프 및 JSON-RPC 서버

4. 최적화 및 배포 고려사항

5. 결론

MCP 서버 성능 최적화: Rust로 구축하는 초고속 처리 파이프라인

MCP 서버 성능 최적화: Rust로 구축하는 초고속 처리 파이프라인

1. 문제 정의: 단일 스레드 병목

2. Rust와 Tokio를 활용한 비동기 처리

기본 설정 (Cargo.toml)

비동기 핸들러 구현 예제

3. 스트리밍(Streaming)을 통한 메모리 최적화

4. 결론: ZeroClaw를 향하여

Rust로 구축하는 ZeroClaw: LLM 기반 멀티 에이전트 런타임 아키텍처

Rust로 구축하는 ZeroClaw: LLM 기반 멀티 에이전트 런타임 아키텍처

1. 왜 Rust인가? (Performance & Safety)

2. ZeroClaw의 핵심 아키텍처

2.1. 파일 기반 상태 관리 (File-Based State Management)

2.2. 이벤트 기반 통신 (Event-Driven Communication)

3. MCP(Model Context Protocol)와의 연동

4. 결론: 2026 상반기 발전 방향

참고 링크

MCP(Model Context Protocol) 기반 멀티 에이전트 시스템 설계 및 구현 가이드

MCP(Model Context Protocol) 기반 멀티 에이전트 시스템 설계 및 구현 가이드

1. MCP 기반 멀티 에이전트 아키텍처 설계

핵심 설계 원칙

아키텍처 다이어그램 (개념적)

2. MCP 서버 구현: Rust로 가벼운 에이전트 만들기

의존성 설정 (Cargo.toml)

MCP 서버 코드 예제

3. 에이전트 간 통신 및 데이터 동기화

파일 기반 상태 공유 예시

4. 결론 및 발전 방향

3.1. 의존성 설정 (`Cargo.toml`)