Getting Started¶

This guide will help you get up and running with AIRS Protocols quickly.

Prerequisites¶

Before you begin, ensure you have the following installed:

Rust 1.88 or later (install instructions)
Cargo (comes with Rust)
A code editor with Rust support (e.g., VS Code with rust-analyzer)

Verify Installation¶

rustc --version
cargo --version

Installation¶

Using MCP (Model Context Protocol)¶

Add AIRS Protocols MCP to your Cargo.toml:

[dependencies]
# From git repository (current):
airsprotocols-mcp = { git = "https://github.com/airsstack/airsprotocols" }

# Or when published to crates.io:
# airsprotocols-mcp = "1.0.0-rc.1"

# Required async runtime:
tokio = { version = "1.47", features = ["full"] }

Future Packages¶

Other packages will be available as they're released:

[dependencies]
# Coming soon:
# airsprotocols-a2a = "0.1.0"
# airsprotocols-anthropic = "0.1.0"
# airsprotocols-openai = "0.1.0"

Quick Start: MCP Client¶

Here's a minimal example of creating an MCP client:

use airsprotocols_mcp::McpClientBuilder;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create an MCP client
    let client = McpClientBuilder::new()
        .client_info("my-app", "0.1.0")
        .timeout(Duration::from_secs(30))
        .build(transport)  // transport implementation needed
        .await?;

    // List available tools from the server
    let tools = client.list_tools().await?;
    println!("Available tools: {}", tools.len());

    Ok(())
}

Transport Required

The example above requires a transport implementation. See MCP Quick Start for complete examples with stdio and HTTP transports.

Quick Start: MCP Server¶

Create a simple MCP server that provides tools:

use std::sync::Arc;
use async_trait::async_trait;
use serde_json::json;
use airsprotocols_mcp::protocol::{JsonRpcMessage, MessageContext, MessageHandler};
use airsprotocols_mcp::providers::{ToolProvider, ToolCall, ToolResult};
use airsprotocols_mcp::transport::adapters::stdio::StdioTransport;
use airsprotocols_mcp::IntegrationError;

// Implement a simple tool provider
struct MyToolProvider;

#[async_trait]
impl ToolProvider for MyToolProvider {
    async fn call_tool(&self, tool_call: ToolCall) -> Result<ToolResult, IntegrationError> {
        match tool_call.name.as_str() {
            "add" => {
                let params = tool_call.params.unwrap_or_default();
                let a = params["a"].as_i64().unwrap_or(0);
                let b = params["b"].as_i64().unwrap_or(0);
                let result = a + b;
                Ok(ToolResult::success(json!({ "result": result })))
            }
            _ => Err(IntegrationError::MethodNotFound(tool_call.name))
        }
    }

    // Other required methods...
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let tool_provider = Arc::new(MyToolProvider);
    // Set up handler and transport...

    Ok(())
}

For complete server examples, see MCP Server Implementation.

Project Structure¶

When working with AIRS Protocols in your project:

my-project/
├── Cargo.toml              # Dependencies
├── src/
│   ├── main.rs            # Application entry point
│   └── ...
└── examples/              # Optional examples
    └── ...

Recommended Project Setup¶

[package]
name = "my-ai-app"
version = "0.1.0"
edition = "2021"

[dependencies]
# AIRS Protocols
airsprotocols-mcp = { git = "https://github.com/airsstack/airsprotocols" }

# Async runtime
tokio = { version = "1.47", features = ["full"] }

# Serialization
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

# Error handling
thiserror = "1.0"

# Logging
tracing = "0.1"
tracing-subscriber = "0.3"

Common Patterns¶

Error Handling¶

Use Rust's Result type for error handling:

use airsprotocols_mcp::IntegrationError;

async fn my_function() -> Result<(), IntegrationError> {
    // Your code here
    Ok(())
}

Async/Await¶

All AIRS Protocols APIs are async:

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = create_client().await?;
    let result = client.list_tools().await?;
    Ok(())
}

Logging¶

Add logging to your application:

use tracing::{info, error};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize logging
    tracing_subscriber::fmt::init();

    info!("Starting application");

    // Your code here

    Ok(())
}

Next Steps¶

Learn More About MCP¶

MCP Quick Start - Detailed MCP tutorial
Basic Examples - Common usage patterns
Advanced Patterns - Advanced techniques

Explore the Architecture¶

Architecture Overview - System design
MCP Architecture - MCP internals

See Examples¶

Examples Overview - Runnable examples
Claude Integration - Integrate with Claude Desktop

API Reference¶

MCP API Reference - Complete API documentation
docs.rs - Generated Rust documentation

Development Workflow¶

Building Your Project¶

# Build in debug mode
cargo build

# Build optimized release
cargo build --release

# Run your application
cargo run

# Run with logging
RUST_LOG=info cargo run

Testing¶

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run with output
cargo test -- --nocapture

Code Quality¶

# Format code
cargo fmt

# Check for issues
cargo clippy

# Check without building
cargo check

Troubleshooting¶

Common Issues¶

Compilation Errors¶

Make sure you're using Rust 1.88 or later:

rustup update

Async Runtime Not Found¶

Ensure tokio is in your dependencies:

[dependencies]
tokio = { version = "1.47", features = ["full"] }

Transport Connection Issues¶

Check that your transport is properly configured and the server is running.

Getting Help¶

If you encounter issues:

Check the documentation
Review examples
Search existing issues
Ask in GitHub Discussions
Open a new issue