magi-tool 0.0.1

# Feature Flags

magi-tool uses Cargo feature flags to make certain functionality optional.

## Available Features

### `pegboard` (Default)

The PegBoard feature includes:
- PegBoard service registry
- Automatic tool discovery from MCP services
- Tool name prefixing and namespace management
- Automatic routing and execution
- Integration with rmcp protocol

**Dependencies added:**
- `rmcp` - Model Context Protocol implementation
- `dashmap` - Concurrent HashMap for thread-safe access
- `tokio` (transitive) - Async runtime via rmcp

**When to enable:**
- ✅ You're managing multiple MCP services
- ✅ You need automatic tool discovery
- ✅ You want namespace conflict resolution
- ✅ You need tool routing and execution

**When to disable:**
- ❌ You only need JSON Schema generation
- ❌ You want minimal dependencies
- ❌ You want faster compilation
- ❌ You're not using MCP services

## Usage

### With PegBoard (Default)

```toml
[dependencies]
magi-tool = "0.0.1"
```

Or explicitly:

```toml
[dependencies]
magi-tool = { version = "0.0.1", features = ["pegboard"] }
```

**Features available:**
```rust
use magi_tool::{
    get_tool,           // Tool schema generation
    PegBoard,           // Service manager
    PegBoardError,      // Error type
    CallToolResult,     // Result type from rmcp
};

// All functionality available
let mut pegboard = PegBoard::new();
pegboard.add_service(Some("web".to_string()), service).await?;
```

### Without PegBoard (Schema Only)

```toml
[dependencies]
magi-tool = { version = "0.0.1", default-features = false }
```

**Features available:**
```rust
use magi_tool::get_tool;  // Tool schema generation only

// PegBoard not available
// use magi_tool::PegBoard;  // ❌ Compile error

// Only tool schema generation works
let tool = get_tool::<MyParams, _, _>("my_tool", Some("description"))?;
```

## Compilation Comparison

| Configuration | Compile Time | Dependencies |
|--------------|--------------|--------------|
| With PegBoard (default) | ~3-4 seconds | rmcp, dashmap, tokio, schemars, serde |
| Without PegBoard | ~0.2 seconds | schemars, serde |

The difference is ~15-20x faster compilation when you only need schema generation!

## Binary Size Comparison

Approximate binary size differences:

| Configuration | Size (debug) | Size (release) |
|--------------|--------------|----------------|
| With PegBoard | ~10 MB | ~2 MB |
| Without PegBoard | ~5 MB | ~500 KB |

## Common Patterns

### Pattern 1: Schema Generation Only

If you're building a library that just generates tool schemas for an LLM API:

```toml
[dependencies]
magi-tool = { version = "0.0.1", default-features = false }
```

```rust
use magi_tool::get_tool;
use schemars::JsonSchema;

#[derive(JsonSchema, serde::Deserialize)]
struct SearchParams {
    query: String,
    max_results: Option<u32>,
}

let tool = get_tool::<SearchParams, _, _>(
    "search",
    Some("Search the web"),
)?;

// Send tool to LLM API
api_client.send_tools(&[tool]).await?;
```

### Pattern 2: Full MCP Integration

If you're building an application that manages MCP services:

```toml
[dependencies]
magi-tool = "0.0.1"  # pegboard enabled by default
```

```rust
use magi_tool::{PegBoard, CallToolResult};
use std::sync::Arc;

let mut pegboard = PegBoard::new();
pegboard.add_service(Some("web".to_string()), service).await?;

let pegboard = Arc::new(pegboard);
let tools = pegboard.get_all_tools();

// Execute tool calls from LLM
let result = pegboard.call_tool("web-search", args).await?;
```

### Pattern 3: Optional PegBoard in Library

If you're building a library that optionally supports PegBoard:

```toml
[features]
default = []
pegboard-support = ["magi-tool/pegboard"]

[dependencies]
magi-tool = { version = "0.0.1", default-features = false }
```

```rust
use magi_tool::get_tool;

#[cfg(feature = "pegboard-support")]
use magi_tool::{PegBoard, PegBoardError};

// Core functionality always available
pub fn create_tool_schema() -> Result<Tool, ToolError> {
    get_tool::<MyParams, _, _>("my_tool", Some("description"))
}

// PegBoard support optional
#[cfg(feature = "pegboard-support")]
pub async fn register_with_pegboard(
    pegboard: &mut PegBoard,
    service: RunningService<...>,
) -> Result<(), PegBoardError> {
    pegboard.add_service(Some("my_service".to_string()), service).await
}
```

## Testing

### Test with PegBoard

```bash
cargo test -p magi-tool
# Runs all 14 tests (5 schema + 9 pegboard)
```

### Test without PegBoard

```bash
cargo test -p magi-tool --no-default-features
# Runs only 5 tests (schema generation only)
```

## Migration Guide

### If You Only Need Schema Generation

**Before:**
```toml
[dependencies]
magi-tool = "0.0.1"
```

**After (faster compilation):**
```toml
[dependencies]
magi-tool = { version = "0.0.1", default-features = false }
```

No code changes needed if you're only using `get_tool`.

### If You Use PegBoard

No changes needed - it's enabled by default:

```toml
[dependencies]
magi-tool = "0.0.1"  # pegboard included
```

## Recommendations

**Use default (with PegBoard) if:**
- You're managing MCP services
- You need the full feature set
- Compilation time is not a concern
- You're building an application (not a library)

**Use `default-features = false` if:**
- You only generate tool schemas
- You want minimal dependencies
- You're building a library that others will depend on
- You're optimizing for compilation speed
- You're deploying to constrained environments

## Future Features

Additional optional features may be added in the future:
- `async-runtime` - Choose between tokio/async-std
- `tracing` - Observability integration
- `metrics` - Performance monitoring

For now, there's only one feature flag: `pegboard`.