magi-tool 0.0.1

# magi-tool Documentation

Documentation for the magi-tool crate.

## Quick Links

### Core Documentation

- **[PEGBOARD_DESIGN.md](./PEGBOARD_DESIGN.md)** - Complete PegBoard design, architecture, and API reference
  - Data structure decisions
  - Namespace and tool prefixing
  - Complete usage examples
  - API reference
  - Thread safety and tokio usage

### Usage Guides

- **[TOKIO_USAGE.md](./TOKIO_USAGE.md)** - Using PegBoard with tokio and async Rust
  - Arc pattern for sharing
  - Web server integration examples
  - Concurrent task patterns
  - Performance characteristics
  - Anti-patterns to avoid

- **[OPTIONAL_NAMESPACE.md](./OPTIONAL_NAMESPACE.md)** - Guide to optional namespace feature
  - When to use namespaces
  - When to skip namespaces
  - Mixed approaches
  - Decision flowchart

- **[FEATURE_FLAGS.md](./FEATURE_FLAGS.md)** - Cargo feature flags guide
  - `pegboard` feature (enabled by default)
  - Compilation time comparison
  - Binary size comparison
  - Usage patterns and examples

### Change History

- **[CHANGES.md](./CHANGES.md)** - Implementation changes and migration guide
  - Latest updates
  - Design decisions
  - API changes
  - Migration guide

## Overview

The magi-tool crate provides:

1. **Tool Schema Generation** - Convert Rust types to JSON Schema for LLM tool definitions
2. **PegBoard** - Tool registry for managing multiple MCP services with automatic name conflict resolution

## Quick Start

### Creating Tool Definitions

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

#[derive(JsonSchema, serde::Deserialize)]
struct WeatherParams {
    /// The city and state, e.g. San Francisco, CA
    location: String,
    unit: Option<String>,
}

// Generate tool definition
let tool = get_tool::<WeatherParams, _, _>(
    "get_weather",
    Some("Get the current weather in a given location"),
)?;

// Send to LLM
let tools = vec![tool];
```

### Using PegBoard

```rust
use magi_tool::PegBoard;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut pegboard = PegBoard::new();

    // Register services (with automatic tool discovery)
    pegboard.add_service(Some("web".to_string()), web_service).await?;
    pegboard.add_service(Some("fs".to_string()), fs_service).await?;

    // Wrap for sharing
    let pegboard = Arc::new(pegboard);

    // Get tools for LLM
    let tools = pegboard.get_all_tools();

    // Route LLM tool calls
    let (service_idx, original_name) = pegboard
        .get_tool_route("web-search")
        .unwrap();

    Ok(())
}
```

## Documentation Structure

```
docs/
├── README.md                  # This file - documentation index
├── PEGBOARD_DESIGN.md        # Complete design and API reference
├── TOKIO_USAGE.md            # Tokio/async usage patterns
├── OPTIONAL_NAMESPACE.md     # Namespace feature guide
├── FEATURE_FLAGS.md          # Cargo feature flags guide
└── CHANGES.md                # Change history and migration
```

## Key Features

### Tool Schema Generation

- Automatic JSON Schema generation from Rust types
- Support for optional fields, enums, arrays
- Doc comments become schema descriptions
- Compatible with Claude's tool format
- **Always available** - Core feature, no dependencies on MCP

### PegBoard (Optional Feature)

- **Automatic Tool Discovery** - Calls `list_tools()` on MCP services
- **Namespace Support** - Optional prefixing to avoid name conflicts
- **Thread-Safe** - DashMap-based concurrent access
- **Routing** - Maps prefixed names to original names for service calls
- **Tokio-Ready** - Designed for async Rust with Arc pattern
- **Optional** - Enable with `pegboard` feature (enabled by default)

### Feature Flags

```toml
# Full features (default) - includes PegBoard
magi-tool = "0.0.1"

# Tool schema generation only (faster compile, no rmcp dependency)
magi-tool = { version = "0.0.1", default-features = false }
```

**Compilation time comparison:**
- With PegBoard: ~3-4 seconds (includes rmcp, tokio, dashmap)
- Without PegBoard: ~0.2 seconds (only schemars, serde)

Use `default-features = false` if you:
- Only need tool schema generation
- Want faster compilation
- Don't use MCP services
- Building for constrained environments

## Examples

See each documentation file for detailed examples:

- Basic tool creation → `PEGBOARD_DESIGN.md`
- Web server integration → `TOKIO_USAGE.md`
- Namespace strategies → `OPTIONAL_NAMESPACE.md`

## Testing

Run tests:
```bash
cargo test -p magi-tool
```

## Contributing

When adding features, please update the relevant documentation files:
- API changes → Update `PEGBOARD_DESIGN.md`
- New patterns → Add to appropriate guide
- Breaking changes → Document in `CHANGES.md`