ContextFabricator

Overview

ContextFabricator functions as a sophisticated intermediary layer, aggregating several independent Model Context Protocol (MCP) service instances beneath a unified interface. This architecture enables leveraging a single client-facing address while achieving near-limitless horizontal scaling of the backend MCP infrastructure.

Initially structured as a command-line interface (CLI) utility, ContextFabricator is targeted for evolution into a comprehensive proxy solution for advanced AI endpoints—serving the role for modern LLMs that Nginx plays for traditional web applications.

Rationale for ContextFabricator

Without ContextFabricator: ┌─────────┐ ┌─────────┐ │ Consumer│────▶│MCP Node A│ │ Client │ │ Server │ └─────────┘ └─────────┘ │ │ ┌─────────┐ └──────────▶│MCP Node B│ │ Server │ └─────────┘

With ContextFabricator: ┌─────────┐ ┌───────────┐ ┌─────────┐ │ Consumer│────▶│ContextFab │────▶│MCP Node A│ │ Client │ │ │ │ Server │ └─────────┘ └───────────┘ └─────────┘ │ │ ┌─────────┐ └─────────▶│MCP Node B│ │ Server │ └─────────┘

ContextFabricator addresses critical operational needs:

• Unifying access to multiple MCP endpoints via a single gateway address.
• Implementing intelligent traffic distribution (load balancing) among backend servers.
• Establishing a consolidated ingress point for consuming applications.

Deployment Instructions

bash

Obtain necessary dependencies

bun install

Compile the source code into a standalone binary

bun build src/index.ts --compile --outfile contextfabricator

Containerization

ContextFabricator images are published on Docker Hub: your-repo/contextfabricator.

bash docker pull your-repo/contextfabricator

Standard operational mode

docker run -p 3001:3001 your-repo/contextfabricator http://mcp-a.internal http://mcp-b.internal

Specifying binding interface and port

docker run -p 4000:4000 your-repo/contextfabricator --listen-host 0.0.0.0 --listen-port 4000 http://mcp-a.internal

Operational Usage

Standard invocation:

bash ./contextfabricator ...

With configuration flags:

bash ./contextfabricator --listen-host 127.0.0.1 --listen-port 8080 http://backend1.svc http://backend2.svc

Utilizing a configuration manifest:

bash ./contextfabricator --manifest settings.json

Parameterization

• --listen-host <address>: The network interface IP address for the proxy listener (Default: localhost).
• --listen-port <number>: The TCP port the proxy listens on (Default: 3001).
• --manifest <path>: Path to the primary configuration file (Default: settings.json).
• --protocol-version <version>: The mandated MCP version negotiated with backends (Default: 1.0.0).
• --service-label <moniker>: Internal identifier for the aggregated service (Default: contextfabricator).
• --help: Display command-line assistance.

Configuration Structure

ContextFabricator accepts configuration via a JSON manifest file. Consult settings.example.json for the schema:

{ "service_name": "contextfabricator", "version": "1.0.0", "description": "An aggregated MCP gateway.", "backends": { "test-streamer": { "uri": "http://10.0.0.5:3000/stream", "label": "streamer-node", "schema_version": "1.0.0", "notes": "Primary high-throughput backend" } } }

An included demonstration backend server can be launched for verification:

bash

Activate the example backend server first

bun run start:demo-server

Then launch ContextFabricator targeting it via the manifest

./contextfabricator --manifest settings.json

Operational Scenarios

Initiate ContextFabricator using only positional backend addresses:

bash ./contextfabricator http://remote-mcp-node-a http://remote-mcp-node-b

Bind to a specific interface and port while listing backends:

bash ./contextfabricator --listen-host 0.0.0.0 --listen-port 9000 http://mcp-pool-1 http://mcp-pool-2

Validation Suite Execution

To execute the full test suite:

bash bun test

To isolate and run only end-to-end validation tests:

bash bun run test:e2e

End-to-End Checks

The E2E suite confirms that ContextFabricator successfully:

1. Establishes connectivity to the target MCP instance(s).
2. Transparently forwards capability declarations received from the backend.
3. Routes client requests correctly to the designated backend server(s) and returns the resulting data stream.

Detailed specifications of the testing harness are available in [test/MANIFESTO.md].

Continuous Integration pipelines automatically invoke these validation steps upon repository events.

Roadmap for Expansion

Future enhancements include:

• Dashboard interface for real-time operational visibility.
• Sophisticated, configurable routing algorithms beyond basic round-robin.
• Automated status probing and failure detection for backend nodes.
• Integration of authorization layers and access governance.
• A modular extension framework for custom data transformations.

Development Environment

Tooling and Style Adherence

This repository leverages:

• TypeScript language compiled via the Bun runtime environment.
• ESLint, configured with strict rules tailored for TypeScript projects, ensuring code quality.
• Prettier for consistent code aesthetics and automatic formatting.

The project configuration is finely tuned for optimal performance within the Bun ecosystem.

Execute these commands for development workflow management:

bash

Apply formatting rules globally

bun run fmt

Verify adherence to formatting standards without modification

bun run fmt:check

Run static analysis via ESLint

bun run check:style

Attempt automated correction of style violations

bun run fix:style

VS Code integration is established to trigger Prettier on save events and display immediate ESLint feedback upon installation of recommended extensions.

Community Contributions

We welcome external input! Please submit detailed issues or propose enhancements via pull requests.