@burdenoff/mcp-libs
Modular MCP SDK shared across all Burdenoff product MCPs.
Each module under src/modules/<name>/ exports an McpModule. Product MCPs become thin shells (~125 lines) that pick which modules to mount, build an McpContext, pick a transport, and ship the binary.
Status — 1.0.0
23 modules cover the full surface of vibecontrols-app's microfrontends (~317 tools / 7 resources / 7 prompts):
| Domain | Modules |
|---|---|
| Identity | auth (full surface incl. mfa, api-keys, sso, delegations), rbac, organizations, tours |
| Workspace primitives | workspaces, groups, tags, files, conversations, security |
| Operations | integrations, channels, scheduler, export, notifications, support, products, devportal |
| Commerce | billing, store |
| Product surface | vibecontrols (rich; 16 sub-entities), sandbox, health |
Mounted in 6 product MCPs: vibecontrols, botlit, fluidgrids, bigconsole, healthybowl, workspaces — each consumes the same 23-module catalogue with product-prefixed tool names via mcpToolName(productName, …).
Beyond the platform catalogue, one domain module per product shell carries that product's own surface
(32 today, e.g. vibecontrols, healthybowl, bigconsole — the latter the 16-tool least-privilege
console-authoring set: data sinks, dashboards/pages, parsers, widgets, export/import, generate-from-prompt).
Install
bun add @burdenoff/mcp-libs @modelcontextprotocol/sdk graphql graphql-request zod
For HTTP transport:
bun add express cors
Quick start (product MCP shell)
#!/usr/bin/env node
import { buildContext, createMcpServer } from '@burdenoff/mcp-libs/core';
import { startStdioServer, startHttpServer } from '@burdenoff/mcp-libs/transports';
import authModule from '@burdenoff/mcp-libs/modules/auth';
import vibecontrolsModule from '@burdenoff/mcp-libs/modules/vibecontrols';
// ... import the rest of the 23 modules as needed
import pkg from '../package.json' with { type: 'json' };
const ctx = buildContext({
productName: 'vibecontrols',
productVersion: pkg.version,
serverName: 'vibecontrols-mcp',
serverVersion: pkg.version,
defaults: {
configDirName: 'vibecontrols-mcp',
oidcClientId: 'burdenoff_mcp_vibecontrols',
workspaceEndpointDefault: 'http://localhost:4003/workspaces/graphql',
globalEndpointDefault: 'http://localhost:4000/global/graphql',
httpPortDefault: 3000,
},
});
const server = createMcpServer(ctx, [authModule, vibecontrolsModule], {
name: 'vibecontrols-mcp',
version: pkg.version,
});
await startStdioServer(server, ctx);
Repository layout
src/core/—McpModule,McpContext, error classes, gql client, auth, config, output helpers.src/transports/— stdio + HTTP transport factories (express dynamic-imported).src/modules/<name>/— one folder per module:index.ts(McpModule export),tools.ts,resources.ts(optional),prompts.ts(optional),operations.ts.
See CLAUDE.md for the full architecture, hard rules, and adding-a-module guide.
License
UNLICENSED — Burdenoff Consultancy Services Pvt. Ltd.
FluidGrids code-first and durable tools
The FluidGrids module includes the SDK's code-first and durable-run operations:
runs_by_workflow_id, runs_count, runs_describe, runs_determinism,
runs_history, runs_pending, runs_signal, runs_stack_trace,
runs_terminate, workflows_create_version, workflows_export,
workflows_import, workflows_import_template, workflows_interface,
workflows_start, and workflows_validate. Tool names receive the host's product
prefix, for example fluidgrids_runs_history.
Run tools that accept run support either a run ID or a
{ workflowKey, workflowId, firstRunId? } target. History is bounded to one page
(1–1,000 events); pass nextAfter as after to continue. File and offloaded
payload URLs are returned without being downloaded. Imports accept exactly one
of definitionJson or inline JSON/TypeScript source files. URL-based source
imports are not exposed because the backend reserves and rejects that mode.
Starts and signals can execute external actions, and termination stops a run
without cancellation handlers. They explicitly advertise destructiveHint: true;
hosts must enable enforceDestructiveConfirmation to require confirm: true
before the handler runs. The FluidGrids MCP host already enables this option.
TERMINATE_EXISTING also requires workflowId and is sent to the separate
startWorkflowTerminateExisting gateway mutation, which enforces delete
permission. Confirmation never grants a missing gateway permission or feature
entitlement. Draft import/version creation does not activate or execute a workflow.
The library's exact MCP SDK peer is 1.32.1. Zod ^3.25.0 remains supported for
existing consumers, while new hosts should install patched Zod ^4.6.6.
Dependency vulnerability checks and host installation tests must cover the
actual resolved graph; a peer range is not a security clearance for old versions.