remote-mcp-kernel 0.1.0-alpha.7

# Custom Router Attachment

The remote-mcp-kernel now supports attaching arbitrary axum Routers to the microkernel server, enabling you to extend the server with custom endpoints while maintaining microkernel architecture principles.

## Overview

The custom router functionality allows you to:
- Add arbitrary HTTP endpoints to your microkernel server
- Organize endpoints with path prefixes
- Maintain clean separation between different functional areas
- Compose multiple routers independently

## Basic Usage

### Simple Router Attachment

```rust
use axum::{Router, routing::get, response::Json};
use remote_mcp_kernel::microkernel::GitHubMicrokernelServer;
use serde_json::json;

async fn health_check() -> Json<serde_json::Value> {
    Json(json!({"status": "healthy"}))
}

let custom_router = Router::new()
    .route("/health", get(health_check));

let server: GitHubMicrokernelServer = GitHubMicrokernelServer::new()
    .with_custom_router(custom_router);
```

### Router with Configuration

```rust
use remote_mcp_kernel::microkernel::core::CustomRouterConfig;

let api_router = Router::new()
    .route("/status", get(api_status));

let config = CustomRouterConfig::with_name_and_prefix("API", "/api");

let server: GitHubMicrokernelServer = GitHubMicrokernelServer::new()
    .with_custom_router_config(api_router, config);
```

### Multiple Routers

```rust
let health_router = Router::new()
    .route("/health", get(health_check));

let metrics_router = Router::new()
    .route("/metrics", get(metrics));

let routers = vec![
    (health_router, CustomRouterConfig::default()),
    (metrics_router, CustomRouterConfig::with_prefix("/monitoring")),
];

let server: GitHubMicrokernelServer = GitHubMicrokernelServer::new()
    .with_custom_routers(routers);
```

## Configuration Options

The `CustomRouterConfig` struct provides the following options:

- `name`: Optional name for the router (used in logging and debugging)
- `path_prefix`: Optional path prefix for all routes in the router

### Configuration Builder Methods

```rust
// Default configuration (no name, no prefix)
CustomRouterConfig::default()

// With name only
CustomRouterConfig::with_name("API Router")

// With prefix only
CustomRouterConfig::with_prefix("/api")

// With both name and prefix
CustomRouterConfig::with_name_and_prefix("API Router", "/api")
```

## Complete Example

Here's a complete example showing how to build a microkernel server with OAuth authentication, MCP handlers, and custom routers:

```rust
use axum::{routing::get, response::Json, Router};
use oauth_provider_rs::{GitHubOAuthConfig, GitHubOAuthProvider, OAuthProvider};
use remote_mcp_kernel::microkernel::{
    core::CustomRouterConfig, 
    GitHubMicrokernelServer, 
    MicrokernelServer,
    factory::create_full_github_microkernel,
};
use serde_json::json;

async fn health_check() -> Json<serde_json::Value> {
    Json(json!({"status": "healthy", "timestamp": chrono::Utc::now()}))
}

async fn metrics() -> Json<serde_json::Value> {
    Json(json!({"requests": 42, "uptime": "5m"}))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create OAuth provider
    let github_config = GitHubOAuthConfig {
        client_id: "your_client_id".to_string(),
        client_secret: "your_client_secret".to_string(),
        redirect_uri: "http://localhost:8080/oauth/callback".to_string(),
        scope: "read:user".to_string(),
        provider_name: "github".to_string(),
    };

    let github_oauth_provider = GitHubOAuthProvider::new_github(github_config);
    let oauth_provider = OAuthProvider::new(github_oauth_provider);

    // Create custom routers
    let health_router = Router::new()
        .route("/health", get(health_check));

    let monitoring_router = Router::new()
        .route("/metrics", get(metrics));

    let routers = vec![
        (health_router, CustomRouterConfig::default()),
        (monitoring_router, CustomRouterConfig::with_prefix("/monitoring")),
    ];

    // Build microkernel server
    let microkernel = create_full_github_microkernel(github_oauth_provider)
        .with_custom_routers(routers);

    // Start server
    let bind_address = "127.0.0.1:8080".parse()?;
    println!("Server starting on http://{}", bind_address);
    
    microkernel.serve(bind_address).await?;
    Ok(())
}
```

## Available Endpoints

When you run the server, you'll have access to:

- **OAuth endpoints**: `/oauth/login`, `/oauth/callback`, `/oauth/token`
- **MCP endpoints**: `/mcp/sse`, `/mcp/streamable` (if configured)
- **Custom endpoints**: Whatever you define in your custom routers

## Architecture Benefits

The custom router functionality maintains microkernel principles:

1. **Independence**: Each router can be developed and tested independently
2. **Composability**: Routers are composed at runtime, allowing flexible configurations
3. **Separation of Concerns**: Different functional areas can be implemented in separate routers
4. **Maintainability**: Clean boundaries between different parts of the system

## Best Practices

1. **Group related functionality**: Put related endpoints in the same router
2. **Use path prefixes**: Organize endpoints with logical prefixes (`/api`, `/admin`, `/monitoring`)
3. **Provide meaningful names**: Use descriptive names for routers to aid debugging
4. **Keep routers focused**: Each router should have a single, well-defined responsibility
5. **Test independently**: Write tests for each router separately before composing them

## Example Project

See the `examples/custom_router_example.rs` file for a complete working example that demonstrates:
- Health check endpoints
- Monitoring endpoints
- API endpoints with versioning
- Admin dashboard with HTML interface
- Webhook handlers

Run it with:
```bash
cargo run --example custom_router_example
```

Then visit:
- `http://localhost:8080/health` - Health check
- `http://localhost:8080/monitoring/metrics` - Metrics
- `http://localhost:8080/api/v1/status` - API status
- `http://localhost:8080/admin` - Admin dashboard