npm package: @osiris-ai/redis-sdk
Description: Osiris Redis SDK
Latest version: 0.1.1

# @osiris-ai/redis-sdk

Redis database adapter for Osiris MCP authentication and session data storage with high-performance caching.

[![npm version](https://badge.fury.io/js/@osiris-ai%2Fredis-sdk.svg)](https://badge.fury.io/js/@osiris-ai%2Fredis-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

The Redis SDK provides high-performance in-memory database storage for the [Osiris](https://docs.osirislabs.xyz) ecosystem. Store MCP authentication data, user sessions, and tokens with automatic expiration and optimized Redis operations.

**Key Features:**
- ⚡ **High Performance** - In-memory storage with sub-millisecond response times
- 🔄 **Auto Expiration** - Optional TTL for automatic data cleanup
- 📊 **Pipeline Operations** - Optimized batch operations for better performance
- 🔑 **Key Organization** - Structured key prefixing for data organization
- 📝 **Full TypeScript** - Complete type safety and IDE support
- 🛡️ **Production Ready** - Connection pooling and error handling

## Installation

```bash
npm install @osiris-ai/redis-sdk ioredis
npm install --save-dev @types/redis
```

## Quick Start

### Basic Redis Setup

```typescript
import { createMcpServer } from '@osiris-ai/sdk';
import { RedisDatabaseAdapter } from '@osiris-ai/redis-sdk';

const redisAdapter = new RedisDatabaseAdapter({
  host: 'localhost',
  port: 6379,
  keyPrefix: 'osiris:',
  // Optional: database number
  db: 0
}, 3600); // Optional: TTL in seconds

await createMcpServer({
  name: 'my-mcp',
  version: '1.0.0',
  auth: {
    useHub: true,
    hubConfig: {
      baseUrl: process.env.HUB_BASE_URL!,
      clientId: process.env.OAUTH_CLIENT_ID!,
      clientSecret: process.env.OAUTH_CLIENT_SECRET!,
    },
    database: redisAdapter
  },
  configure: (server) => {
    // Your MCP tools here
  }
});
```

## Key Structure

The adapter organizes data with structured key prefixes:

```
osiris:auth:{id}                    // Authentication records
osiris:auth:connection:{service}:{connectionId}  // Service lookups
osiris:connection:auths:{connectionId}           // Connection auth sets
osiris:session:{id}                 // Session records
osiris:connection:{id}              // Connection records
osiris:package:connections:{packageId}          // Package connection sets
osiris:secret:{id}                  // Secret records
osiris:token:{deploymentId}:{service}           // Legacy tokens
```

## API Reference

### RedisDatabaseAdapter

High-performance Redis adapter implementing the Osiris DatabaseAdapter interface.

```typescript
class RedisDatabaseAdapter implements DatabaseAdapter
```

#### Constructor

```typescript
new RedisDatabaseAdapter(config: RedisOptions, ttl?: number)
```

**Parameters:**
- `config`: Redis connection configuration
- `ttl`: Optional time-to-live in seconds for automatic expiration

#### Configuration Options

```typescript
interface RedisOptions {
  host?: string;          // Redis host (default: localhost)
  port?: number;          // Redis port (default: 6379)
  password?: string;      // Authentication password
  db?: number;            // Database number (default: 0)
  keyPrefix?: string;     // Key prefix (default: 'legion:')
  connectTimeout?: number; // Connection timeout
  lazyConnect?: boolean;  // Lazy connection
  tls?: any;             // TLS configuration
}
```

#### Core Methods

```typescript
// Authentication management
await adapter.storeAuthentication(auth);
await adapter.getAuthentication(connectionId, service);
await adapter.updateAuthentication(id, updates);

// Session management with auto-expiration
await adapter.storeSession(session);
await adapter.getSession(sessionId);

// Connection management
await adapter.storeConnection(connection);
await adapter.getConnectionsForPackage(packageId);
```

## Usage Examples

### Environment Configuration

```bash
# .env file
REDIS_URL=redis://localhost:6379
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-password

# For production
REDIS_URL=redis://user:pass@redis.example.com:6379
REDIS_TTL=3600
```

## Getting Started

1. **Install Redis:**
   ```bash
   # macOS
   brew install redis
   brew services start redis
   
   # Ubuntu/Debian
   sudo apt-get install redis-server
   
   # Or use managed service (AWS ElastiCache, Railway, Upstash)
   ```

2. **Install the adapter:**
   ```bash
   npm install @osiris-ai/redis-sdk ioredis
   ```

3. **Configure your MCP:**
   ```typescript
   import { RedisDatabaseAdapter } from '@osiris-ai/redis-sdk';
   
   const adapter = new RedisDatabaseAdapter({
     host: 'localhost',
     port: 6379,
     keyPrefix: 'my-app:'
   });
   ```

## Contributing

We welcome contributions! Please see our [Contributing Guide](https://github.com/fetcchx/osiris-ai/blob/main/CONTRIBUTING.md) for details.

## Support

- **Documentation:** [https://docs.osirislabs.xyz](https://docs.osirislabs.xyz)
- **GitHub Issues:** [https://github.com/fetcchx/osiris-ai/issues](https://github.com/fetcchx/osiris-ai/issues)
- **Discord Community:** [Join our Discord](https://discord.osirislabs.xyz)

## License

MIT License - see [LICENSE](LICENSE) file for details.

---

Built with ❤️ by the [Osiris Labs](https://osirislabs.xyz) team.