mcp-ai-agent-guidelines/dist/tools/shared/tool-registry.d.ts

A comprehensive Model Context Protocol server providing advanced tools, resources, and prompts for implementing AI agent best practices

/**
 * Tool Registry for Agent-to-Agent (A2A) Orchestration
 *
 * Provides centralized tool management with:
 * - Tool registration and discovery
 * - Input/output schema validation
 * - Invocation permission management (allowlist)
 * - Tool capability matrix for orchestration planning
 */
import type { z } from "zod";
import type { A2AContext } from "./a2a-context.js";
/**
 * Result of a tool invocation
 */
export interface ToolResult {
    /** Whether the tool executed successfully */
    success: boolean;
    /** Tool output data (structure varies by tool) */
    data?: unknown;
    /** Error message if execution failed */
    error?: string;
    /** Additional metadata about the execution */
    metadata?: {
        toolName: string;
        durationMs: number;
        timestamp: Date;
    };
}
/**
 * Tool handler function signature
 */
export type ToolHandler = (args: unknown, context?: A2AContext) => Promise<ToolResult> | ToolResult;
/**
 * Tool descriptor with metadata and configuration
 */
export interface ToolDescriptor {
    /** Unique tool name (matches MCP tool name) */
    name: string;
    /** Human-readable description */
    description: string;
    /** Zod schema for input validation */
    inputSchema: z.ZodType;
    /** Optional Zod schema for output validation */
    outputSchema?: z.ZodType;
    /** List of tool names this tool is allowed to invoke */
    canInvoke: string[];
    /** Maximum concurrent invocations (undefined = unlimited) */
    maxConcurrency?: number;
    /** Optional tags for categorization */
    tags?: string[];
}
/**
 * Filter for listing tools
 */
export interface ToolFilter {
    /** Filter by tag */
    tags?: string[];
    /** Filter by name pattern (regex) */
    namePattern?: string;
    /** Filter by tools that can invoke a specific tool */
    canInvoke?: string;
}
/**
 * Tool Registry singleton for managing tool registration and invocation
 */
export declare class ToolRegistry {
    private tools;
    private handlers;
    private activeCalls;
    /**
     * Register a tool with its handler
     *
     * @param tool - Tool descriptor
     * @param handler - Tool handler function
     * @throws Error if tool name is already registered
     */
    register(tool: ToolDescriptor, handler: ToolHandler): void;
    /**
     * Check if a tool is registered
     *
     * @param toolName - Tool name to check
     * @returns true if tool is registered
     */
    has(toolName: string): boolean;
    /**
     * Get tool descriptor
     *
     * @param toolName - Tool name
     * @returns Tool descriptor
     * @throws ToolNotFoundError if tool not found
     */
    getDescriptor(toolName: string): ToolDescriptor;
    /**
     * Invoke a tool with the given arguments and context
     *
     * @param toolName - Tool to invoke
     * @param args - Tool arguments
     * @param context - A2A context (optional for top-level invocations)
     * @returns Tool result
     * @throws ToolNotFoundError if tool not found
     * @throws ToolInvocationNotAllowedError if caller not allowed to invoke tool
     * @throws Error if concurrency limit exceeded
     */
    invoke(toolName: string, args: unknown, context?: A2AContext): Promise<ToolResult>;
    /**
     * Check if a tool is allowed to invoke another tool
     *
     * @param callerTool - Calling tool name
     * @param targetTool - Target tool name
     * @throws ToolInvocationNotAllowedError if not allowed
     */
    private checkInvocationPermission;
    /**
     * List all registered tools with optional filtering
     *
     * @param filter - Optional filter criteria
     * @returns Array of tool descriptors
     */
    listTools(filter?: ToolFilter): ToolDescriptor[];
    /**
     * Get capability matrix showing which tools can invoke which
     *
     * @returns Map of tool name to array of invokeable tools
     */
    getCapabilityMatrix(): Map<string, string[]>;
    /**
     * Get tools that can be invoked by a specific tool
     *
     * @param toolName - Tool name
     * @returns Array of invokeable tool names
     */
    getInvokeableTools(toolName: string): string[];
    /**
     * Get current active invocations count for a tool
     *
     * @param toolName - Tool name
     * @returns Number of active invocations
     */
    getActiveInvocations(toolName: string): number;
    /**
     * Clear all registered tools (primarily for testing)
     */
    clear(): void;
    /**
     * Get total number of registered tools
     */
    get size(): number;
}
/**
 * Singleton instance of the tool registry
 */
export declare const toolRegistry: ToolRegistry;
//# sourceMappingURL=tool-registry.d.ts.map