@nuberea/sdk

Client library and CLI for the NuBerea biblical data platform.

Query morphological corpora, lexicons, Bible texts, manuscripts, and scrolls — via MCP tools or SQL analytics.

Install

npm install @nuberea/sdk

# Or globally for the CLI
npm install -g @nuberea/sdk

Quick Start

As a library

import { NuBerea } from '@nuberea/sdk';

const client = new NuBerea();
await client.login(); // Opens browser for sign-in

// Get a verse
const verse = await client.verse('John', 1, 1);
console.log(verse);

// Call any MCP tool
const result = await client.tool('macula_greek_query_verse', {
  book: 'John', chapter: 1, verse: 1,
});
console.log(result.content[0].text);

// Run SQL analytics (cross-database joins)
const rows = await client.query(`
  SELECT h.text, h.lemma, h.strong, b.short_def
  FROM hebrew.morphemes h
  LEFT JOIN bdb.entries b ON h.strong = b.strong
  WHERE h.book_id = 'Gen' AND h.chapter = 1 AND h.verse = 1
  ORDER BY h.word_position
`);
console.log(rows.rows);

As a CLI

# Authenticate
nuberea login

# Get a verse
nuberea verse John 1:1

# Search KJV text
nuberea search "In the beginning"

# Look up Greek word
nuberea greek λόγος

# Look up Hebrew Strong's number
nuberea hebrew H430

# List available tools
nuberea tools

# Call any tool
nuberea tool bible_kjv_get_verse '{"book":"John","chapter":1,"verse":1}'

# Run SQL query
nuberea query "SELECT * FROM hebrew.morphemes WHERE book_id = 'Gen' AND chapter = 1 LIMIT 5"

# Explore databases
nuberea databases
nuberea describe hebrew morphemes
nuberea introspect lsj

# Raw JSON output
nuberea tool bible_kjv_search_text '{"query":"love","limit":3}' --json

Data connectors (BYO-data)

Register your own data so it becomes queryable through the NuBerea MCP server. A connector belongs to a tenant (your org unit); parameterized, SELECT-only SQL tools are registered against it. Two kinds are supported: hf_dataset (Hugging Face Parquet, public or gated) and glue_athena (AWS Glue

• Athena over your own S3, via a secretless OIDC trust).

Library

import { NuBerea } from '@nuberea/sdk';

const client = new NuBerea();
await client.login();

const tenant = await client.catalog.createTenant('My Org');

// Hugging Face dataset (no trust needed)
const connector = await client.catalog.createHfConnector(tenant.tenantId, {
  repo: 'owner/name',
  tableName: 'orders',
  files: ['default/train/*.parquet'],
});

const result = await client.catalog.validateConnector(tenant.tenantId, connector.connectorId);
console.log(result.status, result.columns);

Gated Hugging Face datasets

Gated datasets are read with a short-lived, read-only token minted through HF Trusted Publishers. Register NuBerea's issuer under your HF account's Authentication settings → CI/CD Access, then tell the tenant which account to use. The account is stored once per tenant, so every gated connector under it shares one identity.

// The exact values to paste into HF. Available before an identity exists.
const setup = await client.catalog.getHfSetup(tenant.tenantId);
// { issuer, audience: 'https://huggingface.co', subject: 'tenant:<id>:workload:hf' }

await client.catalog.setHfIdentity(tenant.tenantId, 'your-hf-username');

const check = await client.catalog.verifyHfIdentity(tenant.tenantId);
if (check.status !== 'active') throw new Error(check.reason);

await client.catalog.createHfConnector(tenant.tenantId, {
  repo: 'owner/gated-name',
  tableName: 'lexicon',
  files: ['data/train/*.parquet'],
  auth: 'gated',
});

Private repos are not supported: Trusted-Publisher tokens can read gated repos you have access to, but never private ones.

If you rename your Hugging Face account, call setHfIdentity again — one write fixes every gated connector, because the username is stored per tenant rather than per connector.

Changing an existing connector

updateHfConnector changes a connector's auth mode, revision or files while leaving its registered tools intact — useful when a repo flips from public to gated. repo and tableName are deliberately not updatable: tools select FROM the table name and were validated against that dataset's columns, so pointing elsewhere means creating a new connector.

The connector returns to pending (which hides its tools from discovery), so validate straight after:

await client.catalog.updateHfConnector(tenantId, connectorId, { auth: 'gated' });
const result = await client.catalog.validateConnector(tenantId, connectorId);

CLI

# tenants
nuberea catalog tenants
nuberea catalog tenant-create "My Org"

# Hugging Face dataset connector → validate
nuberea catalog add-hf <tenantId> owner/name orders "default/train/*.parquet"
nuberea catalog validate <tenantId> <connectorId>

