@access-mcp/shared 0.3.2 → 0.3.3

package/dist/__tests__/utils.test.js

@@ -8,8 +8,8 @@ describe("Utils", () => {
         test("should keep valid characters", () => {
             expect(sanitizeGroupId("test.group-123")).toBe("test.group-123");
         });
-        test("should handle empty string", () => {
-            expect(sanitizeGroupId("")).toBe("");
+        test("should throw error for empty string", () => {
+            expect(() => sanitizeGroupId("")).toThrow("groupId parameter is required and cannot be null or undefined");
         });
     });
     describe("formatApiUrl", () => {

package/dist/base-server.d.ts

@@ -28,6 +28,18 @@ export declare abstract class BaseAccessServer {
      * Handle get prompt requests - override in subclasses
      */
     protected handleGetPrompt(request: any): Promise<any>;
+    /**
+     * Helper method to create a standard error response (MCP 2025 compliant)
+     * @param message The error message
+     * @param hint Optional suggestion for how to fix the error
+     */
+    protected errorResponse(message: string, hint?: string): {
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        isError: boolean;
+    };
     /**
      * Helper method to create a JSON resource response
      * @param uri The resource URI

package/dist/base-server.js

@@ -78,9 +78,12 @@ export class BaseAccessServer {
                     content: [
                         {
                             type: "text",
-                            text: `Error: ${errorMessage}`,
+                            text: JSON.stringify({
+                                error: errorMessage
+                            }),
                         },
                     ],
+                    isError: true,
                 };
             }
         });
@@ -140,6 +143,25 @@ export class BaseAccessServer {
     async handleGetPrompt(request) {
         throw new Error("Prompt not found");
     }
+    /**
+     * Helper method to create a standard error response (MCP 2025 compliant)
+     * @param message The error message
+     * @param hint Optional suggestion for how to fix the error
+     */
+    errorResponse(message, hint) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: message,
+                        ...(hint && { hint }),
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
     /**
      * Helper method to create a JSON resource response
      * @param uri The resource URI

package/dist/types.d.ts

@@ -1,58 +1,25 @@
-import { z } from "zod";
-export declare const AffinityGroupSchema: z.ZodObject<{
-    group_id: z.ZodString;
-    name: z.ZodOptional<z.ZodString>;
-    description: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    group_id: string;
-    name?: string | undefined;
-    description?: string | undefined;
-}, {
-    group_id: string;
-    name?: string | undefined;
-    description?: string | undefined;
-}>;
-export declare const EventSchema: z.ZodObject<{
-    id: z.ZodString;
-    title: z.ZodString;
-    description: z.ZodOptional<z.ZodString>;
-    start_date: z.ZodOptional<z.ZodString>;
-    end_date: z.ZodOptional<z.ZodString>;
-    location: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    title: string;
-    id: string;
-    description?: string | undefined;
-    start_date?: string | undefined;
-    end_date?: string | undefined;
-    location?: string | undefined;
-}, {
-    title: string;
-    id: string;
-    description?: string | undefined;
-    start_date?: string | undefined;
-    end_date?: string | undefined;
-    location?: string | undefined;
-}>;
-export declare const KnowledgeBaseResourceSchema: z.ZodObject<{
-    id: z.ZodString;
-    title: z.ZodString;
-    content: z.ZodOptional<z.ZodString>;
-    category: z.ZodOptional<z.ZodString>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    title: string;
-    id: string;
-    content?: string | undefined;
-    category?: string | undefined;
-    tags?: string[] | undefined;
-}, {
-    title: string;
-    id: string;
-    content?: string | undefined;
-    category?: string | undefined;
-    tags?: string[] | undefined;
-}>;
-export type AffinityGroup = z.infer<typeof AffinityGroupSchema>;
-export type Event = z.infer<typeof EventSchema>;
-export type KnowledgeBaseResource = z.infer<typeof KnowledgeBaseResourceSchema>;
+export interface UniversalSearchParams {
+    query?: string;
+    id?: string;
+    type?: string;
+    tags?: string[];
+    date?: "today" | "upcoming" | "past" | "this_week" | "this_month";
+    limit?: number;
+    offset?: number;
+    sort?: string;
+    order?: "asc" | "desc";
+}
+export interface UniversalResponse<T> {
+    total: number;
+    items: T[];
+}
+export interface UniversalResponseWithHints<T> extends UniversalResponse<T> {
+    hints?: {
+        next?: string;
+        tags?: string[];
+    };
+}
+export interface StandardErrorResponse {
+    error: string;
+    hint?: string;
+}

package/dist/types.js

@@ -1,21 +1 @@
-import { z } from "zod";
-export const AffinityGroupSchema = z.object({
-    group_id: z.string(),
-    name: z.string().optional(),
-    description: z.string().optional(),
-});
-export const EventSchema = z.object({
-    id: z.string(),
-    title: z.string(),
-    description: z.string().optional(),
-    start_date: z.string().optional(),
-    end_date: z.string().optional(),
-    location: z.string().optional(),
-});
-export const KnowledgeBaseResourceSchema = z.object({
-    id: z.string(),
-    title: z.string(),
-    content: z.string().optional(),
-    category: z.string().optional(),
-    tags: z.array(z.string()).optional(),
-});
+export {};

package/dist/utils.d.ts

@@ -1,3 +1,74 @@
 export declare function sanitizeGroupId(groupId: string): string;
 export declare function formatApiUrl(version: string, endpoint: string): string;
 export declare function handleApiError(error: any): 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, any>;
+}
+export interface LLMResponse<T = any> {
+    data?: T;
+    count?: number;
+    next_steps?: NextStep[];
+    suggestions?: string[];
+    related_tools?: string[];
+    context?: Record<string, any>;
+}
+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;
+    };
+};

package/dist/utils.js

@@ -1,4 +1,7 @@
 export function sanitizeGroupId(groupId) {
+    if (!groupId) {
+        throw new Error("groupId parameter is required and cannot be null or undefined");
+    }
     return groupId.replace(/[^a-zA-Z0-9.-]/g, "");
 }
 export function formatApiUrl(version, endpoint) {
@@ -13,3 +16,65 @@ export function handleApiError(error) {
     }
     return error.message || "Unknown API error";
 }
+/**
+ * Add helpful next steps to a successful response
+ */
+export function addNextSteps(data, nextSteps) {
+    return {
+        data,
+        next_steps: nextSteps,
+    };
+}
+/**
+ * Create an LLM-friendly error response with suggestions
+ */
+export function createLLMError(error, errorType, options = {}) {
+    return {
+        error,
+        error_type: errorType,
+        ...options,
+    };
+}
+/**
+ * Add discovery suggestions when returning empty results
+ */
+export function addDiscoverySuggestions(data, discoverySteps) {
+    if (data.length === 0) {
+        return {
+            data,
+            count: 0,
+            next_steps: discoverySteps,
+            suggestions: [
+                "No results found. Try the suggested next steps to discover available options.",
+            ],
+        };
+    }
+    return {
+        data,
+        count: data.length,
+    };
+}
+/**
+ * Common next step templates for cross-server consistency
+ */
+export const CommonNextSteps = {
+    discoverResources: {
+        action: "discover_resources",
+        description: "Find available compute resources to filter by",
+        tool: "search_resources",
+        parameters: { include_resource_ids: true },
+    },
+    narrowResults: (currentCount, suggestedFilters) => ({
+        action: "narrow_results",
+        description: `Currently showing ${currentCount} results. Add filters to narrow down: ${suggestedFilters.join(", ")}`,
+    }),
+    exploreRelated: (relatedTool, description) => ({
+        action: "explore_related",
+        description,
+        tool: relatedTool,
+    }),
+    refineSearch: (suggestions) => ({
+        action: "refine_search",
+        description: `Try these refinements: ${suggestions.join(", ")}`,
+    }),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@access-mcp/shared",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Shared utilities for ACCESS-CI MCP servers",
   "type": "module",
   "main": "dist/index.js",