Mcp on Yarang's Tech Lair

MCP Integration Guide: Integrating Discord MCP with ZeroClaw Runtime

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

With the recent release of ZeroClaw, a high-performance Rust agent runtime, we’ve been deeply contemplating ways to maximize the efficiency of multi-agent systems. In particular, the complexity of communication protocols encountered during the design of the [Discord Decision MCP] architecture was a decisive factor in adopting MCP (Model Context Protocol) as a standard interface.

In this post, we will explain how to actually integrate Discord MCP within the ZeroClaw environment, detailing the process of agents receiving and processing Discord messages with concrete code examples.

1. Architecture Design: Dual Communication on a Single Channel

In the previous [Discord MCP] Gateway architecture, the gateway played the role of filtering events and delivering them to agents. However, by directly implementing the MCP client within ZeroClaw, we’ve altered the design to eliminate the intermediate layer and reduce latency.

The core idea is a flow where the MCP Client transmits Discord events to the ZeroClaw process via stdio, and then sends the agent’s responses back to Discord.

2. Essential Dependencies and Setup (Rust)

As ZeroClaw is written in Rust, it utilizes the asynchronous runtime tokio for high concurrency processing and serde for JSON handling. Communication with the MCP server is assumed to involve exchanging JSON-RPC messages via standard input/output (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 Client Implementation

We define a simple client structure to control the Discord MCP server within ZeroClaw. This client uses the tools/call method, which adheres to the MCP standard, to execute Discord bot functionalities.

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 }
 }

 /// Executes an MCP tool to send a message to a Discord channel
 pub async fn send_message(&mut self, channel_id: &str, content: &str) -> Result<(), Box<dyn std::error::Error>> {
 self.id += 1;
 
 // Execute MCP server process (e.g., Python-based Discord MCP server)
 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
 }
 }),
 };

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

 // (In a real implementation, logic to parse the response from an asynchronous reader is needed)
 // Omitted here for simplicity.
 
 Ok(())
 }
}

4. Integration with ZeroClaw Agents

Now, let’s use the DiscordMCPClient created above within ZeroClaw’s agent loop. This scenario demonstrates an agent notifying Discord upon completing a specific task.

struct ZeroClawAgent {
 discord_client: DiscordMCPClient,
}

impl ZeroClawAgent {
 async fn run_task(&mut self, task: &str) {
 println!("[Agent] Starting task: {}", task);
 
 // Complex reasoning or file processing logic (omitted)
 // ...

 let result = format!("Task '{}' completed.", task);

 // Send result to Discord
 match self.discord_client.send_message("123456789", &result).await {
 Ok(_) => println!("[Agent] Successfully sent Discord notification"),
 Err(e) => eprintln!("[Agent] Sending failed: {}", e),
 }
 }
}

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

 agent.run_task("Analyze server logs").await;
}

5. Efficiency and Security Considerations (Architecture Insights)

Resource Management: Similar to the trending ‘Adrafinil’ on [Hacker News], applying speculative decoding by disconnecting the Discord MCP connection when the agent is idle and only establishing it when a task is active can save resources.
Security: As highlighted in issues related to [Anonymous GitHub accounts], parameters passed to the MCP server (e.g., API tokens) should be managed via environment variables or fetched from a separate secure storage (Vault). Hardcoding secrets in code is critical.
Error Handling: As discussed in communication platform design considerations, it’s important to include retry logic in the MCP client, taking into account Discord API’s Rate Limits.

Conclusion

Integrating ZeroClaw and Discord MCP goes beyond simply creating a bot; it’s a process of building a standardized interface for agents to interact with the external world. Leveraging our experience in building [MCP] blog automation systems, we plan to further develop more sophisticated multi-agent collaboration systems.

MCP Server Metadata Synchronization: Context Management Strategies for Developer Productivity

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

MCP Server Metadata Synchronization: Context Management Strategies for Developer Productivity

As the integration between AI agents and developer tooling deepens, we are automating our blog system through the Model Context Protocol (MCP). However, one nagging issue remains: the ’token waste’ phenomenon where we have to repeatedly explain the project’s structure and context in every session with the AI.

As mentioned in the latest Hacker News post, Stop wasting tokens and re explaining your project between sessions, maintaining project context consistently goes beyond mere convenience; it directly impacts cost-effectiveness.

In this post, we propose a practical design for how to efficiently share dynamic metadata (context) with agents, moving beyond the static resources (Tools, Resources, Prompts) provided by the MCP server.

Problem Definition: The “My Project Introduction” Repetition

Existing MCP clients understand functionality through the tools list provided by the server. For instance, if there’s a write_post tool, Claude will call it to write a post. However, Claude doesn’t know the context, such as “What is the writing style of this blog?” or “What are the latest trends?”

Ultimately, the user has to provide prompts like this every time:

“Write a blog post. The style should be technical and specific, and it should refer to the latest Hacker News trends.”

This leads to unnecessary token consumption. To solve this, we can consider integrating the project’s ‘architecture design document’ or ‘development guidelines’ as resources within the MCP server.

Solution: Resource-Based Metadata Provision

In the MCP specification, Resources are data snippets provided by the server. We can utilize these not just for simple file lookups, but as a ‘project state machine’.

1. Automating Architecture Documentation

Documents like the previously written [ZeroClaw] Codebase Architecture Analysis or [Multi-Agent] File-Based Architecture Design might exist as static files or be scattered across platforms like Confluence. We can make it so that the MCP server loads these into memory upon startup or generates them dynamically for provision.

2. Rust Implementation Example

Let’s write code to add a architecture_guide resource to an MCP server written in Rust (e.g., blog-api-server).

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

// A hypothetical MCP handler struct
pub struct BlogMcpServer {
 // Cached metadata
 cached_context: String,
}

impl BlogMcpServer {
 pub fn new() -> Self {
 // Load core context (architecture, rules) during server initialization
 let context = r#"
 Project: ZeroClaw Multi-Agent Runtime
 Architecture: Asynchronous multi-agent system using a file-based event bus.
 Key Rules:
 1. All agents run in independent threads.
 2. Communication follows the JSON-RPC over MCP protocol.
 3. Logs must be output in structured JSON format.
 "#;
 
 Self { cached_context: context.to_string() }
 }

 // MCP resource read handler (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" => {
 // Return cached context when requested by the client
 Ok(json!({
 "contents": [
 {
 "uri": uri,
 "mimeType": "text/plain",
 "text": self.cached_context.clone()
 }
 ]
 }))
 },
 "context://trends/latest" => {
 // Fetch and provide external RSS (Hacker News, etc.) in real-time (dynamic resource)
 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> {
 // In reality, you would use reqwest etc. to parse RSS
 // Returning a simple JSON string for demonstration
 Some(r#"[{"title": "JSON-LD Explained", "link": "..."}]"#.to_string())
}

This code allows the MCP client to instantly retrieve the predefined project architecture rules by requesting the resource with the URI context://architecture/guide.

3. Automatic Prompt Injection

To prevent clients (like Claude) from requiring complex configurations, we can leverage the MCP server’s Prompts functionality to provide templates that automatically complete system prompts.

The MCP server can expose prompt templates like this:

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 }
 ]
}

The actual implementation logic (in Rust) would work as follows:

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"));
 
 // Inject the architecture guide fetched from resources into the prompt
 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, // Architecture information loaded earlier
 topic
 );

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

Effects and Expected Outcomes

The core of this approach is ‘duplication’. Similar to the Hacker News article Prefer duplication over the wrong abstraction, we avoid complex abstractions to simplify the essence of the project. Instead, we copy (duplicate) the necessary information (context) to where it’s needed (prompt).

Maintain Consistency: When documents are updated, simply restarting the MCP server or refreshing resources will ensure all sessions reflect the latest information.
Token Savings: Users no longer need to repeatedly explain, “My project is a multi-agent system built with Rust…”
Automation-Friendly: If documents are automatically generated and registered as MCP resources within a CI/CD pipeline, AI can always generate or review code based on the latest documentation.

Conclusion

We must utilize documents like the [ZeroClaw] Multi-Agent Architecture Design not just as ‘reading material,’ but as executable AI brains (context). Adding this metadata synchronization layer to the MCP server is the first step towards building complex LLM applications, and it lays the foundation for developers to focus on essential logic without wasting tokens.

In the next post, we will discuss how this metadata is actually utilized in the communication architecture of team agents like Claude Code.

Designing MCP Authentication Architecture for Zero-Touch OAuth Implementation

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

Recently, I encountered an interesting technological trend called ‘Zero-Touch OAuth for MCP’. During the integration of MCP (Model Context Protocol) with our ZeroClaw runtime and blog-api-server that we are developing, ensuring security without compromising user experience is an essential task. In this post, we will design a ‘Zero-Touch’ authentication flow that helps users connect to MCP clients without any complex separate configurations, and explore how to implement it in actual code.

Why Zero-Touch?

Traditional OAuth 2.0 flows often require users to obtain a ‘Client ID’ and ‘Client Secret’ and enter them into a configuration file. However, for general users or developers, this presents a significant barrier to entry. Zero-Touch OAuth aims for a flow where the client automatically attempts authentication through pre-registered metadata, and users simply need to click an ‘Allow’ button.

Architecture Design

We will configure blog-api-server as the MCP Provider and Claude Code or custom clients as MCP Consumers. The core idea is to build a Public Client environment that does not store Secrets by using the PKCE (Proof Key for Code Exchange) extension.

Core Components:

MCP Client (Consumer): An agent running in the user’s local environment.
Auth Server: The OAuth2 authentication server implemented within blog-api-server.
Resource Server: The actual blog API.

Implementation Step 1: Server Side (blog-api-server)

First, we need to add a simple authentication endpoint to the Rust-based blog-api-server. We will extend the architecture mentioned in the previous post, ’[blog-api-server] Adding Language Parameter to MCP Blog Client’, to make the Auth module independent.

Here, we will show the core logic: the Verification logic. This is the process of verifying the code_verifier received from the client.

// 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, // Random string generated by the client via 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. Retrieve Authorization Code from DB
 let auth_record = state.db.get_auth_code(&payload.code)
 .await
 .map_err(|_| "Invalid code".to_string())?;

 // 2. PKCE Challenge Verification (Core Security Logic)
 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. Issue 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,
 }))
}

This code hashes the code_verifier sent by the client and checks if it matches the code_challenge generated when the initial authentication request was sent. This process is the core that makes ‘Zero-Touch’ secure.

Implementation Step 2: Client Side (MCP Client)

Now, the client can obtain a token without user intervention (or with minimal intervention). Let’s write an example MCP client using Python.

import hashlib
import base64
import requests
from urllib.parse import urlencode
import os # Import os module

# Zero-Touch Configuration (Hardcoded or Environment Variables)
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"

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

# Generate 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 # Sent to the server for verification
 }
 response = requests.post(TOKEN_URL, data=data)
 return response.json()

# Usage Example
# 1. User authenticates in the browser via get_auth_url() (first time)
# 2. Extract 'code' from the redirected query parameters
# 3. token = exchange_code_for_token(code)

Considerations for ZeroClaw Runtime Integration

As mentioned in our previous retrospective, ’[ZeroClaw] Q1 2026 Development Direction Meeting Minutes’, our agent runtime must prioritize security and scalability. If we integrate the OAuth flow implemented above into ZeroClaw’s Multi-Agent architecture, each agent can have an independent identity.

In particular, as discussed in ’[ZeroClaw] Multi-Agent Communication Protocol Design’, this Access Token can be used to securely access resources (APIs) of other agents during inter-agent communication, laying the foundation for secure access. This goes beyond simple blog automation and marks the first step towards a distributed system where agents trust and delegate tasks to each other.

Conclusion

Zero-Touch OAuth is an excellent approach that achieves both user convenience and security. We plan to start with small projects like blog-api-server and gradually evolve it into a core authentication module for ZeroClaw. The code above provides a basic framework, and for actual operational environments, logic such as state verification and refresh token rotation should be added.

In the next post, we will debug the ‘Handshake’ process of actually exchanging data with the MCP server using the tokens secured in this way.

Designing and Implementing a Communication Protocol for MCP-based Multi-Agent Systems in Rust

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

Recently, while working on the ‘ZeroClaw’ project and MCP (Model Context Protocol), I’ve keenly felt the necessity of a Multi-Agent System that goes beyond a single agent. To build a structure where agents can exchange meaningful data and collaborate, rather than simply sending prompts to an LLM, a robust Communication Protocol is essential.

In this post, we’ll explore the design process for multi-agent communication based on the MCP architecture and how to implement it on ZeroClaw (Rust), a high-performance runtime.

1. Problem Definition: Why a Communication Protocol?

In previous implementations like [blog-api-server] or [Discord MCP], the ‘Request-Response’ structure was primarily followed. This involved a unidirectional flow where the client sent a request, and the server processed and responded. However, in a multi-agent environment, this structure alone is insufficient for the following reasons:

Asynchrony: If Agent A delegates a task to Agent B and Agent A stops execution until B completes, the overall system throughput decreases.
Event-Driven Interaction: Some agents need to monitor system state changes (e.g., file creation, log updates) and signal other agents under specific conditions.
Reliability: Messages must not be lost in situations of network instability or temporary agent failures.

2. Protocol Design: Request, Task, Completion

To address these issues, we designed a Task-Based Messaging Protocol. This protocol extends the MCP standard message format and consists of three main message types:

TaskRequest: Initiates a task. Used when Agent A delegates a specific task to Agent B.
TaskUpdate: Reports progress. Conveys intermediate results for long-running tasks.
TaskResult: Final outcome. Returns data along with a success or failure status.

3. Implementing the ZeroClaw Communication Layer in Rust

ZeroClaw implements this protocol in a type-safe manner using Rust’s powerful type system and its asynchronous runtime (Tokio). Below is a simplified message definition and handler structure.

3.1. Message Definition (Based on JSON-RPC)

MCP is fundamentally based on JSON-RPC 2.0, and we adhere to this standard while including the metadata necessary for inter-agent communication.

// src/protocol/message.rs

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

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AgentMessage {
 pub id: String, // Unique message ID
 pub sender: String, // Sender agent ID
 pub target: String, // Recipient agent ID
 pub timestamp: i64, // Timestamp
 pub payload: Payload, // Actual data
}

#[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), // Reason for failure
 Pending,
}

3.2. Agent Runtime Structure

In ZeroClaw, each agent runs as an independent Tokio task. Inter-agent communication occurs through channels, and a Mediator routes these messages.

// src/runtime/agent.rs

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

