maplestory-mcp-server/dist/tools/base-tool.d.ts

Official-style NEXON MapleStory MCP Server for Claude Desktop - Complete character info, union details, guild data, rankings, and game mechanics

/**
 * Base tool interface and abstract classes for MCP Maple tools
 * Provides common structure and functionality for all MapleStory API tools
 */
import { JSONSchema7 } from 'json-schema';
import { NexonApiClient } from '../api/nexon-client';
import { McpLogger } from '../utils/logger';
export interface ToolContext {
    nexonClient: NexonApiClient;
    logger: McpLogger;
}
export interface ToolResult {
    success: boolean;
    data?: any;
    error?: string;
    metadata?: {
        executionTime?: number;
        cacheHit?: boolean;
        apiCalls?: number;
        [key: string]: any;
    };
}
/**
 * Base interface for all MCP tools
 */
export interface ITool {
    readonly name: string;
    readonly description: string;
    readonly inputSchema: JSONSchema7;
    execute(args: Record<string, any>, context: ToolContext): Promise<any>;
    validate(args: Record<string, any>): boolean;
}
/**
 * Abstract base class for all MCP tools
 * Provides common functionality and structure
 */
export declare abstract class BaseTool implements ITool {
    abstract readonly name: string;
    abstract readonly description: string;
    abstract readonly inputSchema: JSONSchema7;
    private static ajv;
    /**
     * Execute the tool with given arguments
     */
    execute(args: Record<string, any>, context: ToolContext): Promise<any>;
    /**
     * Validate input arguments against the schema
     */
    validate(args: Record<string, any>): boolean;
    /**
     * Tool-specific implementation logic
     */
    protected abstract executeImpl(args: Record<string, any>, context: ToolContext): Promise<any>;
    /**
     * Tool-specific validation logic
     */
    protected validateImpl(_args: Record<string, any>): boolean;
    /**
     * Helper method to format tool results consistently
     */
    protected formatResult(data: any, metadata?: Record<string, any>): ToolResult;
    /**
     * Helper method to format error results consistently
     */
    protected formatError(error: string | Error, metadata?: Record<string, any>): ToolResult;
    /**
     * Helper method to safely get required string parameter
     */
    protected getRequiredString(args: Record<string, any>, key: string): string;
    /**
     * Helper method to safely get optional string parameter
     */
    protected getOptionalString(args: Record<string, any>, key: string, defaultValue?: string): string | undefined;
    /**
     * Helper method to safely get required number parameter
     */
    protected getRequiredNumber(args: Record<string, any>, key: string): number;
    /**
     * Helper method to safely get optional number parameter
     */
    protected getOptionalNumber(args: Record<string, any>, key: string, defaultValue?: number): number;
    /**
     * Helper method to get optional boolean parameter with default value
     */
    protected getOptionalBoolean(args: Record<string, any>, key: string, defaultValue?: boolean): boolean;
    /**
     * Helper method to validate date format (YYYY-MM-DD)
     */
    protected validateDateFormat(date: string): boolean;
    /**
     * Helper method to format date to API format
     */
    protected formatApiDate(date?: Date): string;
    /**
     * Helper method to handle API errors consistently
     */
    protected handleApiError(error: any, operation: string): never;
}
/**
 * Abstract base class for character-related tools
 */
export declare abstract class CharacterTool extends BaseTool {
    protected getCharacterOcid(characterName: string, context: ToolContext): Promise<string>;
}
/**
 * Abstract base class for guild-related tools
 */
export declare abstract class GuildTool extends BaseTool {
    protected getGuildId(guildName: string, worldName: string, context: ToolContext): Promise<string>;
}
/**
 * Tool category enumeration
 */
export declare enum ToolCategory {
    CHARACTER = "character",
    UNION = "union",
    GUILD = "guild",
    RANKING = "ranking",
    UTILITY = "utility"
}
/**
 * Tool metadata interface
 */
export interface ToolMetadata {
    category: ToolCategory;
    tags: string[];
    examples: Array<{
        description: string;
        arguments: Record<string, any>;
    }>;
    rateLimit?: {
        requestsPerMinute: number;
        burstLimit: number;
    };
}
/**
 * Enhanced tool interface with metadata
 */
export interface IEnhancedTool extends ITool {
    readonly metadata: ToolMetadata;
}
/**
 * Enhanced base tool class with metadata support
 */
export declare abstract class EnhancedBaseTool extends BaseTool implements IEnhancedTool {
    abstract readonly metadata: ToolMetadata;
}
//# sourceMappingURL=base-tool.d.ts.map