@dcentralab/iatp-registry-search

Node-only MongoDB query helpers for the IATP registry collections (MCP servers + utility agents).

This package is designed for server runtimes only (Next.js Server Components, Route Handlers, server actions, Node services). It can manage and cache MongoDB connections for you via createRegistryClient().

Install

pnpm add @dcentralab/iatp-registry-search mongodb

Requirements

• Node.js >= 18
• A MongoDB URI with access to the IATP registry DB

Configuration

You can pass config directly to createRegistryClient(...), or rely on environment variables.

Environment variables

• MONGODB_CONNECTION_STRING (required if you don't pass mongoUri)
• ENV (optional; defaults to test; allowed: test | prod)

Quick start

import { createRegistryClient } from "@dcentralab/iatp-registry-search";

// Option 1: Pass connection string directly (e.g., from app config or secret manager)
const registry = createRegistryClient({
  env: "prod",
  mongoUri: "mongodb+srv://...",
  // Optional MongoClient options override (timeouts/pool sizing, etc.)
  clientOptions: { maxPoolSize: 10, serverSelectionTimeoutMS: 10_000 },
});

// Option 2: Use MONGODB_CONNECTION_STRING from environment
// Requires: MONGODB_CONNECTION_STRING env var set (e.g., mongodb+srv://...)
// Optional: ENV env var ("test" | "prod"); defaults to "test" if not provided
const registry = createRegistryClient();

const page1 = await registry.listMcpServers({ page: 1, limit: 10 });
const server = await registry.getMcpServerByUuid({ uuid: "..." });

API

createRegistryClient(config?)

Creates a bound client that manages MongoDB connections internally:

• Caches MongoClient + Db (process-scoped via globalThis)
• Reuses the same connection for subsequent calls with matching mongoUri
• All methods are async and do not require passing a Db instance

config (all fields optional)

• mongoUri: MongoDB connection string. If omitted, reads process.env.MONGODB_CONNECTION_STRING
• env: "test" | "prod" — defaults to "test"
• clientOptions: MongoClientOptions overrides for timeouts, pool sizing, etc.

MCP servers

listMcpServers(params?)

Returns a paginated result:

• servers: array of MCP server documents mapped to MCPServerInfo
• count: total matching documents
• page, limit
• has_more: page * limit < count

Filters:

• Default: only active and verified servers (is_active=true, core_tests_passed=true)
• Override with:
  • include_inactive: true — include inactive servers
  • include_unverified: true — include unverified servers

Optional:

• maxTimeMS (default 8000, minimum 1000)

getMcpServerByUuid({ uuid, user_uuid? })

Lookup by metadata.mcp_server_uuid field. Enforces is_active=true and core_tests_passed=true.

Parameters:

• uuid - MCP server UUID from metadata.mcp_server_uuid field
• user_uuid (optional) - If provided, result will include is_owner: true if the user owns the server

Returns: MCPServerInfo | null

Utility agents

listUtilityAgents(params?)

Lists utility agents (default active_only=true).

getUtilityAgentById({ agentId })

Exact match on agent_id (default active_only=true).

Next.js examples

Server Component

import { createRegistryClient } from "@dcentralab/iatp-registry-search";

export default async function Page() {
  // createRegistryClient() is synchronous; it connects lazily on the first awaited registry method
  // (e.g. await registry.listMcpServers(...))
  const registry = createRegistryClient();
  const { servers } = await registry.listMcpServers({ page: 1, limit: 12 });
  return <pre>{JSON.stringify(servers.slice(0, 1), null, 2)}</pre>;
}

Route Handler

import { NextResponse } from "next/server";
import { createRegistryClient } from "@dcentralab/iatp-registry-search";

export async function GET() {
  const registry = createRegistryClient();
  const data = await registry.listMcpServers({ page: 1, limit: 12 });
  return NextResponse.json({ status: "success", data });
}

Notes on caching

Connections are cached per process using a globalThis map keyed by {mongoUri}. In serverless/edge environments, process lifetime and reuse depend on the platform.

Troubleshooting

• Missing URI: set MONGODB_CONNECTION_STRING or pass mongoUri to createRegistryClient.
• Unexpected empty results: remember the default filters require is_active=true and core_tests_passed=true. Set include_inactive or include_unverified if needed.

import { createRegistryClient } from "@dcentralab/iatp-registry-search";

const registry = createRegistryClient({
  env: "prod",
  mongoUri: "mongodb+srv://...",
  clientOptions: { maxPoolSize: 10, serverSelectionTimeoutMS: 10_000 },
});

const result = await registry.listMcpServers({ page: 1, limit: 10 });
const server = await registry.getMcpServerByUuid({ uuid: "mcp-server-uuid-here" });
const agent = await registry.getUtilityAgentById({ agentId: "agent-123" });