npm package: @osiris-ai/sqlite-sdk
Description: Osiris SQLite SDK
Latest version: 0.1.1

# @osiris-ai/sqlite-sdk

SQLite database adapter for Osiris MCP authentication and session data storage with lightweight file-based storage.

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

## Overview

The SQLite SDK provides lightweight, file-based database storage for the [Osiris](https://docs.osirislabs.xyz) ecosystem. Perfect for local development, testing, and single-user MCPs with automatic schema management and zero-configuration setup.

## Installation

```bash
npm install @osiris-ai/sqlite-sdk sqlite3
npm install --save-dev @types/sqlite3
```

## Quick Start

### File-Based Storage

```typescript
import { createMcpServer } from '@osiris-ai/sdk';
import { SQLiteDatabaseAdapter } from '@osiris-ai/sqlite-sdk';

const sqliteAdapter = new SQLiteDatabaseAdapter('./data/mcp.db');

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: sqliteAdapter
  },
  configure: (server) => {
    // Your MCP tools here
  }
});
```

### In-Memory Storage (Testing)

```typescript
// Perfect for tests and temporary storage
const adapter = new SQLiteDatabaseAdapter(':memory:');

// Or use default (also in-memory)
const adapter = new SQLiteDatabaseAdapter();
```

### Storage Examples

```typescript
// Local file storage
const adapter = new SQLiteDatabaseAdapter('./mcp-data.db');

// Development storage
const adapter = new SQLiteDatabaseAdapter('./dev/auth.sqlite');

// Production with full path
const adapter = new SQLiteDatabaseAdapter('/var/data/production.db');

// Testing (in-memory)
const adapter = new SQLiteDatabaseAdapter(':memory:');
```

## Database Schema

The adapter automatically creates these tables with proper relationships:

```sql
-- Core tables
connections      -- MCP connection records (primary table)
authentications  -- OAuth tokens (references connections)
sessions         -- Authentication sessions
secrets          -- Encrypted credentials (references connections)

-- Legacy table
tokens           -- Backward compatibility
```

## API Reference

### SQLiteDatabaseAdapter

Lightweight database adapter implementing the Osiris DatabaseAdapter interface.

```typescript
class SQLiteDatabaseAdapter implements DatabaseAdapter
```

#### Constructor

```typescript
new SQLiteDatabaseAdapter(dbPath?: string)
```

**Parameters:**
- `dbPath`: Database file path (defaults to ':memory:' for in-memory storage)

#### Core Methods

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

// Session management
await adapter.storeSession(session);
await adapter.cleanupExpiredSessions();

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

## Usage Examples

### Development Setup

```typescript
import { SQLiteDatabaseAdapter } from '@osiris-ai/sqlite-sdk';
import path from 'path';

const dbPath = path.join(process.cwd(), 'data', 'dev.db');
const adapter = new SQLiteDatabaseAdapter(dbPath);

// Use with createMcpServer
await createMcpServer({
  name: 'dev-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: adapter
  },
  configure: (server) => {
    // Your development MCP configuration
  }
});
```

## Getting Started

1. **Install the adapter:**
   ```bash
   npm install @osiris-ai/sqlite-sdk sqlite3
   ```

2. **Basic setup:**
   ```typescript
   import { SQLiteDatabaseAdapter } from '@osiris-ai/sqlite-sdk';
   
   const adapter = new SQLiteDatabaseAdapter('./mcp.db');
   ```

3. **For testing:**
   ```typescript
   const adapter = new SQLiteDatabaseAdapter(':memory:');
   ```

## 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.