@vinkius-core/mcp-fusion 3.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +161 -0
  2. package/package.json +148 -148
package/README.md ADDED
@@ -0,0 +1,161 @@
1
+ <div align="center">
2
+
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://site-assets.vinkius.com/vk/logo-v-black-square.png" width="80" height="80">
5
+ <img src="https://site-assets.vinkius.com/vk/logo-v-black-square.png" style="border-radius:8px;background:#000000;padding:10px;border:1px solid #414141;" width="80" height="80" alt="MCP Fusion">
6
+ </picture>
7
+
8
+ # MCP Fusion
9
+
10
+ **The framework for AI-native MCP servers.**<br>
11
+ Type-safe tools, Presenters for LLM perception, governance lockfiles, and zero boilerplate.
12
+
13
+ [![npm version](https://img.shields.io/npm/v/@vinkius-core/mcp-fusion.svg?color=0ea5e9)](https://www.npmjs.com/package/@vinkius-core/mcp-fusion)
14
+ [![Downloads](https://img.shields.io/npm/dw/@vinkius-core/mcp-fusion)](https://www.npmjs.com/package/@vinkius-core/mcp-fusion)
15
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
16
+ [![MCP Standard](https://img.shields.io/badge/MCP-Standard-purple)](https://modelcontextprotocol.io/)
17
+ [![License](https://img.shields.io/badge/License-Apache_2.0-green)](LICENSE)
18
+
19
+ [Documentation](https://mcp-fusion.vinkius.com/) · [Quick Start](https://mcp-fusion.vinkius.com/quickstart-lightspeed) · [API Reference](https://mcp-fusion.vinkius.com/api/)
20
+
21
+ </div>
22
+
23
+ ---
24
+
25
+ ## Quick Start
26
+
27
+ ```bash
28
+ npx fusion create my-server
29
+ cd my-server && npm run dev
30
+ ```
31
+
32
+ 14 files scaffolded in 6ms — file-based routing, Presenters, Prompts, middleware, Cursor integration, and tests. Ready to go.
33
+
34
+ ## The MVA Pattern
35
+
36
+ MCP Fusion separates three concerns that raw MCP servers mix into a single handler:
37
+
38
+ ```
39
+ Model (Zod Schema) → View (Presenter) → Agent (LLM)
40
+ validates perceives acts
41
+ ```
42
+
43
+ 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.
44
+
45
+ ## Why MCP Fusion
46
+
47
+ - **Fluent API** — Semantic verbs (`f.query`, `f.mutation`, `f.action`) with type-chaining. Full IDE autocomplete in `.handle()` — zero manual interfaces.
48
+ - **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.
49
+ - **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`.
50
+ - **File-Based Routing** — Drop a file in `src/tools/`, it becomes a tool. No central import file, no merge conflicts.
51
+ - **Testing** — In-memory pipeline testing without MCP transport. Schema validation, middleware, handler, presenter — all tested directly.
52
+ - **Governance** — Capability lockfile (`mcp-fusion.lock`), contract diffing, HMAC attestation, semantic probing, entitlement scanning, blast radius analysis.
53
+ - **State Sync** — RFC 7234-inspired cache-control for LLM agents. `invalidates()`, `cached()`, `stale()` — the agent knows whether its data is still valid.
54
+ - **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.
55
+ - **tRPC-Style Client** — Compile-time route validation with `InferRouter<typeof registry>`. Autocomplete for tool names, inputs, and responses.
56
+ - **Adapters** — Deploy to Vercel, Cloudflare Workers, or plain Node.js.
57
+
58
+ ## Code Example
59
+
60
+ ```typescript
61
+ import { initFusion } from '@vinkius-core/mcp-fusion';
62
+
63
+ type AppContext = { db: PrismaClient; user: User };
64
+ const f = initFusion<AppContext>();
65
+
66
+ // Define a tool with one line
67
+ export default f.query('system.health')
68
+ .describe('Returns server operational status')
69
+ .returns(SystemPresenter)
70
+ .handle(async (_, ctx) => ({
71
+ status: 'healthy',
72
+ uptime: process.uptime(),
73
+ version: '1.0.0',
74
+ }));
75
+ ```
76
+
77
+ ```typescript
78
+ // Presenter — the egress firewall
79
+ const SystemPresenter = createPresenter('System')
80
+ .schema({
81
+ status: t.enum('healthy', 'degraded', 'down'),
82
+ uptime: t.number.describe('Seconds since boot'),
83
+ version: t.string,
84
+ })
85
+ .rules(['Version follows semver. Compare with latest to suggest updates.']);
86
+ ```
87
+
88
+ ```typescript
89
+ // Self-healing errors — the LLM can recover
90
+ return f.error('NOT_FOUND', `Project "${input.id}" not found`)
91
+ .suggest('Use projects.list to find valid IDs')
92
+ .actions('projects.list', 'projects.search');
93
+ ```
94
+
95
+ > **Full guide**: [mcp-fusion.vinkius.com/building-tools](https://mcp-fusion.vinkius.com/building-tools)
96
+
97
+ ## Inspector — Real-Time Dashboard
98
+
99
+ ```bash
100
+ npx fusion inspect # Auto-discover and connect
101
+ npx fusion inspect --demo # Built-in simulator
102
+ ```
103
+
104
+ ```
105
+ ┌──────────────────────────────────────────────────────────────┐
106
+ │ ● LIVE: PID 12345 │ RAM: [█████░░░] 28MB │ UP: 01:23 │
107
+ ├───────────────────────┬──────────────────────────────────────┤
108
+ │ TOOL LIST │ X-RAY: billing.create_invoice │
109
+ │ ✓ billing.create │ LATE GUILLOTINE: │
110
+ │ ✓ billing.get │ DB Raw : 4.2KB │
111
+ │ ✗ users.delete │ Wire : 1.1KB │
112
+ │ ✓ system.health │ SAVINGS : ████████░░ 73.8% │
113
+ ├───────────────────────┴──────────────────────────────────────┤
114
+ │ 19:32:01 ROUTE billing.create │ 19:32:01 EXEC ✓ 45ms│
115
+ └──────────────────────────────────────────────────────────────┘
116
+ ```
117
+
118
+ Connects via **Shadow Socket** (Named Pipe / Unix Domain Socket) — no stdio interference, no port conflicts.
119
+
120
+ > **Docs**: [mcp-fusion.vinkius.com/inspector](https://mcp-fusion.vinkius.com/inspector)
121
+
122
+ ## Ecosystem
123
+
124
+ ### Adapters
125
+
126
+ | Package | Target |
127
+ |---|---|
128
+ | [`mcp-fusion-vercel`](https://mcp-fusion.vinkius.com/vercel-adapter) | Vercel Functions (Edge / Node.js) |
129
+ | [`mcp-fusion-cloudflare`](https://mcp-fusion.vinkius.com/cloudflare-adapter) | Cloudflare Workers — zero polyfills |
130
+
131
+ ### Generators & Connectors
132
+
133
+ | Package | Source |
134
+ |---|---|
135
+ | [`mcp-fusion-openapi-gen`](https://mcp-fusion.vinkius.com/openapi-gen) | Generate typed tools from OpenAPI 3.x specs |
136
+ | [`mcp-fusion-prisma-gen`](https://mcp-fusion.vinkius.com/prisma-gen) | Generate CRUD tools from Prisma schemas |
137
+ | [`mcp-fusion-n8n`](https://mcp-fusion.vinkius.com/n8n-connector) | Auto-discover n8n workflows as tools |
138
+ | [`mcp-fusion-aws`](https://mcp-fusion.vinkius.com/aws-connector) | Auto-discover AWS Lambda & Step Functions |
139
+ | [`mcp-fusion-oauth`](https://mcp-fusion.vinkius.com/oauth) | RFC 8628 Device Flow authentication |
140
+ | [`mcp-fusion-jwt`](https://mcp-fusion.vinkius.com/jwt) | JWT verification — HS256/RS256/ES256 + JWKS |
141
+ | [`mcp-fusion-api-key`](https://mcp-fusion.vinkius.com/api-key) | API key validation with timing-safe comparison |
142
+ | [`mcp-fusion-testing`](https://mcp-fusion.vinkius.com/testing) | In-memory pipeline testing |
143
+ | [`mcp-fusion-inspector`](https://mcp-fusion.vinkius.com/inspector) | Real-time terminal dashboard |
144
+
145
+ ## Documentation
146
+
147
+ Full guides, API reference, and cookbook recipes:
148
+
149
+ **[mcp-fusion.vinkius.com](https://mcp-fusion.vinkius.com/)**
150
+
151
+ ## Contributing
152
+
153
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines.
154
+
155
+ ## Security
156
+
157
+ See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
158
+
159
+ ## License
160
+
161
+ [Apache 2.0](LICENSE)
package/package.json CHANGED
@@ -1,148 +1,148 @@
1
- {
2
- "name": "@vinkius-core/mcp-fusion",
3
- "version": "3.0.0",
4
- "description": "MVA (Model-View-Agent) framework for the Model Context Protocol. Structured perception packages with Presenters, cognitive guardrails, self-healing errors, action consolidation, and tRPC-style type safety — so AI agents perceive and act on your data deterministically.",
5
- "type": "module",
6
- "main": "dist/index.js",
7
- "types": "dist/index.d.ts",
8
- "bin": {
9
- "fusion": "./dist/cli/fusion.js"
10
- },
11
- "exports": {
12
- ".": {
13
- "import": "./dist/index.js",
14
- "types": "./dist/index.d.ts"
15
- },
16
- "./client": {
17
- "import": "./dist/client/index.js",
18
- "types": "./dist/client/index.d.ts"
19
- },
20
- "./ui": {
21
- "import": "./dist/presenter/ui.js",
22
- "types": "./dist/presenter/ui.d.ts"
23
- },
24
- "./presenter": {
25
- "import": "./dist/presenter/index.js",
26
- "types": "./dist/presenter/index.d.ts"
27
- },
28
- "./prompt": {
29
- "import": "./dist/prompt/index.js",
30
- "types": "./dist/prompt/index.d.ts"
31
- },
32
- "./state-sync": {
33
- "import": "./dist/state-sync/index.js",
34
- "types": "./dist/state-sync/index.d.ts"
35
- },
36
- "./observability": {
37
- "import": "./dist/observability/index.js",
38
- "types": "./dist/observability/index.d.ts"
39
- },
40
- "./dev": {
41
- "import": "./dist/server/DevServer.js",
42
- "types": "./dist/server/DevServer.d.ts"
43
- },
44
- "./schema": {
45
- "import": "./dist/core/StandardSchema.js",
46
- "types": "./dist/core/StandardSchema.d.ts"
47
- },
48
- "./testing": {
49
- "import": "./dist/testing/MvaMetaSymbol.js",
50
- "types": "./dist/testing/MvaMetaSymbol.d.ts"
51
- },
52
- "./introspection": {
53
- "import": "./dist/introspection/index.js",
54
- "types": "./dist/introspection/index.d.ts"
55
- },
56
- "./sandbox": {
57
- "import": "./dist/sandbox/index.js",
58
- "types": "./dist/sandbox/index.d.ts"
59
- }
60
- },
61
- "scripts": {
62
- "build": "tsc",
63
- "lint": "eslint src/",
64
- "lint:fix": "eslint src/ --fix",
65
- "test": "vitest run",
66
- "test:coverage": "vitest run --coverage",
67
- "prepublishOnly": "npm run build"
68
- },
69
- "keywords": [
70
- "mcp",
71
- "model-context-protocol",
72
- "ai",
73
- "llm",
74
- "tools",
75
- "typescript",
76
- "framework",
77
- "middleware",
78
- "zod",
79
- "mva",
80
- "model-view-agent",
81
- "presenter",
82
- "guardrails",
83
- "agentic",
84
- "structured-data",
85
- "action-consolidation",
86
- "dlp",
87
- "compliance",
88
- "pii-redaction",
89
- "fsm",
90
- "state-machine",
91
- "anti-hallucination"
92
- ],
93
- "author": "Vinkius Labs",
94
- "repository": {
95
- "type": "git",
96
- "url": "git+https://github.com/vinkius-labs/mcp-fusion.git",
97
- "directory": "packages/core"
98
- },
99
- "bugs": {
100
- "url": "https://github.com/vinkius-labs/mcp-fusion/issues"
101
- },
102
- "homepage": "https://mcp-fusion.vinkius.com/",
103
- "files": [
104
- "dist",
105
- "README.md",
106
- "CHANGELOG.md",
107
- "LICENSE"
108
- ],
109
- "engines": {
110
- "node": ">=18.0.0"
111
- },
112
- "publishConfig": {
113
- "access": "public"
114
- },
115
- "dependencies": {
116
- "@toon-format/toon": "^2.1.0",
117
- "zod-to-json-schema": "^3.25.1"
118
- },
119
- "peerDependencies": {
120
- "@modelcontextprotocol/sdk": "^1.12.1",
121
- "fast-json-stringify": "^6.0.0",
122
- "fast-redact": "^3.0.0",
123
- "isolated-vm": "^5.0.4",
124
- "xstate": "^5.0.0",
125
- "zod": "^3.25.1 || ^4.0.0"
126
- },
127
- "peerDependenciesMeta": {
128
- "zod": {
129
- "optional": true
130
- },
131
- "isolated-vm": {
132
- "optional": true
133
- },
134
- "fast-json-stringify": {
135
- "optional": true
136
- },
137
- "fast-redact": {
138
- "optional": true
139
- },
140
- "xstate": {
141
- "optional": true
142
- }
143
- },
144
- "license": "Apache-2.0",
145
- "devDependencies": {
146
- "fast-redact": "^3.5.0"
147
- }
148
- }
1
+ {
2
+ "name": "@vinkius-core/mcp-fusion",
3
+ "version": "3.0.1",
4
+ "description": "MVA (Model-View-Agent) framework for the Model Context Protocol. Structured perception packages with Presenters, cognitive guardrails, self-healing errors, action consolidation, and tRPC-style type safety — so AI agents perceive and act on your data deterministically.",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "types": "dist/index.d.ts",
8
+ "bin": {
9
+ "fusion": "./dist/cli/fusion.js"
10
+ },
11
+ "exports": {
12
+ ".": {
13
+ "import": "./dist/index.js",
14
+ "types": "./dist/index.d.ts"
15
+ },
16
+ "./client": {
17
+ "import": "./dist/client/index.js",
18
+ "types": "./dist/client/index.d.ts"
19
+ },
20
+ "./ui": {
21
+ "import": "./dist/presenter/ui.js",
22
+ "types": "./dist/presenter/ui.d.ts"
23
+ },
24
+ "./presenter": {
25
+ "import": "./dist/presenter/index.js",
26
+ "types": "./dist/presenter/index.d.ts"
27
+ },
28
+ "./prompt": {
29
+ "import": "./dist/prompt/index.js",
30
+ "types": "./dist/prompt/index.d.ts"
31
+ },
32
+ "./state-sync": {
33
+ "import": "./dist/state-sync/index.js",
34
+ "types": "./dist/state-sync/index.d.ts"
35
+ },
36
+ "./observability": {
37
+ "import": "./dist/observability/index.js",
38
+ "types": "./dist/observability/index.d.ts"
39
+ },
40
+ "./dev": {
41
+ "import": "./dist/server/DevServer.js",
42
+ "types": "./dist/server/DevServer.d.ts"
43
+ },
44
+ "./schema": {
45
+ "import": "./dist/core/StandardSchema.js",
46
+ "types": "./dist/core/StandardSchema.d.ts"
47
+ },
48
+ "./testing": {
49
+ "import": "./dist/testing/MvaMetaSymbol.js",
50
+ "types": "./dist/testing/MvaMetaSymbol.d.ts"
51
+ },
52
+ "./introspection": {
53
+ "import": "./dist/introspection/index.js",
54
+ "types": "./dist/introspection/index.d.ts"
55
+ },
56
+ "./sandbox": {
57
+ "import": "./dist/sandbox/index.js",
58
+ "types": "./dist/sandbox/index.d.ts"
59
+ }
60
+ },
61
+ "scripts": {
62
+ "build": "tsc",
63
+ "lint": "eslint src/",
64
+ "lint:fix": "eslint src/ --fix",
65
+ "test": "vitest run",
66
+ "test:coverage": "vitest run --coverage",
67
+ "prepublishOnly": "npm run build"
68
+ },
69
+ "keywords": [
70
+ "mcp",
71
+ "model-context-protocol",
72
+ "ai",
73
+ "llm",
74
+ "tools",
75
+ "typescript",
76
+ "framework",
77
+ "middleware",
78
+ "zod",
79
+ "mva",
80
+ "model-view-agent",
81
+ "presenter",
82
+ "guardrails",
83
+ "agentic",
84
+ "structured-data",
85
+ "action-consolidation",
86
+ "dlp",
87
+ "compliance",
88
+ "pii-redaction",
89
+ "fsm",
90
+ "state-machine",
91
+ "anti-hallucination"
92
+ ],
93
+ "author": "Vinkius Labs",
94
+ "repository": {
95
+ "type": "git",
96
+ "url": "git+https://github.com/vinkius-labs/mcp-fusion.git",
97
+ "directory": "packages/core"
98
+ },
99
+ "bugs": {
100
+ "url": "https://github.com/vinkius-labs/mcp-fusion/issues"
101
+ },
102
+ "homepage": "https://mcp-fusion.vinkius.com/",
103
+ "files": [
104
+ "dist",
105
+ "README.md",
106
+ "CHANGELOG.md",
107
+ "LICENSE"
108
+ ],
109
+ "engines": {
110
+ "node": ">=18.0.0"
111
+ },
112
+ "publishConfig": {
113
+ "access": "public"
114
+ },
115
+ "dependencies": {
116
+ "@toon-format/toon": "^2.1.0",
117
+ "zod-to-json-schema": "^3.25.1"
118
+ },
119
+ "peerDependencies": {
120
+ "@modelcontextprotocol/sdk": "^1.12.1",
121
+ "fast-json-stringify": "^6.0.0",
122
+ "fast-redact": "^3.0.0",
123
+ "isolated-vm": "^5.0.4",
124
+ "xstate": "^5.0.0",
125
+ "zod": "^3.25.1 || ^4.0.0"
126
+ },
127
+ "peerDependenciesMeta": {
128
+ "zod": {
129
+ "optional": true
130
+ },
131
+ "isolated-vm": {
132
+ "optional": true
133
+ },
134
+ "fast-json-stringify": {
135
+ "optional": true
136
+ },
137
+ "fast-redact": {
138
+ "optional": true
139
+ },
140
+ "xstate": {
141
+ "optional": true
142
+ }
143
+ },
144
+ "license": "Apache-2.0",
145
+ "devDependencies": {
146
+ "fast-redact": "^3.5.0"
147
+ }
148
+ }