pub struct Agent {
 id: String,
 tx: mpsc::Sender<AgentMessage>, // Sender for outgoing messages
 rx: mpsc::Receiver<AgentMessage>, // Receiver for incoming messages
}

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

 // The agent's main execution loop
 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 => {
 // Logic to respond to ping with pong
 // In a real environment, this would use the client's tx to send a response
 println!("[{}] Received Ping from {}", self.id, msg.sender);
 }
 Payload::TaskRequest { task_id, description, context } => {
 println!("[{}] Received Task {}: {}", self.id, task_id, description);
 // LLM calls or tool execution logic would go here.
 
 // Example: Result return logic (simulated)
 // self.send_result(task_id, ...).await;
 }
 _ => {
 println!("[{}] Received unhandled message type", self.id);
 }
 }
 Ok(())
 }
}

4. Conclusion and Next Steps

Through the structured communication layer described above, we achieve an architecture capable of task-unit collaboration, moving beyond simple text generation. The ‘high-performance agent runtime’ goal for the [ZeroClaw] project in the first half of 2026 will be realized by integrating LLM inference logic on this solid foundation.

The next post will delve into the implementation details of a ‘Planner’ agent that uses tools by calling an LLM over this communication protocol.

References

[ZeroClaw] Multi-Agent Architecture Design Proposal
[Claude Code] Team Agent Communication Architecture
Rust Tokio Documentation

Building a Lightweight MCP Server with Rust and ZeroClaw: An Efficient Agent Communication Structure

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

Building a Lightweight MCP Server with Rust and ZeroClaw: An Efficient Agent Communication Structure

As evident in the recent article “Grit: Rewriting Git in Rust with Agents,” the Rust language is being re-evaluated for its value as a runtime for agent systems. Our team’s ZeroClaw runtime is also under development with high performance and safety as its goals, and with this in mind, we are increasingly focusing on how to efficiently build an MCP (Model Context Protocol) server.

Instead of traditional heavy Python-based servers or complex Node.js architectures, we propose a lightweight MCP server structure that leverages Rust’s concurrency and low-latency capabilities. In this article, we will write a Rust-based MCP server example that can be immediately applied in practice, while capitalizing on the advantages of the ZeroClaw architecture.

1. Combining ZeroClaw Architecture and MCP

The core of the ZeroClaw project lies in its file-based architectural design and the efficient implementation of its multi-agent communication protocol. The most crucial aspects when building an MCP server are reducing the overhead of data serialization/deserialization (Serde) and asynchronous request handling.

By utilizing Rust’s tokio runtime and serde_json, we can handle JSON-based MCP protocols with an overhead in the nanosecond range. This is a critical element, especially for large-scale log processing or monitoring systems (as experienced with [blog-api-server]).

2. Core Structure: Asynchronous Request Routing

We will build the skeleton of an MCP server using only the standard library and a few essential crates, without complex dependencies. This structure follows ZeroClaw’s agent-to-agent communication pattern and ensures safety in a multi-threaded environment, not just a single-threaded one.

2.1. Cargo.toml Configuration

First, add project dependencies.

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

2.2. Defining MCP Message Structure

MCP fundamentally has a structure similar to JSON-RPC. We actively utilize Rust’s type system to ensure data integrity during agent-to-agent communication.

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

#[derive(Debug, Serialize, Deserialize)]
pub struct MCPRequest {
 pub jsonrpc: String, // Always "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. Implementing a Lightweight Request Handler

In line with ZeroClaw’s philosophy, we will remove unnecessary abstraction layers and write intuitive handlers. The following code demonstrates the flow of parsing incoming requests, performing appropriate processing based on the method name, and returning a response.

// 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" => {
 // Example of returning a list of tools
 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" => {
 // Actual tool execution logic (calling ZeroClaw Agent, etc.)
 // Parameter validation logic goes here.
 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 Parsing
 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 Logic Processing
 let mcp_res = handle_mcp_request(mcp_req).await;
 
 // Response Conversion
 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. Advanced Optimization: ZeroClaw Integration

The code above is a basic HTTP server. To unleash the true power of ZeroClaw, this server needs to be integrated as a task within the agent runtime.

Channel-based Communication: Instead of directly handling HTTP requests, send requests through a tokio::sync::mpsc channel to the internal agent queue. This aligns with ZeroClaw’s asynchronous message passing structure.
Stealable Work Queue: Implement a work queue to allow agents to efficiently distribute tasks in a multi-core environment.

5. Conclusion

By writing an MCP server in Rust, you can fully leverage the benefits of high-performance runtimes like ZeroClaw. The key is not just changing the language, but designing an architecture that minimizes overhead in agent-to-agent communication. We encourage you to build upon the code provided and add your project-specific agent logic.

Note: This code focuses on practicality by simplifying error handling and logging, based on the experience gained from improving logging in blog-api-server.

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

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

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

Recently, Model Context Protocol (MCP) has become a standard interface in the AI agent ecosystem. When building an MCP server in high-performance runtime environments like our team’s ZeroClaw project, Rust’s safety and speed are essential. In this post, we will design a practical, ready-to-implement Rust-based MCP server structure and explore how to build it with actual code.

1. Core Requirements of an MCP Server

To allow AI models to access data, an MCP server must perform the following three core functions:

Resource Discovery: Provide a list of data (files, APIs, etc.) that the model can use.
Resource Access: Efficiently return the actual content of requested data.
Tool Execution: Perform actions within the system based on the model’s instructions.

Rust is ideal for MCP servers handling large-scale requests, especially due to its Zero-cost abstractions and robust asynchronous runtime (tokio).

2. Architecture Design: ZeroClaw Style

Beyond simple RPC calls, we adopt an event-driven architecture for scalability. The structure is as follows:

Transport Layer: Sending and receiving messages via stdio or WebSocket (JSON-RPC 2.0)
Handler Layer: Layer for routing and validating requests
Core Logic: Actual business logic (file system access, DB queries, etc.)

3. Practical Code Examples

We will write a simple MCP server based on stdio (standard input/output), the most common transport. This example implements functionality to allow an LLM to read logs from the local file system.

3.1. Dependency Setup (`Cargo.toml`)

We add crates for serialization and asynchronous processing to leverage Rust’s ecosystem.

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

3.2. Handler Trait Definition

Following the MCP standard, we define a common interface for handling Tool and Resource. This makes it easier to integrate with the ZeroClaw runtime later.

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. Implementing the Log Reading Tool

Now, we implement the logic to actually read files within the server and provide them to the AI model.

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. Parameter validation and extraction
 let file_path = params.get("path")
 .and_then(|v| v.as_str())
 .ok_or("Missing 'path' parameter".to_string())?;

 // 2. Safeguard: Prevent path traversal (Sandboxing)
 // In a production environment, chroot or a dedicated virtual directory should be used.
 if !file_path.ends_with(".log") {
 return Err("Only .log files are allowed".into());
 }

 // 3. File system access (wrapping synchronous I/O in an asynchronous context)
 let content = fs::read_to_string(file_path)
 .map_err(|e| format!("Failed to read file: {}", e))?;

 // 4. Result formatting
 Ok(serde_json::json!({
 "status": "success",
 "content": content,
 "lines": content.lines().count()
 }))
 }
}

3.4. Main Loop and JSON-RPC Server

This is the main loop responsible for communication with the LLM. It reads JSON-RPC requests from standard input and outputs the processing results to standard output.

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

 // Process requests as they arrive from the LLM or host
 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);
 
 // Execute business logic
 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. Optimization and Deployment Considerations

The code above provides a basic framework, but for production environments like ZeroClaw, consider the following:

Concrete Error Types: Use specific thiserror or anyhow-based error types instead of String to facilitate debugging.
Security Sandboxing: Use a virtual file system (VFS) library instead of std::fs to prevent agents from accessing the entire system.
Graceful Shutdown: Utilize tokio’s signal module to handle interrupt signals (SIGTERM) and safely terminate ongoing file operations.

5. Conclusion

Rust is the ideal language for building reliable MCP servers due to its type safety and memory management capabilities. Based on the code above, by integrating with a blog-api-server or monitoring system, you can build a fully automated cycle where AI models directly analyze system logs and suggest patches.

In the next post, we will cover how to agentize this MCP server on the ZeroClaw runtime and communicate with other services.

MCP Server Performance Optimization: Building Ultra-Fast Processing Pipelines with Rust

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

MCP Server Performance Optimization: Building Ultra-Fast Processing Pipelines with Rust

As agent systems utilizing LLMs (Large Language Models) have become a hot topic in the development ecosystem, the importance of the supporting infrastructure, MCP (Model Context Protocol) servers, is growing. In a previous post, we discussed multi-agent architectures, mentioning high-performance runtimes like ZeroClaw. Today, we will focus on Rust-based optimization techniques to dramatically improve the Throughput and Latency of the MCP server itself.

Simply saying “it’s fast” is not enough. The key is how efficiently the server manages resources when thousands of Tool Calls arrive simultaneously. In particular, as the current trend of AI agents collects RSS feeds or real-time data, I/O bound operations often become a bottleneck.

This article will introduce concrete methods for eliminating bottlenecks and writing safe yet fast code by leveraging Tokio, Rust’s powerful asynchronous runtime.

1. Problem Definition: Single-Threaded Bottleneck

Basically, simple MCP servers written in Python or Node.js often rely on a single-threaded event loop. This is advantageous for I/O-heavy tasks, but it has clear limitations when processing MCP tools that involve data manipulation or complex logic, as it only utilizes one CPU core.

For example, when building an automated blog system, if CPU usage reaches 100% during the processing of large amounts of images or log parsing, other requests will pile up in the queue. We need to solve this with multi-threaded asynchronous processing.

2. Asynchronous Processing with Rust and Tokio

Rust can achieve both safety and performance through ‘Zero-cost abstractions’. Let’s parallelize the core logic of the MCP server, tool execution, using tokio::spawn.

Basic Setup (Cargo.toml)

First, add Tokio to your dependencies file.

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

Asynchronous Handler Implementation Example

The following code shows a simple MCP server handler structure that processes incoming requests by separating them into distinct tasks.

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

// Define the MCP request message structure
#[derive(Debug, Deserialize)]
struct McpRequest {
 id: String,
 method: String,
 params: serde_json::Value,
}

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

// Function to simulate heavy processing
async fn process_heavy_tool(params: serde_json::Value) -> Result<String, String> {
 // In a real environment, this would involve database lookups or file I/O
 // Simulate asynchronous waiting with 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?;

 // Create a new task for each incoming connection (parallel processing)
 tokio::spawn(async move {
 let mut buf = [0; 1024];

 loop {
 let n = match socket.read(&mut buf).await {
 Ok(n) if n == 0 => return, // Connection closed
 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 parsing and processing logic (error handling omitted)
 if let Ok(req) = serde_json::from_str::<McpRequest>(&req_str) {
 let req_id = req.id.clone();
 
 // Core logic: spawn an asynchronous function for non-blocking processing
 let handle = tokio::spawn(async move {
 process_heavy_tool(req.params).await
 });

 // Wait for the result and respond (using channels is recommended in actual implementations)
 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;
 }
 }
 }
 }
 });
 }
}

The core of this code is that tokio::spawn allows each request to execute independently without blocking the main loop.

3. Memory Optimization through Streaming

When processing large files or transferring logs, loading all data into memory (RAM) is fatal. Using Rust’s Stream allows you to process data in chunks, maintaining consistent memory usage.

This can be particularly useful in tasks like [blog-api-server] logging improvements or Cloud Monitor operations.

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

// Stream for generating virtual log data
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;
 }
 })
}

// Stream processing example
async fn process_logs() {
 let mut stream = log_stream();
 while let Some(log_entry) = stream.next().await {
 // Process line by line in real-time (write to file or send)
 println!("Processing: {}", log_entry);
 }
}

4. Conclusion: Towards ZeroClaw

The ZeroClaw runtime we aim for must provide asynchronous processing and memory safety as its core features. We need to go beyond simply porting existing Python scripts to Rust and actively leverage Tokio’s scheduling and Zero-copy serialization to withstand an environment where thousands of agents communicate concurrently.

In the next post, we will discuss how to design agent-to-agent communication protocols that operate on these high-performance servers.

Building ZeroClaw with Rust: An LLM-Based Multi-Agent Runtime Architecture

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

The recent surge in interest surrounding automation and agent systems leveraging LLMs (Large Language Models) is undeniable. However, single agents often face limitations when handling complex tasks, leading to the growing prominence of Multi-Agent Systems. In this post, we will introduce the architecture of ZeroClaw, an agent runtime built with Rust for high performance and stability, and explore how inter-agent communication is structured.

1. Why Rust? (Performance & Safety)

Most LLM applications are typically written in Python. However, in a ‘runtime’ environment where multiple agents execute concurrently and need to control their own independent memory spaces or file systems, Rust’s powerful parallel processing capabilities and memory safety become significant advantages.

Notably, as discussed recently on Hacker News, the issue of “Constraint Decay in LLM Agent Backend Code Generation” has emerged. In scenarios where LLM-generated code unintentionally breaks system constraints, Rust’s type system and ownership model can provide a safety net at the runtime level.

2. ZeroClaw’s Core Architecture

ZeroClaw is not just a simple LLM wrapper; it is a runtime engine that manages the lifecycle of agents and relays messages between them.

2.1. File-Based State Management

We have adopted an architecture that manages agent states and contexts based on the file system, without relying on complex databases. This enhances portability and debugging ease.

// Example struct for storing agent state
#[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(())
 }
}

As discussed in the Multi-Agent: File-Based Architecture Design discussion, this approach allows each agent to transparently record its state, increasing the predictability of the overall system.

2.2. Event-Driven Communication

ZeroClaw’s agents do not call each other directly. Instead, they communicate through a central Event Bus or a Pub/Sub mechanism. This reduces coupling and ensures scalability.

// Communication protocol message definition
#[derive(Debug, Clone)]
pub enum AgentMessage {
 TaskRequest { task_id: String, payload: String },
 TaskResponse { task_id: String, result: String },
 StatusUpdate { agent_id: String, status: String },
}

// Simple channel-based message router (using tokio::sync::mpsc)
pub struct MessageRouter {
 // sender: HashMap<AgentId, Sender<AgentMessage>>
 // In a real implementation, it would manage agent-specific channels
}

This structure provides a foundation for addressing the ‘message queue reliability’ issues considered in architectures like the Claude Code Team Agent Communication Architecture or Multi-Agent Communication Protocol Design, using Rust’s robust asynchronous runtime (tokio).

3. Integration with MCP (Model Context Protocol)

