npm package: @osiris-ai/mongodb-sdk
Description: Osiris MongoDB SDK
Latest version: 0.1.1

# @osiris-ai/mongodb-sdk

MongoDB database adapter for Osiris MCP authentication and session data storage.

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

## Overview

The MongoDB SDK provides a flexible NoSQL database adapter for the [Osiris](https://docs.osirislabs.xyz) ecosystem. Store MCP authentication data, user sessions, connections, and secrets in MongoDB with automatic indexing and optimized performance.

**Key Features:**
- 🚀 **NoSQL Flexibility** - Schema-free document storage for complex data
- 📊 **Auto Indexing** - Optimized queries with automatic index creation
- 🔄 **Session Management** - Built-in session lifecycle and cleanup
- 🛡️ **Secure Storage** - Encrypted credential and token management
- 📝 **Full TypeScript** - Complete type safety and IDE support
- ⚡ **High Performance** - Optimized for MCP authentication patterns

## Installation

```bash
npm install @osiris-ai/mongodb-sdk mongodb
```

## Quick Start

### Basic MongoDB Setup

```typescript
import { createMcpServer } from '@osiris-ai/sdk';
import { MongoDBDatabaseAdapter } from '@osiris-ai/mongodb-sdk';

const mongoAdapter = new MongoDBDatabaseAdapter({
  uri: process.env.MONGODB_URI!,
  dbName: 'osiris_mcp',
  collectionName: 'tokens' // Optional: legacy collection name
});

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

### Connection String Examples

```typescript
// Local MongoDB
const localConfig = {
  uri: 'mongodb://localhost:27017',
  dbName: 'osiris_dev'
};

// MongoDB Atlas
const atlasConfig = {
  uri: 'mongodb+srv://username:password@cluster.mongodb.net',
  dbName: 'osiris_prod'
};

// MongoDB with authentication
const authConfig = {
  uri: 'mongodb://user:pass@host:27017/database?authSource=admin',
  dbName: 'osiris_enterprise'
};
```

## Database Collections

The adapter automatically creates and manages these collections:

```typescript
// Core collections (new architecture)
authentications  // OAuth tokens and user authentication data
sessions         // Authentication session management
connections      // MCP connection records
secrets          // Encrypted credential storage

// Legacy collection (backward compatibility)
tokens           // Legacy token storage
```

## API Reference

### MongoDBDatabaseAdapter

Main database adapter class implementing the Osiris DatabaseAdapter interface.

```typescript
class MongoDBDatabaseAdapter implements DatabaseAdapter
```

#### Constructor

```typescript
new MongoDBDatabaseAdapter(config: MongoDBConfig)
```

**Configuration:**
- `uri`: MongoDB connection string
- `dbName`: Database name to use
- `collectionName?`: Optional legacy collection name

#### Authentication Methods

```typescript
// Store OAuth authentication data
await adapter.storeAuthentication(auth);

// Update authentication tokens
await adapter.updateAuthentication(id, { token, userInfo });

// Retrieve authentication for service
await adapter.getAuthentication(connectionId, service);

// Get all authentications for connection
await adapter.getAuthenticationsForConnection(connectionId);
```

#### Session Management

```typescript
// Create authentication session
await adapter.storeSession(session);

// Update session status
await adapter.updateSession(id, { status: 'completed' });

// Retrieve session
await adapter.getSession(sessionId);

// Cleanup expired sessions
await adapter.cleanupExpiredSessions();
```

## Usage Examples

### Environment Configuration

```bash
# .env file
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB_NAME=osiris_mcp

# For MongoDB Atlas
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net
```

### Production Setup

```typescript
import { MongoDBDatabaseAdapter } from '@osiris-ai/mongodb-sdk';

const adapter = new MongoDBDatabaseAdapter({
  uri: process.env.MONGODB_URI!,
  dbName: process.env.MONGODB_DB_NAME || 'osiris_production'
});

// Use with createMcpServer
await createMcpServer({
  name: 'production-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 production MCP configuration
  }
});
```

## Getting Started

1. **Install MongoDB:**
   ```bash
   # Local MongoDB
   brew install mongodb/brew/mongodb-community
   brew services start mongodb/brew/mongodb-community
   
   # Or use MongoDB Atlas (cloud)
   ```

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

3. **Configure your MCP:**
   ```typescript
   import { MongoDBDatabaseAdapter } from '@osiris-ai/mongodb-sdk';
   
   const adapter = new MongoDBDatabaseAdapter({
     uri: 'mongodb://localhost:27017',
     dbName: 'my_mcp'
   });
   ```

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