KFDB Client

Direct access to the KFDB entity API with explicit read scope control. Use KFDBClient when you need programmatic access to marketplace data, notes, tasks, or any entity type.

Setup

import { KFDBClient } from 'rickydata';

const kfdb = new KFDBClient({
  baseUrl: process.env.KFDB_URL || 'http://34.60.37.158',
  apiKey: process.env.KFDB_API_KEY!,
  // or: token: process.env.KFDB_TOKEN,
  // defaultReadScope: 'global' (default if omitted)
});

Scope model

KFDB has two read scopes:

Scope	What you see	When to use
global	Public marketplace data (servers, agents, categories)	Default — browsing, searching, discovery
private	Your tenant-scoped data (notes, tasks, custom entities)	Personal data, per-wallet resources

Key rules:

• Reads default to global and send scope explicitly in the request
• Writes always go through /api/v1/write and are tenant-isolated (scoped to your wallet)
• You can switch scope at the client level or per-call

Reading data

Global read (default)

const servers = await kfdb.listEntities('MCPServer', { limit: 10 });

Switch to private with withScope

Create a scoped client view that reads from private by default:

const privateKfdb = kfdb.withScope('private');
const myNotes = await privateKfdb.listEntities('Note', { limit: 20 });
const myTasks = await privateKfdb.listEntities('Task', { limit: 50 });

The original kfdb instance is unchanged — withScope returns a new view.

Per-call override

Override scope on any individual call, regardless of client default:

// Client defaults to global, but read private for this call
const privateTasks = await kfdb.listEntities('Task', {
  scope: 'private',
  limit: 50,
});

Per-call scope takes precedence over the client-level default.

Other read methods

// List available entity labels
const labels = await kfdb.listLabels();        // global
const myLabels = await kfdb.listLabels('private');

// Get a single entity
const server = await kfdb.getEntity('MCPServer', 'server-123');

// Filter with criteria
const filtered = await kfdb.filterEntities('MCPServer', {
  filters: { registry: 'npm' },
  limit: 25,
});

// Batch fetch
const batch = await kfdb.batchGetEntities({
  requests: [
    { label: 'MCPServer', id: 'server-1' },
    { label: 'MCPServer', id: 'server-2' },
  ],
});

Writing data

Writes always go through the tenant-isolated write endpoint:

await kfdb.write({
  operations: [
    {
      operation: 'create_node',
      label: 'Note',
      properties: {
        title: { String: 'SDK note' },
        content: { String: 'Created via KFDBClient' },
      },
    },
  ],
});

Writes are scoped to your wallet tenant — you cannot write to another wallet's data.

API reference

Method	Description
listLabels(scope?)	List available labels in global/private scope
listEntities(label, opts?)	List entities with explicit scope control
getEntity(label, id, opts?)	Get a single entity by label + ID
filterEntities(label, request)	Filter entities with scoped body request
batchGetEntities(request)	Batch fetch entities with scoped request
withScope(scope)	Create a scoped client view (global or private)
write(request)	Tenant-isolated writes via /api/v1/write

Environment variables

Variable	Purpose
KFDB_URL	KFDB API base URL
KFDB_TOKEN	Wallet session token auth
KFDB_API_KEY	API key auth (alternative to token)

Next steps

• React Hooks — use KFDB data in React components
• MCP Gateway — discover and call MCP tools