ZeroClaw acts as both an MCP server and client, enabling integration with external tools (e.g., blog APIs, Discord Gateway). Recent improvements like the language parameter added to blog-api-server and enhanced logging help ZeroClaw agents maintain context when interacting with external systems.

Safely wrapping the invocation of MCP tools by agents is crucial.

// Safe wrapper for invoking MCP tools
pub async fn invoke_mcp_tool(tool_name: &str, params: serde_json::Value) -> Result<String, AgentError> {
 // 1. Parameter Validation
 if !validate_params(tool_name, &params) {
 return Err(AgentError::InvalidInput);
 }

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

 // 3. Response Parsing and Logging
 tracing::info!("MCP Tool {} called successfully", tool_name);
 Ok(response.text().await?)
}

4. Conclusion: Development Directions for H1 2026

ZeroClaw is evolving beyond a mere experimental project to become a ‘high-performance agent runtime’, as mentioned in the H1 2026 Development Direction Meeting Minutes.

The goal is to simultaneously achieve LLM creativity and system safety, leveraging Rust’s performance. Specifically, there are plans to improve cost-effectiveness by integrating efficient models like DeepSeek, which is a recent trend.

The next post will cover a CI/CD pipeline integration case study where ZeroClaw agents actually generate and deploy code.

Reference Links

MCP (Model Context Protocol) Based Multi-Agent System Design and Implementation Guide

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

MCP (Model Context Protocol) Based Multi-Agent System Design and Implementation Guide

Recently, in the generative AI domain, Multi-Agent Systems are gaining attention to overcome the limitations of single LLMs (Large Language Models). In particular, with the emergence of MCP (Model Context Protocol) for standardized communication between agents, designing scalable and modular architectures has become essential.

This post explores how to design and implement efficient multi-agent architectures using MCP in high-performance agent runtime environments like ZeroClaw. We’ve included architectural design principles and actual code examples so readers can apply them immediately.

1. MCP-Based Multi-Agent Architecture Design

The most crucial aspect when building a multi-agent system is lowering coupling and increasing cohesion. To achieve this, MCP adopts a client-server model, where each agent or tool operates as an independent server and communicates through a standard protocol (based on JSON-RPC 2.0).

Key Design Principles

Standardized Interface: All agents must adhere to the MCP standard to expose tools, resources, and prompts.
Asynchronous Communication: For agents with long task execution times (e.g., file processing, web scraping), an asynchronous message queue should be utilized.
Statelessness: Agent servers should be designed to be as stateless as possible to facilitate horizontal scaling.

Architecture Diagram (Conceptual)

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

In this structure, the Gateway (Orchestrator) analyzes user requests, delegates tasks to the appropriate MCP servers (agents), and aggregates the results to return them to the user.

2. Implementing MCP Servers: Building Lightweight Agents with Rust

We will implement a simple MCP server in Rust to achieve high performance in environments like blog-api-server or ZeroClaw. This server provides a simple tool that returns the current time.

Dependency Setup (Cargo.toml)

We will use Rust’s powerful asynchronous runtime tokio, serde for JSON processing, and hyper or jsonrpc for MCP communication.

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

MCP Server Code Example

The following is a simplified implementation of a standard MCP server that communicates via STDIN/STDOUT.

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

// MCP Request/Response structure definitions
#[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" => {
 // Called when the client wants to check the server's capabilities
 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" => {
 // Returns a list of available tools
 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" => {
 // Actual tool execution logic
 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,
 };
 }
 }
 // Error handling
 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();
 }
 }
}

This code handles the core MCP methods initialize, tools/list, and tools/call, enabling LLMs (e.g., Claude Code) to recognize and invoke this agent as a tool.

3. Agent Communication and Data Synchronization

In architectures like ZeroClaw, where multiple agents collaborate, data sharing is crucial. A file-based architecture allows agents to exchange data while reducing coupling.

Consider a scenario where Agent A generates data, and Agent B consumes it.

Agent A (Producer): Saves the computation result to /tmp/shared/task_result.json.
Agent B (Consumer): Reads the resource file://tmp/shared/task_result.json via MCP, or calls a separate read_file tool.

// Example of Agent A calling a tool (pseudo-code)
fn save_result(data: &str) -> std::io::Result<()> {
 fs::write("/tmp/shared/task_result.json", data)?;
 Ok(())
}

This approach is useful when message queues are complex and effective for continuously tracking data, such as in the logging system or monitoring dashboard of blog-api-server.

4. Conclusion and Future Directions

Leveraging MCP allows for the modularization and maintainability of complex multi-agent systems.

Advantages: Language-agnostic interface (can mix Rust, TypeScript, etc.), tool reusability, standardized error handling.
Considerations: STDIN/STDOUT communication overhead, load balancing for the Gateway to handle large traffic.

The future goal is to build an environment within the ZeroClaw runtime where these MCP servers are containerized and dynamically scaled as needed. This will enable LLMs to evolve beyond simple chatbots into intelligent agent networks that automate complex tasks.

References

ZeroClaw Multi-Agent System: A Guide to Building a Local Testing Environment with Docker Compose

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

ZeroClaw Multi-Agent System: A Guide to Building a Local Testing Environment with Docker Compose

Recently, while designing the high-performance Rust agent runtime and multi-agent architecture for the [ZeroClaw] project, I realized the importance of isolation and communication stability for individual agents. In particular, when developing MCP (Model Context Protocol) clients that interact with external APIs, such as [blog-api-server], it is essential to test them in a local environment that mimics the actual production setup.

In this post, I will share how to build a testing environment using Docker Compose to easily run and debug complex multi-agent systems locally. This guide is based on a Linux environment (e.g., servers transitioning from Ubuntu 16.04 to FreeBSD), but it can be applied to Windows and macOS as well.

1. Architecture Design: Microservices-style Agent Structure

The core of ZeroClaw is a communication platform that adopts a file-based architecture and a gateway pattern. Each agent is treated as an independent microservice and isolated within a Docker container.

Components

Agent Container: Individual agents written in Rust (based on ZeroClaw Runtime)
Gateway Container: Nginx or Envoy for routing external requests to internal agents
Message Broker (Optional): RabbitMQ or Redis (if asynchronous communication is needed)

2. Dockerfile Creation: Optimizing Rust Agents

Since Rust applications have long compile times, Multi-stage builds should be used to reduce the final image size and optimize build caching.

# Dockerfile

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

WORKDIR /app

# Copy Cargo.toml and Cargo.lock first for dependency caching
COPY Cargo.toml Cargo.lock ./
RUN mkdir src && echo "fn main() {}" > src/main.rs
RUN cargo build --release && rm -rf src

# Copy actual source code and build
COPY src ./src
RUN touch src/main.rs && cargo build --release

# 2. Runtime Stage
FROM debian:bookworm-slim

# Install runtime dependencies (e.g., OpenSSL)
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Copy the built binary
COPY --from=builder /app/target/release/zero-claw-agent /app/agent

# Grant execute permissions
RUN chmod +x /app/agent

# Expose port (for MCP communication)
EXPOSE 8080

CMD ["/app/agent"]

3. Orchestration Configuration with Docker Compose

Use the docker-compose.yml file to define multiple agents and networks. This allows the entire system to be launched with a single docker-compose up command.

# docker-compose.yml
version: '3.8'

services:
 # Message Broker (Optional, used depending on the communication protocol)
 redis:
 image: redis:7-alpine
 container_name: zero-claw-redis
 ports:
 - "6379:6379"
 networks:
 - zero-claw-net

 # Agent 1: Blog Handler (acting as 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 role)
 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 role)
 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. Running and Testing

You can now run the entire system with the following command:

# Build and run in background
docker-compose up --build -d

# Check logs (focused monitoring of a specific agent)
docker-compose logs -f blog-agent

# Traffic test (request via Gateway)
curl -X POST http://localhost:8080/api/v1/agent/blog/ping \
 -H "Content-Type: application/json" \
 -d '{"message": "Hello from ZeroClaw"}'

5. Conclusion

Leveraging this structure makes tasks like modifying [ZeroClaw]’s multi-agent communication protocol or injecting [LLM] configurations per agent much easier to test. In particular, by simply modifying environment variables in docker-compose.yml, you can maintain a nearly identical setup for production deployment scripts and local testing environments, thus resolving the “It works on my machine” problem.

In the next post, we will cover how to visualize the logs collected in this environment using [Loki] or [Prometheus].

Enhancing AI Agent Reliability: A Guide to Integrating Forge Guardrails with MCP

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

Recent advancements in AI agents powered by Large Language Models (LLMs) have been remarkable. A notable case on Hacker News, “Forge – Guardrails take an 8B model from 53% to 99% on agentic tasks,” highlighted how applying appropriate Guardrails can dramatically increase the success rate of specific tasks, often more effectively than simply increasing model parameter count.

For our ongoing projects, ZeroClaw and those based on MCP (Model Context Protocol), agent reliability is paramount. In this post, we will explore the concept of Forge, an open-source guardrail framework, and introduce practical methods for integrating it into our existing MCP architecture to ensure agent stability.

Problem Definition: The Dilemma of Autonomy

Granting agents more autonomy increases the risk of unexpected behavior. For instance, when an MCP request is made to generate a blog post, an agent might attempt to execute system commands or call unauthorized APIs.

Our previous implementation of [blog-api-server] attempted to mitigate this through prompt engineering and basic JSON schema validation, but these proved insufficient in complex multi-agent environments. To address this, we decided to introduce an L1 Guardrail layer for pre-filtering inputs and outputs.

Solution: Applying the Guardrails Pattern

As demonstrated by Forge, the key to improving agent task success rates (53% → 99%) lies in pre-execution validation. We designed a structure where a middleware layer validates the agent’s responses before they are delivered to the user or used to execute tools.

Architecture Overview

A Validator layer is placed between the existing MCP client and the LLM to perform the following:

Input Validation: Checks if user requests violate system policies (e.g., filtering for aggressive prompts).
Output Validation: Verifies if LLM-generated JSON or function call arguments conform to the schema.

Practical Code Example: Implementing Safeguards in Rust

Let’s implement a lightweight output validator within the Rust environment of ZeroClaw. This example uses serde and regex to safely wrap code execution commands generated by the LLM, without complex external libraries.

1. Implementing Validation Logic

First, here’s a simple validator to determine if a command generated by the agent is safe.

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

// Structure for commands an agent might generate
#[derive(Debug, Serialize, Deserialize)]
struct AgentCommand {
 tool_name: String,
 parameters: String,
}

pub struct Guardrail;

impl Guardrail {
 // Simple example for filtering dangerous strings
 fn is_dangerous(input: &str) -> bool {
 let dangerous_patterns = vec!["rm -rf", "sudo", "eval", "__import__"];
 dangerous_patterns.iter().any(|&pat| input.contains(pat))
 }

 // Validation logic before command execution
 pub fn validate_command(cmd: &AgentCommand) -> Result<&AgentCommand, String> {
 // 1. Check tool name against a whitelist
 let allowed_tools = vec!["blog_post", "search", "read_file"];
 if !allowed_tools.contains(&cmd.tool_name.as_str()) {
 return Err(format!("Attempt to use disallowed tool: {}", cmd.tool_name));
 }

 // 2. Check for dangerous keywords within parameters
 if Self::is_dangerous(&cmd.parameters) {
 return Err("Potentially dangerous command included in parameters.".to_string());
 }

 // 3. If safe, approve the command
 Ok(cmd)
 }
}

2. Integrating into the Agent Loop

Now, we connect the validator to the request processing loop of the MCP server. After the agent generates a response, it must pass through the Guardrail before the actual system executes it.

// Hypothetical agent execution function
fn execute_agent_task(llm_output: &str) -> Result<String, String> {
 // 1. Parse LLM output (in reality, this would involve JSON parsing, etc.)
 // We assume parsing is successful here for simplicity.
 let command = AgentCommand {
 tool_name: "blog_post".to_string(),
 parameters: "title: 'Hello World'".to_string(),
 };

 // 2. Before guardrail passage
 println!("[System] LLM response received: {}", command.tool_name);

 // 3. Execute guardrail validation
 let safe_command = Guardrail::validate_command(&command)?;

 // 4. Execute validated command
 println!("[System] Executing safe command...");
 // Actual tool execution logic (e.g., calling the blog API)
 Ok("Post successfully created.".to_string())
}

fn main() {
 // Normal case
 match execute_agent_task("valid_response") {
 Ok(msg) => println!("Success: {}", msg),
 Err(e) => println!("Blocked: {}", e),
 }

 // Simulate an abnormal case
 let malicious_cmd = AgentCommand {
 tool_name: "system_shell".to_string(), // Not in whitelist
 parameters: "rm -rf /".to_string(),
 };

 match Guardrail::validate_command(&malicious_cmd) {
 Ok(_) => println!("Error: Hacker has infiltrated!"),
 Err(e) => println!("Protected: {}", e), // "Protected: Attempt to use disallowed tool: system_shell"
 }
}

Benefits and Outlook

By establishing this L1 defense line, we gain the following advantages:

Improved Stability: Similar to the Forge case, even 8B models can be utilized safely, reducing inference costs.
Enhanced Transparency: Logs clearly indicate why an agent rejected a specific task.
Maintainability: Security policy changes only require modifications to the Guardrail module.

Moving forward, the ZeroClaw project plans to integrate this validation logic into an asynchronous runtime, enabling real-time safety monitoring during inter-agent communication ([Discord MCP], [Cloud Monitor]).

Instead of solely focusing on improving model performance, the key to deploying AI agents in actual production environments will lie in how we design system-level safeguards like these.

This article was written with reference to architectural design documents related to ZeroClaw and MCP.

Agentic Workflow: Building a Blog Automation Pipeline with MCP Tools

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

Agentic Workflow: Building a Blog Automation Pipeline with MCP Tools

Recently, while working on the ZeroClaw project, I’ve been contemplating efficient workflows in multi-agent environments. How can we enable agents to not just answer questions, but to actually perform tasks using tools?

Today, I’ll share the process of building an automation pipeline where an LLM directly publishes blog posts using Model Context Protocol (MCP). This goes beyond simple API calls, serving as a practical example of Agentic Workflow where an agent handles everything from ‘authentication’ to ‘deployment’.

Background: Connecting LLMs with Development Tools

The biggest bottlenecks when integrating LLMs into business logic are the ’lack of context’ and ’limitations in tool execution’. Looking at recent Hacker News and tech trends, there’s an increasing effort to make LLMs function as part of software, rather than just generating text.

Our team manages the blog system through blog-api-server and is currently revamping the communication architecture between team agents using tools like Claude Code. In this process, we adopted Anthropic’s MCP to create an environment where agents can safely and structurally call our server’s APIs.

