API Reference

A highly dense reference manual for every public class, function, type, and interface exported by the MCP Fusion framework.

---

Response Helpers

Because MCP dictates strict return structures, rather than sending complex JSON array trees by hand, use the Fusion helper libraries for instant payload mappings.

success(data)

Creates a success response payload. Auto-detects the input type. If a string is passed, it is used as is. If an object is passed, it is intelligently serialized via JSON.stringify.

import { success } from '@vinkius-core/mcp-fusion';

return success('Task created');
return success({ id: '1', title: 'My task', status: 'open' });

error(message)

Returns an error response wrapped in a <tool_error> XML envelope with isError: true.

import { error } from '@vinkius-core/mcp-fusion';

return error('Task not found');
// Output:
// <tool_error>
// <message>Task not found</message>
// </tool_error>

required(field)

Returns a missing-field error with an error code and recovery instruction.

import { required } from '@vinkius-core/mcp-fusion';

return required('project_id');
// Output:
// <tool_error code="MISSING_REQUIRED_FIELD">
// <message>Required field "project_id" is missing.</message>
// <recovery>Provide the "project_id" parameter and retry.</recovery>
// </tool_error>

toolError(code, options)

Creates a self-healing error response with structured recovery instructions for LLM agents.

import { toolError } from '@vinkius-core/mcp-fusion';

return toolError('ProjectNotFound', {
    message: `Project '${id}' does not exist.`,
    suggestion: 'Call projects.list to see available IDs.',
    availableActions: ['projects.list'],
});
// Output:
// <tool_error code="ProjectNotFound">
// <message>Project 'xyz' does not exist.</message>
// <recovery>Call projects.list to see available IDs.</recovery>
// <available_actions>projects.list</available_actions>
// </tool_error>

Options:

Field	Type	Description
message	string	Required. Human-readable error message.
suggestion	string?	Optional. Maps to <recovery> in the XML output.
availableActions	string[]?	Optional. Maps to <available_actions> in the XML output.

toonSuccess(data)

Creates a standard success response with a TOON-encoded payload via the @toon-format/toon compression schema.

import { toonSuccess } from '@vinkius-core/mcp-fusion';

return toonSuccess(users);                        // Pipe-delimited natively
return toonSuccess(users, { delimiter: ',' });    // Custom delimiter

---

Tool Builders

createTool(name) — Builder Pattern

The fluent builder for composing tools with Zod schemas.

import { createTool } from '@vinkius-core/mcp-fusion';

const tool = createTool<AppContext>('projects');

Method	Returns	Description
.description(desc)	this	The highest-level tool description summary sent to the LLM.
.discriminator(field)	this	Overrides the field key the LLM uses to select operations (default: action).
.annotations(map)	this	Sets explicit ToolAnnotations (e.g. { readOnlyHint: true }).
.tags(...tags)	this	Embeds categorical tags for ToolRegistry.getTools({ filter }) exclusions.
.toonDescription()	this	Injects TOON tabular compression instead of standard Markdown spacing.

Structural Composition

Method	Returns	Description
.commonSchema(zod)	this	Appends a base Zod schema applied identically across every tool branch.
.use(middleware)	this	Pushes a Global Middleware function to the very top of the execution graph.
.action(config)	this	Mounts a flat execution route. Incompatible with .group().
.group(name, ...)	this	Mounts a hierarchical sub-route. Incompatible with .action().

Introspection & Execution

Method	Returns	Description
.buildToolDefinition()	McpTool	Triggers framework compilation loop and freezes internal mappings.
.execute(ctx, args)	Promise	Safely evaluates discriminator chains and fires the middleware array.
.debug(observer)	this	Attaches a DebugObserverFn for pipeline observability. See Observability.
.getActionNames()	string[]	Dumps native flat keys or dot-notated compound keys.
.getActionMetadata()	Object[]	Pulls deep context mapping arrays about execution boundaries natively.

defineTool(name, config) — Declarative Config

The JSON-first API for defining tools without Zod imports.

