@vinkius-core/mcp-fusion 1.11.0 → 2.3.0

package/llms.txt

@@ -1,593 +0,0 @@
-# mcp-fusion
-
-> The MVA (Model-View-Agent) framework for building MCP servers where AI agents are first-class consumers.
-
-## What is mcp-fusion?
-
-mcp-fusion is a TypeScript framework for the Model Context Protocol (MCP) that introduces the **MVA (Model-View-Agent)** architectural pattern — created by Renato Marinho at Vinkius Labs. Instead of dumping raw JSON and hoping the AI figures it out, MVA adds a **Presenter** (the View layer) that gives every response structure: validated data, domain rules, rendered charts, action affordances, and cognitive guardrails.
-
-## Core Architecture: MVA (Model-View-Agent)
-
-```
-Model (Zod Schema) → View (Presenter) → Agent (LLM)
-   validates            perceives          acts
-```
-
-The Presenter replaces the human-centric View with an agent-centric perception layer. Every tool response becomes a **structured perception package** — not raw JSON.
-
-## Core Concepts
-
-- **MVA Pattern**: Model-View-Agent — the architectural foundation where Presenters replace Views
-- **Presenter**: Domain-level View layer — schema validation, system rules, UI blocks, affordances, guardrails
-- **GroupedToolBuilder**: Fluent builder that groups related actions into a single MCP tool
-- **createTool()**: Factory function to create a GroupedToolBuilder with full Zod power
-- **defineTool()**: JSON-first factory — define tools without Zod imports using plain strings/objects
-- **createPresenter()**: Fluent builder for domain-level Presenters
-- **ResponseBuilder**: Fine-grained manual response composition
-- **Action**: A single operation within a grouped tool (e.g., "list", "create", "delete")
-- **Group**: Hierarchical namespace for actions (e.g., "users.create", "billing.refund")
-- **Discriminator**: The field name the LLM uses to select the action (default: "action")
-- **CommonSchema**: Shared Zod schema injected into every action
-- **ToolRegistry**: Centralized registry for all tool builders
-- **Middleware**: Pre-compiled middleware chains following the next() pattern
-- **Tags**: Capability labels for selective tool exposure per session
-- **TOON**: Token-Oriented Object Notation for compact descriptions/responses
-- **State Sync**: RFC 7234-inspired cache-control signals to prevent temporal blindness
-- **Tool Exposition**: Compile-time topology compiler — choose flat (one tool per action) or grouped (one tool per builder with discriminator enum) at attach time. Same handlers, different wire format.
-- **Dynamic Manifest**: RBAC-filtered server capabilities exposed as a native MCP Resource
-
-## Quick Start — MVA with Presenter
-
-```typescript
-import { createPresenter, ui, defineTool, success } from '@vinkius-core/mcp-fusion';
-import { z } from 'zod';
-
-// 1. Define the Presenter — the MVA View Layer
-export const InvoicePresenter = createPresenter('Invoice')
-    .schema(z.object({
-        id: z.string(),
-        amount_cents: z.number(),
-        status: z.enum(['paid', 'pending', 'overdue']),
-    }))
-    .systemRules(['CRITICAL: amount_cents is in CENTS. Divide by 100.'])
-    .uiBlocks((inv) => [
-        ui.echarts({ series: [{ type: 'gauge', data: [{ value: inv.amount_cents / 100 }] }] }),
-    ])
-    .suggestActions((inv) =>
-        inv.status === 'pending'
-            ? [{ tool: 'billing.pay', reason: 'Process payment' }]
-            : []
-    );
-
-// 2. Attach to any tool — handler returns raw data, Presenter does the rest
-const billing = defineTool<AppContext>('billing', {
-    actions: {
-        get_invoice: {
-            returns: InvoicePresenter,
-            params: { id: 'string' },
-            handler: async (ctx, args) => await ctx.db.invoices.findUnique(args.id),
-        },
-    },
-});
-
-const registry = new ToolRegistry<AppContext>();
-registry.register(billing);
-registry.attachToServer(server, {
-    contextFactory: (extra) => createAppContext(extra),
-});
-```
-
-## Quick Start — defineTool() (No Zod Required)
-
-```typescript
-import { defineTool, ToolRegistry, success, error } from '@vinkius-core/mcp-fusion';
-
-const projects = defineTool<AppContext>('projects', {
-    description: 'Manage workspace projects',
-    shared: { workspace_id: 'string' },
-    actions: {
-        list: {
-            readOnly: true,
-            params: { status: { enum: ['active', 'archived'] as const, optional: true } },
-            handler: async (ctx, args) => success(await ctx.db.projects.findMany()),
-        },
-        create: {
-            params: {
-                name: { type: 'string', min: 1, max: 100 },
-                email: { type: 'string', regex: '^[\\w-.]+@([\\w-]+\\.)+[\\w-]{2,4}$' },
-            },
-            handler: async (ctx, args) => success(await ctx.db.projects.create(args)),
-        },
-        delete: {
-            destructive: true,
-            params: { project_id: 'string' },
-            handler: async (ctx, args) => {
-                await ctx.db.projects.delete(args.project_id);
-                return success('Project deleted');
-            },
-        },
-    },
-});
-```
-
-## Quick Start — createTool() (Full Zod Power)
-
-```typescript
-import { createTool, ToolRegistry, success, error } from '@vinkius-core/mcp-fusion';
-import { z } from 'zod';
-
-const projects = createTool<AppContext>('projects')
-    .description('Manage workspace projects')
-    .commonSchema(z.object({
-        workspace_id: z.string().describe('Workspace identifier'),
-    }))
-    .action({
-        name: 'list',
-        readOnly: true,
-        schema: z.object({ status: z.enum(['active', 'archived']).optional() }),
-        handler: async (ctx, args) => success(await ctx.db.projects.findMany({ where: args })),
-    })
-    .action({
-        name: 'create',
-        schema: z.object({ name: z.string() }),
-        handler: async (ctx, args) => success(await ctx.db.projects.create({ data: args })),
-    })
-    .action({
-        name: 'delete',
-        destructive: true,
-        schema: z.object({ project_id: z.string() }),
-        handler: async (ctx, args) => {
-            await ctx.db.projects.delete({ where: { id: args.project_id } });
-            return success('Deleted');
-        },
-    });
-```
-
-## Presenter API
-
-```typescript
-import { createPresenter, ui } from '@vinkius-core/mcp-fusion';
-
-const UserPresenter = createPresenter('User')
-    .schema(z.object({ id: z.string(), name: z.string(), role: z.string() }))
-    .systemRules(['Display name in bold'])
-    .systemRules((user, ctx) => ctx.isAdmin ? ['Show internal fields'] : ['Hide internal fields'])
-    .uiBlocks((user) => [ui.summary({ total: 1, showing: 1 })])
-    .agentLimit(50, { warningMessage: 'Showing {shown} of {total}. Use filters.' })
-    .suggestActions((user) => [
-        { tool: 'users.update', reason: 'Edit this user', args: { id: user.id } },
-    ])
-    .embed('team', TeamPresenter);
-```
-
-## Presenter Composition
-
-```typescript
-const OrderPresenter = createPresenter('Order')
-    .schema(OrderSchema)
-    .embed('customer', CustomerPresenter)
-    .embed('items', LineItemPresenter);
-// Child Presenters' rules, UI blocks, and suggestions are automatically merged.
-```
-
-## ResponseBuilder (Manual Composition)
-
-```typescript
-import { ResponseBuilder } from '@vinkius-core/mcp-fusion';
-
-const response = ResponseBuilder.create(data)
-    .systemRules(['Format currency in USD'])
-    .uiBlock(ui.echarts({ /* chart config */ }))
-    .llmHint('This invoice is overdue')
-    .suggestActions([{ tool: 'billing.pay', reason: 'Pay now' }])
-    .build();
-```
-
-## DX Shortcuts
-
-```typescript
-import { response, ui } from '@vinkius-core/mcp-fusion';
-
-return response.ok(data);                          // Simple success
-return response.withRules(data, ['Rule 1']);        // Data + rules
-ui.echarts({ series: [...] });                     // ECharts chart
-ui.mermaid('graph TD; A-->B');                      // Mermaid diagram
-ui.summary({ total: 100, showing: 10 });           // Collection summary
-```
-
-## Hierarchical Groups
-
-```typescript
-const platform = createTool<AppContext>('platform')
-    .tags('core')
-    .group('users', 'User management', g => {
-        g.use(requireAdmin)
-         .action({ name: 'list', readOnly: true, handler: listUsers })
-         .action({ name: 'ban', destructive: true, schema: banSchema, handler: banUser });
-    })
-    .group('billing', 'Billing operations', g => {
-        g.action({ name: 'refund', destructive: true, schema: refundSchema, handler: issueRefund });
-    });
-// Discriminator values: "users.list" | "users.ban" | "billing.refund"
-```
-
-## Middleware
-
-```typescript
-const requireAuth: MiddlewareFn<AppContext> = async (ctx, args, next) => {
-    if (!ctx.user) return error('Unauthorized');
-    return next();
-};
-
-// tRPC-style context derivation
-const withDb = defineMiddleware(async (ctx) => ({
-    ...ctx,
-    db: await createDbConnection(ctx.tenantId),
-}));
-
-createTool<AppContext>('projects')
-    .use(requireAuth)
-    .use(withDb)
-    .action({ name: 'list', handler: async (ctx, args) => success(await ctx.db.query()) });
-```
-
-## Self-Healing Errors
-
-```typescript
-import { toolError } from '@vinkius-core/mcp-fusion';
-
-return toolError('INVALID_DATE_RANGE', {
-    message: 'Start date must be before end date',
-    recovery: { action: 'retry', suggestion: 'Swap the date values' },
-    suggestedArgs: { start: args.end, end: args.start },
-});
-```
-
-All error XML output is automatically escaped to prevent injection. Pipeline errors use structured codes: `MISSING_DISCRIMINATOR`, `UNKNOWN_ACTION`, `UNKNOWN_TOOL`, `MISSING_REQUIRED_FIELD`.
-
-## State Sync
-
-```typescript
-registry.attachToServer(server, {
-    contextFactory: (extra) => createAppContext(extra),
-    stateSync: {
-        defaults: { cacheControl: 'no-store' },
-        policies: [
-            { match: 'sprints.update', invalidates: ['sprints.*'] },
-            { match: 'tasks.update',   invalidates: ['tasks.*', 'sprints.*'] },
-            { match: 'countries.*',    cacheControl: 'immutable' },
-        ],
-    },
-});
-```
-
-## Runtime Guards
-
-Built-in concurrency control and payload size limiting. Fulfills the MCP spec requirement: "Servers MUST rate limit tool invocations."
-
-```typescript
-// Concurrency Bulkhead — limit simultaneous executions per tool
-const billing = createTool<AppContext>('billing')
-    .concurrency({ maxActive: 5, maxQueue: 20 })
-    .action({
-        name: 'process_invoice',
-        handler: async (ctx, args) => success(await ctx.stripe.charges.create(args)),
-    });
-// 5 concurrent, 20 queued, rest rejected with SERVER_BUSY
-
-// Egress Guard — truncate oversized responses
-const logs = createTool<AppContext>('logs')
-    .maxPayloadBytes(2 * 1024 * 1024) // 2MB
-    .action({
-        name: 'search',
-        handler: async (ctx, args) => success(await ctx.db.logs.findMany(args)),
-    });
-// Responses > 2MB are truncated + system intervention injected
-
-// Both combined
-const analytics = createTool<AppContext>('analytics')
-    .concurrency({ maxActive: 3, maxQueue: 10 })
-    .maxPayloadBytes(2 * 1024 * 1024)
-    .action({
-        name: 'query',
-        handler: async (ctx, args) => success(await ctx.db.$queryRaw(args.sql)),
-    });
-
-// Intent Mutex — anti-race condition guard
-const users = createTool<AppContext>('users')
-    .action({
-        name: 'delete',
-        destructive: true, // Automatically serializes concurrent calls to this action key
-        handler: async (ctx, args) => success(await ctx.db.users.delete(args.id)),
-    });
-```
-
-Load shedding returns `toolError('SERVER_BUSY')` — a self-healing error that causes the LLM to reduce its cadence. Egress truncation injects `[SYSTEM INTERVENTION: Payload truncated. You MUST use pagination.]`. Intent Mutex prevents LLM double-firing hallucinations. Zero overhead when not configured.
-
-
-## Dynamic Manifest
-
-```typescript
-registry.attachToServer(server, {
-    contextFactory: (extra) => createAppContext(extra),
-    serverName: 'my-platform',
-    introspection: {
-        enabled: process.env.NODE_ENV !== 'production',
-        filter: (manifest, ctx) => {
-            if (ctx.user.role !== 'admin') {
-                delete manifest.capabilities.tools['admin'];
-            }
-            return manifest;
-        },
-    },
-});
-// Exposes fusion://manifest.json via MCP resources/list + resources/read
-// Manifest includes: all tools, actions (destructive/readOnly flags, required_fields),
-// input schemas, presenter references — RBAC-filtered per session
-```
-
-## Tag Filtering
-
-```typescript
-registry.attachToServer(server, { filter: { tags: ['core'] } });      // Only core tools
-registry.attachToServer(server, { filter: { exclude: ['internal'] } }); // No internal tools
-```
-
-## Tool Exposition
-
-Two strategies for the same codebase — choose at attach time:
-
-```typescript
-// Flat (default) — each action becomes an independent MCP tool
-// projects → projects_list, projects_create, projects_delete
-registry.attachToServer(server, {
-    toolExposition: 'flat',
-    actionSeparator: '_',
-});
-
-// Grouped — one MCP tool per builder with discriminator enum
-// projects → { action: 'list' | 'create' | 'delete' }
-registry.attachToServer(server, {
-    toolExposition: 'grouped',
-});
-```
-
-**Flat** — precision per action: isolated schemas, per-action MCP annotations, per-tool toggles in clients. Best for small-to-medium APIs and weaker LLMs.
-
-**Grouped** — density at scale: one schema, one description, shared params appear once. Best for large domain APIs (50+ actions) and token-constrained contexts.
-
-MCP annotation semantics: Fusion emits `destructiveHint: false` on non-destructive actions because the MCP spec defaults `destructiveHint` to `true` (assume dangerous). Read-only actions get both `readOnlyHint: true` and `destructiveHint: false`. Destructive actions get `destructiveHint: true`. `readOnlyHint: false` is never emitted (matches spec default).
-
-## Response Helpers
-
-```typescript
-import { success, error, required, toonSuccess, toolError } from '@vinkius-core/mcp-fusion';
-
-return success('Task completed');
-return success({ id: '123', name: 'Acme' });
-return error('Project not found');
-return required('workspace_id');
-return toonSuccess(users);                  // ~40% fewer tokens
-return toolError('NOT_FOUND', { message: 'Invoice not found', recovery: { action: 'list' } });
-```
-
-## Streaming Progress
-
-Generator handlers yield `progress()` events that are **automatically** forwarded to the MCP client as `notifications/progress` when the client includes a `progressToken` in its request `_meta`. Zero configuration, zero overhead when not used.
-
-```typescript
-handler: async function* (ctx, args) {
-    yield progress(25, 'Loading data...');
-    const data = await ctx.db.query();
-    yield progress(75, 'Processing...');
-    return success(data);
-}
-// 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}`),
-            ],
-        };
-    },
-});
-```
-
-## Hydration Timeout Sandbox
-
-Prompt handlers fetch data from external sources (APIs, databases). If any source hangs, the UI freezes. The Hydration Timeout Sandbox wraps the handler in a strict `Promise.race` deadline. Three guarantees: (1) handler completes → normal result, (2) handler exceeds deadline → `<hydration_alert><status>TIMEOUT</status>` alert, (3) handler throws → `<hydration_alert><status>ERROR</status>` alert. The UI ALWAYS unblocks.
-
-```typescript
-// Per-prompt deadline
-const Briefing = definePrompt<AppContext>('morning_briefing', {
-    hydrationTimeout: 3000, // 3 seconds strict
-    handler: async (ctx, args) => {
-        // If Jira takes 15s, framework cuts at 3s → returns SYSTEM ALERT
-        const tickets = await ctx.invokeTool('jira.get_assigned');
-        return { messages: [PromptMessage.user(tickets.text)] };
-    },
-});
-
-// Registry-level default (global safety net)
-const prompts = new PromptRegistry<AppContext>();
-prompts.setDefaultHydrationTimeout(5000); // 5s for all prompts
-prompts.register(Briefing); // overrides with 3s
-```
-
-Zero overhead when no timeout configured. Timer cleanup via `finally` — no resource leaks. Interceptors still run after timeout.
-
-## 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.'),
-            ],
-        };
-    },
-});
-```
-
-## Stateless Cursor Pagination
-
-Prompt Registries support cryptographic, stateless cursor-based pagination out of the box. Cursors encode the current position securely (`globalThis.crypto.subtle`) ensuring O(1) memory overhead.
-
-```typescript
-const registry = new PromptRegistry<AppContext>();
-registry.configurePagination({ pageSize: 50 }); // enable pagination
-```
-
-## Important Rules
-
-1. `.action()` and `.group()` are MUTUALLY EXCLUSIVE on the same builder
-2. Action names must NOT contain dots (dots are reserved for group.action keys)
-3. After `buildToolDefinition()`, the builder is FROZEN — no more modifications
-4. `execute()` auto-calls `buildToolDefinition()` if not already called
-5. `commonSchema` fields are marked `(always required)` in auto-generated descriptions
-6. Zod `.merge().strip()` is used at runtime — unknown fields are silently stripped
-7. Middleware chains are pre-compiled at build time — zero runtime allocation
-8. Tool names must be unique across a ToolRegistry
-9. Presenters are immutable after creation — define once, reuse across tools
-10. `.agentLimit()` automatically truncates and injects guidance blocks
-
-## Public API (all from '@vinkius-core/mcp-fusion')
-
-### Builder
-- `createTool<TContext>(name)` → GroupedToolBuilder (fluent builder, requires Zod)
-- `defineTool<TContext>(name, config)` → GroupedToolBuilder (JSON-first, no Zod required)
-- `GroupedToolBuilder<TContext>` — .description(), .commonSchema(), .discriminator(), .tags(), .annotations(), .toonDescription(), .concurrency(), .maxPayloadBytes(), .use(), .action(), .group(), .buildToolDefinition(), .execute(), .previewPrompt(), .getName(), .getTags(), .getActionNames(), .getActionMetadata()
-- `ActionGroupBuilder<TContext>` — .use(), .action()
-
-### Presenter (MVA View Layer)
-- `createPresenter(name)` → PresenterBuilder — .schema(), .systemRules(), .uiBlocks(), .agentLimit(), .suggestActions(), .embed()
-- `ResponseBuilder.create(data)` → ResponseBuilder — .systemRules(), .uiBlock(), .llmHint(), .suggestActions(), .build()
-- `ui.echarts(config)` → UIBlock (ECharts chart)
-- `ui.mermaid(code)` → UIBlock (Mermaid diagram)
-- `ui.summary(stats)` → UIBlock (Collection summary)
-- `response.ok(data)` → ToolResponse (success shortcut)
-- `response.withRules(data, rules)` → ToolResponse (data + system rules)
-
-### Registry
-- `ToolRegistry<TContext>` — .register(), .registerAll(), .getAllTools(), .getTools(filter), .routeCall(), .attachToServer(), .has(), .clear(), .size
-
-### FusionClient (tRPC-style)
-- `createFusionClient<TRouter>(transport)` → FusionClient — type-safe client with autocomplete
-- `FusionClient<TRouter>` — .execute(action, args) with full type inference
-
-### Response Helpers
-- `success(data)` → ToolResponse
-- `error(message)` → ToolResponse (isError: true)
-- `required(field)` → ToolResponse (isError: true)
-- `toolError(code, options)` → ToolResponse (structured recovery hints for LLM agents)
-- `toonSuccess(data, options?)` → ToolResponse (TOON-encoded)
-
-### State Sync
-- `cacheSignal(data, options)` → ToolResponse with cache-control metadata
-- `invalidates(data, scopes)` → ToolResponse with invalidation signals
-
-### Dynamic Manifest
-- `registerIntrospectionResource(server, config, serverName, builders, contextFactory?)` — registers MCP resources/list + resources/read handlers
-- `compileManifest(serverName, builders)` → ManifestPayload (structured server capabilities)
-- `cloneManifest(manifest)` → deep clone for RBAC isolation
-- `Presenter.getSchemaKeys()` → string[] (read-only accessor)
-- `Presenter.getUiBlockTypes()` → string[] (read-only accessor)
-- `Presenter.hasContextualRules()` → boolean (read-only accessor)
-- `ToolRegistry.getBuilders()` → Iterable<ToolBuilder> (for introspection)
-
-### Streaming Progress
-- `progress(percent, message)` → ProgressEvent (yield from generator handlers)
-- `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(), .setDefaultHydrationTimeout(), .notifyChanged(), .has(), .clear(), .size
-
-### Result Monad
-- `succeed<T>(value)` → Success<T>
-- `fail(response)` → Failure
-- `Result<T>` = Success<T> | Failure
-
-### Middleware
-- `defineMiddleware(deriveFn)` → MiddlewareDefinition (tRPC-style context derivation)
-- `resolveMiddleware(input)` → MiddlewareFn
-
-### Observability
-- `createDebugObserver(options?)` → Observer for runtime debugging
-- Event types: tool:start, tool:end, tool:error, middleware:start, middleware:end
-
-### Tracing (OpenTelemetry-Compatible)
-- `FusionTracer` / `FusionSpan` — structural subtyping interfaces matching OpenTelemetry (no `@opentelemetry/api` dependency)
-- `SpanStatusCode` — exported constants: `UNSET` (0), `OK` (1), `ERROR` (2)
-- `.tracing(tracer)` on builders — per-tool tracing
-- `ToolRegistry.enableTracing(tracer)` — propagate to all builders
-- `AttachOptions.tracing` — pass tracer to `attachToServer()` for full server tracing
-- **Error classification**: AI errors (`validation_failed`, `missing_discriminator`, `unknown_action`, `unknown_tool`, `handler_returned_error`) → `SpanStatusCode.UNSET` (no PagerDuty). System errors (handler `throw`) → `SpanStatusCode.ERROR` (triggers alerts).
-- **Enterprise attributes**: `mcp.system`, `mcp.tool`, `mcp.action`, `mcp.durationMs`, `mcp.isError`, `mcp.error_type`, `mcp.tags`, `mcp.description`, `mcp.response_size`
-- **Span events**: `mcp.route`, `mcp.validate` (with `mcp.valid`, `mcp.durationMs`), `mcp.middleware` (with `mcp.chainLength`)
-- Zero overhead when no tracer is set — separate fast path
-
-### Types
-- `ToolResponse` — { content: [{ type: "text", text: string }], isError?: boolean }
-- `MiddlewareFn<TContext>` — (ctx, args, next) => Promise<ToolResponse>
-- `ActionConfig<TContext>` — { name, description?, schema?, destructive?, readOnly?, handler, returns? }
-- `PresenterConfig` — { schema, systemRules?, uiBlocks?, agentLimit?, suggestActions?, embeds? }
-- `ToolBuilder<TContext>` — Interface for custom builders
-- `ActionMetadata` — { key, actionName, groupName, description, destructive, idempotent, readOnly, requiredFields, hasMiddleware, presenterName?, presenterSchemaKeys?, presenterUiBlockTypes?, presenterHasContextualRules? }
-- `ToolFilter` — { tags?: string[], exclude?: string[] }
-- `AttachOptions<TContext>` — { contextFactory?, filter?, debug?, stateSync?, introspection?, serverName?, toolExposition?, actionSeparator?, tracing? }
-- `ConcurrencyConfig` — { maxActive: number, maxQueue?: number }
-- `EgressConfig` — { maxPayloadBytes: number }
-- `ToolExposition` — 'flat' | 'grouped'
-- `IntrospectionConfig<TContext>` — { enabled, uri?, filter? }
-- `ManifestPayload` — { server, mcp_fusion_version, architecture, capabilities: { tools, presenters } }
-- `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?, hydrationTimeout?, handler }
-
-### Domain Models
-- `BaseModel` — abstract base (name, title, description, meta, icons)
-- `GroupItem` — leaf with multi-parent groups
-- `Group` — tree node (addChildGroup, addChildTool, addChildPrompt, addChildResource)
-- `Tool` — inputSchema, outputSchema, toolAnnotations
-- `Resource` — uri, size, mimeType, annotations
-- `Prompt` — promptArguments
-- `PromptArgument` — required: boolean