# Gated Hugging Face: set the tenant's HF account once, then add connectors
nuberea catalog hf-identity-setup <tenantId>   # values to paste into HF CI/CD Access
nuberea catalog hf-identity-set <tenantId> your-hf-username
nuberea catalog hf-identity-verify <tenantId>
nuberea catalog add-hf <tenantId> owner/gated-name lexicon "data/train/*.parquet" --auth gated
nuberea catalog validate <tenantId> <connectorId>

# change a connector without rebuilding it (tools survive), then re-validate
nuberea catalog update-hf <tenantId> <connectorId> --auth gated
nuberea catalog validate <tenantId> <connectorId>

# AWS Glue + Athena: trust → connector → validate
nuberea catalog trust-aws <tenantId>
nuberea catalog trust-role <tenantId> arn:aws:iam::<acct>:role/<name>
nuberea catalog trust-verify <tenantId>
nuberea catalog add-glue <tenantId> us-west-2 primary --databases sales --tables sales.orders
nuberea catalog validate <tenantId> <connectorId>

# inspect or remove a connection (removal is refused while connectors still use it)
nuberea catalog trust <tenantId>
nuberea catalog hf-identity <tenantId>
nuberea catalog trust-delete <tenantId>
nuberea catalog hf-identity-delete <tenantId>

# tools
nuberea catalog suggest-tools <tenantId> <connectorId> --max 5
nuberea catalog register-tool <tenantId> '{"name":"orders_by_region", ... }'
nuberea catalog tools <tenantId>

Available Databases

| Schema | Table | Description | Rows | |---|---|---|---| | hebrew | morphemes | Hebrew Bible morphological analysis | 467,770 | | greek | morphemes | Greek NT morphological analysis | 137,741 | | lxx | morphemes | Septuagint morphological analysis | 623,693 | | lsj | entries | Liddell-Scott-Jones Greek Lexicon | 119,553 | | bdb | entries | Brown-Driver-Briggs Hebrew Lexicon | 10,221 | | abbott_smith | entries | Abbott-Smith NT Greek Lexicon | 555 | | kjv | verses | King James Version Bible text | 36,821 | | cntr | transcriptions | Greek NT manuscript transcriptions | 41,956 | | aland | pericopes | Synoptic parallel pericopes | 330 |

Available MCP Tools

55+ tools organized by collection:

• bible_kjv_* — KJV Bible text (get_verse, get_chapter, search_text, ...)
• macula_hebrew_* — Hebrew morphology (query_verse, search_lemma, search_strong, ...)
• macula_greek_* — Greek NT morphology
• macula_lxx_* — Septuagint morphology
• lexicon_lsj_* — LSJ Greek lexicon (lookup, search, search_latin, ...)
• lexicon_bdb_* — BDB Hebrew lexicon
• lexicon_abbott_smith_* — Abbott-Smith lexicon
• transcription_cntr_* — CNTR manuscripts
• synoptic_* — Synoptic parallels
• analytics_* — SQL queries, schema introspection

Run nuberea tools to see the full list.

Configuration

Environment Variables

| Variable | Description | |---|---| | NUBEREA_BASE_URL | OAuth base URL (default: https://auth.nuberea.com) | | NUBEREA_MCP_URL | MCP transport URL (default: https://mcp.nuberea.com/mcp) | | NUBEREA_ACCESS_TOKEN | Pre-set access token (skip login) | | NUBEREA_FIREBASE_TOKEN | Pre-set Firebase token (skip browser sign-in) |

Programmatic

const client = new NuBerea({
  baseUrl: 'https://auth.nuberea.com',
  mcpUrl: 'https://mcp.nuberea.com/mcp',
  accessToken: 'your-token', // Skip login
});

The SDK automatically selects the branded MCP endpoint for known NuBerea OAuth/control-plane hosts. OAuth authorization, token, issuer, and discovery requests continue to use baseUrl; only MCP protocol and tool-list requests use mcpUrl. Development and preproduction callers can override both URLs explicitly.

Authentication

NuBerea uses OAuth 2.1 with PKCE.

1. nuberea login opens your browser to nuberea.com/login
2. Sign in to your nuberea account
3. Tokens are stored per OAuth host in the OS keychain when available, otherwise under the platform state directory (for example, ~/Library/Application Support/nuberea/tokens-auth.nuberea.com.json on macOS)
4. Tokens auto-refresh — you rarely need to re-login

Install @nuberea/sdk in the consuming project or reference it through an npm workspace/file dependency. Node.js ESM does not use NODE_PATH to resolve packages from sibling directories.

License

MIT