MCP (Model Context Protocol) Architecture Design

MCP is a standard communication protocol between a client (e.g., Claude Desktop or IDE) and a host program (in this case, our blog server). Previously, we created ad-hoc HTTP endpoints to provide tools to LLMs, but by introducing MCP, we’ve gained the following benefits:

Standardized Interface: Defines Resources, Prompts, and Tools in a consistent manner.
Enhanced Security: Secure connection based on local communication and SSE (Server-Sent Events).
Scalability: New tools can be added simply by defining the protocol.

1. Implementing the MCP Server in the Blog Server (Rust)

First, we integrated MCP server functionality into the existing blog-api-server. We leverage Rust’s high performance to quickly process agent requests.

Below is a simple example code that defines a ‘create blog post’ tool (Tool) according to the MCP standard.

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

/// MCP tool request schema
#[derive(Debug, Deserialize)]
struct CreatePostArgs {
 title: String,
 content: String,
 tags: Option<Vec<String>>,
}

/// MCP tool response schema
#[derive(Debug, Serialize)]
struct ToolResponse {
 success: bool,
 post_id: String,
 message: String,
}

/// Blog post creation tool handler
pub async fn handle_create_post(args: Value) -> Result<ToolResponse, String> {
 // 1. Parse and validate arguments
 let args: CreatePostArgs = serde_json::from_value(args)
 .map_err(|e| format!("Invalid arguments: {}", e))?;

 // 2. Execute business logic (e.g., database save)
 let post_id = create_post_in_db(&args.title, &args.content, &args.tags).await?;

 // 3. Return result
 Ok(ToolResponse {
 success: true,
 post_id,
 message: "Post created successfully via MCP".to_string(),
 })
}

This code executes when an agent calls the create_post tool. The agent passes the title, content, and tags in JSON format, and the server validates them and saves them to the database.

2. Communication with Agents: Prompt Engineering

Now that the tools are ready, we need to inform the LLM how to use them. By specifying the MCP tool definitions in the system prompt, we encourage the LLM to call functions on its own when needed.

You are a Blog Manager Agent. You have access to the following tools defined via MCP:

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.

Practical Application: Automated Posting Workflow

Now that the structure is in place, let’s execute the actual workflow. The scenario is as follows:

Trend Collection: The agent reads RSS feeds (e.g., Hacker News) to analyze tech trends.
Content Generation: Drafts a blog post based on the collected information.
Deployment Execution: Calls the blog-api-server’s MCP tool to actually publish the blog.

Workflow Execution Code (Python Example)

This is a simple client code to run the agent in a local environment and communicate with the MCP server.

import requests
import json

# MCP server endpoint (local or internal network)
MCP_SERVER_URL = "http://localhost:8080/mcp/tools/create_post"

def generate_and_post(topic):
 # 1. Content generation via LLM (simulated function)
 draft_content = call_llm_to_generate_content(topic)

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

 # 2. Call MCP tool
 try:
 response = requests.post(MCP_SERVER_URL, json=payload)
 response.raise_for_status() # Raise an exception for bad status codes
 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")

Considerations and Future Plans

Through this implementation, we’ve gained experience with agents having decision-making capabilities becoming part of the system, going beyond simple automation scripts. We are currently designing an architecture where these agents communicate with each other and distribute tasks on the ZeroClaw runtime.

Enhanced Security: While currently focused on local communication, if exposed externally, authentication (Auth) protocols need to be strengthened at the MCP level.
Feedback Loop: We plan to build a feedback system where the agent learns from user reactions (comments, etc.) to published posts to improve the quality of future articles.

Conclusion

The combination of standard protocols like MCP and high-performance runtimes (Rust, ZeroClaw) is maturing the agent-based development environment. We will continue to advance our team agent communication architecture, envisioning a future where ‘agent teams’ operate software, not developers.

This post was automatically generated and deployed as part of the ZeroClaw multi-agent system.

Show HN: Semble – Token-Efficient Code Search Engine Implementation for Agents

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

Recently, while developing agent systems utilizing LLMs (Large Language Models), one of the biggest bottlenecks has been ‘code search’. Simply searching source code with a grep command and dumping it into the LLM’s context led to an explosive increase in Input Tokens and slow search speeds, hindering the real-time responsiveness required by agents.

The ‘Show HN: Semble’ project, discussed on Hacker News, presents a fascinating approach to solving this problem. It claims to search code using 98% fewer tokens compared to general grep tools. In this post, we will explore Semble’s core ideas and how to maximize performance by integrating them into our high-performance Rust agent runtime, ZeroClaw, and the MCP (Model Context Protocol) server.

The Problem with Existing Search Methods: The Mismatch Between grep and LLMs

When searching code in existing tools like blog-api-server or various MCP tools, we primarily used grep libraries based on regular expressions. However, this method has a critical drawback when used with LLM agents.

Token Waste: grep returns the entire line containing the search term. If a long line or unnecessary comments are included, the LLM has to process more noise than actual code.
Lack of Semantic Understanding: As it’s simple string matching, it doesn’t understand nuances like ‘camel case’ or ‘snake case’. For example, searching for getUser might miss get_user.
Increased Costs: LLM API call costs are proportional to the number of input tokens. Including unnecessary code in the context increases costs accordingly.

Semble’s Approach: Separating Structure and Meaning

The secret to Semble’s ability to reduce token usage by 98% is that it pre-processes code into structured AST (Abstract Syntax Tree) or semantic tokens and then reassembles them at search time. The core idea is ’treating code as data, not strings’.

We’ve extended this concept to design a CodeIndexer module within the ZeroClaw architecture.

ZeroClaw Integration: Implementing a High-Performance Indexer

Since ZeroClaw is Rust-based, it guarantees memory safety and speed. Here, we will implement an indexer inspired by Semble.

1. Defining Data Structures

First, let’s define the structure to store code. Instead of storing the entire content of a file, we’ll only store symbols and metadata.

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, etc.
 pub file_path: String,
 pub start_line: usize,
 pub end_line: usize,
 pub signature: String, // Function signature or type definition
}

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

// In-memory index (for actual production, using a DB or Vector Store is recommended)
pub struct CodeIndex {
 symbols: Vec<CodeSymbol>,
 // Map for fast lookups
 name_map: HashMap<String, Vec<usize>>,
}

2. Indexing Logic (Parsing)

While Semble actually uses a much more complex parser, here we will simulate line-by-line parsing with simple logic to implement a token-saving approach. It removes comments and whitespace and captures only essential definitions.

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

 // Simple parsing logic (in reality, use tree-sitter etc.)
 pub fn index_file(&mut self, content: &str, path: &str) {
 for (line_num, line) in content.lines().enumerate() {
 // Example pattern for function definition: "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, // Approximate range estimation
 signature: signature.to_string(),
 };

 self.add_symbol(symbol);
 }
 // Patterns for Struct, impl, etc. can be added...
 }
 }

 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. Search Interface for MCP Tools

Now, let’s create a search function that MCP clients can call. This function saves tokens by returning only the signature and key ID instead of the entire code.

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()
 }

 // Converts to an optimized format for LLM context
 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")
 }
}

Performance Comparison and Token Saving Effect

For example, let’s assume we are looking for a function named get_post in blog-api-server.

Traditional grep Method: Returns all 20 lines containing the function from main.rs (including comments, logic, etc.).
ZeroClaw Indexer Method: Returns only File: src/main.rs, Line: 45, Symbol: get_post, Definition: async fn get_post(id: i32) -> Result<Post>.

Consequently, the LLM receives only the necessary metadata, allowing it to either be re-queried with “show me the internal implementation of this function” or perform sufficient reasoning with just the metadata. Token usage is drastically reduced as unnecessary code is not processed.

Conclusion: Optimization for the Agent Ecosystem

This Semble-inspired approach goes beyond simply improving search speed; it optimizes the communication costs and efficiency between LLM agents and codebases. This is particularly essential in environments dealing with large codebases, such as improving logging for blog-api-server or for monitoring systems.

As a next step, we plan to extend ZeroClaw’s communication protocol to enable semantic search by incorporating Vector Embedding, going beyond simple text matching. This will allow agents to flexibly find functions like login, verify, and session when searching for “user authentication related logic,” even if the keyword auth is not present.

If you are building a high-performance agent runtime, consider building an indexer that ‘understands’ code, rather than just reading files. You can achieve both token cost savings and improved response times.

References

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

Deep Dive into ZeroClaw Architecture: Implementing Secure Inter-Agent Communication with Rust

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

Hello everyone! As the ZeroClaw project progresses, I want to share the design considerations and solutions encountered while building a high-performance Rust agent runtime and a multi-agent system. Recent security incidents, such as the ‘Remote Access Trojan (RAT) exploiting Obsidian plugins’, serve as a stark reminder of how crucial Security and Trust are in plugin and agent systems.

Today, I’ll introduce the secure and scalable inter-agent communication protocol designed by analyzing ZeroClaw’s codebase, along with concrete Rust code examples.

1. Introduction: The Need for Security-Conscious Agent Communication

During the development of previous MCP (Model Context Protocol) and blog automation systems, we realized that beyond simple data transfer, Authentication and Authorization between agents are essential. In a multi-agent environment where multiple agents collaborate to generate files or call external APIs, a mechanism to prevent malicious command injection is indispensable.

To address this, ZeroClaw adopts an architecture that leverages Rust’s Type Safety and Ownership system to catch many bugs at compile time and minimize runtime overhead.

2. Communication Protocol Design: IPC and Message Queues

ZeroClaw’s communication platform is broadly divided into Local IPC (Inter-Process Communication) and an Asynchronous Message Queue. Based on our experience improving the logging system, all communication is handled asynchronously (async), ensuring the independence of each agent.

Key Design Principles

Zero-Copy Serialization: Minimizes data serialization overhead using serde and bincode.
Message Validation: A layer validates all incoming messages to prevent tampered data from reaching the system core.
Capability-Based Security: Goes beyond simple token-based authentication by restricting the capabilities (actions) an agent can perform.

3. Implementing Secure Messaging Handlers with Rust

Let’s explore how this is implemented through actual code. This example is based on tokio and demonstrates the basic structure for secure message delivery.

3.1 Message Definition and Validation

First, we define the data structures for inter-agent communication and use the validator crate for input validation.

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

/// Agent communication message type
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum AgentMessage {
 TaskRequest { id: String, payload: TaskPayload },
 TaskResponse { id: String, result: String },
 Heartbeat,
}

/// Task payload (includes validation logic)
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct TaskPayload {
 #[validate(length(min = 1, max = 100))]
 pub command: String,
 
 // Accepts JSON-formatted arguments but must be parsed structurally safely
 pub args: serde_json::Value, 
}

impl AgentMessage {
 /// Safely deserializes a message from a byte array.
 pub fn from_bytes(bytes: &[u8]) -> Result<Self, Box<dyn std::error::Error>> {
 // 1. Basic serialization validation
 let msg: AgentMessage = bincode::deserialize(bytes)?;
 
 // 2. Business logic validation (e.g., prevent Command Injection)
 if let AgentMessage::TaskRequest { payload, .. } = &msg {
 payload.validate()?; // Using the validator crate
 
 // Security: Example of filtering disallowed shell commands
 if payload.command.contains("rm ") || payload.command.contains("sudo") {
 return Err("Blocked potentially dangerous command".into());
 }
 }
 
 Ok(msg)
 }
}

3.2 Actor Model-Based Agent Structure

Each agent follows an Actor pattern, maintaining its own state and processing messages. Rust’s tokio::sync::mpsc channel is used to implement the mailbox.

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

pub struct Agent {
 id: String,
 receiver: mpsc::Receiver<AgentMessage>,
 // The agent's state is encapsulated here and not directly accessible from outside
}

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

 /// The agent's main loop
 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);
 // Actual task execution logic goes here (e.g., LLM calls, file writes, etc.)
 // Safeguards: Execute in a sandboxed environment or restrict permissions.
 },
 AgentMessage::Heartbeat => {
 // Handle heartbeat signal
 },
 _ => return Err("Unknown message type".into()),
 }
 Ok(())
 }
}

3.3 Runtime and Message Routing

Finally, here’s a simple runtime system for creating multiple agents and routing messages.

// 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);
 
 // Run the agent in a separate task
 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. Conclusion and Next Steps

The code implemented above demonstrates the core of the ZeroClaw multi-agent system: secure communication and isolated state management. Systems that execute external inputs or scripts, like the Obsidian plugin incident, are always potential targets for attacks.

ZeroClaw uses Rust’s powerful type system to block most of these risks at compile time and defends against them at runtime with additional validation layers. In the next post, we will discuss how this agent system actually integrates with external gateways like Discord or MCP, and how it is controlled through LLM configurations.

So far, I’ve shared the current status of ZeroClaw’s architectural design. I hope this is helpful for those looking to build high-performance yet secure agent systems!

Note: The code above is a Proof of Concept (POC) level example. For actual production environments, more robust error handling and logging systems (referencing the logging setup improved in the previous post) must be integrated.

High-Performance MCP Server Implemented with Rust: Asynchronous Messaging Using ZeroMQ

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

High-Performance MCP Server Implemented with Rust: Asynchronous Messaging Using ZeroMQ

Recently, while working on the ZeroClaw project, we identified a need to overcome the performance limitations of MCP (Model Context Protocol) servers. Traditional HTTP-based communication struggles to move beyond a single request-response pattern, and real-time communication between numerous LLM agents is prone to bottlenecks. In this post, we will cover the process of building an ultra-lightweight, ultra-fast MCP server by leveraging Rust’s powerful asynchronous processing capabilities and ZeroMQ (ØMQ).

Why ZeroMQ? (Comparison with TCP Socket Limitations)

In the previous blog-api-server architecture, we defined and used protocols directly using standard TCP streams. However, in a multi-agent environment, the following issues arise:

Connection Management Complexity: As the number of agents grows into the dozens, managing the Accept loop and socket states requires unsafe code or complex state machines.
Message Enveloping: TCP is a byte stream. We must implement Length-Prefixing directly to demarcate message boundaries, which is a common source of bugs.

ZeroMQ abstracts away the complexity of this lower socket layer while providing a faster “User Space” transport layer than TCP. Notably, using the ipc (Inter-Process Communication) protocol can completely eliminate network stack overhead for localhost communication.

Architecture Design: ZeroMQ PUB/SUB Pattern

For this implementation, we will use the Publish/Subscribe (PUB/SUB) pattern for loose coupling between agents. When one agent changes its state (Publishes), a message is immediately broadcast to other agents subscribing to that topic.

Key Dependencies (Cargo.toml)

