Class: ToolRegistry<TContext>

Defined in: packages/core/src/core/registry/ToolRegistry.ts:77

Centralized registry for MCP tool builders.

Manages tool registration, filtered retrieval, call routing, and MCP server attachment.

Example

const registry = new ToolRegistry<AppContext>();

// Register individually
registry.register(projectsTool);

// Register multiple at once
registry.registerAll(usersTool, billingTool, adminTool);

// Query registered tools
registry.has('projects');  // true
registry.size;             // 4

Type Parameters

Type Parameter	Default type	Description
TContext	void	Application context type shared across all tools

Constructors

Constructor

new ToolRegistry<TContext>(): ToolRegistry<TContext>;

Returns

ToolRegistry<TContext>

Accessors

size

Get Signature

get size(): number;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:275

Number of registered tools.

Returns

number

Methods

attachToServer()

attachToServer(server, options?): Promise<DetachFn>;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:261

Attach this registry to an MCP server.

Registers tools/list and tools/call handlers on the server. Supports both McpServer (high-level SDK) and Server (low-level SDK) via duck-type detection.

Parameters

Parameter	Type	Description
server	unknown	Any MCP server instance (duck-typed)
options	AttachOptions<TContext>	Attachment options (context factory, tag filter)

Returns

Promise<DetachFn>

A detach function for clean teardown

Example

// Basic attachment
const detach = registry.attachToServer(server, {
    contextFactory: (extra) => createAppContext(extra),
});

// With tag filtering
registry.attachToServer(server, {
    contextFactory: (extra) => createAppContext(extra),
    filter: { tags: ['core'] },
});

// Clean teardown (e.g. in tests)
detach();

See

• DetachFn for the teardown function type
• AttachOptions for all options

---

clear()

clear(): void;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:272

Remove all registered tools.

Returns

void

---

enableDebug()

enableDebug(observer): void;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:294

Enable debug observability for ALL registered tools.

Propagates the debug observer to every registered builder that supports it (duck-typed via .debug() method).

Also enables registry-level debug events (unknown tool errors).

Parameters

Parameter	Type	Description
observer	DebugObserverFn	A DebugObserverFn created by createDebugObserver()

Returns

void

Example

const debug = createDebugObserver();
registry.enableDebug(debug);
// Now ALL tools + registry routing emit debug events

---

enableTelemetry()

enableTelemetry(sink): void;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:354

Enable telemetry emission for ALL registered tools.

Propagates the TelemetrySink to every registered builder that supports it (duck-typed via .telemetry() method). This enables real-time event emission to the Inspector TUI via Shadow Socket IPC.

Parameters

Parameter	Type	Description
sink	TelemetrySink	A TelemetrySink from startServer() or TelemetryBus

Returns

void

---

enableTracing()

enableTracing(tracer): void;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:332

Enable OpenTelemetry-compatible tracing for ALL registered tools.

Propagates the tracer to every registered builder that supports it (duck-typed via .tracing() method).

Also enables registry-level tracing for unknown tool routing errors.

Important: When both enableDebug() and enableTracing() are active, tracing takes precedence and debug events are NOT emitted from tool builders.

Parameters

Parameter	Type	Description
tracer	FusionTracer	A FusionTracer (or OTel Tracer) instance

Returns

void

Example

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('mcp-fusion');
registry.enableTracing(tracer);
// Now ALL tools + registry routing emit OTel spans

See

• FusionTracer for the tracer interface contract
• SpanStatusCode for status code semantics

---

getAllTools()

getAllTools(): {
  _meta?: {
   [key: string]: unknown;
  };
  annotations?: {
     destructiveHint?: boolean;
     idempotentHint?: boolean;
     openWorldHint?: boolean;
     readOnlyHint?: boolean;
     title?: string;
  };
  description?: string;
  execution?: {
     taskSupport?: "optional" | "required" | "forbidden";
  };
  icons?: {
     mimeType?: string;
     sizes?: string[];
     src: string;
     theme?: "light" | "dark";
  }[];
  inputSchema: {
   [key: string]: unknown;
     properties?: {
      [key: string]: object;
     };
     required?: string[];
     type: "object";
  };
  name: string;
  outputSchema?: {
   [key: string]: unknown;
     properties?: {
      [key: string]: object;
     };
     required?: string[];
     type: "object";
  };
  title?: string;
}[];

Defined in: packages/core/src/core/registry/ToolRegistry.ts:136

Get all registered MCP tool definitions.

Returns the compiled McpTool objects for all registered builders.

Returns

