remote-mcp-kernel 0.1.0-alpha.4

# Remote MCP Kernel Examples

This directory contains examples demonstrating how to use the remote-mcp-kernel library with different configurations and custom MCP server implementations.

## Examples Overview

### 1. `oauth_standard_mcp_server.rs`
Basic MCP server with OAuth authentication using the standard built-in MCP server implementation.

### 2. `oauth_cognito_mcp_server.rs`
MCP server with AWS Cognito OAuth authentication using in-memory storage.

### 3. `oauth_cognito_dynamodb_mcp_server.rs`
MCP server with AWS Cognito OAuth authentication and DynamoDB persistent storage.

### 4. `custom_mcp_server_example.rs` 🆕
**Custom MCP Server Implementation Example**

This example demonstrates how to create and use a custom MCP server implementation with the microkernel architecture. It shows:

- **Custom MCP Server**: Implementation of a specialized MCP server with file operations, system utilities, and text processing tools
- **Tool Implementation**: Using rmcp's `#[tool]` and `#[tool_router]` macros to create custom tools
- **Microkernel Integration**: How to integrate custom MCP servers with the OAuth and transport infrastructure
- **AWS Cognito + DynamoDB**: Full OAuth and persistent storage setup

#### Custom Tools Included:
- `list_files`: List files and directories with optional hidden file inclusion
- `read_file`: Read file contents with optional line limits
- `write_file`: Write content to files with append support
- `get_system_info`: Get system information (OS, architecture, working directory, etc.)
- `count_words`: Count words, lines, characters, and bytes in text
- `search_text`: Search for patterns in text with case sensitivity options
- `get_datetime`: Get current date and time in various formats

## Running the Examples

### Prerequisites

1. **Environment Variables**: Copy `.env.example` to `.env` and configure:
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

2. **AWS Credentials**: For Cognito and DynamoDB examples, ensure AWS credentials are configured:
   ```bash
   export AWS_ACCESS_KEY_ID="your_access_key"
   export AWS_SECRET_ACCESS_KEY="your_secret_key"
   export AWS_REGION="us-east-1"
   ```

3. **Cognito Configuration**: Set up AWS Cognito User Pool and configure:
   ```bash
   export COGNITO_CLIENT_ID="your_client_id"
   export COGNITO_CLIENT_SECRET="your_client_secret"
   export COGNITO_DOMAIN="mydomain.auth.us-east-1.amazoncognito.com"
   export COGNITO_REGION="us-east-1"
   export COGNITO_USER_POOL_ID="us-east-1_XXXXXXXXX"
   ```

### Running Examples

```bash
# Basic OAuth with standard MCP server
cargo run --example oauth_standard_mcp_server

# AWS Cognito with in-memory storage
cargo run --example oauth_cognito_mcp_server

# AWS Cognito with DynamoDB storage
cargo run --example oauth_cognito_dynamodb_mcp_server

# Custom MCP server with AWS Cognito and DynamoDB
cargo run --example custom_mcp_server_example
```

## Custom MCP Server Development Guide

The `custom_mcp_server_example.rs` serves as a comprehensive guide for developing your own MCP servers. Here's the key pattern:

### 1. Define Your MCP Server Struct

```rust
#[derive(Debug, Clone)]
pub struct CustomMcpServer {
    tool_router: ToolRouter<Self>,
    name: String,
}
```

### 2. Implement Tools Using Macros

```rust
#[tool_router]
impl CustomMcpServer {
    pub fn new(name: String) -> Self {
        Self {
            tool_router: Self::tool_router(),
            name,
        }
    }

    #[tool(description = "Your tool description")]
    async fn your_tool(&self, Parameters(req): Parameters<YourRequest>) -> Result<CallToolResult, McpError> {
        // Your tool implementation
        Ok(CallToolResult::success(vec![Content::text("result")]))
    }
}
```

### 3. Implement ServerHandler

```rust
#[tool_handler]
impl ServerHandler for CustomMcpServer {
    fn get_info(&self) -> ServerInfo {
        ServerInfo {
            protocol_version: Default::default(),
            capabilities: ServerCapabilities::builder()
                .enable_tools()
                .build(),
            server_info: Implementation {
                name: self.name.clone(),
                version: "1.0.0".to_string(),
            },
            instructions: Some("Your server description".to_string()),
        }
    }
}
```

### 4. Integrate with Microkernel

```rust
// Create custom MCP server
let custom_mcp_server = CustomMcpServer::new("My Custom Server".to_string());

// Build microkernel with custom server
let microkernel = MicrokernelServer::new()
    .with_oauth_provider(oauth_provider)
    .with_mcp_streamable_handler(custom_mcp_server.clone())
    .with_mcp_sse_handler(custom_mcp_server, SseHandlerConfig::default());
```

## Architecture Benefits

The microkernel architecture provides:

- **Independence**: Each handler operates standalone
- **Composability**: Mix and match OAuth providers, storage backends, and MCP servers
- **Testability**: Test components in isolation
- **Flexibility**: Easy to extend and modify
- **Reusability**: Custom MCP servers work with any OAuth/storage combination

## API Endpoints

Once running, the server provides these endpoints:

### MCP Protocol Endpoints
- **HTTP (streamable)**: `http://localhost:8080/mcp/streamable`
- **SSE**: `http://localhost:8080/mcp/sse`
- **SSE Messages**: `http://localhost:8080/mcp/message`

### OAuth 2.0 Endpoints (AWS Cognito)
- **Authorization**: `https://your-domain.auth.region.amazoncognito.com/oauth2/authorize`
- **Token**: `https://your-domain.auth.region.amazoncognito.com/oauth2/token`
- **JWKS**: `https://your-domain.auth.region.amazoncognito.com/oauth2/jwks`
- **UserInfo**: `https://your-domain.auth.region.amazoncognito.com/oauth2/userInfo`

## Testing Your Custom MCP Server

Use the MCP Inspector or any MCP client to test your custom tools:

```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Connect to your server
npx @modelcontextprotocol/inspector http://localhost:8080/mcp/streamable
```

## Next Steps

1. Study the `custom_mcp_server_example.rs` for implementation patterns
2. Create your own custom MCP server with domain-specific tools
3. Integrate with your preferred OAuth provider and storage backend
4. Deploy using the microkernel architecture for production use

The examples demonstrate the power and flexibility of the microkernel approach, allowing you to build sophisticated MCP servers while leveraging robust authentication and storage infrastructure.