✨ 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
• 🌍 HTTP Outcalls - Fetch external data from any API
• ⏰ Autonomous Operations - Schedule tasks with built-in timers

📊 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

Add to Your Project

[dependencies]
# Recommended: Simple, includes everything for canister development
icarus = "0.5.8"

# Or specify features explicitly
icarus = { version = "0.5.8", features = ["canister"] }

# Other required dependencies for canister development
ic-cdk = "0.16"
candid = "0.10"
serde = { version = "1.0", features = ["derive"] }

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
• Intelligent Parameter Translation - Seamless JSON to Candid conversion for any parameter style
• Type Safety - Full Rust type checking and IDE support
• Hot Reload - Local development with instant feedback
• Rich CLI - Project scaffolding, deployment, and management

🌍 HTTP Outcalls

use icarus::prelude::*;

// Fetch any external API with one line
let data = http::get("https://api.example.com/data").await?;

// POST JSON with automatic serialization
let response = http::post_json(url, json!({
    "user": "alice",
    "action": "subscribe"
})).await?;

// Built-in retry logic and error handling
let config = HttpConfig {
    max_retries: 5,
    timeout_seconds: 30,
    ..Default::default()
};
let result = http::get_with_config(url, config).await?;

⏰ Autonomous Timers

use icarus::prelude::*;

// Schedule one-time tasks
let cleanup = timers::schedule_once(3600, "hourly-cleanup", || {
    // This runs after 1 hour
    cleanup_old_data();
})?;

// Create recurring tasks
let heartbeat = timers::schedule_periodic(300, "health-check", || {
    // This runs every 5 minutes forever
    check_system_health();
})?;

// Manage timers dynamically
timers::cancel_timer(cleanup)?;
let active = timers::list_active_timers();

💾 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 deploy              # Deploy to ICP (builds automatically)
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

🔄 Migration from 0.4.x to 0.5.0

New Features: HTTP outcalls and timers are now built-in! No breaking changes.

To upgrade:

1. Update your dependency: icarus = "0.5.8"
2. Redeploy: icarus deploy (builds automatically)

The bridge will automatically use the new list_tools() endpoint. No code changes needed unless you were directly calling get_metadata().

📖 Documentation

• Getting Started Guide - Step-by-step tutorial
• Parameter Translation - How MCP JSON maps to ICP Candid
• Parameter Style Guide - Best practices for function parameters
• 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/galenoshea/icarus-sdk
cd icarus-sdk

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

# Run tests
cargo test

# Build everything
cargo build --all

Updating Candid Interfaces

When you modify your tool functions in an Icarus project, you need to update the Candid interface (.did file) to reflect the changes:

# Install the generate-did tool (one-time setup)
cargo install candid-extractor
cargo install generate-did

# After modifying your tools, rebuild and update the .did file
cargo build --target wasm32-unknown-unknown --release
generate-did .

# The .did file is automatically updated with all your tool functions

The #[icarus_module] macro automatically generates all the necessary endpoints, and ic_cdk::export_candid!() embeds the interface in your WASM for extraction.

💬 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.