@vinkius-core/mcp-fusion 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.6.0] - 2026-02-23
+
+### 🔗 MVA-Driven Prompts — `PromptMessage.fromView()`
+
+Bridge the Presenter layer into the Prompt Engine with zero duplication. `PromptMessage.fromView()` decomposes a `ResponseBuilder` into XML-tagged prompt messages (`<domain_rules>`, `<dataset>`, `<visual_context>`, `<system_guidance>`) — same source of truth as the Tool response.
+
+### Added
+
+- **`PromptMessage.fromView(builder)`:** Static method that decomposes a `ResponseBuilder` into `PromptMessagePayload[]`. Extracts rules, validated data, UI blocks, hints, and action suggestions into semantically separated XML-tagged blocks optimized for frontier LLMs.
+- **`ResponseBuilder` introspection getters:** `getData()`, `getRules()`, `getUiBlocks()`, `getHints()`, `getSuggestions()` — read-only access to internal layers without calling `.build()`.
+
+### Documentation
+
+- **`prompts.md`:** New H2 section "MVA-Driven Prompts — `fromView()`" with Before/After comparison, decomposition architecture diagram, XML tag table, composability example.
+- **`presenter.md`:** New section "Using Presenters in Prompts" with cross-reference to Prompt Engine docs. Added Prompt Engine link to Next Steps.
+- **`api-reference.md`:** New Prompt Engine section with `definePrompt`, `PromptMessage` (all methods), `PromptMessage.fromView()` decomposition table, `PromptRegistry` methods, and Prompt types.
+- **VitePress sidebar:** Prompts section expanded from 1 to 5 items. Reference section expanded from 1 to 12 anchor-linked entries.
+- **README.md:** Complete rewrite — engineering-focused documentation matching Prisma/tRPC style. Every section: 1-line technical description + code + output.
+- **llms.txt:** Prompt Engine and MVA-Driven Prompts sections with examples. Public API expanded with 11 Prompt entries and 5 Prompt types.
+
+### Test Suite
+
+- **14 new tests** in `PromptMessageFromView.test.ts` covering rules decomposition, data extraction (JSON fencing), UI blocks, hints, suggestions, full composition, Presenter integration, and edge cases.
+- **Test count:** 1,356 tests across 61 files, all passing.
+
+## [1.5.0] - 2026-02-23
+
+### 💬 Prompt Engine — 100% MCP Spec Compliance
+
+Full implementation of MCP `prompts/list` and `prompts/get` handlers with `definePrompt()`, `PromptMessage`, `PromptRegistry`, schema-informed coercion, middleware, tag-based filtering, and lifecycle sync (`notifications/prompts/list_changed`).
+
+### Added
+
+- **`definePrompt(name, config)`:** JSON-first prompt builder with flat schema constraint (primitives only — string, number, boolean, enum).
+- **`PromptMessage`:** Factory methods — `.system()`, `.user()`, `.assistant()`, `.image()`, `.audio()`, `.resource()`.
+- **`PromptRegistry<TContext>`:** Registration, tag-based RBAC filtering, `routeGet()` handler routing, `notifyChanged()` lifecycle sync, `attachToServer()`.
+- **Schema-informed coercion:** Automatic string → number/boolean conversion based on declared schema types.
+- **Flat schema constraint enforcement:** Nested objects/arrays rejected at definition time with actionable errors.
+- **Middleware support:** Same `defineMiddleware()` chain as Tools — auth, RBAC, context derivation.
 
 ## [1.4.0] - 2026-02-23
 

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1>⚡️ mcp-fusion</h1>
-  <p><b>The first framework for building MCP servers that agents actually understand.</b></p>
-  <p>Not another SDK wrapper. A fundamentally new architecture for the Model Context Protocol.</p>
+  <p><b>The MVA (Model-View-Agent) framework for the Model Context Protocol.</b></p>
+  <p>Structured perception for AI agents — validated data, domain rules, UI blocks, and action affordances in every response.</p>
   
   [![npm version](https://img.shields.io/npm/v/@vinkius-core/mcp-fusion.svg?style=flat-square&color=0ea5e9)](https://www.npmjs.com/package/@vinkius-core/mcp-fusion)
   [![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue.svg?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
@@ -11,148 +11,35 @@
 
 <br/>
 
-**[📖 Documentation & Guides](https://vinkius-labs.github.io/mcp-fusion/)** · **[💰 Cost & Hallucination](https://vinkius-labs.github.io/mcp-fusion/cost-and-hallucination)** · **[🍳 Cookbook & Examples](https://vinkius-labs.github.io/mcp-fusion/examples)**
+**[Documentation](https://vinkius-labs.github.io/mcp-fusion/)** · **[API Reference](https://vinkius-labs.github.io/mcp-fusion/api-reference)** · **[Examples](https://vinkius-labs.github.io/mcp-fusion/examples)**
 
-<br/>
-
-## The Problem: Every MCP Server Today Is Built Wrong
-
-Look at any MCP server on GitHub. They all look like this:
-
-```typescript
-// ❌ What every MCP server looks like today
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
-
-    switch (name) {
-        case 'get_invoice':
-            const invoice = await db.invoices.findUnique(args.id);
-            return { content: [{ type: 'text', text: JSON.stringify(invoice) }] };
-        //                                          ↑ Raw JSON. The AI has no idea
-        //                                            that amount_cents is in cents,
-        //                                            what actions are available next,
-        //                                            or which fields are sensitive.
-        case 'list_invoices':
-            // ...50 more cases
-    }
-});
+```bash
+npm install @vinkius-core/mcp-fusion zod
 ```
 
-**This is the state of the art in 2025.** Raw JSON output. Manual switch/case routing. No validation. No domain context. No guardrails. The AI sees `{ amount_cents: 45000 }` and guesses — often wrong — whether it's dollars, cents, or yen.
-
-The result:
-- 🎯 **Parameter hallucination** — The AI invents field names that don't exist
-- 💀 **Data misinterpretation** — `45000` cents displayed as $45,000 instead of $450
-- 🔀 **Action blindness** — The AI doesn't know what to do next, so it hallucinates tool names
-- 🔓 **No security** — Internal fields leak to the LLM context
-
 ---
 
-<div align="center">
-
-### 🧠 The Revolution: MVA (Model-View-Agent)
-
-**MVC was designed for humans. Agents are not humans.**
+## Overview
 
-The AI industry builds agents on MVC, REST, and patterns made for browsers.<br/>
-None of them were designed for an autonomous consumer that **hallucinates when given ambiguous data.**
-
-**mcp-fusion** introduces **MVA** — a foundational architecture where the<br/>**Presenter** replaces the human-centric View with an **agent-centric perception layer.**
-
-</div>
+mcp-fusion introduces the **MVA (Model-View-Agent)** pattern — a Presenter layer between your data and the AI agent. Instead of passing raw JSON through `JSON.stringify()`, every response is a **structured perception package**: validated data, domain rules, rendered charts, action affordances, and cognitive guardrails.
 
 ```text
-┌──────────────────────────────────────────────────────────┐
-│              ⚡ Model-View-Agent (MVA)                    │
-├──────────────────────────────────────────────────────────┤
-│                                                          │
-│    Model              →   View             →   Agent     │
-│    Zod Schema             Presenter            LLM       │
-│    (validates)            (perceives)          (acts)     │
-│                                                          │
-│    ┌────────────────────────────────────────────────┐     │
-│    │  📄 Validated Data                            │     │
-│    │  📋 Domain Rules — "CENTS. Divide by 100."    │     │
-│    │  📊 UI Blocks — ECharts, Mermaid, Summaries   │     │
-│    │  🔗 Action Hints — "→ billing.pay"            │     │
-│    │  ⚠️  Guardrails — "50 shown, 250 hidden."     │     │
-│    └────────────────────────────────────────────────┘     │
-│              ▲ Structured Perception Package              │
-└──────────────────────────────────────────────────────────┘
-```
-
-<div align="center">
-
-> **Every response is a structured perception package — not raw JSON.**<br/>
-> The AI doesn't guess. It *knows*.
-
-📖 **[Read the full MVA Pattern Guide →](https://vinkius-labs.github.io/mcp-fusion/mva-pattern)**
-
-</div>
-
-### Without MVA vs With MVA
-
-| | Without MVA | With MVA (mcp-fusion) |
-|---|---|---|
-| **Tool count** | 50 registered tools. LLM sees ALL. Token explosion. | **Action consolidation** — 5,000+ ops in ONE tool via `module.action` discriminator. 10x fewer tokens. |
-| **Response** | `JSON.stringify(data)` — the AI guesses | **Structured perception package** — data + rules + UI + affordances |
-| **Domain context** | None. `45000` — dollars? cents? yen? | **System rules**: *"amount_cents is in CENTS. Divide by 100."* |
-| **Next actions** | AI hallucinates tool names | **Agentic HATEOAS** — `.suggestActions()` with explicit hints |
-| **Large datasets** | 10,000 rows dump into context | **Cognitive guardrails** — `.agentLimit(50)` + filter guidance |
-| **Security** | Internal fields leak to LLM | **Schema as boundary** — Zod `.strict()` rejects undeclared fields with actionable errors |
-| **Charts** | Not possible | **UI Blocks** — `.uiBlocks()` — ECharts, Mermaid, summaries |
-| **Routing** | `switch/case` × 50 branches | **Hierarchical groups** — `platform.users.list` — infinite nesting |
-| **Error recovery** | `throw Error` — AI gives up | **Self-healing** — `toolError()` + **Agentic Error Presenter** — auto-formatted validation/routing errors with coaching prompts |
-| **Token cost** | Full JSON payloads every time | **TOON encoding** — ~40% fewer tokens |
-| **Type safety** | Manual casting, no client types | **tRPC-style client** — `createFusionClient()` with full inference |
-| **Reusability** | Same entity rendered differently everywhere | **Presenter** — define once, reuse across all tools |
-
-📖 **[See the full side-by-side comparison with code examples →](https://vinkius-labs.github.io/mcp-fusion/comparison)**
-
----
-
-## What It Looks Like in Code
-
-```typescript
-// ✅ The mcp-fusion way — your handler returns raw data. That's it.
-const billing = defineTool<AppContext>('billing', {
-    actions: {
-        get_invoice: {
-            returns: InvoicePresenter,     // ← The AI will UNDERSTAND this data
-            params: { id: 'string' },
-            handler: async (ctx, args) => {
-                return await ctx.db.invoices.findUnique({ where: { id: args.id } });
-                // Raw data → Presenter validates, renders, guides — automatically
-            },
-        },
-    },
-});
+Model (Zod Schema) → View (Presenter) → Agent (LLM)
+   validates            perceives          acts
 ```
 
-The **Presenter** automatically:
-- ✅ **Validates** data through Zod (rejects unknown fields with actionable errors, validates shapes)
-- ✅ **Injects domain rules** — "amount_cents is in CENTS. Divide by 100."
-- ✅ **Renders charts** — Server-side ECharts, Mermaid diagrams
-- ✅ **Suggests next actions** — "→ billing.pay: Process payment"
-- ✅ **Truncates intelligently** — "50 shown, 250 hidden. Use filters."
-
-No switch/case. No manual JSON.stringify. No praying.
-
-```bash
-npm install @vinkius-core/mcp-fusion zod
-```
+The Presenter is defined once per domain entity. Every tool that returns that entity uses the same Presenter. The agent receives consistent, validated, contextually-rich data across your entire API surface.
 
 ---
 
-## The Presenter: Your Agent's Perception Layer
+## Presenter
 
-The Presenter is domain-level, not tool-level. Define `InvoicePresenter` once — every tool that returns invoices uses it. Consistent perception. Zero hallucination.
+The View layer in MVA. Defines how an entity is perceived by the agent — schema validation, system rules, UI blocks, cognitive guardrails, and action affordances.
 
 ```typescript
-import { createPresenter, ui, defineTool } from '@vinkius-core/mcp-fusion';
+import { createPresenter, ui } from '@vinkius-core/mcp-fusion';
 import { z } from 'zod';
 
-// ── Define the Presenter (MVA View Layer) ──
 export const InvoicePresenter = createPresenter('Invoice')
     .schema(z.object({
         id: z.string(),
@@ -162,7 +49,7 @@ export const InvoicePresenter = createPresenter('Invoice')
     .systemRules((invoice, ctx) => [
         'CRITICAL: amount_cents is in CENTS. Divide by 100 before display.',
         ctx?.user?.role !== 'admin'
-            ? 'RESTRICTED: Mask totals for non-admin users.'
+            ? 'RESTRICTED: Do not reveal exact totals to non-admin users.'
             : null,
     ])
     .uiBlocks((invoice) => [
@@ -171,7 +58,7 @@ export const InvoicePresenter = createPresenter('Invoice')
         }),
     ])
     .agentLimit(50, (omitted) =>
-        ui.summary(`⚠️ 50 shown, ${omitted} hidden. Use filters.`)
+        ui.summary(`⚠️ 50 shown, ${omitted} hidden. Use status or date_range filters.`)
     )
     .suggestActions((invoice) =>
         invoice.status === 'pending'
@@ -180,110 +67,104 @@ export const InvoicePresenter = createPresenter('Invoice')
     );
 ```
 
-The agent receives a complete perception package:
+The agent receives:
 
 ```text
-📄 DATA       → Validated, sensitive fields stripped
+📄 DATA       → Validated through Zod .strict() — undeclared fields rejected
 📋 RULES      → "amount_cents is in CENTS. Divide by 100."
 📊 UI BLOCKS  → ECharts gauge rendered server-side
 ⚠️ GUARDRAIL  → "50 shown, 250 hidden. Use filters."
-🔗 HINTS      → "→ billing.pay: Process payment"
+🔗 AFFORDANCE → "→ billing.pay: Process payment"
 ```
 
-### Pipeline Integration — Zero Boilerplate
-
-Attach the Presenter to any action. The handler returns raw data. The framework handles everything.
+Presenters compose via `.embed()` — child Presenter rules, UI blocks, and suggestions merge automatically:
 
 ```typescript
-const billing = defineTool<AppContext>('billing', {
-    actions: {
-        get_invoice: {
-            returns: InvoicePresenter,  // ← MVA View Layer
-            params: { id: 'string' },
-            handler: async (ctx, args) => {
-                return await ctx.db.invoices.findUnique({
-                    where: { id: args.id },
-                    include: { client: true },
-                });
-                // Raw data → Presenter validates, renders, suggests — automatically
-            },
-        },
-    },
-});
-```
-
-### Presenter Composition
-
-Real data has relationships. `.embed()` composes child Presenters for nested data — rules and UI blocks merge automatically.
-
-```typescript
-const ClientPresenter = createPresenter('Client')
-    .schema(clientSchema)
-    .systemRules(['Display company name prominently.']);
-
 const InvoicePresenter = createPresenter('Invoice')
     .schema(invoiceSchema)
-    .embed('client', ClientPresenter);  // ← nested composition
+    .embed('client', ClientPresenter)
+    .embed('payment_method', PaymentMethodPresenter);
 ```
 
 ---
 
-## Action Consolidation: One Tool, Not Fifty
+## Tool Definition
+
+Two APIs, identical output. `defineTool()` uses JSON shorthand (no Zod imports). `createTool()` uses full Zod schemas.
 
-Standard MCP servers expose individual tools per operation. 50 tools = 50 schemas burning tokens. mcp-fusion consolidates related operations behind a discriminator field.
+### `defineTool()` — JSON-First
 
 ```typescript
-const projects = defineTool<AppContext>('projects', {
-    description: 'Manage workspace projects',
+import { defineTool } from '@vinkius-core/mcp-fusion';
+
+const billing = defineTool<AppContext>('billing', {
+    description: 'Billing operations',
     shared: { workspace_id: 'string' },
     actions: {
-        list: {
+        get_invoice: {
             readOnly: true,
-            returns: ProjectPresenter,
-            handler: async (ctx, args) => await ctx.db.projects.findMany(),
+            returns: InvoicePresenter,
+            params: { id: 'string' },
+            handler: async (ctx, args) =>
+                await ctx.db.invoices.findUnique({ where: { id: args.id } }),
         },
-        create: {
-            params: { name: { type: 'string', min: 1 } },
-            handler: async (ctx, args) => await ctx.db.projects.create(args),
+        create_invoice: {
+            params: {
+                client_id: 'string',
+                amount: { type: 'number', min: 0 },
+                currency: { enum: ['USD', 'EUR', 'BRL'] as const },
+            },
+            handler: async (ctx, args) =>
+                await ctx.db.invoices.create({ data: args }),
         },
-        delete: {
+        void_invoice: {
             destructive: true,
-            params: { project_id: 'string' },
+            params: { id: 'string', reason: { type: 'string', optional: true } },
             handler: async (ctx, args) => {
-                await ctx.db.projects.delete(args.project_id);
-                return 'Deleted';
+                await ctx.db.invoices.void(args.id);
+                return 'Invoice voided';
             },
         },
     },
 });
 ```
 
-The LLM sees one perfectly structured tool:
-```text
-Action: list | create | delete
-- 'list': Requires: workspace_id. For: list
-- 'create': Requires: workspace_id, name. For: create
-- 'delete': Requires: workspace_id, project_id ⚠️ DESTRUCTIVE
+### `createTool()` — Full Zod
+
+```typescript
+import { createTool } from '@vinkius-core/mcp-fusion';
+
+const billing = createTool<AppContext>('billing')
+    .description('Billing operations')
+    .commonSchema(z.object({ workspace_id: z.string() }))
+    .action({
+        name: 'get_invoice',
+        readOnly: true,
+        returns: InvoicePresenter,
+        schema: z.object({ id: z.string() }),
+        handler: async (ctx, args) =>
+            await ctx.db.invoices.findUnique({ where: { id: args.id } }),
+    });
 ```
 
-### Two APIs — One Framework
+### Action Consolidation
 
-| Feature | `defineTool()` | `createTool()` |
-|---|---|---|
-| **Syntax** | Declarative config object | Fluent builder chain |
-| **Zod needed?** | No (auto-converts) | Yes |
-| **Best for** | Rapid prototyping | Complex validation |
+Multiple actions register as a single MCP tool with a discriminator field. The agent sees one well-structured tool instead of 50 individual registrations:
 
-Both produce identical MCP tools. Mix and match freely.
+```text
+billing — Billing operations
+  Action: get_invoice | create_invoice | void_invoice
+  - 'get_invoice': Requires: workspace_id, id. READ-ONLY
+  - 'create_invoice': Requires: workspace_id, client_id, amount, currency
+  - 'void_invoice': Requires: workspace_id, id ⚠️ DESTRUCTIVE
+```
 
----
+### Hierarchical Groups
 
-## Enterprise Engineering Core
+For large APIs (5,000+ operations), nest actions into groups:
 
-### Hierarchical Groups — 5,000+ Actions
 ```typescript
-new GroupedToolBuilder<AppContext>('platform')
-    .tags('core')
+createTool<AppContext>('platform')
     .group('users', 'User management', g => {
         g.use(requireAdmin)
          .action({ name: 'list', readOnly: true, handler: listUsers })
@@ -292,134 +173,229 @@ new GroupedToolBuilder<AppContext>('platform')
     .group('billing', 'Billing operations', g => {
         g.action({ name: 'refund', destructive: true, schema: refundSchema, handler: issueRefund });
     });
-// Discriminator: users.list | users.ban | billing.refund
+// Discriminator values: users.list | users.ban | billing.refund
 ```
 
-### Context Derivation — `defineMiddleware()`
-tRPC-style middleware that derives typed data into context:
+---
+
+## Prompt Engine
+
+Full MCP `prompts/list` + `prompts/get` implementation. Prompt arguments are **flat primitives only** (string, number, boolean, enum) — MCP clients render them as forms.
+
+```typescript
+import { definePrompt, PromptMessage } from '@vinkius-core/mcp-fusion';
+
+const AuditPrompt = definePrompt<AppContext>('financial_audit', {
+    title: 'Financial Audit',
+    description: 'Run a compliance audit on an invoice.',
+    args: {
+        invoiceId: 'string',
+        depth: { enum: ['quick', 'thorough'] as const },
+    } as const,
+    middleware: [requireAuth, requireRole('auditor')],
+    handler: async (ctx, { invoiceId, depth }) => {
+        const invoice = await ctx.db.invoices.get(invoiceId);
+
+        return {
+            messages: [
+                PromptMessage.system('You are a Senior Financial Auditor.'),
+                ...PromptMessage.fromView(InvoicePresenter.make(invoice, ctx)),
+                PromptMessage.user(`Perform a ${depth} audit on this invoice.`),
+            ],
+        };
+    },
+});
+```
+
+### `PromptMessage.fromView()`
+
+Decomposes a `ResponseBuilder` (from `Presenter.make()`) into XML-tagged prompt messages. Rules, data, UI blocks, and action suggestions from the Presenter are extracted into semantically separated blocks — same source of truth as the Tool response, zero duplication:
+
+```text
+Presenter.make(data, ctx) → ResponseBuilder
+    │
+    ├─ <domain_rules>    → system role  │ Presenter's systemRules()
+    ├─ <dataset>         → user role    │ Validated JSON
+    ├─ <visual_context>  → user role    │ UI blocks (ECharts, Mermaid, tables)
+    └─ <system_guidance> → system role  │ Hints + HATEOAS action suggestions
+```
+
+---
+
+## Middleware
+
+tRPC-style context derivation with pre-compiled chains:
+
 ```typescript
 import { defineMiddleware } from '@vinkius-core/mcp-fusion';
 
 const requireAuth = defineMiddleware(async (ctx: { token: string }) => {
     const user = await db.getUser(ctx.token);
     if (!user) throw new Error('Unauthorized');
-    return { user };  // ← TS infers: { user: User }
+    return { user };  // ← merged into ctx, TS infers { user: User }
+});
+
+// Apply globally or per-action
+defineTool<AppContext>('projects', {
+    middleware: [requireAuth, requireRole('editor')],
+    actions: { ... },
 });
 ```
 
-### Self-Healing Errors — `toolError()`
-Structured recovery for autonomous agents:
+---
+
+## Error Handling
+
+Structured errors with recovery instructions. The agent receives the error code, a suggestion, and a list of valid actions to try:
+
 ```typescript
+import { toolError } from '@vinkius-core/mcp-fusion';
+
 return toolError('ProjectNotFound', {
     message: `Project '${id}' does not exist.`,
     suggestion: 'Call projects.list first to get valid IDs.',
     availableActions: ['projects.list'],
 });
-// Output: [ProjectNotFound] Project 'xyz' does not exist.
-//         💡 Suggestion: Call projects.list first.
-//         📋 Try: projects.list
 ```
 
-### Streaming Progress — `progress()`
-```typescript
-handler: async function* (ctx, args) {
-    yield progress(10, 'Cloning repository...');
-    yield progress(50, 'Building AST...');
-    yield progress(90, 'Almost done...');
-    return success('Deployed successfully');
-}
+```text
+[ProjectNotFound] Project 'xyz' does not exist.
+💡 Suggestion: Call projects.list first to get valid IDs.
+📋 Try: projects.list
 ```
 
-### Type-Safe Client — `createFusionClient()`
-End-to-end type safety from server to client:
+---
+
+## Type-Safe Client
+
+End-to-end type inference from server to client — autocomplete for action names and typed arguments:
+
 ```typescript
 import { createFusionClient } from '@vinkius-core/mcp-fusion/client';
-import type { AppRouter } from './mcp-server';
+import type { AppRouter } from './server';
 
 const client = createFusionClient<AppRouter>(transport);
-const result = await client.execute('projects.create', { name: 'Vinkius V2' });
-//                                   ^^^^^^^^^^^^^^^^    ^^^^^^^^^^^^^^^^^
-//                                   autocomplete!       typed args!
+const result = await client.execute('billing.get_invoice', { workspace_id: 'ws_1', id: 'inv_42' });
+//                                   ^^^^^^^^^^^^^^^^^^^^    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+//                                   autocomplete            typed args
 ```
 
-### State Sync — Temporal Awareness
-RFC 7234-inspired cache-control signals prevent agents from using stale data:
+---
+
+## Registry & Server Integration
+
 ```typescript
-registry.attachToServer(server, {
-    stateSync: {
+import { ToolRegistry, PromptRegistry } from '@vinkius-core/mcp-fusion';
+
+const tools = new ToolRegistry<AppContext>();
+tools.register(billing);
+tools.register(projects);
+
+const prompts = new PromptRegistry<AppContext>();
+prompts.register(AuditPrompt);
+prompts.register(SummarizePrompt);
+
+// Attach to MCP server (works with Server and McpServer — duck-typed)
+tools.attachToServer(server, {
+    contextFactory: (extra) => createAppContext(extra),
+    filter: { tags: ['public'] },              // Tag-based context gating
+    toolExposition: 'flat',                     // 'flat' or 'grouped' wire format
+    stateSync: {                                // RFC 7234-inspired cache signals
         defaults: { cacheControl: 'no-store' },
         policies: [
             { match: 'sprints.update', invalidates: ['sprints.*'] },
-            { match: 'tasks.update',   invalidates: ['tasks.*', 'sprints.*'] },
             { match: 'countries.*',    cacheControl: 'immutable' },
         ],
     },
 });
+
+prompts.attachToServer(server, {
+    contextFactory: (extra) => createAppContext(extra),
+});
+```
+
+---
+
+## Streaming Progress
+
+Generator handlers yield progress events — automatically forwarded as MCP `notifications/progress` when the client provides a `progressToken`:
+
+```typescript
+handler: async function* (ctx, args) {
+    yield progress(10, 'Cloning repository...');
+    yield progress(50, 'Building AST...');
+    yield progress(90, 'Running analysis...');
+    return success(analysisResult);
+}
 ```
 
-### Zod Parameter Validation (.strict())
-When the LLM sends arguments, Fusion merges schemas using `.merge().strict()`, then `safeParse()`. Unknown fields trigger an **actionable validation error** naming each unrecognized field. **The LLM learns which fields are valid and self-corrects on retry.**
+---
+
+## Observability
+
+Zero-overhead typed event system. Debug observers attach per-tool or globally:
 
-### Tag-Based Context Gating
-Control exactly what the LLM sees per session:
 ```typescript
-registry.attachToServer(server, { filter: { tags: ['core'] } });      // Only core tools
-registry.attachToServer(server, { filter: { exclude: ['internal'] } }); // No internal tools
+import { createDebugObserver } from '@vinkius-core/mcp-fusion';
+
+// Per-tool
+billing.debug(createDebugObserver());
+
+// Global — propagates to all registered tools
+tools.enableDebug(createDebugObserver((event) => {
+    opentelemetry.addEvent(event.type, event);
+}));
 ```
 
-### Freeze-After-Build Immutability
-After `buildToolDefinition()`, the builder is permanently frozen. `Object.freeze()` prevents mutation. Mutation methods throw. This eliminates accidental post-registration bugs.
+OpenTelemetry-compatible tracing with structural subtyping (no `@opentelemetry/api` dependency required):
+
+```typescript
+tools.enableTracing(tracer);
+// Spans: mcp.tool, mcp.action, mcp.durationMs, mcp.isError, mcp.tags
+```
 
 ---
 
-## Complete Capability Matrix
+## Capability Matrix
 
-| Capability | What It Solves |
+| Capability | Mechanism |
 |---|---|
-| **MVA Presenter** | Domain rules, UI blocks, affordances — consistent agent perception |
-| **Presenter Composition** | `.embed()` nests child Presenters for relational data |
-| **Cognitive Guardrails** | `.agentLimit()` prevents context DDoS from large datasets |
-| **Agentic Affordances** | `.suggestActions()` HATEOAS-style next-action hints |
-| **Context-Aware Rules** | RBAC/DLP through dynamic `systemRules()` with `ctx` |
-| **Action Consolidation** | Grouped tools with discriminator enum reduce token burn |
-| **Hierarchical Groups** | Namespace 5,000+ actions with `module.action` keys |
-| **4-Tier Field Annotations** | LLM knows exactly which fields to send per action |
-| **Zod `.merge().strict()`** | Security boundary — unknown fields rejected with actionable errors |
-| **Two APIs** | `defineTool()` (zero Zod) and `createTool()` (full Zod) |
-| **Context Derivation** | tRPC-style `defineMiddleware()` with type inference |
-| **Self-Healing Errors** | `toolError()` + Agentic Error Presenter — auto-formatted validation/routing errors |
-| **Streaming Progress** | Generator handlers yield `progress()` events |
-| **Type-Safe Client** | `createFusionClient()` with autocomplete and typed args |
-| **State Sync** | RFC 7234 cache-control prevents temporal blindness |
-| **Prompt Engine** | `definePrompt()` — server-side hydrated templates with flat schema constraint |
-| **TOON Encoding** | Token-optimized descriptions and responses |
-| **Tag Filtering** | Context gating — control what the LLM sees per session |
-| **Observability** | Debug observers with zero-overhead typed event system |
-| **Introspection API** | Runtime metadata for compliance audits |
-| **Tool Exposition** | `'flat'` or `'grouped'` — decouple authoring topology from wire format |
-| **Freeze-After-Build** | `Object.freeze()` — immutability after registration |
-| **Duck-Typed Server** | Works with `Server` and `McpServer` — zero coupling |
+| **Presenter** | Domain-level View layer — `.schema()`, `.systemRules()`, `.uiBlocks()`, `.suggestActions()`, `.embed()` |
+| **Cognitive Guardrails** | `.agentLimit(max, onTruncate)` — truncates arrays, injects filter guidance |
+| **Action Consolidation** | Multiple actions → single MCP tool with discriminator enum |
+| **Hierarchical Groups** | `.group()` — namespace 5,000+ actions as `module.action` |
+| **Prompt Engine** | `definePrompt()` with flat schema constraint, middleware, lifecycle sync |
+| **MVA-Driven Prompts** | `PromptMessage.fromView()` — Presenter → XML-tagged prompt messages |
+| **Context Derivation** | `defineMiddleware()` — tRPC-style typed context merging |
+| **Self-Healing Errors** | `toolError()` — structured recovery with action suggestions |
+| **Type-Safe Client** | `createFusionClient<T>()` — full inference from server to client |
+| **Streaming Progress** | `yield progress()` → MCP `notifications/progress` |
+| **State Sync** | RFC 7234 cache-control signals — `invalidates`, `no-store`, `immutable` |
+| **Tool Exposition** | `'flat'` or `'grouped'` wire format — same handlers, different topology |
+| **Tag Filtering** | RBAC context gating — `{ tags: ['core'] }` / `{ exclude: ['internal'] }` |
+| **Observability** | Zero-overhead debug observers + OpenTelemetry-compatible tracing |
+| **TOON Encoding** | Token-Optimized Object Notation — ~40% fewer tokens |
+| **Validation** | Zod `.merge().strict()` — unknown fields rejected with actionable errors |
+| **Introspection** | Runtime metadata via `fusion://manifest.json` MCP resource |
+| **Immutability** | `Object.freeze()` after `buildToolDefinition()` — no post-registration mutation |
 
 ---
 
-## Learn by Doing
+## Documentation
 
-| Guide | Description |
+| Guide | |
 |---|---|
-| 🧠 **[The MVA Manifesto](docs/mva-pattern.md)** | Why every MCP server today is built wrong — and how MVA fixes it |
-| 💰 **[Cost & Hallucination](docs/cost-and-hallucination.md)** | Fewer tokens + fewer requests = less hallucination + less cost |
-| 🏁 **[5-Minute Quickstart](docs/quickstart.md)** | Build your first Fusion server from zero |
-| 🍳 **[Cookbook & Examples](docs/examples.md)** | 14 copy-pasteable real-world patterns for every feature |
-| 🎯 **[Presenter Deep Dive](docs/presenter.md)** | The agent-centric View layer — schema, rules, UI, suggestions |
-| 📖 **[Introduction](docs/introduction.md)** | Core concepts and philosophy |
-| 🏗️ **[Architecture](docs/architecture.md)** | Domain model, strategy engine, execution pipeline |
-| 🛡️ **[Middleware](docs/middleware.md)** | Context derivation, authentication, pre-compiled chains |
-| 📈 **[Scaling](docs/scaling.md)** | Tag filtering, TOON, hierarchical groups at scale |
-| 🧠 **[State Sync](docs/state-sync.md)** | Prevent temporal blindness with cache signals |
-| 💬 **[Prompt Engine](docs/prompts.md)** | Server-side hydrated prompts with coercion and lifecycle sync |
-| 🔭 **[Observability](docs/observability.md)** | Zero-overhead debug observers with typed event system |
-| 🔀 **[Tool Exposition](docs/tool-exposition.md)** | Flat vs grouped wire strategies — per-action isolation |
-| 📖 **[API Reference](docs/api-reference.md)** | Complete typings and method reference |
+| **[MVA Architecture](https://vinkius-labs.github.io/mcp-fusion/mva-pattern)** | The MVA pattern — why and how |
+| **[Quickstart](https://vinkius-labs.github.io/mcp-fusion/quickstart)** | Build a Fusion server from zero |
+| **[Presenter](https://vinkius-labs.github.io/mcp-fusion/presenter)** | Schema, rules, UI blocks, affordances, composition |
+| **[Prompt Engine](https://vinkius-labs.github.io/mcp-fusion/prompts)** | `definePrompt()`, `PromptMessage.fromView()`, registry |
+| **[Middleware](https://vinkius-labs.github.io/mcp-fusion/middleware)** | Context derivation, authentication, chains |
+| **[State Sync](https://vinkius-labs.github.io/mcp-fusion/state-sync)** | Cache-control signals, causal invalidation |
+| **[Observability](https://vinkius-labs.github.io/mcp-fusion/observability)** | Debug observers, tracing |
+| **[Tool Exposition](https://vinkius-labs.github.io/mcp-fusion/tool-exposition)** | Flat vs grouped wire strategies |
+| **[Cookbook](https://vinkius-labs.github.io/mcp-fusion/examples)** | Real-world patterns |
+| **[API Reference](https://vinkius-labs.github.io/mcp-fusion/api-reference)** | Complete typings |
+| **[Cost & Hallucination](https://vinkius-labs.github.io/mcp-fusion/cost-and-hallucination)** | Token reduction analysis |
 
 ---
 
@@ -429,4 +405,3 @@ After `buildToolDefinition()`, the builder is permanently frozen. `Object.freeze
 - TypeScript 5.7+
 - `@modelcontextprotocol/sdk ^1.12.1` (peer dependency)
 - `zod ^3.25.1 || ^4.0.0` (peer dependency)
-- `@toon-format/toon` (for TOON features)

package/dist/framework/presenter/ResponseBuilder.d.ts

@@ -172,6 +172,42 @@ export declare class ResponseBuilder {
      * @internal
      */
     rawBlock(text: string): this;
+    /**
+     * Get the serialized data payload.
+     *
+     * Returns the JSON-stringified (or raw string) data
+     * that was passed to the constructor.
+     *
+     * @returns The data string
+     *
+     * @remarks Used by {@link PromptMessage.fromView} to decompose
+     * a Presenter view into prompt messages without calling `.build()`.
+     */
+    getData(): string;
+    /**
+     * Get the accumulated domain rules.
+     *
+     * @returns Read-only array of rule strings
+     */
+    getRules(): readonly string[];
+    /**
+     * Get the accumulated UI blocks.
+     *
+     * @returns Read-only array of UI blocks
+     */
+    getUiBlocks(): readonly UiBlock[];
+    /**
+     * Get the accumulated LLM hints.
+     *
+     * @returns Read-only array of hint strings
+     */
+    getHints(): readonly string[];
+    /**
+     * Get the accumulated action suggestions.
+     *
+     * @returns Read-only array of action suggestions
+     */
+    getSuggestions(): readonly ActionSuggestion[];
     /**
      * Compile all layers into a multi-block MCP `ToolResponse`.
      *

package/dist/framework/presenter/ResponseBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ResponseBuilder.d.ts","sourceRoot":"","sources":["../../../src/framework/presenter/ResponseBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAO1E;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IACxB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,0BAA0B;IAE1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAE3C,qDAAqD;gBACzC,IAAI,EAAE,MAAM,GAAG,MAAM;IAMjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAC7B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAU5C;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAK1C;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK3B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAK3C;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI;IAK1D;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,YAAY;CA2CxB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,CAE/D;yBAFe,QAAQ;mBAmBQ,MAAM,GAAG,MAAM,KAAG,UAAU,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;0BAsB5E,MAAM,GAAG,MAAM,SACd,SAAS,MAAM,EAAE,KACzB,UAAU,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC"}
+{"version":3,"file":"ResponseBuilder.d.ts","sourceRoot":"","sources":["../../../src/framework/presenter/ResponseBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAO1E;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IACxB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,0BAA0B;IAE1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAE3C,qDAAqD;gBACzC,IAAI,EAAE,MAAM,GAAG,MAAM;IAMjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAC7B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAU5C;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAK1C;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK3B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAK3C;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI;IAK1D;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO5B;;;;;;;;;;OAUG;IACH,OAAO,IAAI,MAAM;IAIjB;;;;OAIG;IACH,QAAQ,IAAI,SAAS,MAAM,EAAE;IAI7B;;;;OAIG;IACH,WAAW,IAAI,SAAS,OAAO,EAAE;IAIjC;;;;OAIG;IACH,QAAQ,IAAI,SAAS,MAAM,EAAE;IAI7B;;;;OAIG;IACH,cAAc,IAAI,SAAS,gBAAgB,EAAE;IAM7C;;;;;;;;;;;OAWG;IACH,KAAK,IAAI,YAAY;CA2CxB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,eAAe,CAE/D;yBAFe,QAAQ;mBAmBQ,MAAM,GAAG,MAAM,KAAG,UAAU,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;0BAsB5E,MAAM,GAAG,MAAM,SACd,SAAS,MAAM,EAAE,KACzB,UAAU,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC"}

package/dist/framework/presenter/ResponseBuilder.js

@@ -181,6 +181,54 @@ export class ResponseBuilder {
         this._rawBlocks.push(text);
         return this;
     }
+    // ── Introspection (for cross-module composition) ─────
+    /**
+     * Get the serialized data payload.
+     *
+     * Returns the JSON-stringified (or raw string) data
+     * that was passed to the constructor.
+     *
+     * @returns The data string
+     *
+     * @remarks Used by {@link PromptMessage.fromView} to decompose
+     * a Presenter view into prompt messages without calling `.build()`.
+     */
+    getData() {
+        return this._data;
+    }
+    /**
+     * Get the accumulated domain rules.
+     *
+     * @returns Read-only array of rule strings
+     */
+    getRules() {
+        return this._rules;
+    }
+    /**
+     * Get the accumulated UI blocks.
+     *
+     * @returns Read-only array of UI blocks
+     */
+    getUiBlocks() {
+        return this._uiBlocks;
+    }
+    /**
+     * Get the accumulated LLM hints.
+     *
+     * @returns Read-only array of hint strings
+     */
+    getHints() {
+        return this._hints;
+    }
+    /**
+     * Get the accumulated action suggestions.
+     *
+     * @returns Read-only array of action suggestions
+     */
+    getSuggestions() {
+        return this._suggestions;
+    }
+    // ── Compilation ──────────────────────────────────────
     /**
      * Compile all layers into a multi-block MCP `ToolResponse`.
      *

package/dist/framework/presenter/ResponseBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"ResponseBuilder.js","sourceRoot":"","sources":["../../../src/framework/presenter/ResponseBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ResponseBuilder.js","sourceRoot":"","sources":["../../../src/framework/presenter/ResponseBuilder.ts"],"names":[],"mappings":"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"}

package/dist/framework/prompt/PromptMessage.d.ts

@@ -24,6 +24,7 @@
  * @module
  */
 import { type PromptMessagePayload } from './PromptTypes.js';
+import { type ResponseBuilder } from '../presenter/ResponseBuilder.js';
 /**
  * Factory for creating MCP prompt messages.
  *
@@ -86,5 +87,47 @@ export declare const PromptMessage: {
         text?: string;
         blob?: string;
     }) => PromptMessagePayload;
+    /**
+     * Decompose a Presenter view into prompt messages.
+     *
+     * MVA-Driven Prompts — the bridge between the Presenter layer
+     * (MVA View for Tools) and the Prompt Engine. Extracts system rules,
+     * data, UI blocks, and action suggestions from a `ResponseBuilder`
+     * into composable `PromptMessagePayload[]` messages.
+     *
+     * Uses XML-tagged semantic blocks (`<domain_rules>`, `<dataset>`,
+     * `<visual_context>`, `<system_guidance>`) optimized for frontier
+     * LLM context handling — prevents context leakage between layers.
+     *
+     * **Single Source of Truth**: If a Presenter's `systemRules()` change,
+     * both Tools and Prompts update automatically — zero duplication.
+     *
+     * @param builder - A `ResponseBuilder` from `Presenter.make()` or `response()`
+     * @returns Array of prompt messages, ready to spread into `messages: [...]`
+     *
+     * @example
+     * ```typescript
+     * import { definePrompt, PromptMessage } from '@vinkius-core/mcp-fusion';
+     * import { InvoicePresenter } from './presenters';
+     *
+     * const AuditPrompt = definePrompt<AppContext>('audit', {
+     *     args: { invoiceId: 'string' } as const,
+     *     handler: async (ctx, { invoiceId }) => {
+     *         const invoice = await ctx.db.getInvoice(invoiceId);
+     *         return {
+     *             messages: [
+     *                 PromptMessage.system('You are a Senior Financial Auditor.'),
+     *                 ...PromptMessage.fromView(InvoicePresenter.make(invoice, ctx)),
+     *                 PromptMessage.user('Begin the audit for this invoice.'),
+     *             ],
+     *         };
+     *     },
+     * });
+     * ```
+     *
+     * @see {@link Presenter} for the MVA View layer
+     * @see {@link ResponseBuilder} for the data source
+     */
+    readonly fromView: (builder: ResponseBuilder) => PromptMessagePayload[];
 };
 //# sourceMappingURL=PromptMessage.d.ts.map

package/dist/framework/prompt/PromptMessage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PromptMessage.d.ts","sourceRoot":"","sources":["../../../src/framework/prompt/PromptMessage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACtB;;;;;;;;OAQG;4BACU,MAAM,KAAG,oBAAoB;IAI1C;;;;OAIG;0BACQ,MAAM,KAAG,oBAAoB;IAIxC;;;;;;;OAOG;+BACa,MAAM,KAAG,oBAAoB;IAI7C;;;;;;OAMG;2BACS,MAAM,GAAG,WAAW,QAAQ,MAAM,YAAY,MAAM,KAAG,oBAAoB;IAIvF;;;;;;OAMG;2BACS,MAAM,GAAG,WAAW,QAAQ,MAAM,YAAY,MAAM,KAAG,oBAAoB;IAIvF;;;;;;OAMG;8BAEO,MAAM,GAAG,WAAW,OACrB,MAAM,YACD;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAC9D,oBAAoB;CASjB,CAAC"}
+{"version":3,"file":"PromptMessage.d.ts","sourceRoot":"","sources":["../../../src/framework/prompt/PromptMessage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACtB;;;;;;;;OAQG;4BACU,MAAM,KAAG,oBAAoB;IAI1C;;;;OAIG;0BACQ,MAAM,KAAG,oBAAoB;IAIxC;;;;;;;OAOG;+BACa,MAAM,KAAG,oBAAoB;IAI7C;;;;;;OAMG;2BACS,MAAM,GAAG,WAAW,QAAQ,MAAM,YAAY,MAAM,KAAG,oBAAoB;IAIvF;;;;;;OAMG;2BACS,MAAM,GAAG,WAAW,QAAQ,MAAM,YAAY,MAAM,KAAG,oBAAoB;IAIvF;;;;;;OAMG;8BAEO,MAAM,GAAG,WAAW,OACrB,MAAM,YACD;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAC9D,oBAAoB;IAUvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;iCACe,eAAe,KAAG,oBAAoB,EAAE;CA4CpD,CAAC"}

package/dist/framework/prompt/PromptMessage.js

@@ -24,6 +24,7 @@
  * @module
  */
 import {} from './PromptTypes.js';
+import {} from '../presenter/ResponseBuilder.js';
 /**
  * Factory for creating MCP prompt messages.
  *
@@ -100,5 +101,82 @@ export const PromptMessage = {
             },
         };
     },
+    /**
+     * Decompose a Presenter view into prompt messages.
+     *
+     * MVA-Driven Prompts — the bridge between the Presenter layer
+     * (MVA View for Tools) and the Prompt Engine. Extracts system rules,
+     * data, UI blocks, and action suggestions from a `ResponseBuilder`
+     * into composable `PromptMessagePayload[]` messages.
+     *
+     * Uses XML-tagged semantic blocks (`<domain_rules>`, `<dataset>`,
+     * `<visual_context>`, `<system_guidance>`) optimized for frontier
+     * LLM context handling — prevents context leakage between layers.
+     *
+     * **Single Source of Truth**: If a Presenter's `systemRules()` change,
+     * both Tools and Prompts update automatically — zero duplication.
+     *
+     * @param builder - A `ResponseBuilder` from `Presenter.make()` or `response()`
+     * @returns Array of prompt messages, ready to spread into `messages: [...]`
+     *
+     * @example
+     * ```typescript
+     * import { definePrompt, PromptMessage } from '@vinkius-core/mcp-fusion';
+     * import { InvoicePresenter } from './presenters';
+     *
+     * const AuditPrompt = definePrompt<AppContext>('audit', {
+     *     args: { invoiceId: 'string' } as const,
+     *     handler: async (ctx, { invoiceId }) => {
+     *         const invoice = await ctx.db.getInvoice(invoiceId);
+     *         return {
+     *             messages: [
+     *                 PromptMessage.system('You are a Senior Financial Auditor.'),
+     *                 ...PromptMessage.fromView(InvoicePresenter.make(invoice, ctx)),
+     *                 PromptMessage.user('Begin the audit for this invoice.'),
+     *             ],
+     *         };
+     *     },
+     * });
+     * ```
+     *
+     * @see {@link Presenter} for the MVA View layer
+     * @see {@link ResponseBuilder} for the data source
+     */
+    fromView(builder) {
+        const messages = [];
+        // 1. RULES → SYSTEM ROLE (domain directives travel with the data)
+        const rules = builder.getRules();
+        if (rules.length > 0) {
+            messages.push(PromptMessage.system(`<domain_rules>\n${rules.map(r => `- ${r}`).join('\n')}\n</domain_rules>`));
+        }
+        // 2. DATA & UI BLOCKS → USER ROLE (context for the LLM)
+        const data = builder.getData();
+        const uiBlocks = builder.getUiBlocks();
+        let userContent = '';
+        if (data) {
+            userContent += `<dataset>\n\`\`\`json\n${data}\n\`\`\`\n</dataset>\n\n`;
+        }
+        if (uiBlocks.length > 0) {
+            userContent += `<visual_context>\n${uiBlocks.map(b => b.content).join('\n\n')}\n</visual_context>\n\n`;
+        }
+        if (userContent.trim()) {
+            messages.push(PromptMessage.user(userContent.trim()));
+        }
+        // 3. AFFORDANCES → SYSTEM ROLE (hints + HATEOAS suggestions)
+        const hints = builder.getHints();
+        const suggestions = builder.getSuggestions();
+        if (hints.length > 0 || suggestions.length > 0) {
+            let guidance = '<system_guidance>\n';
+            if (hints.length > 0) {
+                guidance += hints.map(h => `Hint: ${h}`).join('\n') + '\n';
+            }
+            if (suggestions.length > 0) {
+                guidance += `Suggested Next Actions: ${suggestions.map(s => `${s.tool} (${s.reason})`).join(', ')}\n`;
+            }
+            guidance += '</system_guidance>';
+            messages.push(PromptMessage.system(guidance));
+        }
+        return messages;
+    },
 };
 //# sourceMappingURL=PromptMessage.js.map

package/dist/framework/prompt/PromptMessage.js.map

@@ -1 +1 @@
-{"version":3,"file":"PromptMessage.js","sourceRoot":"","sources":["../../../src/framework/prompt/PromptMessage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAA6B,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IACzB;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAY;QACf,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;IAC7D,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,IAAY;QACb,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;IAC7D,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,IAAY;QAClB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC;IAClE,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAA0B,EAAE,IAAY,EAAE,QAAgB;QAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;IAChE,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAA0B,EAAE,IAAY,EAAE,QAAgB;QAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,CAAC;IAChE,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CACJ,IAA0B,EAC1B,GAAW,EACX,OAA6D;QAE7D,OAAO;YACH,IAAI;YACJ,OAAO,EAAE;gBACL,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE,EAAE,GAAG,EAAE,GAAG,OAAO,EAAE;aAChC;SACJ,CAAC;IACN,CAAC;CACK,CAAC"}
+{"version":3,"file":"PromptMessage.js","sourceRoot":"","sources":["../../../src/framework/prompt/PromptMessage.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -339,6 +339,52 @@ handler: async function* (ctx, args) {
 // Wire format: { method: 'notifications/progress', params: { progressToken, progress: 25, total: 100, message: 'Loading data...' } }
 ```
 
+## Prompt Engine
+
+Server-side hydrated prompt templates with schema-informed coercion and lifecycle sync. The `definePrompt()` factory enforces a **flat schema constraint** — prompt arguments must be primitives (string, number, boolean, enum) because MCP clients render them as forms.
+
+```typescript
+import { definePrompt, PromptMessage } from '@vinkius-core/mcp-fusion';
+
+const SummarizePrompt = definePrompt<AppContext>('summarize', {
+    title: 'Summarize Document',
+    description: 'Generate a summary of a document.',
+    args: {
+        docId: 'string',
+        length: { enum: ['short', 'medium', 'long'] as const },
+    } as const,
+    handler: async (ctx, { docId, length }) => {
+        const doc = await ctx.db.documents.get(docId);
+        return {
+            messages: [
+                PromptMessage.system('You are a Senior Technical Writer.'),
+                PromptMessage.user(`Summarize this document (${length}):\n\n${doc.content}`),
+            ],
+        };
+    },
+});
+```
+
+## MVA-Driven Prompts — fromView()
+
+Bridge your Presenter layer into Prompts with zero duplication. `PromptMessage.fromView()` decomposes a `ResponseBuilder` into XML-tagged prompt messages (`<domain_rules>`, `<dataset>`, `<visual_context>`, `<system_guidance>`) optimized for frontier LLMs. Domain rules, UI blocks, and action suggestions from the Presenter are automatically extracted — single source of truth.
+
+```typescript
+const AuditPrompt = definePrompt<AppContext>('audit', {
+    args: { invoiceId: 'string' } as const,
+    handler: async (ctx, { invoiceId }) => {
+        const invoice = await ctx.db.getInvoice(invoiceId);
+        return {
+            messages: [
+                PromptMessage.system('You are a Senior Financial Auditor.'),
+                ...PromptMessage.fromView(InvoicePresenter.make(invoice, ctx)),
+                PromptMessage.user('Begin the audit.'),
+            ],
+        };
+    },
+});
+```
+
 ## Important Rules
 
 1. `.action()` and `.group()` are MUTUALLY EXCLUSIVE on the same builder
@@ -401,6 +447,17 @@ handler: async function* (ctx, args) {
 - `isProgressEvent(value)` → type guard
 - `ProgressSink` — callback type `(event: ProgressEvent) => void` — auto-wired by `attachToServer()`, or pass manually to `execute()` / `routeCall()` for testing
 
+### Prompt Engine
+- `definePrompt<TContext>(name, config)` → PromptBuilder — JSON-first or Zod schema for args, flat primitives only
+- `PromptMessage.system(text)` → PromptMessagePayload (system instruction as MCP user role)
+- `PromptMessage.user(text)` → PromptMessagePayload
+- `PromptMessage.assistant(text)` → PromptMessagePayload (multi-turn seeding)
+- `PromptMessage.image(role, data, mimeType)` → PromptMessagePayload
+- `PromptMessage.audio(role, data, mimeType)` → PromptMessagePayload
+- `PromptMessage.resource(role, uri, options?)` → PromptMessagePayload
+- `PromptMessage.fromView(builder)` → PromptMessagePayload[] — decomposes ResponseBuilder into XML-tagged messages (<domain_rules>, <dataset>, <visual_context>, <system_guidance>)
+- `PromptRegistry<TContext>` — .register(), .registerAll(), .getAllPrompts(), .getPrompts(filter), .routeGet(), .notifyChanged(), .has(), .clear(), .size
+
 ### Result Monad
 - `succeed<T>(value)` → Success<T>
 - `fail(response)` → Failure
@@ -440,6 +497,11 @@ handler: async function* (ctx, args) {
 - `ManifestTool` — { description, tags, actions, input_schema }
 - `ManifestAction` — { description, destructive, idempotent, readOnly, required_fields, returns_presenter }
 - `ManifestPresenter` — { schema_keys, ui_blocks_supported, has_contextual_rules }
+- `PromptResult` — { description?: string, messages: PromptMessagePayload[] }
+- `PromptMessagePayload` — { role: 'user' | 'assistant', content: PromptContentBlock }
+- `PromptContentBlock` — PromptTextContent | PromptImageContent | PromptAudioContent | PromptResourceContent
+- `PromptBuilder<TContext>` — DIP interface: .name, .getDefinition(), .handleGet(), .tags
+- `PromptConfig<TContext>` — { title?, description?, args?, tags?, middleware?, handler }
 
 ### Domain Models
 - `BaseModel` — abstract base (name, title, description, meta, icons)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@vinkius-core/mcp-fusion",
-    "version": "1.5.0",
+    "version": "1.6.0",
     "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.",
     "type": "module",
     "main": "dist/index.js",