🚀 Icarus SDK

Build persistent AI tools that run forever on the blockchain

Quick Start • Docs • Examples • Contributing

✨ Why Icarus?

Traditional MCP servers are ephemeral - they lose state when restarted. Icarus changes that.

By combining the Model Context Protocol (MCP) with the Internet Computer Protocol (ICP), Icarus enables you to build AI tools that:

• 🔄 Persist Forever - No more lost state between sessions
• 🌐 Run Globally - Deploy once, accessible from anywhere
• 🔒 Stay Secure - Built-in blockchain security and authentication
• 💰 Cost Pennies - ICP's reverse gas model means predictable, low costs
• ⚡ Scale Instantly - Automatic scaling with canister architecture

📊 Comparison

🎯 Perfect For

• 🤖 AI Assistants - Build Claude/ChatGPT tools with persistent memory
• 📊 Data Tools - Analytics and monitoring that never forget
• 🎮 Game Backends - Persistent game state and player data
• 💼 Enterprise Tools - Secure, auditable business automation
• 🔬 Research Tools - Long-running experiments and data collection

🚀 Quick Start

Installation

# Install the CLI
cargo install icarus-cli

# Create a new project
icarus new my-ai-tool
cd my-ai-tool

# Deploy to ICP
icarus deploy

Your First Persistent Tool

use icarus::prelude::*;

#[icarus_module]
mod tools {
    // This memory persists forever on the blockchain
    stable_storage! {
        MEMORIES: StableBTreeMap<String, String, Memory> = memory_id!(0);
    }
    
    #[update]
    #[icarus_tool("Store a memory that lasts forever")]
    pub fn remember(key: String, value: String) -> Result<String, String> {
        MEMORIES.with(|m| m.borrow_mut().insert(key, value));
        Ok("Memory stored permanently! 🎉".to_string())
    }
    
    #[query]
    #[icarus_tool("Recall a memory from any session")]
    pub fn recall(key: String) -> Result<String, String> {
        MEMORIES.with(|m| 
            m.borrow()
                .get(&key)
                .ok_or_else(|| "Memory not found".to_string())
        )
    }
}

Connect to Claude Desktop

# Add your deployed canister to Claude
icarus bridge add <your-canister-id>

# Now Claude has persistent memory! 🧠

📦 Project Structure

icarus/
├── 🧩 icarus-core        # Core MCP protocol implementation
├── 🔮 icarus-derive      # Procedural macros for less boilerplate
├── 📦 icarus-canister    # ICP canister integration
├── 🛠️  icarus-cli         # Command-line tools
└── 📚 examples/          # Ready-to-deploy examples

🌟 Features

🔧 Developer Experience

• Zero Boilerplate - Macros generate all the MCP metadata
• Type Safety - Full Rust type checking and IDE support
• Hot Reload - Local development with instant feedback
• Rich CLI - Project scaffolding, deployment, and management

💾 Stable Storage

// Your data structures
#[derive(IcarusStorable)]
struct UserProfile {
    id: String,
    preferences: HashMap<String, String>,
    created_at: u64,
}

// Automatic persistence with stable storage
stable_storage! {
    USERS: StableBTreeMap<String, UserProfile, Memory> = memory_id!(0);
    SETTINGS: StableVec<Settings, Memory> = memory_id!(1);
}

🔐 Built-in Security

• Internet Identity - Secure authentication out of the box
• Principal-based Access - Fine-grained permissions
• Candid Interface - Type-safe client generation

📚 Examples

Check out our examples directory for complete, deployable projects:

• Memory Assistant - Persistent note-taking for AI
• GitHub Integration - Repository management tool
• Data Analytics - Time-series data storage

🛠️ CLI Commands

# Project Management
icarus new <name>           # Create a new project
icarus build               # Build your canister
icarus deploy              # Deploy to ICP
icarus test                # Run tests

# Bridge Commands (Claude Desktop integration)
icarus bridge add <id>     # Add canister to Claude
icarus bridge list         # List connected canisters
icarus bridge remove <id>  # Remove a canister

# Development
icarus dev                 # Start local development
icarus logs <id>          # View canister logs

📖 Documentation

• Getting Started Guide - Step-by-step tutorial
• API Documentation - Complete API reference
• Architecture Overview - How Icarus works
• Migration Guide - Migrate existing MCP servers

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/icarusai/icarus-sdk
cd icarus-sdk

# Install dependencies
./scripts/install-deps.sh

# Run tests
cargo test

# Build everything
cargo build --all

💬 Community & Support

• Discord - Join our community
• GitHub Issues - Report bugs
• Discussions - Ask questions

📄 License

Icarus SDK is licensed under the Business Source License 1.1 (BSL). See LICENSE for details.

The BSL allows you to use Icarus SDK for developing and deploying MCP tools to the Icarus Marketplace.

Built with ❤️ by the Icarus Team

Website • Twitter • Blog