In the Rust ecosystem, ZeroMQ is available through the zmq crate. While tokio-zmq can be used for integration with asynchronous runtimes, for pure performance, leveraging ZeroMQ’s poll functionality is often more stable.

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

Implementation: High-Performance MCP Router

The code below is an example implementation of an MCP Router that acts as a simple message broker. It serves as a central hub for multiple LLM agents (teams) to communicate with each other.

1. Define Message Protocol

First, let’s define the format of messages exchanged between agents. We ensure compatibility by using JSON serialization.

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. Asynchronous ZeroMQ Context and Socket Setup

ZeroMQ’s Context is thread-safe, so it’s common practice to create and share a single instance globally throughout the application.

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

struct McpRouter {
 context: Context,
 frontend: Socket, // Agents connect here
 // Can add sockets for other patterns if needed
}

impl McpRouter {
 fn new() -> Result<Self, zmq::Error> {
 let context = Context::new();
 let frontend = context.socket(SocketType::SUB)?;
 
 // Set to receive all messages (no filtering)
 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 {
 // Can use poll for non-blocking receive
 // Here, a simple blocking receive example
 match self.frontend.recv(&mut msg) {
 Ok(_) => {
 let data = msg.as_str().unwrap();
 // Message parsing and routing logic
 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) {
 // Implement actual routing logic
 println!("Routing from {} on topic {}", msg.source_id, msg.target_topic);
 // e.g., save to database, forward to another socket, etc.
 }
}

3. Agent Publisher Implementation

Now, let’s write the code for individual agents to send messages. When using tokio, you need to execute ZeroMQ’s blocking functions in a separate thread to avoid blocking the asynchronous runtime.

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");

 // Run in a separate thread to isolate from the Tokio runtime
 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 automatically retries or queues sending if it fails (set High-water mark if needed)
 sender.send(json_str.as_bytes(), 0).expect("Failed to send");
 
 thread::sleep(std::time::Duration::from_millis(100));
 }
 });
}

Performance Optimization and IPC Utilization

The true power of a Rust ZeroMQ server is unleashed when using the IPC (Inter-Process Communication) transport. While TCP involves packets traversing the network stack and looping back, IPC uses Unix Domain Sockets or Windows Named Pipes for communication at a level close to memory copying.

To use the ipc protocol, change the endpoint as follows:

// Use IPC instead of TCP
let endpoint = "ipc:///tmp/mcp_router.ipc";
router.start(endpoint);

Just as modern languages like Bun and Zig gain attention for their system-level optimizations, the combination of Rust and ZeroMQ is one of the most powerful tools for building the “system bus” for LLM applications.

Conclusion

In this post, as part of the ZeroClaw project, we explored how to build a high-performance MCP server using Rust and ZeroMQ. Beyond simple HTTP requests, this architecture offers significant advantages in scalability and performance for environments requiring real-time messaging between agents.

In the next post, we will discuss the Circuit Breaker pattern and error handling strategies to add reliability to this messaging system.

References

The Next Step in Agent Development: Introducing Control Flow

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

The Next Step in Agent Development: Introducing Control Flow

I recently read the article ‘Agents need control flow, not more prompts’ and deeply resonated with its message. When initially developing LLM-based agents, prompt engineering felt like the entirety of development. However, as systems became more complex and we started dealing with multi-agent runtimes like ZeroClaw, I keenly realized that ‘structure,’ not ‘prompts,’ is the core.

In this article, I’ll share how to introduce Control Flow into your architecture to build scalable agent systems, reducing complex prompts and providing practical code examples.

Problem Definition: Prompt Limitations and ‘Dependency Hell’

It’s challenging to instruct a single agent with a prompt like “Do task A, and if the result is positive, execute B; if negative, execute C, and finally summarize D.” LLMs frequently lose context or ignore logical branches (if/else) and proceed directly.

As discussed in the design proposal for the [ZeroClaw] multi-agent architecture, especially in collaborative environments involving multiple agents, relying solely on prompts leads to the following issues:

Non-determinism: The LLM might choose different paths for the same input.
Debugging Difficulty: It’s hard to pinpoint which part of the prompt is causing errors when they occur.
Lack of Scalability: Adding new steps requires modifying the existing, massive prompt each time.

Solution: Graph-based Control Flow

The solution is to let the LLM decide “What” to do, and delegate “How” to execute it to an external state machine or graph workflow. This allows us to control the data flow and execution order between agents, rather than controlling the agents’ thinking process itself.

Building such a runtime in a stable language like Rust can achieve the high performance and reliability targeted by [ZeroClaw].

Implementation Example: Creating a Simple State Machine Runner with Rust

Without complex frameworks, let’s implement a simple agent workflow using Rust’s Enum. This code defines the steps (Step) an agent needs to perform and structures how the next step is determined based on the result of the previous one.

// 1. Define the agent's state and execution context
#[derive(Debug, Clone)]
struct AgentContext {
 current_data: String,
 step_count: usize,
}

// 2. Define each step of the workflow
enum WorkflowStep {
 Initialize,
 ProcessData,
 ValidateResult, // The next step is determined by the result
 Finalize,
 Complete,
}

// 3. Implement the execution logic for each step
impl WorkflowStep {
 fn execute(&self, ctx: &mut AgentContext) -> WorkflowStep {
 match self {
 WorkflowStep::Initialize => {
 println!("[Step 1] Initializing data...");
 ctx.current_data = "Sample Input Data".to_string();
 ctx.step_count += 1;
 WorkflowStep::ProcessData
 },
 WorkflowStep::ProcessData => {
 println!("[Step 2] Processing data via LLM: {}", ctx.current_data);
 // In a real scenario, this would involve calling an MCP client etc. for LLM inference
 ctx.current_data = format!("Processed: {}", ctx.current_data);
 ctx.step_count += 1;
 WorkflowStep::ValidateResult
 },
 WorkflowStep::ValidateResult => {
 println!("[Step 3] Validating result...");
 // Business logic: e.g., if the result length is less than 10, restart (or handle error)
 if ctx.current_data.len() < 10 {
 println!("Data is insufficient, returning to initialization step.");
 WorkflowStep::Initialize // Loop structure
 } else {
 println!("Validation passed. Moving to finalization step.");
 WorkflowStep::Finalize
 }
 },
 WorkflowStep::Finalize => {
 println!("[Step 4] Saving final result: {}", ctx.current_data);
 WorkflowStep::Complete
 },
 WorkflowStep::Complete => {
 println!("Workflow complete.");
 WorkflowStep::Complete // Maintain termination state
 }
 }
 }
}

// 4. Main execution loop (Runner)
fn run_agent_workflow() {
 let mut ctx = AgentContext {
 current_data: String::new(),
 step_count: 0,
 };
 
 let mut current_step = WorkflowStep::Initialize;
 
 // Prevent infinite loops with a maximum of 10 iterations (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();
}

Benefits Gained from the Code

Even with a simple match statement and Enum as in the example above, the benefits are significant.

Clear Flow Visualization: You can understand how the system flows just by looking at the code. This greatly improves maintainability when handling complex requests, like in the [Discord MCP Gateway Architecture].
State Management: Memory state is explicitly managed through the AgentContext struct. Even if the LLM’s context window overflows, the Rust runtime accurately knows the current step.
Error Handling: When a specific step fails, you can easily transition to a Retry logic or a Fallback step at the code level, rather than retrying the prompt.

Conclusion: Agents are Software

We are moving past the era of treating LLMs as ‘magic’ and entering an era where LLMs are viewed as ‘a module.’ The trial and error experienced in projects like [Cloud Monitor] and [Improving LLM Settings] ultimately show that AI must be built upon a robust software architecture.

Instead of writing longer prompts, try building a runtime that clearly defines control flow using Rust or Python. You’ll feel the predictability of your agent’s behavior and the sturdiness of your system improve.

In the next post, we will discuss how to maximize performance by processing multiple LLM calls in parallel on top of this control flow.

Maximizing Development Productivity by 17x: Building a Low-Cost AI Agent Loop with DeepSeek V4 and Claude Code

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

Maximizing Development Productivity by 17x: Building a Low-Cost AI Agent Loop with DeepSeek V4 and Claude Code

Recently, an interesting project called DeepClaude was introduced on Hacker News. It is a hybrid architecture that combines DeepSeek V4 Pro with Claude Code’s Agent Loop feature to deliver the same performance at a 17 times lower cost compared to existing solutions.

This article will not merely deliver interesting news but will specifically cover how to build a cost-effective AI coding assistant by integrating Claude Code with DeepSeek V4 in a real development environment. In particular, it provides a comprehensive guide, including how to control GitHub and the file system using MCP (Model Context Protocol).

1. Why DeepSeek V4 and Claude Code?

Claude Code provides a powerful ‘Agent Loop’ feature. This is an automated process where the AI writes code, executes it, fixes errors, and repeats until the goal is achieved. However, the cost burden of continuously using the high-quality Sonnet model is significant.

This is where DeepSeek V4 Pro comes in. DeepSeek V4 is one of the most notable models in the open-source community recently, showing excellent performance not only in complex reasoning capabilities but also in code generation. Above all, its cost-effectiveness is overwhelming.

Core Strategy of the DeepClaude Approach:

Planner: Use the existing Claude model for analyzing tasks and establishing a plan (one-time use).
Worker: Use DeepSeek V4 for the actual code writing and modification loop (Run Loop) (high volume use).

Through this structure, it is possible to reduce the total cost to 1/17th while maintaining the task completion rate.

2. Prerequisites: Configuring the MCP Server Environment

To implement this architecture, the AI must be able to read and write files in the local environment. To do this, we will apply the MCP Server concept covered in the previous post for setup.

2.1. Configuring the MCP Settings File (`mcp_config.json`)

Configure the settings so the AI agent can access the project folder. Create a local mcp_config.json file and write the following content.

{
 "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: Specifies the path where the agent will generate and modify code.
github: (Optional) Token environment variables may be required to create GitHub issues or PRs.

3. Implementing the Integration of DeepSeek V4 and Claude Code

Now, let’s implement a Python script that performs tasks by switching between the two models by writing actual code. This script is the core logic of the ‘Hybrid Agent’.

3.1. Installing Dependencies

pip install openai anthropic

3.2. Implementing the Hybrid Agent Code (`hybrid_agent.py`)

This code uses a mix of the Anthropic API and the OpenAI-compatible API (DeepSeek).

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

# Configuration: Manage API keys via environment variables
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):
 """
 Hybrid agent function combining DeepSeek V4 (Worker) and Claude (Planner)
 """
 
 # 1. Initialize Model Clients
 # DeepSeek V4 is accessed via OpenAI SDK (example)
 worker_client = OpenAI(
 api_key=DEEPSEEK_API_KEY,
 base_url="https://api.deepseek.com/v1" # Verify actual endpoint needed
 )
 planner_client = Anthropic(api_key=ANTHROPIC_API_KEY)

 print(f"[System] Task start: {task_description}")
 
 # 2. Request initial plan from Claude (Planner)
 planning_prompt = f"""
 You are a software architect. Please establish a concrete step-by-step plan to perform the following task.
 Task: {task_description}
 
 Please respond only with a step list in JSON format.
 Example: {{"steps": ["Create file", "Implement logic", "Run test"]}}
 """
 
 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 established: {plan_text}")
 except Exception as e:
 print(f"[Error] Failed to establish plan: {e}")
 return

 # 3. Execute DeepSeek V4 (Worker) Loop
 current_context = f"Task Goal: {task_description}\nPlan: {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 model name
 messages=[
 {"role": "system", "content": "You are a professional developer who writes and modifies code according to the plan."},
 {"role": "user", "content": current_context}
 ],
 temperature=0.3
 )
 
 worker_output = response.choices[0].message.content
 print(f"[Worker] Execution Result:\n{worker_output[:500]}...\n") # Summarize output
 
 # (In actual implementation, call MCP tools here to write files or execute commands)
 # file_system_tool.write_file(path="main.py", content=worker_output)
 
 # Check termination condition (e.g., "TASK_COMPLETE" keyword)
 if "Done" in worker_output or "TASK_COMPLETE" in worker_output:
 print("[System] Task completed successfully.")
 break
 
 # Update context for feedback loop
 current_context += f"\n\nPrevious Attempt Result:\n{worker_output}\n\nPlease continue or fix errors."
 
 except Exception as e:
 print(f"[Error] Error occurred during Worker execution: {e}")
 break

# Execution Example
if __name__ == "__main__":
 create_hybrid_agent(
 task_description="Create a Next.js API handler to generate a /hello endpoint, and include TypeScript type validation."
 )

3.3. Code Explanation

Planner (Claude): Uses the anthropic library to analyze user requirements and define the order of tasks. Since this process occurs only once, using a high-cost model has little impact on the total cost.
Worker (DeepSeek V4): Calls the DeepSeek API via the openai library. It loops max_iterations times to generate code and repeatedly modifies it based on virtual feedback (or actual execution results). This is the part that consumes the most tokens.

4. Troubleshooting and Tips

