@access-mcp/shared/dist/utils.d.ts

Shared utilities for ACCESS-CI MCP servers

export declare function sanitizeGroupId(groupId: string): string;
export declare function formatApiUrl(version: string, endpoint: string): string;
export declare function handleApiError(error: unknown): string;
/**
 * LLM-Friendly Response Utilities
 *
 * These utilities help create responses that guide LLMs through multi-step workflows,
 * provide clear next actions, and improve error handling.
 */
export interface NextStep {
    action: string;
    description: string;
    tool?: string;
    parameters?: Record<string, unknown>;
}
export interface LLMResponse<T = unknown> {
    data?: T;
    count?: number;
    next_steps?: NextStep[];
    suggestions?: string[];
    related_tools?: string[];
    context?: Record<string, unknown>;
}
export interface LLMError {
    error: string;
    error_type: "validation" | "not_found" | "api_error" | "invalid_parameter";
    suggestions?: string[];
    next_steps?: NextStep[];
    did_you_mean?: string[];
    related_queries?: string[];
}
/**
 * Add helpful next steps to a successful response
 */
export declare function addNextSteps<T>(data: T, nextSteps: NextStep[]): LLMResponse<T>;
/**
 * Create an LLM-friendly error response with suggestions
 */
export declare function createLLMError(error: string, errorType: LLMError["error_type"], options?: {
    suggestions?: string[];
    nextSteps?: NextStep[];
    didYouMean?: string[];
    relatedQueries?: string[];
}): LLMError;
/**
 * Add discovery suggestions when returning empty results
 */
export declare function addDiscoverySuggestions<T>(data: T[], discoverySteps: NextStep[]): LLMResponse<T[]>;
/**
 * Common next step templates for cross-server consistency
 */
export declare const CommonNextSteps: {
    discoverResources: {
        action: string;
        description: string;
        tool: string;
        parameters: {
            include_resource_ids: boolean;
        };
    };
    narrowResults: (currentCount: number, suggestedFilters: string[]) => {
        action: string;
        description: string;
    };
    exploreRelated: (relatedTool: string, description: string) => {
        action: string;
        description: string;
        tool: string;
    };
    refineSearch: (suggestions: string[]) => {
        action: string;
        description: string;
    };
};
/**
 * Resource ID Resolution Utilities
 *
 * These utilities help resolve human-readable resource names (e.g., "Anvil", "Delta")
 * to full resource IDs (e.g., "anvil.purdue.access-ci.org").
 */
export interface ResourceMatch {
    id: string;
    name: string;
}
export type ResolveResult = {
    success: true;
    id: string;
} | {
    success: false;
    error: string;
    suggestion?: string;
};
/**
 * Resolve a human-readable name to a resource ID.
 *
 * @param input - The input string (name or ID)
 * @param searchFn - A function that searches for resources by name and returns matches
 * @returns ResolveResult with either the resolved ID or an error message
 *
 * @example
 * ```ts
 * const result = await resolveResourceId("Anvil", async (query) => {
 *   const resources = await searchResources({ query });
 *   return resources.map(r => ({ id: r.id, name: r.name }));
 * });
 *
 * if (result.success) {
 *   console.log(result.id); // "anvil.purdue.access-ci.org"
 * } else {
 *   console.log(result.error); // "Multiple resources match..."
 * }
 * ```
 */
export declare function resolveResourceId(input: string, searchFn: (query: string) => Promise<ResourceMatch[]>): Promise<ResolveResult>;