@reddb-io/mcp 1.16.0

package/LICENSE

@@ -0,0 +1,111 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             RedDB.io <hello@reddb.io>
+
+Licensed Work:        RedDB
+                      The Licensed Work is (c) 2026 RedDB.io
+
+Additional Use Grant: You may make use of the Licensed Work, provided that
+                      you do not use the Licensed Work for a Database
+                      Service.
+
+                      A "Database Service" is a commercial offering that
+                      allows third parties (other than your employees and
+                      individual contractors) to access the functionality
+                      of the Licensed Work by creating tables, documents,
+                      graphs, vectors, key-value entries, queues, or
+                      time-series whose schemas and/or data are determined
+                      by those third parties, or by querying, storing, or
+                      retrieving data determined by those third parties,
+                      whether as a hosted, managed, "as-a-service",
+                      database-as-a-service (DBaaS), platform-as-a-service
+                      (PaaS), software-as-a-service (SaaS), or cloud
+                      database product.
+
+                      For clarity, the Additional Use Grant permits, among
+                      other things, the following uses, none of which
+                      constitute a Database Service: personal use; internal
+                      use within your own organization; research and
+                      educational use; development and testing; use in
+                      open source projects; and self-hosting the Licensed
+                      Work for your own organization's own data.
+
+Change Date:          2030-06-22
+
+Change License:       GNU Affero General Public License version 3.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact hello@reddb.io.
+
+Notice
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -0,0 +1,69 @@
+# @reddb-io/mcp
+
+Zero-install [MCP](https://modelcontextprotocol.io) launcher for [RedDB](https://github.com/reddb-io/reddb).
+
+```bash
+npx -y @reddb-io/mcp
+```
+
+That's the whole thing. The launcher resolves (or downloads) the matching
+`red` engine binary from GitHub Releases and spawns `red mcp` over stdio.
+Because `npx -y @reddb-io/mcp` always pulls the latest published launcher,
+you always run the latest released engine — no local install, no stale
+binary.
+
+No tool or knowledge logic is reimplemented in JavaScript. The launcher
+only fetches the native binary and execs `red mcp`; the MCP tool surface
+and `red://` knowledge resources come from the engine itself.
+
+## Use it as an MCP server
+
+Point your agent host at the launcher as a stdio MCP server:
+
+```json
+{
+  "mcpServers": {
+    "reddb": {
+      "command": "npx",
+      "args": ["-y", "@reddb-io/mcp"],
+      "env": {
+        "REDDB_MCP_URI": "${REDDB_MCP_URI:-memory://}"
+      }
+    }
+  }
+}
+```
+
+The default `memory://` URI starts an embedded ephemeral engine. To use a
+file-backed or remote database, export `REDDB_MCP_URI` in the host environment
+before your MCP host starts. Keep credentials in the host environment, not in
+the committed `.mcp.json`.
+
+Extra arguments are forwarded to `red mcp` after the subcommand, e.g. an
+explicit connection URI:
+
+```bash
+npx -y @reddb-io/mcp --uri file:///var/lib/reddb/agent.rdb
+```
+
+## Binary resolution
+
+Resolution reuses RedDB's internal bin-resolver / asset-fetcher and follows
+the same precedence as the SDK (PATH is never consulted, per ADR 0006):
+
+1. `REDDB_BIN` — absolute path to a `red` binary you provide. Returned verbatim.
+2. A binary already cached at `<package>/bin/red[.exe]`.
+3. Otherwise the matching release asset is downloaded from GitHub Releases.
+
+### Environment overrides
+
+| Variable            | Effect                                              |
+| ------------------- | --------------------------------------------------- |
+| `REDDB_BIN`         | Use this binary; skip all download logic.           |
+| `REDDB_MCP_URI`     | Connection URI forwarded to `red mcp --uri`.        |
+| `REDDB_MCP_VERSION` | Pull a specific release tag instead of the default. |
+| `REDDB_MCP_REPO`    | Fetch from a fork (default: `reddb-io/reddb`).       |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@reddb-io/mcp",
+  "version": "1.16.0",
+  "description": "Zero-install npx launcher for the RedDB MCP surface — fetches the matching red binary and spawns `red mcp` over stdio.",
+  "type": "module",
+  "bin": {
+    "reddb-mcp": "./src/launcher.js"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "reddb",
+    "mcp",
+    "model-context-protocol",
+    "database",
+    "agent",
+    "npx",
+    "launcher"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/reddb-io/reddb",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reddb-io/reddb.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/reddb-io/reddb/issues"
+  },
+  "scripts": {
+    "test": "node test/launcher.test.mjs"
+  }
+}

