mongo-agent-hub

Build a secure AI chat service across multiple MongoDB databases. AgentHub connects aliases such as CRM, finance, and support; creates namespaced read tools; asks your chosen LLM to plan and call those tools; then returns the final answer.

Node.js 20+ and ESM are required.

Install

npm install mongo-agent-hub mongodb

The core package is provider-neutral. Add the official SDK for OpenAI, Anthropic, Google, or Azure separately and adapt it through AIProvider.

Use it

import { MongoClient } from 'mongodb';
import { AgentHub } from 'mongo-agent-hub';
import type { AIProvider } from '@dheerajatoria/providers';

const provider: AIProvider = {
  name: 'openai',
  async complete({ messages, tools, signal }) {
    // Call the vendor SDK using messages/tools, then map native calls to:
    // { text: string, toolCalls: [{ id, name, input }] }
    return { text: 'Adapter not configured', toolCalls: [] };
  }
};

const hub = new AgentHub({
  databases: {
    crm: process.env.CRM_DB!,
    finance: process.env.FINANCE_DB!,
    support: process.env.SUPPORT_DB!
  },
  clientFactory: (uri) => new MongoClient(uri),
  provider: 'openai',
  providers: [provider],
  maxSteps: 8
});

await hub.initialize();
const result = await hub.chat(
  'Which clients have overdue invoices and open support tickets?',
  { sessionId: 'user-42', roles: ['read'] }
);

initialize() connects every database and registers <alias>_find and <alias>_aggregate tools. chat() continues tool planning until the provider returns an answer or maxSteps is exceeded. Reuse a sessionId to retain history; call clearSession(sessionId) to remove it.

Configure MongoDB

await hub.connectMongo('analytics', {
  uri: process.env.ANALYTICS_DB!,
  database: 'reporting',
  readOnly: true
});

const collections = await hub.getCollections('analytics');
const schema = await hub.discoverSchema('analytics', 'invoices');

Schema discovery samples up to 100 documents and reports fields, types, nullability, and example values. Safe reads are capped at 500 results. $where, $function, $accumulator, $out, and $merge are rejected, but you must also use MongoDB users with read-only, least-privilege permissions.

Add tools

hub.tools.register({
  name: 'billing_get_status',
  description: 'Returns invoice status for a customer ID.',
  inputSchema: { type: 'object', required: ['customerId'] },
  permission: 'read',
  async execute(input) {
    return { customerId: input.customerId, status: 'overdue' };
  }
});

Tool names use lowercase snake case. read, write, and admin permissions are checked against roles supplied to chat; callers with admin may access every tool. hub.tools.discover(roles), execute(), and health() provide tool metadata, execution, and monitoring.

Production checklist

• Authenticate before calling chat; pass trusted roles, never browser-supplied roles.
• Use @dheerajatoria/auth JWT/rate-limit/audit primitives with durable storage.
• Keep MongoDB credentials in a secret manager and enforce database-level read-only roles.
• Validate HTTP bodies, rate limit principals, restrict CORS, and pass an abort signal for request timeouts.
• Review tool outputs before exposing sensitive data and persist audit events.

Related packages

• @dheerajatoria/react-chat supplies <AgentChat endpoint="/api/chat" theme="dark" />; the endpoint accepts { message } and returns { answer }.
• @dheerajatoria/rag provides vector-store/document-loader contracts. TextLoader supports TXT/Markdown; add PDF/DOCX and Qdrant/Pinecone/Chroma adapters as needed.
• @dheerajatoria/mcp, providers, mongo, and auth can also be used independently.

The complete source, architecture notes, and contribution guide are at https://github.com/mongo-agent-hub/mongo-agent-hub.