import { defineTool } from '@vinkius-core/mcp-fusion';

const tool = defineTool<AppContext>('projects', {
    description: 'Manage projects',
    tags: ['core'],
    shared: { workspace_id: 'string' },
    middleware: [authMiddleware],
    actions: {
        list: { readOnly: true, handler: listProjects },
        create: {
            params: { name: { type: 'string', min: 1 } },
            handler: createProject,
        },
    },
    groups: {
        admin: {
            middleware: [requireAdmin],
            actions: { reset: { destructive: true, handler: resetProjects } },
        },
    },
});

Config Fields:

Field	Type	Description
description	string?	Tool description for the LLM.
tags	string[]?	Tags for tag-based filtering.
discriminator	string?	Discriminator field name (default: 'action').
toonDescription	boolean?	Enable TOON token compression for descriptions.
annotations	Record<string, unknown>?	Explicit MCP tool annotations.
shared	ParamsMap?	Parameters injected into every action.
middleware	MiddlewareFn[]?	Global middleware chain.
actions	Record<string, ActionDef>	Action definitions (keyed by action name).
groups	Record<string, GroupDef>?	Nested group definitions.

ActionDef Fields:

Field	Type	Description
description	string?	Action-specific description.
params	ParamsMap | ZodObject?	Parameters (JSON shorthand or Zod).
readOnly	boolean?	Marks as read-only for LLM.
destructive	boolean?	Marks as destructive (⚠️ warning).
idempotent	boolean?	Marks as safe to retry.
returns	Presenter?	MVA Presenter — handler returns raw data.
handler	(ctx, args) => Promise<ToolResponse>	Required. The action handler.

ParamsMap Shorthand Values:

Value	Equivalent
'string'	{ type: 'string' }
'number'	{ type: 'number' }
'boolean'	{ type: 'boolean' }
{ type, min, max, regex, optional, array, enum }	Full descriptor

---

Middleware

defineMiddleware(deriveFn)

Creates a context-deriving middleware definition (tRPC-style):

import { defineMiddleware } from '@vinkius-core/mcp-fusion';

const withUser = defineMiddleware(async (ctx: { token: string }) => {
    const user = await verifyToken(ctx.token);
    return { user };  // Merged into ctx
});

// Convert to MiddlewareFn:
tool.use(withUser.toMiddlewareFn());

Method	Returns	Description
.toMiddlewareFn()	MiddlewareFn	Converts to a standard middleware function.
.derive	Function	The raw derive function.

isMiddlewareDefinition(value)

Type guard to check if a value is a MiddlewareDefinition.

resolveMiddleware(input)

Converts either a MiddlewareDefinition or a plain MiddlewareFn to a MiddlewareFn.

---

Streaming Progress

progress(percent, message)

Creates a ProgressEvent for use in generator handlers:

import { progress } from '@vinkius-core/mcp-fusion';

yield progress(50, 'Building project...');

Field	Type	Description
percent	number	Progress percentage (0–100).
message	string	Human-readable status message.

isProgressEvent(value)

Type guard to check if a yielded value is a ProgressEvent.

MCP Notification Wiring

When attached to an MCP server via attachToServer(), progress events are automatically forwarded to the MCP client as notifications/progress when the client includes a progressToken in its request _meta. Zero configuration required — the framework detects the token and wires the notifications transparently.

Internal Event	MCP Wire Format
yield progress(50, 'Building...')	{ method: 'notifications/progress', params: { progressToken, progress: 50, total: 100, message: 'Building...' } }

