MCP Fusion
AI-First DX for the Model Context Protocol.
MCP Fusion

MCP Fusion ​

The framework for AI-native MCP servers.
Type-safe tools, Presenters for LLM perception, governance lockfiles, and zero boilerplate.

npm versionDownloadsTypeScriptMCP StandardLicense

Documentation · Quick Start · API Reference

Quick Start ​

bash
npx fusion create my-server
cd my-server && fusion dev

14 files scaffolded in 6ms — file-based routing, Presenters, Prompts, middleware, Cursor integration, and tests. Ready to go.

The MVA Pattern ​

MCP Fusion separates three concerns that raw MCP servers mix into a single handler:

Model (Zod Schema) → View (Presenter) → Agent (LLM)
   validates            perceives          acts

The handler returns raw data. The Presenter shapes what the agent sees. The middleware governs access. Works with any MCP client — Cursor, Claude Desktop, Claude Code, Windsurf, Cline, VS Code + GitHub Copilot.

Why MCP Fusion ​

  • Fluent API — Semantic verbs (f.query, f.mutation, f.action) with type-chaining. Full IDE autocomplete in .handle() — zero manual interfaces.
  • Presenters — Egress firewall for LLMs. Zod-validated schemas strip undeclared fields in RAM. JIT system rules, server-rendered UI, cognitive guardrails, and HATEOAS-style next actions.
  • Zero-Trust Sandbox — V8 Isolate engine (isolated-vm). The LLM sends logic to your data instead of data to the LLM. Sealed execution — no process, require, fs, net.
  • File-Based Routing — Drop a file in src/tools/, it becomes a tool. No central import file, no merge conflicts.
  • Testing — In-memory pipeline testing without MCP transport. Schema validation, middleware, handler, presenter — all tested directly.
  • Governance — Capability lockfile (mcp-fusion.lock), contract diffing, HMAC attestation, semantic probing, entitlement scanning, blast radius analysis.
  • State Sync — RFC 7234-inspired cache-control for LLM agents. invalidates(), cached(), stale() — the agent knows whether its data is still valid.
  • Inspector — Real-time terminal dashboard via Shadow Socket (IPC). Zero stdio interference. Live tool registry, traffic log, X-RAY deep inspection, Late Guillotine token metrics.
  • tRPC-Style Client — Compile-time route validation with InferRouter<typeof registry>. Autocomplete for tool names, inputs, and responses.
  • Adapters — Deploy to Vercel, Cloudflare Workers, or plain Node.js.

Code Example ​

typescript
import { initFusion } from '@vinkius-core/mcp-fusion';

type AppContext = { db: PrismaClient; user: User };
const f = initFusion<AppContext>();

// Define a tool with one line
export default f.query('system.health')
    .describe('Returns server operational status')
    .returns(SystemPresenter)
    .handle(async (_, ctx) => ({
        status: 'healthy',
        uptime: process.uptime(),
        version: '1.0.0',
    }));
typescript
// Presenter — the egress firewall
const SystemPresenter = createPresenter('System')
    .schema({
        status:  t.enum('healthy', 'degraded', 'down'),
        uptime:  t.number.describe('Seconds since boot'),
        version: t.string,
    })
    .rules(['Version follows semver. Compare with latest to suggest updates.']);
typescript
// Self-healing errors — the LLM can recover
return f.error('NOT_FOUND', `Project "${input.id}" not found`)
    .suggest('Use projects.list to find valid IDs')
    .actions('projects.list', 'projects.search');

Full guide: mcp-fusion.vinkius.com/building-tools

Inspector — Real-Time Dashboard ​

bash
npx fusion inspect        # Auto-discover and connect
npx fusion inspect --demo  # Built-in simulator
┌──────────────────────────────────────────────────────────────┐
│  ● LIVE: PID 12345  │  RAM: [█████░░░] 28MB  │  UP: 01:23  │
├───────────────────────┬──────────────────────────────────────┤
│  TOOL LIST            │  X-RAY: billing.create_invoice       │
│  ✓ billing.create     │   LATE GUILLOTINE:                   │
│  ✓ billing.get        │    DB Raw  : 4.2KB                   │
│  ✗ users.delete       │    Wire    : 1.1KB                   │
│  ✓ system.health      │    SAVINGS : ████████░░ 73.8%        │
├───────────────────────┴──────────────────────────────────────┤
│  19:32:01  ROUTE  billing.create    │  19:32:01  EXEC  ✓ 45ms│
└──────────────────────────────────────────────────────────────┘

Connects via Shadow Socket (Named Pipe / Unix Domain Socket) — no stdio interference, no port conflicts.

Docs: mcp-fusion.vinkius.com/inspector

Ecosystem ​

Adapters ​

PackageTarget
mcp-fusion-vercelVercel Functions (Edge / Node.js)
mcp-fusion-cloudflareCloudflare Workers — zero polyfills

Generators & Connectors ​

PackageSource
mcp-fusion-openapi-genGenerate typed tools from OpenAPI 3.x specs
mcp-fusion-prisma-genGenerate CRUD tools from Prisma schemas
mcp-fusion-n8nAuto-discover n8n workflows as tools
mcp-fusion-awsAuto-discover AWS Lambda & Step Functions
mcp-fusion-oauthRFC 8628 Device Flow authentication
mcp-fusion-jwtJWT verification — HS256/RS256/ES256 + JWKS
mcp-fusion-api-keyAPI key validation with timing-safe comparison
mcp-fusion-testingIn-memory pipeline testing
mcp-fusion-inspectorReal-time terminal dashboard

Documentation ​

Full guides, API reference, and cookbook recipes:

mcp-fusion.vinkius.com

Contributing ​

See CONTRIBUTING.md for development setup and PR guidelines.

Security ​

See SECURITY.md for reporting vulnerabilities.

License ​

Apache 2.0