Without MVA vs With MVA

Prerequisites

Install Vurb.ts before following this guide: npm install @vurb/core @modelcontextprotocol/sdk zod — or scaffold a project with vurb create.

---

THE AHA MOMENT

See the difference in 3 seconds.
Raw MCP vs Vurb.

Every tool response in raw MCP is JSON.stringify() — the AI gets a flat blob and guesses. Vurb replaces guessing with structured perception.

Aspect	Raw MCP	Vurb MVA
Tool count	50 individual tools. Token explosion.	Action consolidation — module.action discriminator
Response	JSON.stringify() — AI guesses	Structured perception — data + rules + UI + affordances
Domain context	amount_cents: 45000 — dollars? cents?	System rules: "amount_cents is in CENTS."
Next actions	AI hallucinates tool names	Agentic HATEOAS — .suggest() based on state
Large datasets	10,000 rows dump — token DDoS	.limit(50) truncates and teaches filters
Security	Internal fields leak	Schema IS the boundary
Error recovery	throw new Error('not found') — gives up	toolError() with recovery hints
Middleware	Copy-paste auth checks	tRPC-style defineMiddleware()
Deployment	Stdio only	Vercel, Cloudflare, Lambda

---

Invoice: Before & After

RAW MCP

server.setRequestHandler(async (request) => {
  const { name, arguments: args } = request.params;
  if (name === 'get_invoice') {
    const invoice = await db.invoices.findUnique(args.id);
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(invoice)
      }]
    };
  }
  // ...50 more if/else branches
});
// AI: { "internal_margin": 0.12,
//        "customer_ssn": "123-45-6789" } ← leaked

VURB MVA

const InvoicePresenter = createPresenter('Invoice')
  .schema(InvoiceModel)
  .rules([
    'amount_cents is in CENTS. Divide by 100.',
    'Always show currency as USD.',
  ])
  .ui((inv) => [
    ui.echarts({
      series: [{ type: 'gauge',
        data: [{ value: inv.amount_cents / 100 }]
      }],
    }),
  ])
  .suggest((inv) =>
    inv.status === 'pending'
      ? [suggest('billing.pay', 'Process payment')]
      : [suggest('billing.archive', 'Archive')]
  );

---

Users: Before & After

RAW MCP — TOKEN DDoS

case 'list_users':
  const users = await db.users.findMany();
  return { content: [{
    type: 'text',
    text: JSON.stringify(users)
  }]};
  // 10,000 users × ~500 tokens = context DDoS

VURB — SMART TRUNCATION

const UserPresenter = createPresenter('User')
  .schema(UserModel)
  .limit(50)
  .suggest(() => [
    suggest('users.search',
      'Search by name or role'),
  ]);
// 50 users. Agent guided to filters.
// ~25k tokens instead of ~5,000,000.

---

Error Recovery: Before & After

RAW MCP — GIVES UP

if (!invoice) {
  return {
    content: [{
      type: 'text',
      text: 'Invoice not found'
    }],
    isError: true
  };
}
// AI: "I encountered an error." ← dead end

VURB — SELF-HEALS

if (!invoice) {
  return toolError('NOT_FOUND', {
    message: `Invoice ${args.id} not found`,
    recovery: {
      action: 'list',
      suggestion: 'List invoices first'
    },
    suggestedArgs: { status: 'pending' },
  });
}
// AI: "Let me list pending invoices..." ✓

---

The Architecture Difference

❌

Without MVA

Handler → JSON.stringify() → raw data blob → LLM guesses everything

✅

With MVA

Handler → raw data → Presenter (Schema + Rules + UI + Limits + Suggestions) → Structured Perception Package → LLM acts with confidence

	Without MVA	With MVA
Lines of code per tool	20-50 (routing + validation + formatting)	3-5 (handler only)
Security	Hope you didn't forget to strip fields	Schema IS the boundary
Token cost per call	High (raw dumps)	Low (guardrails, truncation)
Deployment	Stdio + manual HTTP bridge	Stdio, SSE, Vercel, Cloudflare
Maintenance	Every tool re-implements rendering	Presenter defined once