When no progressToken is present (the client didn't opt in), progress events are silently consumed — zero overhead.

ProgressSink

For direct usage (testing, custom pipelines), ProgressSink is a callable type:

type ProgressSink = (event: ProgressEvent) => void;

Pass a ProgressSink to builder.execute() or registry.routeCall() as the optional last parameter.

---

Result Monad

Railway-Oriented Programming for composable error handling. See Result Monad Guide for full patterns.

succeed(value)

Wraps a value into Success<T>:

import { succeed } from '@vinkius-core/mcp-fusion';

const result = succeed({ id: '1', name: 'Alice' });
// { ok: true, value: { id: '1', name: 'Alice' } }

fail(response)

Wraps a ToolResponse into Failure:

import { fail, error } from '@vinkius-core/mcp-fusion';

const result = fail(error('User not found'));
// { ok: false, response: ToolResponse }

Types

Type	Fields	Description
Success<T>	ok: true, value: T	Successful result
Failure	ok: false, response: ToolResponse	Failed result
Result<T>	—	Success<T> | Failure discriminated union

---

FusionClient

createFusionClient(transport)

Creates a type-safe client for calling tools through a transport layer:

import { createFusionClient } from '@vinkius-core/mcp-fusion';

type AppRouter = {
    'projects.list': { workspace_id: string };
    'projects.create': { workspace_id: string; name: string };
};

const client = createFusionClient<AppRouter>(transport);

const result = await client.execute('projects.list', { workspace_id: 'ws_1' });

FusionTransport Interface:

interface FusionTransport {
    callTool(name: string, args: Record<string, unknown>): Promise<ToolResponse>;
}

The client splits dotted action paths: 'projects.list' → tool 'projects' + arg { action: 'list' }.

---

ToolRegistry

The unified global router that manages attaching and filtering compiled Builders against the actual bare-metal MCP connection arrays.

import { ToolRegistry } from '@vinkius-core/mcp-fusion';

const registry = new ToolRegistry<AppContext>();

Method	Returns	Description
.register(builder)	void	Mounts a single builder and implicitly fires compilation natively.
.registerAll(...)	void	Maps variable array of builders seamlessly into memory.
.getAllTools()	McpTool[]	Returns all registered tool definitions.
.getTools(filter)	McpTool[]	Filters payload dumps based strictly on inclusion/exclusion tags.
.routeCall(ctx, name, args, progressSink?)	Promise	Proxies execution requests deeply into the assigned Builder. Optional progressSink forwards generator ProgressEvents.
.enableDebug(observer)	void	Propagates a debug observer to ALL registered builders. See Observability.
.has(name)	boolean	Check if a tool is registered.
.clear()	void	Remove all registered tools.
.size	number	Number of registered tools.

.attachToServer(server, options?)

Mounts the registry directly to the underlying MCP Server Protocol instances silently via generic duck-typing logic.

const detach = registry.attachToServer(server, {
    // Limits the exposure of available Tools strictly to allowed tags:
    filter: { tags: ['public'] },
    
    // Injects highly specific Context variables per MCP execution context:
    contextFactory: (extra) => resolveSessionContext(extra),

    // Enable debug observability for ALL tools (optional):
    debug: createDebugObserver(),
});

// Progress events from generator handlers are automatically sent
// as MCP notifications/progress when the client provides a progressToken.
// No configuration needed — zero overhead when not used.

// Optionally strip handlers gracefully from the server memory on shutdown:
detach();

AttachOptions Fields:

Field	Type	Description
filter	ToolFilter?	Tag-based inclusion/exclusion filter.
contextFactory	Function?	Per-request context factory. Supports async.
toolExposition	ToolExposition?	'flat' (default) or 'grouped'. Controls how grouped tools appear on the wire. See Tool Exposition.
actionSeparator	string?	Separator for flat tool names (default: '_'). E.g. '_' → projects_list, '.' → projects.list.
debug	DebugObserverFn?	Debug observer — propagated to all builders. See Observability.
stateSync	StateSyncConfig?	Cache-control and causal invalidation. See State Sync.

ToolExposition

type ToolExposition = 'flat' | 'grouped';

Value	Behavior
'flat'	Each action becomes an independent MCP tool with isolated schema and annotations.
'grouped'	One MCP tool per builder with discriminator enum — optimized for token efficiency and domain cohesion.

ExpositionConfig

interface ExpositionConfig {
    toolExposition?: ToolExposition;  // Default: 'flat'
    actionSeparator?: string;        // Default: '_'
}

See the full Tool Exposition Guide for details.

---

Observability

createDebugObserver(handler?)

Factory function that creates a typed debug event observer. See Observability Guide for comprehensive examples.

import { createDebugObserver } from '@vinkius-core/mcp-fusion';

// Default: pretty console.debug output
const debug = createDebugObserver();

// Custom: forward to telemetry
const debug = createDebugObserver((event) => {
    opentelemetry.addEvent(event.type, event);
});

DebugEvent

Discriminated union of all pipeline events. Use event.type for exhaustive handling.

Event Type	Fields	When Emitted
route	tool, action, timestamp	First event — incoming call matched
validate	tool, action, valid, error?, durationMs, timestamp	After Zod validation
middleware	tool, action, chainLength, timestamp	Before middleware chain (only if middleware exists)
execute	tool, action, durationMs, isError, timestamp	After handler completes
error	tool, action, error, step, timestamp	On unrecoverable pipeline errors

Builder .debug(observer)

Attach a debug observer to a single tool:

const tool = createTool<AppContext>('projects')
    .debug(createDebugObserver())
    .action({ name: 'list', handler: listProjects });

---

State Sync

Prevents LLM Temporal Blindness by injecting cache-control signals into the MCP protocol. See State Sync Guide for comprehensive examples.

StateSyncConfig

interface StateSyncConfig {
    policies: SyncPolicy[];
    defaults?: { cacheControl?: CacheDirective };
}

Field	Type	Description
policies	SyncPolicy[]	Policy rules, evaluated in declaration order (first match wins).
defaults	object?	Fallback cache directive for unmatched tools.

SyncPolicy

interface SyncPolicy {
    match: string;
    cacheControl?: CacheDirective;
    invalidates?: string[];
}

Field	Type	Description
match	string	Dot-separated glob pattern (e.g. sprints.*, **.get).
cacheControl	CacheDirective?	'no-store' or 'immutable' — appended to tool descriptions.
invalidates	string[]?	Glob patterns of tools whose cache is invalidated on success.

CacheDirective

type CacheDirective = 'no-store' | 'immutable';

ResolvedPolicy

interface ResolvedPolicy {
    cacheControl?: CacheDirective;
    invalidates?: readonly string[];
}

PolicyEngine

For advanced use cases (custom pipelines, testing).

Method	Returns	Description
constructor(policies, defaults?)	—	Validates and caches policies
resolve(toolName)	ResolvedPolicy | null	Resolves the applicable policy (cached)

matchGlob(pattern, name)

Pure function for dot-separated glob matching.

import { matchGlob } from '@vinkius-core/mcp-fusion';

matchGlob('sprints.*',  'sprints.get');       // true
matchGlob('sprints.*',  'sprints.tasks.get'); // false
matchGlob('sprints.**', 'sprints.tasks.get'); // true
matchGlob('**',         'anything.at.all');   // true

---

Prompt Engine

Server-side hydrated prompt templates with schema-informed coercion, middleware, and lifecycle sync. See the full Prompt Engine Guide for patterns and examples.

definePrompt(name, config)

Factory for creating type-safe, validated prompt builders:

import { definePrompt, PromptMessage } from '@vinkius-core/mcp-fusion';

const SummarizePrompt = definePrompt<AppContext>('summarize', {
    title: 'Summarize Document',
    args: { docId: 'string', length: { enum: ['short', 'long'] as const } } as const,
    handler: async (ctx, { docId, length }) => ({
        messages: [
            PromptMessage.system('You are a Technical Writer.'),
            PromptMessage.user(`Summarize document ${docId} (${length}).`),
        ],
    }),
});

Parameter	Type	Description
name	string	Unique prompt identifier (slash command name)
config.title	string?	Human-readable display title
config.description	string?	Human-readable description
config.args	PromptParamsMap | ZodObject?	Argument definitions (flat primitives only)
config.tags	string[]?	Capability tags for RBAC filtering
config.middleware	MiddlewareFn[]?	Middleware chain
config.handler	(ctx, args) => Promise<PromptResult>	Hydration handler
Returns	PromptBuilder<TContext>	Ready for PromptRegistry.register()

Flat Schema Constraint

Prompt arguments must be flat primitives (string, number, boolean, enum). MCP clients render them as visual forms — complex structures cannot be represented. Fetch complex data server-side inside the handler.

PromptMessage

Factory methods for creating MCP-compliant prompt messages:

Method	Signature	Description
.system(text)	(string) => PromptMessagePayload	System instruction (encoded as user role per MCP spec)
.user(text)	(string) => PromptMessagePayload	User message
.assistant(text)	(string) => PromptMessagePayload	Seed assistant response (multi-turn)
.image(role, data, mimeType)	(Role, string, string) => PromptMessagePayload	Base64 image
.audio(role, data, mimeType)	(Role, string, string) => PromptMessagePayload	Base64 audio
.resource(role, uri, options?)	(Role, string, Options?) => PromptMessagePayload	Embedded resource
.fromView(builder)	(ResponseBuilder) => PromptMessagePayload[]	MVA-Driven Prompts — decompose a Presenter view

PromptMessage.fromView(builder) NEW

Decomposes a ResponseBuilder (from Presenter.make() or response()) into XML-tagged prompt messages optimized for frontier LLMs:

messages: [
    PromptMessage.system('You are a Compliance Officer.'),
    ...PromptMessage.fromView(InvoicePresenter.make(invoice, ctx)),
    PromptMessage.user('Begin the audit.'),
]

Decomposition layers:

Order	XML Tag	MCP Role	Source
1	<domain_rules>	system	Presenter.systemRules()
2	<dataset>	user	Validated JSON in code fence
3	<visual_context>	user	UI blocks (ECharts, Mermaid, etc.)
4	<system_guidance>	system	LLM hints + HATEOAS action suggestions

PromptRegistry<TContext>

Centralized registry for prompt builders with tag filtering and lifecycle sync:

import { PromptRegistry } from '@vinkius-core/mcp-fusion';

const prompts = new PromptRegistry<AppContext>();
prompts.register(SummarizePrompt);

Method	Returns	Description
.register(builder)	void	Register a single prompt builder
.registerAll(...builders)	void	Register multiple prompt builders
.getAllPrompts()	PromptDefinition[]	Get all prompt definitions for prompts/list
.getPrompts(filter)	PromptDefinition[]	Get filtered prompt definitions
.routeGet(ctx, name, args)	Promise<PromptResult>	Route a prompts/get request
.notifyChanged()	void	Notify clients of catalog changes (debounced)
.has(name)	boolean	Check if a prompt is registered
.clear()	void	Remove all registered prompts
.size	number	Number of registered prompts

Prompt Types

Type	Description
PromptResult	{ description?: string, messages: PromptMessagePayload[] }
PromptMessagePayload	{ role: 'user' | 'assistant', content: PromptContentBlock }
PromptContentBlock	PromptTextContent | PromptImageContent | PromptAudioContent | PromptResourceContent
PromptBuilder<T>	DIP interface: .name, .getDefinition(), .handleGet(), .tags
PromptConfig<T>	Configuration for definePrompt()
PromptParamDef	Union of flat primitive descriptors
PromptParamsMap	Record<string, PromptParamDef>
PromptFilter	{ tags?, anyTag?, exclude? }

---

Domain Model Classes

All underlying structural classes use public fields for highly dense, performant direct property access.

Group

Base hierarchical tree node for plotting Tool paths natively.

Field	Type	Description
parent	Group | null	Upstream target nullated if root block.
childGroups	Group[]	Recursive sub-group tracking arrays.
getFullyQualifiedName()	string	Spits out recursive dot-separated identifiers (e.g. root.parent.child).

Tool

The strictly evaluated LLM parameter payload logic.

Field	Type	Description
inputSchema	string	Fully expanded JSON Schema string definitions natively.
toolAnnotations	Annotations	Bound behavior hint blocks evaluated by language models.