remote-mcp-kernel 0.1.0-alpha.3

# Remote MCP Kernel

[![Crates.io](https://img.shields.io/crates/v/remote-mcp-kernel.svg)](https://crates.io/crates/remote-mcp-kernel)
[![Documentation](https://docs.rs/remote-mcp-kernel/badge.svg)](https://docs.rs/remote-mcp-kernel)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A microkernel-based MCP (Model Context Protocol) server with OAuth authentication and multiple transport protocols.

## Features

- 🔧 **Microkernel Architecture** - Modular design with independent handlers
- 🔐 **OAuth Authentication** - Secure authentication with multiple providers
- 🚀 **Multiple Transport Protocols** - SSE (Server-Sent Events) and HTTP support
- 📡 **MCP Protocol Support** - Full Model Context Protocol implementation
- 🔌 **Pluggable Handlers** - Extensible handler system
- 🎯 **Runtime Composition** - Dynamic service configuration

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
remote-mcp-kernel = "0.1.0-alpha.1"
```

## Quick Start

### Basic MCP Server

```rust
use remote_mcp_kernel::microkernel::MicrokernelServer;
use remote_mcp_kernel::handlers::{SseHandler, StreamableHttpHandler};
use oauth_provider_rs::providers::McpOAuthProvider;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create OAuth provider
    let oauth_provider = McpOAuthProvider::new(/* ... */);
    
    // Create handlers
    let sse_handler = SseHandler::new(oauth_provider.clone());
    let streamable_handler = StreamableHttpHandler::new(oauth_provider.clone());
    
    // Build microkernel server
    let server = MicrokernelServer::new()
        .with_oauth_provider(oauth_provider)
        .with_sse_handler(sse_handler, Default::default())
        .with_streamable_handler(streamable_handler);
    
    // Start server
    server.start("127.0.0.1:8080".parse()?).await?;
    Ok(())
}
```

### OAuth-Only Server

```rust
use remote_mcp_kernel::microkernel::MicrokernelServer;
use oauth_provider_rs::providers::McpOAuthProvider;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let oauth_provider = McpOAuthProvider::new(/* ... */);
    
    let server = MicrokernelServer::new()
        .with_oauth_provider(oauth_provider);
    
    server.start("127.0.0.1:8080".parse()?).await?;
    Ok(())
}
```

## Architecture

The Remote MCP Kernel follows a microkernel architecture where:

- **Core Kernel** - Minimal core with basic routing and composition
- **Handlers** - Independent, composable service handlers
- **OAuth Provider** - Centralized authentication service
- **Transport Protocols** - Multiple communication methods (SSE, HTTP)

### Handler Types

- **SSE Handler** - Server-Sent Events for real-time communication
- **Streamable HTTP Handler** - HTTP-based streaming communication
- **OAuth Handler** - Authentication and authorization endpoints

## Configuration

The server can be configured through environment variables or programmatically:

```rust
use remote_mcp_kernel::config::Config;

let config = Config::from_env()?;
```

## Examples

The crate includes several examples:

- `oauth_standard_mcp_server` - Standard MCP server with OAuth
- `oauth_cognito_mcp_server` - AWS Cognito integration
- `oauth_cognito_dynamodb_mcp_server` - Full AWS integration

Run examples with:

```bash
cargo run --example oauth_standard_mcp_server
```

## OAuth Providers

Supports multiple OAuth providers:

- **GitHub** - GitHub OAuth integration
- **AWS Cognito** - AWS Cognito User Pools
- **Generic** - Custom OAuth provider support

## Transport Protocols

### Server-Sent Events (SSE)

Real-time, unidirectional communication from server to client:

```rust
let sse_handler = SseHandler::new(oauth_provider);
```

### Streamable HTTP

Bidirectional HTTP-based communication:

```rust
let streamable_handler = StreamableHttpHandler::new(oauth_provider);
```

## Error Handling

The kernel provides comprehensive error handling:

```rust
use remote_mcp_kernel::error::{KernelError, KernelResult};

fn handle_request() -> KernelResult<()> {
    // Your implementation
    Ok(())
}
```

## Security

- OAuth 2.0 with PKCE support
- Secure token validation
- CORS configuration
- Request authentication middleware

## Development

```bash
# Run tests
cargo test

# Run with specific features
cargo run --features aws-integration

# Build documentation
cargo doc --open
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Related Crates

- [`oauth-provider-rs`](https://crates.io/crates/oauth-provider-rs) - OAuth 2.0 provider implementation
- [`rmcp`](https://crates.io/crates/rmcp) - Model Context Protocol implementation