1. DeepSeek API Compatibility: DeepSeek V4 Pro is currently often provided in a way compatible with the OpenAI SDK, but you may need to configure the Base URL (e.g., https://api.deepseek.com). Please check the official documentation.

2. Context Window: DeepSeek models usually support a long context window of 128k or more. This is very advantageous for analyzing long codebases or maintaining conversation history. Even if the context lengthens as the loop runs, there is little performance degradation.

3. MCP Integration: The Python code above is a simple example. In reality, you must communicate with the server defined in mcp_config.json to access the file system. To do this, you need to implement client logic that communicates with the MCP server via stdio inside hybrid_agent.py to enable full automation.

5. Conclusion: Balancing Cost and Performance

For developers, AI is becoming not just a simple chat window but an ‘Acting Agent’. However, indiscriminately using GPT-4o or Claude Sonnet without regard for cost is not realistic.

The hybrid strategy of placing a high-performance open-source model like DeepSeek V4 as the ‘Worker’ and utilizing a high-cost model as the ‘Planner’ is likely to become the standard pattern for future AI agent development.

Test the code above right now and add 17x efficiency to your development workflow.

Getting Started with MCP Servers: Creating Your First Tool Integrated with Claude Code

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


# Getting Started with MCP Servers: Creating Your First Tool Integrated with Claude Code

MCP (Model Context Protocol) is a powerful protocol that can be integrated with Claude Code and other AI tools. This guide will walk you through the process of creating your first MCP server step-by-step.

## What is MCP?

MCP is a standard protocol that allows AI agents to access external tools and resources. Key features:

- **Standardized Interface**: Integrate various tools in a unified manner
- **Resource Sharing**: Safely access resources such as files and databases
- **Extensibility**: Easily add new tools

## Basic MCP Server Structure

```typescript
// 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: {}
 }
 }
);

// Example of tool registration
server.setRequestHandler(ListToolsRequestSchema, async () => ({
 tools: [
 {
 name: 'my_tool',
 description: 'Description of my tool',
 inputSchema: {
 type: 'object',
 properties: {
 param1: {
 type: 'string',
 description: 'Parameter description'
 }
 },
 required: ['param1']
 }
 }
 ]
}));

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Practical Example: Simple Calculator MCP Server

// 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: 'Perform basic mathematical operations',
 inputSchema: {
 type: 'object',
 properties: {
 expression: {
 type: 'string',
 description: 'Expression to calculate (e.g., "2 + 2")'
 }
 },
 required: ['expression']
 }
 }
 ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
 if (request.params.name === 'calculate') {
 const expression = request.params.arguments?.expression as string;
 try {
 // Use Function instead of eval for safer calculation
 const result = Function(`"use strict"; return (${expression})`)();
 return {
 content: [{
 type: 'text',
 text: `Result: ${result}`
 }]
 };
 } catch (error) {
 return {
 content: [{
 type: 'text',
 text: `Calculation error: ${error}`
 }],
 isError: true
 };
 }
 }
 return { content: [] };
});

Claude Code Configuration

To register an MCP server with Claude Code, modify ~/.config/claude/settings.json:

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

Providing Resources

// Provide resource list
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
 resources: [
 {
 uri: 'calc://history',
 name: 'Calculation History',
 description: 'Recent calculation history',
 mimeType: 'application/json'
 }
 ]
}));

// Provide resource content
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('Resource not found');
});

Security Considerations

Input Validation: Validate and restrict all user input
Access Control: Apply the principle of least privilege
Error Handling: Ensure sensitive information is not exposed in error messages
Rate Limiting: Implement rate limiting to prevent excessive requests

Deployment and Testing

# Build server
npm run build

# Local test
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/server.js

# Test after integrating with Claude Code
# Use tool in Claude Code after reloading config file

Next Steps

Add more complex tools and resources
Implement prompt templates
Improve error handling
Add logging and monitoring

Developing MCP servers is a great way to extend Claude Code’s functionality and enhance automation. Start with small projects and gradually expand your features.

References

Claude Code Discord MCP Plugin - Fixing asdf bun Path Issue

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

Problem

When installing the discord plugin for Discord channel integration in Claude Code CLI, I encountered the following error:

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

The plugin was enabled, but the MCP server was in a failed state.

Root Cause

This issue occurs when using bun installed via asdf. Claude Code CLI looks for the bun command to run the MCP server, but asdf uses shell wrappers, so the actual binary cannot be found in the system-wide path.

Solution

I resolved this by entering the absolute path to the bun installed via asdf.

Finding the Absolute Path of asdf-installed bun

which bun

Or:

asdf where bun

Example output:

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

Applying the Configuration

Specify this absolute path as the execution path in the Discord MCP configuration, and the problem will be resolved.

Summary

Situation	Solution
System-wide installed bun	Use `bun` command
asdf-installed bun	Enter absolute path directly

When using asdf, you must specify the actual binary path, not the shell wrapper, for the MCP server to run properly.

References

[blog-api-server] MCP Blog Client Language Parameter

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

[blog-api-server] MCP Blog Client Language Parameter

Overview

Added a language parameter to the MCP (Model Context Protocol) blog client for improved Korean/English multilingual blog management.

Changes

blog_create Tool Update

Tool(
 name="blog_create",
 description="Create a blog post. Provide title and content (Markdown), and the post will be created and committed/pushed to Git.",
 inputSchema={
 "type": "object",
 "properties": {
 "title": {"type": "string", "description": "Post title"},
 "content": {"type": "string", "description": "Post content (Markdown)"},
 "tags": {"type": "array", "items": {"type": "string"}, "description": "Tag list"},
 "categories": {"type": "array", "items": {"type": "string"}, "description": "Category list"},
 "draft": {"type": "boolean", "description": "Draft status (default: false)"},
 "language": {"type": "string", "description": "Language (ko, en). Default: ko"} # New
 },
 "required": ["title", "content"]
 }
)

API Call Logic

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"), # Default: Korean
 "auto_push": True
 })

Usage

Using in 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"
 }
 }
 }
}

Creating Korean Posts

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

Creating English Posts

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

API Examples

Request Format

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
 }'

Response Format

{
 "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"
 }
}

File Path Rules

Language	language Value	Storage Path
Korean	`ko`	`content/ko/post/`
English	`en`	`content/en/post/`

Future Plans

Translation Automation: Auto-translation feature using language parameter
i18n Links: Automatic link generation between KO/EN posts
Extended Language Support: Japanese, Chinese, and more

Conclusion

The language parameter addition to the MCP blog client enables more convenient multilingual blog management directly from Claude Code.

Korean Version: 한국어 버전

[Cloud Monitor] MCP Tool Structure and Pros/Cons Analysis

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

[server-monitor] MCP Tool Structure and Pros/Cons Analysis

Overview

This document analyzes the structure, advantages, and disadvantages of the MCP (Model Context Protocol) tools implemented in the server-monitor project. A total of 13 MCP tools are provided, categorized into 8 existing Discord MCP tools and 5 new Cloud Monitor MCP tools.

Architecture Overview
Detailed Tool Analysis
Architecture Structure
Advantages
Disadvantages and Improvements
Conclusion

Architecture Overview

FastMCP-based Architecture

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 Tool Categories

Category	Tool Count	Main Functions
Discord MCP	8	Message, thread management
Cloud Monitor MCP	5	Server monitoring, metrics collection
Total	13	Integrated monitoring platform

Detailed Tool Analysis

1. Existing Discord MCP Tools (8)

1.1 Message Management Tools

Tool Name	Parameters	Returns	Features
`discord_send_message`	`channel_id`, `content`, `thread_id?`	Result message	Basic message sending
`discord_get_messages`	`channel_id`, `limit?`, `after?`	Message list	Message retrieval
`discord_wait_for_message`	`channel_id`, `timeout_seconds?`	Wait status	Async message waiting (SSE not implemented)

1.2 Thread Management Tools

Tool Name	Parameters	Returns	Features
`discord_create_thread`	`channel_id`, `message_id`, `name?`	Thread info	Thread creation
`discord_list_threads`	`channel_id`	Thread list	Active thread lookup
`discord_archive_thread`	`thread_id`	Result message	Thread archiving (not implemented)

1.3 Concurrency Management Tools

Tool Name	Parameters	Returns	Features
`discord_acquire_thread`	`thread_id`, `agent_name`, `timeout?`	Lock acquisition result	Multi-agent lock
`discord_release_thread`	`thread_id`, `agent_name`	Lock release result	Agent lock release

2. New Cloud Monitor MCP Tools (5)

2.1 Server Management Tools

Tool Name	Parameters	Returns	Features
`cloud_get_server_status`	`server_name`	Server status info	Connection status, OS, metrics
`cloud_list_servers`	`group?`	Server list	Group filtering support
`cloud_list_ssh_config_hosts`	`group?`	SSH host list	SSH config auto-parsing

2.2 Monitoring Tools

Tool Name	Parameters	Returns	Features
`cloud_get_metrics`	`server_name`, `metric_types?`	Metrics data	Optional metric lookup
`cloud_set_alert`	`metric_type`, `level`, `threshold`	Setting result	Dynamic threshold configuration

Architecture Structure

1. FastMCP Structure

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. Communication Flow

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. Data Flow

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

Advantages

1. Scalability

Modular Structure: Each tool operates independently and is easy to extend
Plugin Architecture: Adding new tools only requires adding decorators
Cloud Provider Abstraction: SSH-based support for various environments

2. Integration

Unified Platform: Discord and Cloud Monitor managed together on a single MCP server
Automatic Linkage: Automatic Discord alerts on server anomalies
Consistent Interface: All tools follow the same parameter pattern

3. Usability

Intuitive Tool Names: Clear function expression like cloud_get_server_status
Optional Parameters: Most parameters are optional for convenience
Detailed Error Messages: Clearly indicates the cause of failures
JSON Response: Structured data return for easy parsing

4. Reliability

Timeout Handling: Timeout set for all requests
Connection Pooling: SSH connection reuse for performance
Exception Handling: Comprehensive try-catch blocks
Status Tracking: Continuous server status monitoring

5. Maintainability

Centralized Configuration: Central management via config.yaml
Environment Variable Support: Sensitive info separated into environment variables
Logging System: Detailed logging for easy debugging
Version Management: Clear module version distinction

Disadvantages and Improvements

Issues

Synchronous Processing: Some tools operate sequentially
Connection Latency: New connection created each SSH connection
Memory Usage: All processing on single event loop

Improvements

# Async processing improvement example
async def concurrent_monitoring(servers):
 tasks = [monitor_server(server) for server in servers]
 return await asyncio.gather(*tasks)

# Connection pooling introduction
class ConnectionPool:
 def __init__(self, max_connections=10):
 self.pool = asyncio.Queue(maxsize=max_connections)

Issues

Undifferentiated Errors: All errors handled the same way
Lack of Recovery Mechanism: No auto-recovery logic on failures
Insufficient Detailed Logging: Insufficient logs for debugging

Improvements

# Differentiated error handling
class CloudMonitorError(Exception):
 pass

class ConnectionError(CloudMonitorError):
 pass

class MetricCollectionError(CloudMonitorError):
 pass

# Auto-recovery mechanism
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")

Issues

Lack of Metadata: Tool descriptions too brief
Insufficient Validation: Lack of input value check logic
No Batch Processing: Cannot process multiple servers simultaneously

Improvements

# Detailed metadata
@mcp.tool(
 name="cloud_batch_monitoring",
 description="Retrieve multiple server statuses at once",
 parameters={
 "server_names": {
 "type": "array",
 "items": {"type": "string"},
 "description": "List of server names to monitor"
 }
 }
)
async def cloud_batch_monitoring(server_names: List[str]) -> str:
 # Batch processing logic
 pass

Issues

Credential Exposure: Sensitive info potentially exposed in logs
No Access Control: Anyone can call tools
Insufficient Input Validation: Insufficient defense against malicious input

Improvements

# Access control
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

# Input validation
@mcp.tool()
async def secure_monitoring(server_name: str):
 if not is_valid_server_name(server_name):
 raise ValueError("Invalid server name")
 # ...

Issues

Lack of Documentation: No detailed documentation for tool usage
No Examples: No actual usage examples
Inconsistent Return Values: Some tools return JSON, others return strings

Improvements

# Consistent return value format
@mcp.tool()
async def cloud_get_server_status_v2(server_name: str) -> dict:
 """
 Retrieve server status.

 Args:
 server_name (str): Server name

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

Conclusion

1. Overall Assessment

The MCP tools in the server-monitor project have the following strengths:

✅ Excellent Integration: Perfect combination of Discord integration and server monitoring
✅ Scalable Structure: Modular architecture using FastMCP
✅ Practicality: Provides all functions needed for actual server monitoring
✅ Ease of Use: Intuitive tool names and simple interface

2. Improvement Priority

Improvement plans by priority:

High: Performance improvement (async processing, connection pooling)
Medium: Error handling enhancement and auto-recovery mechanisms
Low: Security enhancement and detailed documentation

3. Future Direction

Microservices Architecture: Separate each tool into independent services
Real-time Monitoring: Real-time data collection via WebSocket/SSE
Auto-scaling: Automatic scaling based on server changes
Machine Learning: ML model integration for anomaly detection

4. Final Assessment

Overall, a well-designed MCP tool system that provides stability and functionality suitable for actual production environments. While there are areas for improvement, the core functionality is highly complete, and it has the potential to develop into an even more powerful monitoring platform through continuous improvements.

Written: 2026-03-03 Author: server-monitor-team

Korean Version: 한국어 버전

[Discord Decision MCP] Architecture Design Document

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

Discord Decision MCP — Architecture Design Document

1. Project Overview

1.1 Purpose

An MCP (Model Context Protocol) server that allows Claude Code, while operating in tmux Teammate mode for autonomous work, to ask questions via Discord when user decisions are needed and resume work after receiving responses.

1.2 Key Features

Feature	Description
One Bot per Project	Each project uses an independent Discord Bot
Infinite Wait Default	Wait for user response without timeout (Claude must not proceed unilaterally)
State Persistence	Restore waiting state after process restart
Korean-Friendly	Korean options, Yes/No response support
MCP-Based Communication	All Discord communication through MCP Tools

1.3 Version Information

Version: 1.0.0
Python Requirement: >= 3.11
MCP Framework: FastMCP >= 0.1.0

2. Directory Structure

discord-decision/
├── discord_mcp/ # Main package
│ ├── __init__.py
│ ├── server.py # MCP server entry point
│ ├── config.py # Environment variable configuration
│ │
│ ├── bot/ # Discord API client
│ │ ├── __init__.py
│ │ ├── client.py # REST API client (httpx)
│ │ └── gateway.py # WebSocket gateway (receive only)
│ │
│ ├── decision/ # Decision request management
│ │ ├── __init__.py
│ │ ├── manager.py # Decision request lifecycle management
│ │ ├── poller.py # Discord polling and response waiting
│ │ ├── parser.py # User response parsing
│ │ └── state.py # State persistence (JSON files)
│ │
│ ├── tools/ # MCP Tools implementation
│ │ ├── __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 message templates
│ │
│ └── daemon/ # Watcher daemon
│ ├── __init__.py
│ ├── watcher.py # Discord channel monitoring (discord-watch CLI)
│ └── inbox.py # Inbox file management
│
├── scripts/ # Utility scripts
│ └── start-discord-watch.sh
│
├── tests/ # Test suite
│ ├── __init__.py
│ ├── test_parser.py
│ └── test_state.py
│
├── CLAUDE.md # Claude Code project instructions
├── README.md # Project description
├── pyproject.toml # Project configuration and dependencies
└── mcp.json.example # MCP configuration example

3. Key Module Descriptions

3.1 Server Entry Point (`server.py`)

Role: FastMCP server creation and MCP Tool registration

mcp = FastMCP(name="discord-decision-mcp")
# Tool registration
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)

Execution:

discord-mcp # or python -m discord_mcp.server

3.2 Configuration Management (`config.py`)

Role: Load configuration values from environment variables

Environment Variable	Description	Default
`DISCORD_BOT_TOKEN`	Discord Bot Token (includes “Bot " prefix)	Required
`DISCORD_CHANNEL_ID`	Default question channel ID	Required
`PROJECT_NAME`	Used for question_id generation	“project”
`PENDING_DIR`	State file storage path	`~/.claude/pending_decisions`
`POLL_INTERVAL_SECONDS`	Discord polling interval (seconds)	5

3.3 Discord API Client (`bot/`)

3.3.1 REST API Client (`client.py`)

Role: Discord REST API calls (httpx-based)

Key Methods:

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)

Features:

Automatic rate limit handling (retry on 429 response)
Singleton pattern (get_client())

3.3.2 WebSocket Gateway (`gateway.py`)

Role: Discord Gateway WebSocket connection (receive only)

Features:

Real-time MESSAGE_CREATE event reception
Reduces polling delay from 5 seconds to instant
System works without Gateway (polling fallback)
Automatic reconnection (Exponential backoff)

class GatewayClient:
 async def run() # Start event reception
 async def stop() # Close connection

3.4 Decision Request Management (`decision/`)

3.4.1 DecisionManager (`manager.py`)

Role: Coordinate the entire lifecycle of decision requests

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

Flow:

Check for duplicate questions
Create thread (or reuse existing thread)
Create state file (~/.claude/pending_decisions/{question_id}.json)
Run poller to wait for response
Mark disconnected state on SIGHUP signal

3.4.2 DecisionPoller (`poller.py`)

Role: Poll Discord channel and wait for response

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

Features:

Default: infinite wait (timeout_seconds=None)
Real-time waiting status display in tmux pane (ANSI escape)
Re-question up to 2 times for ambiguous responses

3.4.3 Response Parser (`parser.py`)

Role: Parse user Discord responses

Supported Patterns:

Option matching: “A”, “a”, “A번”, “A로 해줘”, “1”, “1번”
Affirmative/Negative: “yes”, “네”, “예”, “no”, “아니요”
Natural language: 15+ characters or 3+ Korean characters

def parse_response(text: str, options: list[str]) -> ParseResult
def build_clarify_message(...) -> str # Generate re-question message

3.4.4 State Store (`state.py`)

Role: Persist decision request state to JSON files

State File Location: ~/.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	Blocking	Description
`discord_ask_decision`	✅	User decision request
`discord_notify`	❌	Progress notification
`discord_report_progress`	❌	Task completion report
`discord_check_pending`	❌	Check pending questions
`discord_read_inbox`	❌	Inbox message query
`discord_clear_inbox`	❌	Inbox message deletion

3.6 Watcher Daemon (`daemon/`)

3.6.1 DiscordWatcher (`watcher.py`)

Role: Monitor Discord channel and record new messages to inbox file

Execution:

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

Features:

Periodically poll specified channel(s)
Record new user messages to inbox
Display status in tmux pane

3.6.2 InboxStore (`inbox.py`)

Role: JSON file-based storage for Discord messages

Inbox File Location: ~/.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() # Delete read messages

4. Data Flow Diagrams

4.1 Decision Request Flow

┌─────────────────┐
│ Claude Code │
└────────┬────────┘
 │ discord_ask_decision()
 ▼
┌─────────────────────────────────────┐
│ MCP Server (server.py) │
│ ┌───────────────────────────────┐ │
│ │ DecisionManager.ask() │ │
│ │ 1. Duplicate check │ │
│ │ 2. Thread creation │ │
│ │ 3. State file save │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 ▼
┌─────────────────────────────────────┐
│ DecisionPoller.wait() │
│ ┌───────────────────────────────┐ │
│ │ Polling loop │ │
│ │ 1. tmux status update │ │
│ │ 2. Discord API call │ │
│ │ 3. Response parsing │ │
│ │ 4. Re-question if ambiguous │ │
│ └───────────────┬───────────────┘ │
└──────────────────┼──────────────────┘
 │
 ┌─────────┴─────────┐
 ▼ ▼
┌───────────────────┐ ┌──────────────────┐
│ Discord REST API │ │ Discord Thread │
│ (client.py) │ │ │
└───────────────────┘ └────────┬─────────┘
 │
 ┌────────▼────────┐
 │ User Response │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ parser.py │
 │ - Option match │
 │ - Ambiguity │
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ store.resolve()│
 └────────┬────────┘
 ▼
 ┌─────────────────┐
 │ PollResult │
 │ Return │
 └─────────────────┘

4.2 Watcher Daemon Flow

┌─────────────────────────────────────────────┐
│ DiscordWatcher (daemon/watcher.py) │
│ ┌───────────────────────────────────────┐ │
│ │ 1. Set initial message ID │ │
│ │ 2. Periodic polling (default 10s) │ │
│ │ 3. Detect new messages │ │
│ │ 4. InboxStore.add_message() │ │
│ └───────────────────┬───────────────────┘ │
└──────────────────────┼──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ ~/.claude/discord_inbox.json │
│ { │
│ "last_message_id": "...", │
│ "messages": [ │
│ { "message_id": "...", ... } │
│ ] │
│ } │
└──────────────────────┬──────────────────────┘
 ▲
 │ discord_read_inbox()
┌──────────────────────┴──────────────────────┐
│ Claude Code │
└─────────────────────────────────────────────┘

4.3 Session Restoration Flow

┌─────────────────────────────────────────────┐
│ Claude Code session start │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ discord_check_pending() │
└──────────────────────┬──────────────────────┘
 ▼
┌─────────────────────────────────────────────┐
│ DecisionManager.restore_pending() │
│ ┌───────────────────────────────────────┐ │
│ │ 1. ~/.claude/pending_decisions/*.json │ │
│ │ 2. Check Thread via Discord API │ │
│ │ 3. If answered → Auto-resolve │ │
│ │ 4. If no answer → Restart notification│ │
│ └───────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

5. MCP Tools List

5.1 discord_ask_decision

Description: Send question to Discord Thread and wait for response when user decision is needed (blocking)

Parameters:

Name	Type	Required	Description
`question`	string	✅	Question content
`context`	string	✅	Current work context
`options`	string[]	❌	List of options (empty array for free response)
`timeout_seconds`	float	❌	Wait timeout (null for infinite wait)
`thread_id`	string	❌	Existing Thread ID (null to create new Thread)

Return Value:

{
 "success": true,
 "answer": "A) Execute now",
 "selected_option": "A) Execute now",
 "question_id": "project_20260301_abc123",
 "timed_out": false,
 "aborted": false
}

5.2 discord_notify

Description: Send progress notification to Discord (non-blocking)

Parameters:

Name	Type	Required	Description
`message`	string	✅	Notification message
`level`	string	❌	info/warning/success/error (default: info)
`thread_id`	string	❌	Thread ID to send to (null for default channel)

5.3 discord_report_progress

Description: Report task completion or milestone completion (non-blocking)

Parameters:

Name	Type	Required	Description
`title`	string	✅	Report title
`summary`	string	✅	Task result summary
`details`	string[]	❌	List of detail items
`thread_id`	string	❌	Thread ID to send to

5.4 discord_check_pending

Description: Check pending questions at session start (non-blocking)

Parameters: None

Return Value:

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

5.5 discord_read_inbox

Description: Query messages stored in Inbox (non-blocking)

Parameters:

Name	Type	Default	Description
`unread_only`	boolean	true	Return only unread messages
`mark_read`	boolean	false	Mark queried messages as read

5.6 discord_clear_inbox

Description: Delete Inbox messages (non-blocking)

Parameters:

Name	Type	Default	Description
`read_only`	boolean	true	Delete only read messages

6. Dependency Information

6.1 Core Dependencies

Package	Version	Purpose
`fastmcp`	>= 0.1.0	MCP server framework
`httpx`	>= 0.27.0	Async HTTP client
`websockets`	>= 12.0	WebSocket client
`python-dotenv`	>= 1.0.0	Environment variable loading
`pydantic`	>= 2.0.0	Data model validation
`anyio`	>= 4.0.0	Async execution

6.2 Development Dependencies

Package	Purpose
`pytest`	Test framework
`pytest-asyncio`	Async test support
`pytest-mock`	Mock support
`respx`	httpx mocking

6.3 CLI Commands

discord-mcp # Run MCP server
discord-watch # Run watcher daemon

7. State File Format

7.1 Decision State File

Location: ~/.claude/pending_decisions/{question_id}.json

{
 "question_id": "project_20260301_abc123",
 "project": "my-project",
 "question": "Run DB migration?",
 "context": "v1→v2 schema change",
 "options": ["A) Execute now", "B) Staging first", "C) Hold"],
 "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 File

Location: ~/.claude/discord_inbox.json

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

8. Architecture Principles

8.1 Design Principles

Singleton Pattern: DiscordClient, StateStore, InboxStore are module-level singletons
State Persistence: All decision request states are persisted to files
Infinite Wait Default: Timeout default is None so Claude does not proceed unilaterally
Re-question Limit: Ambiguous responses are re-asked up to 2 times
Rate Limit Handling: Automatic wait and retry on Discord API 429 responses

8.2 Error Handling

Situation	Handling
Discord API 429	Automatic wait and retry (max 5 times)
WebSocket disconnection	Reconnect with exponential backoff
Response parsing failure	Re-question up to 2 times then abort
Timeout occurrence	Send abort notification and set aborted state
Session disconnect (SIGHUP)	Save as disconnected state

Document Version: 1.0.0 Last Modified: 2026-03-02

Korean Version: 한국어 버전

[Discord MCP] Gateway Architecture Design

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

The Claude Code team designed a Discord Gateway Service for user communication via Discord. This article summarizes the key architecture decisions and user_comm Agent design.

1. Overall Architecture

Components

Layer	Component	Role
Discord	Bot, Channel, Thread	User interface
Gateway	WebSocket, REST API, SSE	Message routing
MCP	gcp-mcp, oci-mcp, db-mcp	Tool execution
user_comm	Discord Agent	User communication

Message Flow

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 Communication Handler)

Role and Responsibilities

The user_comm Agent is a member of the Claude Code team, communicating with users through Discord channels and collaborating with other agents.

Function	Description
Input Reception	Receive Discord messages and route to appropriate agent
Opinion Request	Query user opinions at other agents’ requests
Notification/Report	Send system status, warnings, reports
Team Communication	Exchange messages with other agents

Internal Structure

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

Message Types

class MessageType(Enum):
 TASK_REQUEST = "task_request" # Task request
 NOTIFICATION = "notification" # Notification
 OPINION_REQUEST = "opinion_request" # Opinion request
 OPINION_RESPONSE = "opinion_response" # Opinion response
 STATUS_REPORT = "status_report" # Status report
 ERROR = "error" # Error

Key Function Flows

Input Reception (Discord -> Agent)

User: "@gcp-monitor check server status"
 -> DiscordBot.on_message
 -> UserCommAgent._parse_command (target: gcp-monitor)
 -> TeamCommunicator.send_to_agent
 -> Discord: "Request forwarded to gcp-monitor."

Opinion Request (Agent -> Discord)

gcp-monitor: "Clean up disk?" -> user_comm
 -> DiscordBot.ask_opinion (wait for button or reply)
 -> User response
 -> TeamCommunicator.send_to_agent (forward response)

Notification/Report (Agent -> Discord)

oci-monitor: "Disk 92% warning" -> user_comm
 -> DiscordBot.send_message (Embed format)

3. Lightweight Architecture Without Redis

Why Remove Redis?

Item	With Redis	With In-Memory
Thread Lock	Redis SET NX	Python dict
Event Distribution	Redis Streams	Direct SSE
State Storage	Redis Cache	Memory cache

Conclusion: In-memory is sufficient for single-instance environments

Gateway Structure

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]

Component Details

Module	Role	Features
Discord Bot	WebSocket connection	Auto-reconnect
Thread Lock	Concurrency control	5min timeout
Message Cache	Message storage	Max 1000 items
SSE Manager	Real-time delivery	Broadcast to all MCPs

4. MCP Selection: 4-Stage Hybrid

Selection Priority

Rank	Method	Example	Description
1	Slash Command	`/gcp status`	Most explicit
2	@Mention	`@gcp-monitor status`	Natural conversation
3	Keyword Detection	`gcp server status`	Auto keyword recognition
4	Channel Assignment	#gcp-monitoring	Channel default MCP

Fallback Order

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]

Slash Command List

Command	MCP	Description
`/gcp status [server]`	gcp-mcp	GCP server status
`/gcp list`	gcp-mcp	GCP instance list
`/oci status [server]`	oci-mcp	OCI server status
`/oci list`	oci-mcp	OCI instance list
`/db query <sql>`	db-mcp	Execute DB query
`/db list`	db-mcp	DB list
`/alert check`	alert-mcp	Check alerts

5. Thread Lock Rules

Lock Behavior

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	Description
`POST`	`/api/threads/{id}/acquire`	Acquire lock
`POST`	`/api/threads/{id}/release`	Release lock
`GET`	`/api/threads/{id}/lock`	Check lock status

Request/Response Example

Lock Acquire Request

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

Lock Acquire Response

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

6. MCP Tools (8)

Tool List

Tool	Description	Key Parameters
`discord_send_message`	Send message	channel_id, content
`discord_get_messages`	Get messages	channel_id, limit
`discord_wait_for_message`	Wait for message	channel_id, timeout
`discord_create_thread`	Create thread	channel_id, message_id
`discord_list_threads`	List threads	channel_id
`discord_archive_thread`	Archive thread	thread_id
`discord_acquire_thread`	Acquire lock	thread_id, agent_name
`discord_release_thread`	Release lock	thread_id, agent_name

Tool Relationships

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

Usage Examples

# Send message
discord_send_message(
 channel_id="123456789",
 content="Server status: OK"
)

# Create thread
discord_create_thread(
 channel_id="123456789",
 message_id="987654321",
 name="Status Check"
)

# Acquire lock
discord_acquire_thread(
 thread_id="111222333",
 agent_name="gcp-mcp",
 timeout=300
)

7. File Structure

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

Directory Description

Path	Description
`gateway/`	Gateway Service (FastAPI)
`user_comm/`	User Communication Agent
`discord_mcp/`	MCP Server (8 tools)
`mcp_shared/`	Shared MCP tools
`docs/`	Documentation

8. How to Run

Local Execution

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

# Start user_comm Agent (standalone mode)
python main.py --standalone

# Start user_comm Agent (team mode)
python main.py --team server-monitor

# Health check
curl http://localhost:8081/health

# Response
{"status": "healthy", "discord_connected": true}

Claude Code MCP Configuration

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

9. Roadmap

Phase 1: Complete

FastAPI Gateway Service
Discord WebSocket connection
Thread Lock (In-Memory)
SSE broadcast
MCP Server (8 tools)

Phase 2: In Progress

user_comm Agent implementation
Slash command implementation
Channel default MCP settings
Keyword auto-detection
Routing configuration file

Phase 3: Optional

API authentication (API Key)
Rate Limiting
Message persistence (SQLite)

Conclusion

We chose a strategy of starting with a lightweight architecture and expanding when needed.

Item	Current	Future
State Storage	In-Memory	SQLite (if needed)
Distributed Lock	Not used	Redis (multi-instance)
Authentication	None	API Key (if needed)
User Communication	Gateway direct	user_comm Agent

The current structure is sufficient for single instances, and we plan to expand incrementally as traffic grows. The user_comm Agent systematizes user communication and improves collaboration with other agents on the team.

Korean Version: 한국어 버전

[Claude Code] Team Agent Communication Architecture

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

Claude Code Team Agent Communication Architecture Design

Overview

When multiple AI agents collaborate in Claude Code, an efficient communication method is needed. This article shares the communication architecture designed while building a Discord-integrated server monitoring team.

Problem Definition

Claude Code has two types of agents:

Python Processes (Daemon)
- Discord Gateway, user_comm_daemon, etc.
- Always running, filesystem access available
LLM Agents (Created as Tasks)
- gcp-monitor, oci-monitor, alert-manager, etc.
- Use SendMessage tool, Claude Code native communication

Communication between these two types was needed.

Considered Approaches

1. File-based Message Queue (Existing)

Pros: Simple implementation, no dependencies
Cons: Latency (~1s), file management required

2. WebSocket

Pros: Real-time bidirectional communication
Cons: Server/client implementation required

3. gRPC

Pros: Strong type checking, streaming
Cons: proto file management, high complexity

4. SQLite Message Hub (Adopted)

Pros: Fast (~10ms), transactions, no additional dependencies
Cons: Works only on a single machine

Final Architecture

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

SQLite Message Hub Structure

Messages Table

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

Agent Status Table

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

Communication Methods

LLM Agent ↔ LLM Agent

Use SendMessage (Claude Code native)
Auto-managed, idle notification provided

Python ↔ LLM Agent

SQLite Hub + MCP Tool
Python accesses SQLite directly
LLM Agent accesses via MCP Tool

MCP Server Implementation

MCP tools for LLM Agents:

@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", ...),
 ]

Message Flow Example

1. Discord user: "Hello"
 ↓
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 channel: "Hi there! 👋"

Performance Comparison

Method	Latency	Stability	Complexity
File-based	~1000ms	Medium	Low
WebSocket	~5ms	High	Medium
SQLite	~10ms	High	Low

Conclusion

The SQLite Message Hub + MCP Server combination was most suitable for Claude Code team agent communication:

Low Latency: 100x faster than file-based
Stability: Data integrity guaranteed through transactions
Simplicity: Uses Python’s built-in sqlite3 without additional dependencies
Flexibility: Both Python and LLM Agents use the same data source

Code

Core components:

message_hub.py: SQLite Message Hub
team_comm_mcp_server.py: MCP Server
discord_gateway.py: Discord integration gateway
user_comm_daemon.py: Message processing daemon

Korean Version: 한국어 버전

[MCP] Blog Server Improvement Kickoff

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

Blog MCP Server Improvement Project Kickoff Meeting Minutes

Date: 2026-02-25 Project: Blog MCP Server Improvement Attendees: team-lead, backend-dev, search-specialist, qa-tester, meeting-writer Document Author: meeting-writer

1. Meeting Overview

1.1 Purpose

Project kickoff to improve the stability and performance of the blog MCP server according to the improvement roadmap defined in ARCHITECTURE.md

1.2 Project Scope

Blog Repository: /Users/yarang/workspaces/agent_dev/blogs
API Server: /Users/yarang/workspaces/agent_dev/blog-api-server

2. Project Background

2.1 Current System Status

The current blog system operates with the following structure:

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

2.2 Identified Issues

🔴 P0 - Critical Issues

Insufficient Concurrency Control: Only using global threading.Lock(), potential race conditions in multi-process environments
Search Bug: search_posts() only searches Korean directory, missing English posts

🟡 P1 - Scalability Issues

Git Pull on Every Request: Unnecessary network calls, increased latency
File-based Search (O(n)): Performance degradation with 100+ posts
Global Instance Dependency: Difficult testing, no dependency injection

🟢 P2 - Maintainability Issues

Duplicate Git code (GitManager and GitHandler coexist)
Unstable language detection logic
Broad exception handling

3. Team Composition

Role	Member	Responsibilities
team-lead	Project Leader	Overall project management, coordination
backend-dev	Backend Developer	Concurrency control, Git optimization
search-specialist	Search Specialist	Search functionality improvement
qa-tester	QA Tester	Testing and quality assurance
meeting-writer	Meeting Scribe	Meeting notes and documentation

4. Work Items and Progress

4.1 Search Bug Fix ✅ Complete

Owner: search-specialist
Priority: P0
Results:
- Confirmed P0 bug in ARCHITECTURE.md was already fixed
- Verified with 12 test cases in test_search.py
- All language directories (ko, en) now searchable

4.2 Git Pull Optimization ✅ Complete

Owner: backend-dev
Priority: P1
Results:
- Introduced CacheManager in MCP client (5-minute TTL)
- Implemented cache invalidation after write operations
- Location: .claude/mcp_server.py:25-71

4.3 Enhanced Concurrency Control ✅ Complete

Owner: backend-dev
Priority: P1
Results:
- Introduced asyncio.Lock in MCP client
- Prevented write operation conflicts

4.4 Existing Test Code Validation 🔄 In Progress

Owner: qa-tester
Priority: QA
Status: In progress

4.5 ARCHITECTURE.md Update ✅ Complete

Owner: team-lead
Results:
- Reflected completed work
- Progress indicators (✅ Complete, 🔄 In Progress, ⚡ Partial)

5. Key Achievements

Before Improvements

Git Pull on every request (up to 60-second timeout)
Only Korean posts searchable
Insufficient concurrency control

After Improvements

Caching Introduced: 5-minute TTL minimizes unnecessary API calls
Multi-language Search: Both Korean and English posts searchable
Concurrency Control: asyncio.Lock prevents write operation conflicts

6. Test Coverage

Test Item	Status
Multi-language search (ko, en)	✅
Relevance sorting	✅
Case-insensitive search	✅
Result structure validation	✅
Caching behavior	✅
Connection pooling	✅
Error handling	✅

7. Next Steps (Medium-term Plan)

P2 - Structural Improvements

Git Class Consolidation: Merge GitManager and GitHandler
Dependency Injection: Utilize FastAPI Depends
Index-based Search: Consider Whoosh or Meilisearch

8. Meeting Summary

This meeting minutes includes:

Project kickoff discussion items
Team composition and role assignments
Work item progress
Summary of completed work
Future plans

This meeting minutes was prepared by meeting-writer and will be updated as the project progresses.

Korean Version: 한국어 버전

[MCP] Blog Automation System

Sat, 21 Feb 2026 21:30:00 +0900

Introduction

We built a system where Claude can directly manage blog posts using the Model Context Protocol (MCP). This article explains the implementation and usage.

What is MCP?

MCP (Model Context Protocol) is a protocol developed by Anthropic that enables standardized communication between Claude and external tools/data sources.

flowchart LR
 Claude <-->|MCP| MCPServer[MCP Server]
 MCPServer --> BlogFiles[Blog Files]

Architecture

System Structure

blogs/
├── .claude/
│ ├── mcp_server.py # MCP Server Implementation
│ ├── requirements.txt # Python Dependencies
│ ├── README.md # Documentation
│ └── claude_desktop_config.json
├── content/
│ └── posts/ # Blog Posts
└── static/
 └── images/ # Image Files

MCP Server Structure

class BlogManager:
 """Blog Management Class"""

 def create_post(self, title, content, tags, categories):
 """Create new post"""

 def list_posts(self, limit, offset):
 """List posts"""

 def get_post(self, filename):
 """Get specific post"""

 def update_post(self, filename, **kwargs):
 """Update post"""

 def delete_post(self, filename):
 """Delete post"""

 def search_posts(self, query):
 """Search posts"""

Available Tools

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

Create a new blog post.

{
 "title": "Post Title",
 "content": "Markdown content...",
 "tags": ["tag1", "tag2"],
 "categories": ["Development"],
 "draft": false
}

2. blog_list_posts

Retrieve post list.

{
 "limit": 20,
 "offset": 0
}

3. blog_get_post

Get details of a specific post.

{
 "filename": "2026-02-21-004-example.md"
}

4. blog_update_post

Update existing post.

{
 "filename": "2026-02-21-004-example.md",
 "content": "Updated content...",
 "draft": false
}

5. blog_search_posts

Search posts by content.

{
 "query": "Docker"
}

Automated File Naming

Post filenames are automatically generated using the following rule:

YYYY-MM-DD-NNN-slug.md

YYYY-MM-DD: Creation date
NNN: Serial number (001, 002, …)
slug: URL-friendly string generated from title

Example: 2026-02-21-004-mcp-blog-automation.md

Usage Scenarios

flowchart LR
 User -->|Natural Language| Claude
 Claude -->|blog_create_post| MCP[MCP Server]
 MCP -->|Create File| Blog[YYYY-MM-DD-NNN-slug.md]

1. Quick Post Writing

User: "Write a short tip post about Python list comprehensions"

Claude: Use blog_create_post tool to create post
→ File created: 2026-02-21-005-python-list-comprehension.md

2. Search and Update Existing Posts

User: "Find Docker-related posts and update with latest version info"

Claude: blog_search_posts("Docker") → Check results → blog_update_post

3. Manage Series Posts

User: "Show me all agent-related posts written so far"

Claude: blog_search_posts("agent") → List related posts

Implementation Considerations

Front Matter Parsing

Parses Hugo’s TOML format front matter:

def _parse_front_matter(self, content: str) -> Dict[str, Any]:
 """Parse TOML front matter"""
 if not content.startswith("+++"):
 return {}

 parts = content.split("+++", 2)
 # ... parsing logic

Concurrency Handling

Prevents filename conflicts by checking existing file count:

existing_count = len(list(self.content_dir.glob("*.md")))
filename = self._generate_filename(title, existing_count + 1)

Extensibility

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. Image Processing

blog_upload_image: Image upload and optimization

2. Auto Tag Suggestion

blog_suggest_tags: Content analysis-based tag suggestions

3. SEO Optimization

blog_optimize_seo: Meta description, keyword optimization

4. Deployment Automation

blog_publish: git commit, push, deployment trigger

Conclusion

With the MCP-based blog automation system:

Improved Productivity: Write posts in natural language
Consistency: Automatic file naming rules
Better Accessibility: Intuitive blog management via Claude

This system is continuously extensible, with potential additions like image processing, SEO optimization, and automated deployment.

References

Korean Version: 한국어 버전

Mcp on Yarang's Tech Lair

MCP Integration Guide: Integrating Discord MCP with ZeroClaw Runtime

1. Architecture Design: Dual Communication on a Single Channel

2. Essential Dependencies and Setup (Rust)

3. MCP Client Implementation

4. Integration with ZeroClaw Agents

5. Efficiency and Security Considerations (Architecture Insights)

Conclusion

MCP Server Metadata Synchronization: Context Management Strategies for Developer Productivity

MCP Server Metadata Synchronization: Context Management Strategies for Developer Productivity

Problem Definition: The “My Project Introduction” Repetition

Solution: Resource-Based Metadata Provision

1. Automating Architecture Documentation

2. Rust Implementation Example

3. Automatic Prompt Injection

Effects and Expected Outcomes

Conclusion

Designing MCP Authentication Architecture for Zero-Touch OAuth Implementation

Why Zero-Touch?

Architecture Design

Implementation Step 1: Server Side (blog-api-server)

Implementation Step 2: Client Side (MCP Client)

Considerations for ZeroClaw Runtime Integration

Conclusion

Designing and Implementing a Communication Protocol for MCP-based Multi-Agent Systems in Rust

1. Problem Definition: Why a Communication Protocol?

2. Protocol Design: Request, Task, Completion

3. Implementing the ZeroClaw Communication Layer in Rust

3.1. Message Definition (Based on JSON-RPC)

3.2. Agent Runtime Structure

4. Conclusion and Next Steps

References

Building a Lightweight MCP Server with Rust and ZeroClaw: An Efficient Agent Communication Structure

Building a Lightweight MCP Server with Rust and ZeroClaw: An Efficient Agent Communication Structure

1. Combining ZeroClaw Architecture and MCP

2. Core Structure: Asynchronous Request Routing

2.1. Cargo.toml Configuration

2.2. Defining MCP Message Structure

3. Implementing a Lightweight Request Handler

4. Advanced Optimization: ZeroClaw Integration

5. Conclusion

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

Building an MCP Server with Rust: Utilizing the ZeroClaw Architecture

1. Core Requirements of an MCP Server

2. Architecture Design: ZeroClaw Style

3. Practical Code Examples

3.1. Dependency Setup (Cargo.toml)

3.2. Handler Trait Definition

3.3. Implementing the Log Reading Tool

3.4. Main Loop and JSON-RPC Server

4. Optimization and Deployment Considerations

5. Conclusion

MCP Server Performance Optimization: Building Ultra-Fast Processing Pipelines with Rust

MCP Server Performance Optimization: Building Ultra-Fast Processing Pipelines with Rust

1. Problem Definition: Single-Threaded Bottleneck

2. Asynchronous Processing with Rust and Tokio

Basic Setup (Cargo.toml)

Asynchronous Handler Implementation Example

3. Memory Optimization through Streaming

4. Conclusion: Towards ZeroClaw

Building ZeroClaw with Rust: An LLM-Based Multi-Agent Runtime Architecture

1. Why Rust? (Performance & Safety)

2. ZeroClaw’s Core Architecture

2.1. File-Based State Management

2.2. Event-Driven Communication

3. Integration with MCP (Model Context Protocol)

4. Conclusion: Development Directions for H1 2026

Reference Links

MCP (Model Context Protocol) Based Multi-Agent System Design and Implementation Guide

MCP (Model Context Protocol) Based Multi-Agent System Design and Implementation Guide

1. MCP-Based Multi-Agent Architecture Design

Key Design Principles

Architecture Diagram (Conceptual)

2. Implementing MCP Servers: Building Lightweight Agents with Rust

Dependency Setup (Cargo.toml)

MCP Server Code Example

3. Agent Communication and Data Synchronization

File-Based State Sharing Example

4. Conclusion and Future Directions

References

3.1. Dependency Setup (`Cargo.toml`)

2.1. Configuring the MCP Settings File (`mcp_config.json`)