@decocms/mcp-utils

Provides composable primitives for MCP bridges, proxies, gateways, transports, and sandboxed execution.

| Attribute | Value | | --- | --- | | Workspace | @decocms/mcp-utils (packages/mcp-utils) | | Kind | TypeScript MCP utility library | | Runtime | Node.js 24+ | | Distribution | Public npm package |

Overview

The Model Context Protocol SDK provides clients, servers, and transports. This package supplies the glue for joining those pieces: in-process transport pairs, client-to-server delegation, transport middleware, multi-client aggregation, shared JSON Schema validation, and QuickJS execution.

The utilities are independent of Studio applications and can be used by other MCP gateways or proxies.

Responsibilities

• Connect MCP clients and servers without a network hop.
• Expose an IClient implementation as an MCP server.
• Compose transport middleware around any MCP SDK transport.
• Aggregate tools, prompts, resources, and resource templates from many clients.
• Execute JavaScript against a narrow MCP client inside QuickJS.
• Reuse a memoized JSON Schema validator across proxy servers.

Usage

Install the package and its MCP SDK peer (>=1.27.0):

bun add @decocms/mcp-utils @modelcontextprotocol/sdk

Bridge a client and server in process:

import { createBridgeTransportPair } from "@decocms/mcp-utils";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";

const { client: clientTransport, server: serverTransport } =
  createBridgeTransportPair();

const server = new Server(
  { name: "example-server", version: "1.0.0" },
  { capabilities: { tools: {} } },
);
const client = new Client({ name: "example-client", version: "1.0.0" });

await server.connect(serverTransport);
await client.connect(clientTransport);

Supported package exports:

| Import path | Surface | | --- | --- | | @decocms/mcp-utils | Bridge transports, server delegation, transport composition, IClient, and shared schema validation | | @decocms/mcp-utils/aggregate | GatewayClient and namespace helpers | | @decocms/mcp-utils/sandbox | runCode and sandbox result types |

Consumers of the sandbox entry point must also install its QuickJS runtime:

bun add [email protected] @jitl/[email protected]

Architecture

The root entry point contains three layers. bridge-transport.ts creates a client/server transport pair, server-from-client.ts turns any IClient into an MCP server, and compose-transport.ts builds wrapper pipelines around MCP SDK transports.

aggregate/GatewayClient extends the MCP SDK client. It lazily resolves upstream clients, fetches all list pages, caches list results, filters selected capabilities, namespaces tools and prompts, and routes calls back to the owning client. Resource URIs remain unchanged and use an internal routing map.

sandbox/runCode.ts evaluates an ES module in QuickJS. The module must export a default function that receives a plain MCP client object. Execution applies time, memory, and stack limits and returns captured console output alongside a return value or error.

Development

Run commands from the repository root:

bun install
bun run --cwd=packages/mcp-utils check
bun run --cwd=packages/mcp-utils test

Run a focused test with:

bun test packages/mcp-utils/src/server-from-client.test.ts

Tests cover transport lifecycle, middleware ordering, proxy delegation, aggregation, schema-validator reuse, and QuickJS execution.

Boundaries

This package owns reusable MCP mechanics. Studio authentication, tenant policy, storage, observability wiring, application contracts, and UI behavior do not belong here.

Keep @modelcontextprotocol/sdk as the public peer contract. Do not introduce a dependency on @decocms/shared, an application workspace, or a Studio-only context; those dependencies would make the low-level bridge layer cyclic or non-reusable.

Only the three package exports listed above are public. Files below src/ are implementation details.

Protocol behavior

Bridge transports schedule delivery in process and avoid serialization or sockets. Closing one side propagates lifecycle events to its peer.

createServerFromClient delegates tools and, when advertised by capabilities, resources and prompts. It removes tool outputSchema declarations at the proxy boundary so an intermediary does not reject structured content that the origin server owns. toolCallTimeoutMs overrides the MCP SDK timeout for forwarded tool calls.

composeTransport reduces middleware from left to right: later wrappers become the outer layers for outgoing messages, and incoming messages traverse the reverse path.

Related documentation

• Studio repository overview
• Contribution guide
• Testing policy