@osiris-ai/mongodb-sdk

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

Overview

The MongoDB SDK provides a flexible NoSQL database adapter for the Osiris 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

npm install @osiris-ai/mongodb-sdk mongodb

Quick Start

Basic MongoDB Setup

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

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

// MongoDB Atlas
const atlasConfig = {
  uri: 'mongodb+srv://username:[email protected]',
  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:

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

class MongoDBDatabaseAdapter implements DatabaseAdapter

Constructor

new MongoDBDatabaseAdapter(config: MongoDBConfig)

Configuration:

• uri: MongoDB connection string
• dbName: Database name to use
• collectionName?: Optional legacy collection name

Authentication Methods

// 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

// 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

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

# For MongoDB Atlas
MONGODB_URI=mongodb+srv://user:[email protected]

Production Setup

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:

   # Local MongoDB
   brew install mongodb/brew/mongodb-community
   brew services start mongodb/brew/mongodb-community
      
   # Or use MongoDB Atlas (cloud)

2. Install the adapter:

   npm install @osiris-ai/mongodb-sdk mongodb

3. Configure your MCP:

   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 for details.

Support

• Documentation: https://docs.osirislabs.xyz
• GitHub Issues: https://github.com/fetcchx/osiris-ai/issues
• Discord Community: Join our Discord

License

MIT License - see LICENSE file for details.

Built with ❤️ by the Osiris Labs team.