kodegen_mcp_client-0.1.0 has been yanked.

kodegen-mcp-client

A Rust client library for interacting with MCP (Model Context Protocol) servers, specifically designed for KODEGEN.ᴀɪ database query and schema exploration tools.

Features

✨ Type-Safe MCP Client

Strongly-typed response structures for all 75+ KODEGEN tools
Compile-time type checking with call_tool_typed<T>()
Support for both camelCase and snake_case field names

🚀 Async & Efficient

Built on Tokio for high-performance async operations
Cheap-to-clone client handles (Arc-based internally)
Configurable timeouts with sensible defaults

🔌 Multiple Transports

HTTP/SSE (Server-Sent Events)
Streamable HTTP
Easy transport selection

🛡️ Robust Error Handling

Comprehensive error types with context
Clear error messages for debugging
Timeout tracking with operation details

Installation

Add to your Cargo.toml:

[dependencies]
kodegen_mcp_client = "0.1"

Requirements:

Rust nightly toolchain
Tokio async runtime

Quick Start

use kodegen_mcp_client::{create_streamable_client, tools};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client connection
    let (client, _conn) = create_streamable_client("http://localhost:8000/mcp").await?;
    
    // List available tools
    let tools = client.list_tools().await?;
    println!("Available tools: {}", tools.len());
    
    // Call a tool with JSON arguments
    let result = client.call_tool(
        tools::LIST_SCHEMAS,
        json!({}),
    ).await?;
    
    println!("Result: {:?}", result);
    
    Ok(())
}

Usage Examples

Type-Safe Tool Calls

Use strongly-typed responses instead of manual JSON parsing:

use kodegen_mcp_client::responses::StartSearchResponse;
use kodegen_mcp_client::tools;

// Type-safe tool call with automatic deserialization
let response: StartSearchResponse = client
    .call_tool_typed(tools::START_SEARCH, json!({
        "path": "/project",
        "pattern": "*.rs",
        "searchType": "files"
    }))
    .await?;

// Use the typed response
println!("Search session ID: {}", response.session_id);

Clone-able Client Handles

Client handles are cheap to clone and can be shared across tasks:

let (client, _conn) = create_streamable_client(url).await?;

// Clone the client for concurrent operations
let client2 = client.clone();
tokio::spawn(async move {
    client2.list_tools().await
});

// Original client still works
client.call_tool(tools::READ_FILE, args).await?;

Custom Timeouts

use tokio::time::Duration;

let (client, _conn) = create_streamable_client(url).await?;

// Set custom timeout (default is 30 seconds)
let client = client.with_timeout(Duration::from_secs(60));

GitHub Integration

use kodegen_mcp_client::responses::{GitHubIssuesResponse, GitHubIssue};

let response: GitHubIssuesResponse = client
    .call_tool_typed(tools::LIST_ISSUES, json!({
        "owner": "myorg",
        "repo": "myrepo",
        "state": "open"
    }))
    .await?;

for issue in response.issues {
    println!("#{}: {}", issue.number, issue.title);
}

Database Operations

use kodegen_mcp_client::tools;

// Execute SQL query
let result = client.call_tool(tools::EXECUTE_SQL, json!({
    "query": "SELECT * FROM users WHERE active = true",
    "database": "production"
})).await?;

// Get table schema
let schema = client.call_tool(tools::GET_TABLE_SCHEMA, json!({
    "table_name": "users",
    "schema": "public"
})).await?;

Architecture

Handle + Connection Pattern

The library uses a two-struct pattern for resource management:

KodegenClient: Cheap-to-clone handle for performing MCP operations
- Clone freely and share across async tasks
- Wraps Arc internally for efficient cloning
- Thread-safe and shareable
KodegenConnection: Non-clonable lifecycle manager
- Must be held as long as the connection should remain active
- Provides close() for graceful shutdown
- Automatically cancels connection when dropped

let (client, _conn) = create_streamable_client(url).await?;
// client: Clone freely
// _conn: Hold until shutdown desired (auto-cleanup on drop)

Available Tool Categories

The library provides type-safe access to 75+ KODEGEN.ᴀɪ tools across multiple categories:

Filesystem (14 tools): File operations, search, directory management
Terminal (5 tools): Command execution, process management
Database (7 tools): Schema exploration, query execution, connection pooling
Git (20 tools): Repository operations, branching, commits, worktrees
GitHub (25 tools): Issues, PRs, reviews, code search, repositories
Claude Agents (5 tools): Multi-agent orchestration, spawning, communication
Web Crawling (4 tools): Site crawling, search, content extraction
Configuration (2 tools): Server config management
Prompts (4 tools): Template management and rendering
Sequential Thinking (1 tool): Chain-of-thought reasoning

All tool names are available as constants in the tools module.

Error Handling

The library provides comprehensive error types with context:

use kodegen_mcp_client::ClientError;

match client.call_tool(tools::READ_FILE, args).await {
    Ok(result) => println!("Success: {:?}", result),
    Err(ClientError::Timeout(msg)) => eprintln!("Timeout: {}", msg),
    Err(ClientError::ParseError(msg)) => eprintln!("Parse error: {}", msg),
    Err(ClientError::Connection(msg)) => eprintln!("Connection failed: {}", msg),
    Err(e) => eprintln!("Other error: {}", e),
}

Error variants:

Protocol: MCP protocol errors
Timeout: Operation timeouts (includes duration)
ParseError: Response deserialization failures
Connection: Transport connection failures
ServiceError, InitError, Io, JoinError: Lower-level errors

Transport Options

Streamable HTTP (Recommended)

use kodegen_mcp_client::create_streamable_client;

let (client, conn) = create_streamable_client("http://localhost:8000/mcp").await?;

HTTP/SSE (Server-Sent Events)

use kodegen_mcp_client::transports::http::create_http_client;

let (client, conn) = create_http_client("http://localhost:8000/mcp").await?;

Development

Building

cargo build              # Debug build
cargo build --release    # Release build

Testing

cargo test               # Run all tests
cargo test --lib         # Library tests only

Linting & Formatting

cargo clippy             # Run linter
cargo fmt                # Format code

Documentation

cargo doc --open         # Build and open docs

License

Dual-licensed under Apache 2.0 OR MIT terms.

See LICENSE.md for details.

kodegen_mcp_client 0.1.0