{ _meta?: { [key: string]: unknown; }; annotations?: { destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean; readOnlyHint?: boolean; title?: string; }; description?: string; execution?: { taskSupport?: "optional" | "required" | "forbidden"; }; icons?: { mimeType?: string; sizes?: string[]; src: string; theme?: "light" | "dark"; }[]; inputSchema: { [key: string]: unknown; properties?: { [key: string]: object; }; required?: string[]; type: "object"; }; name: string; outputSchema?: { [key: string]: unknown; properties?: { [key: string]: object; }; required?: string[]; type: "object"; }; title?: string; }[]

Array of MCP Tool objects

---

getBuilders()

getBuilders(): Iterable<ToolBuilder<TContext>>;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:152

Get an iterable of all registered tool builders.

Used by the introspection module to extract action metadata and presenter information from each builder.

Returns

Iterable<ToolBuilder<TContext>>

Iterable of registered ToolBuilder instances

---

getTools()

getTools(filter): {
  _meta?: {
   [key: string]: unknown;
  };
  annotations?: {
     destructiveHint?: boolean;
     idempotentHint?: boolean;
     openWorldHint?: boolean;
     readOnlyHint?: boolean;
     title?: string;
  };
  description?: string;
  execution?: {
     taskSupport?: "optional" | "required" | "forbidden";
  };
  icons?: {
     mimeType?: string;
     sizes?: string[];
     src: string;
     theme?: "light" | "dark";
  }[];
  inputSchema: {
   [key: string]: unknown;
     properties?: {
      [key: string]: object;
     };
     required?: string[];
     type: "object";
  };
  name: string;
  outputSchema?: {
   [key: string]: unknown;
     properties?: {
      [key: string]: object;
     };
     required?: string[];
     type: "object";
  };
  title?: string;
}[];

Defined in: packages/core/src/core/registry/ToolRegistry.ts:176

Get tool definitions filtered by tags.

Uses the ToolFilter to include/exclude tools based on their capability tags.

Parameters

Parameter	Type	Description
filter	ToolFilter	Tag-based filter configuration

Returns

{ _meta?: { [key: string]: unknown; }; annotations?: { destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean; readOnlyHint?: boolean; title?: string; }; description?: string; execution?: { taskSupport?: "optional" | "required" | "forbidden"; }; icons?: { mimeType?: string; sizes?: string[]; src: string; theme?: "light" | "dark"; }[]; inputSchema: { [key: string]: unknown; properties?: { [key: string]: object; }; required?: string[]; type: "object"; }; name: string; outputSchema?: { [key: string]: unknown; properties?: { [key: string]: object; }; required?: string[]; type: "object"; }; title?: string; }[]

Filtered array of MCP Tool objects

Example

// Only core tools
const coreTools = registry.getTools({ tags: ['core'] });

// Everything except internal tools
const publicTools = registry.getTools({ exclude: ['internal'] });

See

ToolFilter for filter options

---

has()

has(name): boolean;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:269

Check if a tool with the given name is registered.

Parameters

Parameter	Type
name	string

Returns

boolean

---

register()

register(builder): void;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:101

Register a single tool builder.

Validates that the tool name is unique and triggers GroupedToolBuilder.buildToolDefinition to compile the tool definition at registration time.

Parameters

Parameter	Type	Description
builder	ToolBuilder<TContext>	A built or unbuilt tool builder

Returns

void

Throws

If a tool with the same name is already registered

Example

registry.register(
    createTool<AppContext>('projects')
        .action({ name: 'list', handler: listProjects })
);

---

registerAll()

registerAll(...builders): void;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:123

Register multiple tool builders at once.

Parameters

Parameter	Type	Description
...builders	ToolBuilder<TContext>[]	One or more tool builders

Returns

void

Example

registry.registerAll(usersTool, projectsTool, billingTool);

---

routeCall()

routeCall(
   ctx, 
   name, 
   args, 
   progressSink?, 
signal?): Promise<ToolResponse>;

Defined in: packages/core/src/core/registry/ToolRegistry.ts:202

Route an incoming tool call to the correct builder.

Looks up the builder by name and delegates to its execute() method. Returns an error response if the tool is not found.

Parameters

Parameter	Type	Description
ctx	TContext	Application context
name	string	Tool name from the incoming MCP call
args	Record<string, unknown>	Raw arguments from the LLM
progressSink?	ProgressSink	Optional callback for streaming progress notifications. When called from attachToServer(), this is automatically wired to MCP notifications/progress. When omitted, progress events are silently consumed.
signal?	AbortSignal	-

Returns

Promise<ToolResponse>

The handler's response

Example

const response = await registry.routeCall(ctx, 'projects', {
    action: 'list',
    workspace_id: 'ws_123',
});