bot-relay-mcp

library2.8.0jsnpmunverified

Local-first MCP server for AI coding agent terminal-to-terminal communication. Version 2.8.0, active development. Provides durable message inboxes, task queues, and wakeups backed by a single SQLite file, enabling coordination across multiple AI coding tools (e.g., Claude Code, Cursor, Cline) and external systems via HTTP+SSE webhooks. Key differentiator: LLM-agnostic, self-hosted, and federation-bound, unlike vendor-native solutions like Claude Agent Teams. Releases follow a phased feature arc (see CHANGELOG). Requires Node.js >=20.0.0, ships TypeScript types.

ai-ml devops

npm install bot-relay-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · BOT-RELAY-MCP

bot-relay-mcp

ai-mljavascriptv2.8.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createMCPServer

✓ import { createMCPServer } from 'bot-relay-mcp'

✗ import createMCPServer from 'bot-relay-mcp'

Named export, not default. ESM module.

RelayClient

✓ import { RelayClient } from 'bot-relay-mcp'

✗ const { RelayClient } = require('bot-relay-mcp')

ESM-only, no CommonJS support. Use dynamic import() if needed.

config

✓ import { config } from 'bot-relay-mcp/config'

✗ import { config } from 'bot-relay-mcp'

Config is exported from a subpath - import from 'bot-relay-mcp/config' for type-safe config access.

Demonstrates programmatic startup of the MCP server with stdio transport and local SQLite database.

// Start the relay server programmatically import { createMCPServer } from 'bot-relay-mcp'; const server = await createMCPServer({ transport: 'stdio', dbPath: process.env.RELAY_DB_PATH || '~/.bot-relay/relay.db', }); // The server is now running and can handle MCP requests // For HTTP+SSE transport: // const server = await createMCPServer({ transport: 'http', port: 3000 });

Debug

Known issues

gotchaDatabase path defaults to ~/.bot-relay/relay.db; ensure directory exists before first run.

fix

Create directory: mkdir -p ~/.bot-relay

affects: >=1.0.0

deprecatedImporting 'bot-relay-mcp' without subpath for config is deprecated since v2.7.

fix

Use import { config } from 'bot-relay-mcp/config' instead.

affects: >=2.7.0

breakingv2.0 dropped CommonJS support. require() calls will fail.

fix

Use ESM imports or dynamic import().

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'bot-relay-mcp'

Package not installed or wrong Node version (<20).

fix

Install with 'npm install bot-relay-mcp' and ensure Node >=20.

TypeError: bot_relay_mcp_1.createMCPServer is not a function

Used default import instead of named import.

fix

Change to: import { createMCPServer } from 'bot-relay-mcp'

Error: ENOENT: no such file or directory, open '~/.bot-relay/relay.db'

Default database directory does not exist.

fix

Run: mkdir -p ~/.bot-relay

Upgrade

Version history

2.8.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

30 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/Maxlumiere/bot-relay-mcp ↗

packagebot-relay-mcp ↗

homepagehttps://github.com/Maxlumiere/bot-relay-mcp ↗