package/src/binary.js

@@ -0,0 +1,99 @@
+/**
+ * Locate (or download) the `red` binary for the `@reddb-io/mcp` launcher.
+ *
+ * Resolution precedence (reuses the vendored bin-resolver — env > local,
+ * PATH is never consulted, per ADR 0006):
+ *   1. `REDDB_BIN` env var → returned verbatim.
+ *   2. `<package>/bin/red[.exe]` if already present (e.g. a previous npx run
+ *      cached it, or a workspace checkout vendored it).
+ *   3. Otherwise download the matching GitHub Release asset (reusing the
+ *      vendored asset-fetcher — no new download logic) into `<package>/bin/`
+ *      and return that path.
+ *
+ * The download tag tracks this package's own version (`v<pkg.version>`),
+ * which the release flow keeps locked to the engine version. Because
+ * `npx -y @reddb-io/mcp` always pulls the latest published launcher, this
+ * yields the latest released engine with zero local install.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, chmodSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve, join } from 'node:path'
+
+import { resolveBin } from './internal/bin-resolver/index.js'
+import { fetchReleaseAsset } from './internal/asset-fetcher/index.js'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = resolve(HERE, '..')
+
+export const DEFAULT_REPO = 'reddb-io/reddb'
+
+/** Platform-specific base name of the engine binary. */
+export function binaryName(platform = process.platform) {
+  return platform === 'win32' ? 'red.exe' : 'red'
+}
+
+/**
+ * Non-throwing probe reusing the vendored bin-resolver: returns an
+ * absolute path when `REDDB_BIN` is set or a local binary exists, else
+ * `null` (so the caller can decide to download).
+ *
+ * @param {{ packageRoot?: string, platform?: string }} [opts]
+ * @returns {string|null}
+ */
+export function tryResolveBinary({ packageRoot = PACKAGE_ROOT, platform = process.platform } = {}) {
+  try {
+    return resolveBin({ name: binaryName(platform), packageRoot, envVar: 'REDDB_BIN' })
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Resolve the engine binary, downloading it from GitHub Releases when it is
+ * not already available. Returns the absolute path to a runnable binary.
+ *
+ * @param {{
+ *   version: string,
+ *   packageRoot?: string,
+ *   platform?: string,
+ *   arch?: string,
+ *   repo?: string,
+ *   fetchAsset?: typeof fetchReleaseAsset,
+ * }} opts
+ * @returns {Promise<string>}
+ */
+export async function ensureBinary({
+  version,
+  packageRoot = PACKAGE_ROOT,
+  platform = process.platform,
+  arch = process.arch,
+  repo = process.env.REDDB_MCP_REPO || DEFAULT_REPO,
+  fetchAsset = fetchReleaseAsset,
+} = {}) {
+  if (typeof version !== 'string' || version === '') {
+    throw new TypeError('ensureBinary: `version` must be a non-empty string')
+  }
+
+  const existing = tryResolveBinary({ packageRoot, platform })
+  if (existing) {
+    return existing
+  }
+
+  const tag = normalizeTag(process.env.REDDB_MCP_VERSION || version)
+  const body = await fetchAsset({ repo, tag, platform, arch, binName: 'red' })
+
+  const binDir = join(packageRoot, 'bin')
+  mkdirSync(binDir, { recursive: true })
+  const dest = join(binDir, binaryName(platform))
+  writeFileSync(dest, body)
+  if (platform !== 'win32') {
+    chmodSync(dest, 0o755)
+  }
+  return dest
+}
+
+function normalizeTag(value) {
+  const v = String(value).trim()
+  return v.startsWith('v') ? v : `v${v}`
+}

package/src/internal/asset-fetcher/asset-name.js

@@ -0,0 +1,37 @@
+/**
+ * Resolve the GitHub release asset filename for a given Node
+ * `process.platform` / `process.arch` pair and binary base name.
+ *
+ * Mapping is the existing scheme from `drivers/js/postinstall.js`:
+ *   linux  + x64       → <bin>-linux-x86_64
+ *   linux  + arm64     → <bin>-linux-aarch64
+ *   linux  + arm/armv7l→ <bin>-linux-armv7
+ *   darwin + x64       → <bin>-macos-x86_64
+ *   darwin + arm64     → <bin>-macos-aarch64
+ *   win32  + x64       → <bin>-windows-x86_64.exe
+ *
+ * Throws `UnsupportedPlatformError` for any other combination.
+ */
+
+export class UnsupportedPlatformError extends Error {
+  constructor(platform, arch) {
+    super(`unsupported platform/arch combination: ${platform}/${arch}`)
+    this.name = 'UnsupportedPlatformError'
+    this.code = 'UNSUPPORTED_PLATFORM'
+    this.platform = platform
+    this.arch = arch
+  }
+}
+
+export function composeAssetName({ platform, arch, binName }) {
+  if (typeof binName !== 'string' || binName === '') {
+    throw new TypeError('composeAssetName: `binName` must be a non-empty string')
+  }
+  if (platform === 'linux' && arch === 'x64') return `${binName}-linux-x86_64`
+  if (platform === 'linux' && arch === 'arm64') return `${binName}-linux-aarch64`
+  if (platform === 'linux' && (arch === 'arm' || arch === 'armv7l')) return `${binName}-linux-armv7`
+  if (platform === 'darwin' && arch === 'x64') return `${binName}-macos-x86_64`
+  if (platform === 'darwin' && arch === 'arm64') return `${binName}-macos-aarch64`
+  if (platform === 'win32' && arch === 'x64') return `${binName}-windows-x86_64.exe`
+  throw new UnsupportedPlatformError(platform, arch)
+}

package/src/internal/asset-fetcher/checksum.js

@@ -0,0 +1,23 @@
+import { createHash } from 'node:crypto'
+
+export class ChecksumMismatchError extends Error {
+  constructor(expected, actual) {
+    super(`checksum mismatch: expected sha256=${expected}, got sha256=${actual}`)
+    this.name = 'ChecksumMismatchError'
+    this.code = 'CHECKSUM_MISMATCH'
+    this.expected = expected
+    this.actual = actual
+  }
+}
+
+export function sha256Hex(buf) {
+  return createHash('sha256').update(buf).digest('hex')
+}
+
+export function verifySha256(buf, expected) {
+  const expectedNorm = String(expected).trim().toLowerCase()
+  const actual = sha256Hex(buf)
+  if (actual !== expectedNorm) {
+    throw new ChecksumMismatchError(expectedNorm, actual)
+  }
+}

package/src/internal/asset-fetcher/download.js

@@ -0,0 +1,89 @@
+import { request as httpsRequest } from 'node:https'
+import { request as httpRequest } from 'node:http'
+
+const MAX_REDIRECTS = 5
+
+export class AssetNotFoundError extends Error {
+  constructor(url) {
+    super(`asset not found (HTTP 404) at ${url}`)
+    this.name = 'AssetNotFoundError'
+    this.code = 'ASSET_NOT_FOUND'
+    this.url = url
+  }
+}
+
+export class HttpError extends Error {
+  constructor(status, url) {
+    super(`HTTP ${status} fetching ${url}`)
+    this.name = 'HttpError'
+    this.code = 'HTTP_ERROR'
+    this.status = status
+    this.url = url
+  }
+}
+
+export class TooManyRedirectsError extends Error {
+  constructor(url) {
+    super(`too many redirects (>${MAX_REDIRECTS}) starting at ${url}`)
+    this.name = 'TooManyRedirectsError'
+    this.code = 'TOO_MANY_REDIRECTS'
+    this.url = url
+  }
+}
+
+function pickRequest(url) {
+  return url.startsWith('http://') ? httpRequest : httpsRequest
+}
+
+function resolveLocation(currentUrl, location) {
+  if (/^https?:\/\//i.test(location)) return location
+  return new URL(location, currentUrl).toString()
+}
+
+export function downloadFollowingRedirects(url, { userAgent, originalUrl } = {}, depth = 0) {
+  const startUrl = originalUrl || url
+  if (depth > MAX_REDIRECTS) {
+    return Promise.reject(new TooManyRedirectsError(startUrl))
+  }
+  const request = pickRequest(url)
+  return new Promise((resolve, reject) => {
+    const req = request(
+      url,
+      {
+        method: 'GET',
+        headers: {
+          'User-Agent': userAgent || 'reddb-internal-asset-fetcher',
+          Accept: 'application/octet-stream',
+        },
+      },
+      (res) => {
+        const status = res.statusCode || 0
+        if (status >= 300 && status < 400 && res.headers.location) {
+          res.resume()
+          const next = resolveLocation(url, res.headers.location)
+          downloadFollowingRedirects(next, { userAgent, originalUrl: startUrl }, depth + 1).then(
+            resolve,
+            reject,
+          )
+          return
+        }
+        if (status === 404) {
+          res.resume()
+          reject(new AssetNotFoundError(startUrl))
+          return
+        }
+        if (status < 200 || status >= 300) {
+          res.resume()
+          reject(new HttpError(status, url))
+          return
+        }
+        const chunks = []
+        res.on('data', (chunk) => chunks.push(chunk))
+        res.on('end', () => resolve(Buffer.concat(chunks)))
+        res.on('error', reject)
+      },
+    )
+    req.on('error', reject)
+    req.end()
+  })
+}

package/src/internal/asset-fetcher/index.js

@@ -0,0 +1,52 @@
+/**
+ * @reddb-io/internal-asset-fetcher — fetch a `red`/`red_client` binary
+ * from a GitHub release.
+ *
+ * Public surface: one function.
+ *
+ *   fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256? }) → Buffer
+ *
+ * Steps:
+ *   1. Map (platform, arch, binName) → asset filename.
+ *   2. Compose the GitHub download URL: `https://github.com/<repo>/releases/download/<tag>/<asset>`.
+ *   3. Follow up to 5 redirects, returning the final body as a Buffer.
+ *   4. If `sha256` was supplied, verify before returning.
+ *
+ * Errors carry distinct `.code` values so callers can differentiate:
+ *   - UNSUPPORTED_PLATFORM   — no asset for this platform/arch
+ *   - ASSET_NOT_FOUND        — HTTP 404 (release/tag/asset name wrong)
+ *   - CHECKSUM_MISMATCH      — body downloaded but sha256 mismatched
+ *   - HTTP_ERROR             — any other non-2xx status
+ *   - TOO_MANY_REDIRECTS     — redirect chain longer than 5 hops
+ *
+ * Internal modules (`./asset-name.js`, `./download.js`, `./checksum.js`)
+ * are not part of the public contract — only `fetchReleaseAsset` is.
+ * They are imported directly in tests for focused coverage.
+ */
+
+import { composeAssetName } from './asset-name.js'
+import { downloadFollowingRedirects } from './download.js'
+import { verifySha256 } from './checksum.js'
+
+export async function fetchReleaseAsset({ repo, tag, platform, arch, binName, sha256 } = {}) {
+  if (typeof repo !== 'string' || repo === '') {
+    throw new TypeError('fetchReleaseAsset: `repo` must be a non-empty string (e.g. "reddb-io/reddb")')
+  }
+  if (typeof tag !== 'string' || tag === '') {
+    throw new TypeError('fetchReleaseAsset: `tag` must be a non-empty string (e.g. "v0.2.9")')
+  }
+  if (typeof platform !== 'string' || platform === '') {
+    throw new TypeError('fetchReleaseAsset: `platform` must be a non-empty string')
+  }
+  if (typeof arch !== 'string' || arch === '') {
+    throw new TypeError('fetchReleaseAsset: `arch` must be a non-empty string')
+  }
+
+  const assetName = composeAssetName({ platform, arch, binName })
+  const url = `https://github.com/${repo}/releases/download/${tag}/${assetName}`
+  const body = await downloadFollowingRedirects(url)
+  if (sha256) {
+    verifySha256(body, sha256)
+  }
+  return body
+}

package/src/internal/bin-resolver/index.js

@@ -0,0 +1,57 @@
+/**
+ * @reddb-io/internal-bin-resolver — runtime lookup for a pinned binary.
+ *
+ * Precedence:
+ *   1. `process.env[envVar]` if set and non-empty → returned verbatim.
+ *      No existence probe: the env var is the user's "I know what I'm
+ *      doing" override.
+ *   2. `<packageRoot>/bin/<name>` if it exists.
+ *   3. Otherwise throw an actionable error naming the env var, the
+ *      expected local path, and a one-line `pnpm install` hint.
+ *
+ * `PATH` is deliberately never consulted. SDK/client wire formats are
+ * version-coupled to the binary; silent fallback to a stale `PATH`
+ * binary fails as misframed RPC, not "command not found". See ADR 0006.
+ */
+
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * @param {{ name: string, packageRoot: string, envVar: string }} opts
+ * @returns {string} absolute path to the binary
+ * @throws {Error} when neither env override nor local binary is usable
+ */
+export function resolveBin(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new TypeError('resolveBin: options object required')
+  }
+  const { name, packageRoot, envVar } = opts
+  if (typeof name !== 'string' || name === '') {
+    throw new TypeError('resolveBin: `name` must be a non-empty string')
+  }
+  if (typeof packageRoot !== 'string' || packageRoot === '') {
+    throw new TypeError('resolveBin: `packageRoot` must be a non-empty string')
+  }
+  if (typeof envVar !== 'string' || envVar === '') {
+    throw new TypeError('resolveBin: `envVar` must be a non-empty string')
+  }
+
+  const override = process.env?.[envVar]
+  if (typeof override === 'string' && override !== '') {
+    return override
+  }
+
+  const local = join(packageRoot, 'bin', name)
+  if (existsSync(local)) {
+    return local
+  }
+
+  throw new Error(
+    `reddb: binary "${name}" not found.\n` +
+      `  expected at: ${local}\n` +
+      `  override:    set ${envVar}=/path/to/${name}\n` +
+      `  fix:         re-run \`pnpm install\` (the postinstall script downloads it),\n` +
+      `               or check the postinstall log for a download error.`,
+  )
+}

package/src/launcher.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * @reddb-io/mcp — zero-install npx launcher for the RedDB MCP surface.
+ *
+ *   npx -y @reddb-io/mcp [args…]
+ *
+ * Resolves (or downloads) the matching `red` binary and execs `red mcp`
+ * over stdio. No tool/knowledge logic lives here — the launcher only
+ * fetches + spawns the native engine, so the MCP surface is always the
+ * latest released engine's.
+ */
+
+import { createRequire } from 'node:module'
+
+import { ensureBinary, DEFAULT_REPO } from './binary.js'
+import { spawnMcp } from './spawn.js'
+
+const require = createRequire(import.meta.url)
+const pkg = require('../package.json')
+
+ensureBinary({ version: pkg.version })
+  .then((binary) => {
+    const child = spawnMcp(binary, process.argv.slice(2))
+    child.on('error', (err) => {
+      process.stderr.write(`reddb-mcp: failed to spawn red (${err.message})\n`)
+      process.exit(1)
+    })
+    child.on('exit', (code, signal) => {
+      process.exit(signal ? 1 : (code ?? 0))
+    })
+  })
+  .catch((err) => {
+    process.stderr.write(formatFailure(err))
+    process.exit(1)
+  })
+
+function formatFailure(err) {
+  const repo = process.env.REDDB_MCP_REPO || DEFAULT_REPO
+  const escapeHatches =
+    `       Escape hatches:\n` +
+    `         - Provide the binary yourself:  export REDDB_BIN=/path/to/red\n` +
+    `         - Install red via the official installer:\n` +
+    `             curl -fsSL https://raw.githubusercontent.com/${repo}/main/install.sh | bash\n` +
+    `             export REDDB_BIN="$(command -v red)"\n` +
+    `         - Download a release binary manually from\n` +
+    `             https://github.com/${repo}/releases\n`
+
+  if (err && err.code === 'UNSUPPORTED_PLATFORM') {
+    return (
+      `reddb-mcp: no prebuilt red binary for ${process.platform}/${process.arch}.\n` +
+      `       Build from source: https://github.com/${repo}#build-from-source\n` +
+      escapeHatches
+    )
+  }
+  if (err && err.code === 'ASSET_NOT_FOUND') {
+    return (
+      `reddb-mcp: release asset not found${err.url ? ` at ${err.url}` : ''}.\n` +
+      `       The GitHub Release for this launcher version may not be published yet,\n` +
+      `       or your platform's binary was not produced for that release.\n` +
+      escapeHatches
+    )
+  }
+  return (
+    `reddb-mcp: could not obtain the red binary (${(err && err.message) || err}).\n` +
+    escapeHatches
+  )
+}

package/src/spawn.js

@@ -0,0 +1,54 @@
+/**
+ * Spawn `red mcp` over stdio.
+ *
+ * The launcher reimplements no tool/knowledge logic — it simply execs the
+ * native engine's `mcp` subcommand and inherits stdio so the MCP JSON-RPC
+ * stream flows straight through to the parent (the agent host). Any extra
+ * argv passed to `npx @reddb-io/mcp ...` is forwarded after `mcp` (e.g.
+ * `--uri <addr>` for connection mode selection).
+ *
+ * `spawn` is injectable so tests can assert the binary, argv, and stdio
+ * wiring without launching a real process.
+ */
+
+import { spawn as nodeSpawn } from 'node:child_process'
+
+/**
+ * @param {string} binary absolute path to the `red` binary
+ * @param {string[]} [extraArgs] argv forwarded after the `mcp` subcommand
+ * @param {{
+ *   spawn?: typeof nodeSpawn,
+ *   stdio?: import('node:child_process').StdioOptions,
+ *   env?: NodeJS.ProcessEnv,
+ *   cwd?: string,
+ * }} [opts]
+ * @returns {import('node:child_process').ChildProcess}
+ */
+export function spawnMcp(
+  binary,
+  extraArgs = [],
+  { spawn = nodeSpawn, stdio = 'inherit', env = process.env, cwd = process.cwd() } = {},
+) {
+  if (typeof binary !== 'string' || binary === '') {
+    throw new TypeError('spawnMcp: `binary` must be a non-empty string')
+  }
+  return spawn(binary, redMcpArgs(extraArgs, env), { stdio, env, cwd })
+}
+
+export function redMcpArgs(extraArgs = [], env = process.env) {
+  if (hasFlag(extraArgs, 'uri')) {
+    return ['mcp', ...extraArgs]
+  }
+
+  const uri = env.REDDB_MCP_URI
+  if (typeof uri === 'string' && uri !== '') {
+    return ['mcp', '--uri', uri, ...extraArgs]
+  }
+
+  return ['mcp', ...extraArgs]
+}
+
+function hasFlag(args, name) {
+  const long = `--${name}`
+  return args.some((arg) => arg === long || arg.startsWith(`${long}=`))
+}