MCP Fusion
The framework for AI-native MCP servers. Type-safe tools, Presenters for LLM perception, governance lockfiles, and zero boilerplate.
Documentation · Quick Start · API Reference
Quick Start
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 — noprocess,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
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',
}));
// 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.']);
// 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
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.
Ecosystem
Adapters
| Package | Target |
|---|---|
| mcp-fusion-vercel | Vercel Functions (Edge / Node.js) |
| mcp-fusion-cloudflare | Cloudflare Workers — zero polyfills |
Generators & Connectors
| Package | Source |
|---|---|
| mcp-fusion-openapi-gen | Generate typed tools from OpenAPI 3.x specs |
| mcp-fusion-prisma-gen | Generate CRUD tools from Prisma schemas |
| mcp-fusion-n8n | Auto-discover n8n workflows as tools |
| mcp-fusion-aws | Auto-discover AWS Lambda & Step Functions |
| mcp-fusion-oauth | RFC 8628 Device Flow authentication |
| mcp-fusion-jwt | JWT verification — HS256/RS256/ES256 + JWKS |
| mcp-fusion-api-key | API key validation with timing-safe comparison |
| mcp-fusion-testing | In-memory pipeline testing |
| mcp-fusion-inspector | Real-time terminal dashboard |
Documentation
Full guides, API reference, and cookbook recipes:
Contributing
See CONTRIBUTING.md for development setup and PR guidelines.
Security
See SECURITY.md for reporting vulnerabilities.