@access-mcp/shared 0.3.2 → 0.5.0

package/dist/__tests__/base-server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/base-server.test.js

@@ -0,0 +1,176 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { BaseAccessServer } from "../base-server.js";
+// Concrete implementation for testing
+class TestServer extends BaseAccessServer {
+    constructor() {
+        super("test-server", "1.0.0", "https://api.example.com");
+    }
+    getTools() {
+        return [
+            {
+                name: "test_tool",
+                description: "A test tool",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        message: { type: "string" },
+                    },
+                },
+            },
+        ];
+    }
+    getResources() {
+        return [
+            {
+                uri: "test://resource",
+                name: "Test Resource",
+                mimeType: "application/json",
+            },
+        ];
+    }
+    async handleToolCall(request) {
+        if (request.params.name === "test_tool") {
+            const args = request.params.arguments;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ echo: args.message || "no message" }),
+                    },
+                ],
+            };
+        }
+        return this.errorResponse(`Unknown tool: ${request.params.name}`);
+    }
+}
+describe("BaseAccessServer HTTP Mode", () => {
+    let server;
+    let port;
+    let baseUrl;
+    beforeEach(async () => {
+        server = new TestServer();
+        port = 3100 + Math.floor(Math.random() * 100);
+        baseUrl = `http://localhost:${port}`;
+        await server.start({ httpPort: port });
+    });
+    afterEach(async () => {
+        // Server cleanup handled by process exit
+    });
+    describe("Health endpoint", () => {
+        it("should return health status", async () => {
+            const response = await fetch(`${baseUrl}/health`);
+            const data = await response.json();
+            expect(response.status).toBe(200);
+            expect(data.server).toBe("test-server");
+            expect(data.version).toBe("1.0.0");
+            expect(data.status).toBe("healthy");
+            expect(data.timestamp).toBeDefined();
+        });
+    });
+    describe("Tools endpoint", () => {
+        it("should list available tools", async () => {
+            const response = await fetch(`${baseUrl}/tools`);
+            const data = await response.json();
+            expect(response.status).toBe(200);
+            expect(data.tools).toHaveLength(1);
+            expect(data.tools[0].name).toBe("test_tool");
+        });
+    });
+    describe("Tool execution endpoint", () => {
+        it("should execute a tool via POST", async () => {
+            const response = await fetch(`${baseUrl}/tools/test_tool`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ arguments: { message: "hello" } }),
+            });
+            const data = await response.json();
+            expect(response.status).toBe(200);
+            expect(data.content).toBeDefined();
+            const result = JSON.parse(data.content[0].text);
+            expect(result.echo).toBe("hello");
+        });
+        it("should return 404 for unknown tool", async () => {
+            const response = await fetch(`${baseUrl}/tools/unknown_tool`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(404);
+            const data = await response.json();
+            expect(data.error).toContain("not found");
+        });
+    });
+    describe("SSE endpoint", () => {
+        it("should accept SSE connections", async () => {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 1000);
+            try {
+                const response = await fetch(`${baseUrl}/sse`, {
+                    signal: controller.signal,
+                });
+                expect(response.status).toBe(200);
+                expect(response.headers.get("content-type")).toContain("text/event-stream");
+            }
+            catch (e) {
+                // AbortError is expected when we timeout
+                if (e instanceof Error && e.name !== "AbortError") {
+                    throw e;
+                }
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        });
+    });
+});
+describe("BaseAccessServer helper methods", () => {
+    let server;
+    beforeEach(() => {
+        server = new TestServer();
+    });
+    describe("errorResponse", () => {
+        it("should create error response without hint", () => {
+            const result = server["errorResponse"]("Something went wrong");
+            expect(result.isError).toBe(true);
+            const textContent = result.content[0];
+            const content = JSON.parse(textContent.text);
+            expect(content.error).toBe("Something went wrong");
+            expect(content.hint).toBeUndefined();
+        });
+        it("should create error response with hint", () => {
+            const result = server["errorResponse"]("Invalid input", "Try using a number");
+            expect(result.isError).toBe(true);
+            const textContent = result.content[0];
+            const content = JSON.parse(textContent.text);
+            expect(content.error).toBe("Invalid input");
+            expect(content.hint).toBe("Try using a number");
+        });
+    });
+    describe("createJsonResource", () => {
+        it("should create JSON resource response", () => {
+            const result = server["createJsonResource"]("test://data", { foo: "bar" });
+            expect(result.contents).toHaveLength(1);
+            expect(result.contents[0].uri).toBe("test://data");
+            expect(result.contents[0].mimeType).toBe("application/json");
+            expect(JSON.parse(result.contents[0].text)).toEqual({ foo: "bar" });
+        });
+    });
+    describe("createMarkdownResource", () => {
+        it("should create Markdown resource response", () => {
+            const result = server["createMarkdownResource"]("test://doc", "# Hello");
+            expect(result.contents).toHaveLength(1);
+            expect(result.contents[0].uri).toBe("test://doc");
+            expect(result.contents[0].mimeType).toBe("text/markdown");
+            expect(result.contents[0].text).toBe("# Hello");
+        });
+    });
+    describe("createTextResource", () => {
+        it("should create plain text resource response", () => {
+            const result = server["createTextResource"]("test://text", "Hello world");
+            expect(result.contents).toHaveLength(1);
+            expect(result.contents[0].uri).toBe("test://text");
+            expect(result.contents[0].mimeType).toBe("text/plain");
+            expect(result.contents[0].text).toBe("Hello world");
+        });
+    });
+});

package/dist/__tests__/interserver.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/interserver.integration.test.js

@@ -0,0 +1,116 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { spawn } from "child_process";
+import path from "path";
+/**
+ * Integration tests for inter-server HTTP communication
+ * These tests start actual MCP servers and test tool execution via HTTP
+ */
+describe("Inter-server Communication Integration Tests", () => {
+    let nsfServer;
+    const NSF_PORT = 3199;
+    const NSF_URL = `http://localhost:${NSF_PORT}`;
+    beforeAll(async () => {
+        // Start NSF Awards server in HTTP mode
+        const serverPath = path.resolve(process.cwd(), "packages/nsf-awards/dist/index.js");
+        nsfServer = spawn("node", [serverPath], {
+            env: {
+                ...process.env,
+                PORT: String(NSF_PORT),
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        // Wait for server to be ready
+        await new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new Error("Server startup timeout"));
+            }, 10000);
+            nsfServer.stdout?.on("data", (data) => {
+                if (data.toString().includes("HTTP server running")) {
+                    clearTimeout(timeout);
+                    resolve();
+                }
+            });
+            nsfServer.on("error", (err) => {
+                clearTimeout(timeout);
+                reject(err);
+            });
+        });
+    }, 15000);
+    afterAll(async () => {
+        if (nsfServer) {
+            nsfServer.kill("SIGTERM");
+            // Wait for process to exit
+            await new Promise((resolve) => {
+                nsfServer.on("exit", () => resolve());
+                setTimeout(resolve, 1000); // Fallback timeout
+            });
+        }
+    });
+    describe("NSF Awards Server HTTP API", () => {
+        it("should respond to health check", async () => {
+            const response = await fetch(`${NSF_URL}/health`);
+            const data = await response.json();
+            expect(response.status).toBe(200);
+            expect(data.status).toBe("healthy");
+            expect(data.server).toBe("access-mcp-nsf-awards");
+        });
+        it("should list available tools", async () => {
+            const response = await fetch(`${NSF_URL}/tools`);
+            const data = await response.json();
+            expect(response.status).toBe(200);
+            expect(data.tools).toBeDefined();
+            expect(Array.isArray(data.tools)).toBe(true);
+            const toolNames = data.tools.map((t) => t.name);
+            expect(toolNames).toContain("search_nsf_awards");
+        });
+        it("should execute search_nsf_awards tool via HTTP", async () => {
+            const response = await fetch(`${NSF_URL}/tools/search_nsf_awards`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    arguments: {
+                        keyword: "machine learning",
+                        limit: 5,
+                    },
+                }),
+            });
+            const data = await response.json();
+            expect(response.status).toBe(200);
+            expect(data.content).toBeDefined();
+            expect(data.content[0].type).toBe("text");
+            // Parse the result
+            const result = JSON.parse(data.content[0].text);
+            expect(result).toBeDefined();
+        }, 15000);
+        it("should return 404 for unknown tool", async () => {
+            const response = await fetch(`${NSF_URL}/tools/nonexistent_tool`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(404);
+        });
+    });
+    describe("SSE Endpoint", () => {
+        it("should accept SSE connections on /sse", async () => {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 2000);
+            try {
+                const response = await fetch(`${NSF_URL}/sse`, {
+                    signal: controller.signal,
+                });
+                expect(response.status).toBe(200);
+                expect(response.headers.get("content-type")).toContain("text/event-stream");
+            }
+            catch (e) {
+                // AbortError is expected
+                if (e instanceof Error && e.name !== "AbortError") {
+                    throw e;
+                }
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        });
+    });
+});

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", () => {
@@ -38,12 +38,12 @@ describe("Utils", () => {
             };
             expect(handleApiError(error)).toBe("API error: 404 Not Found");
         });
-        test("should handle error message", () => {
-            const error = { message: "Network error" };
+        test("should handle Error instance", () => {
+            const error = new Error("Network error");
             expect(handleApiError(error)).toBe("Network error");
         });
         test("should handle unknown error", () => {
-            const error = {};
+            const error = "some string error";
             expect(handleApiError(error)).toBe("Unknown API error");
         });
     });

package/dist/base-server.d.ts

@@ -1,6 +1,8 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Tool, Resource, Prompt, CallToolResult, ReadResourceResult, GetPromptResult, CallToolRequest, ReadResourceRequest, GetPromptRequest } from "@modelcontextprotocol/sdk/types.js";
 import { AxiosInstance } from "axios";
+export type { Tool, Resource, Prompt, CallToolResult, ReadResourceResult, GetPromptResult };
 export declare abstract class BaseAccessServer {
     protected serverName: string;
     protected version: string;
@@ -10,30 +12,37 @@ export declare abstract class BaseAccessServer {
     private _httpClient?;
     private _httpServer?;
     private _httpPort?;
+    private _sseTransports;
     constructor(serverName: string, version: string, baseURL?: string);
     protected get httpClient(): AxiosInstance;
     private setupHandlers;
-    protected abstract getTools(): any[];
-    protected abstract getResources(): any[];
-    protected abstract handleToolCall(request: any): Promise<any>;
+    protected abstract getTools(): Tool[];
+    protected abstract getResources(): Resource[];
+    protected abstract handleToolCall(request: CallToolRequest): Promise<CallToolResult>;
     /**
      * Get available prompts - override in subclasses to provide prompts
      */
-    protected getPrompts(): any[];
+    protected getPrompts(): Prompt[];
     /**
      * Handle resource read requests - override in subclasses
      */
-    protected handleResourceRead(request: any): Promise<any>;
+    protected handleResourceRead(request: ReadResourceRequest): Promise<ReadResourceResult>;
     /**
      * Handle get prompt requests - override in subclasses
      */
-    protected handleGetPrompt(request: any): Promise<any>;
+    protected handleGetPrompt(request: GetPromptRequest): Promise<GetPromptResult>;
+    /**
+     * 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): CallToolResult;
     /**
      * Helper method to create a JSON resource response
      * @param uri The resource URI
      * @param data The data to return as JSON
      */
-    protected createJsonResource(uri: string, data: any): {
+    protected createJsonResource(uri: string, data: unknown): {
         contents: {
             uri: string;
             mimeType: string;
@@ -71,13 +80,17 @@ export declare abstract class BaseAccessServer {
         httpPort?: number;
     }): Promise<void>;
     /**
-     * Start HTTP service layer for inter-server communication
+     * Start HTTP service layer with SSE support for remote MCP connections
      */
     private startHttpService;
+    /**
+     * Set up MCP handlers on a server instance
+     */
+    private setupServerHandlers;
     /**
      * Call a tool on another ACCESS-CI MCP server via HTTP
      */
-    protected callRemoteServer(serviceName: string, toolName: string, args?: Record<string, any>): Promise<any>;
+    protected callRemoteServer(serviceName: string, toolName: string, args?: Record<string, unknown>): Promise<unknown>;
     /**
      * Get service endpoint from environment configuration
      * Expected format: ACCESS_MCP_SERVICES=nsf-awards=http://localhost:3001,xdmod-metrics=http://localhost:3002

package/dist/base-server.js

@@ -1,5 +1,6 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import express from "express";
@@ -12,6 +13,7 @@ export class BaseAccessServer {
     _httpClient;
     _httpServer;
     _httpPort;
+    _sseTransports = new Map();
     constructor(serverName, version, baseURL = "https://support.access-ci.org/api") {
         this.serverName = serverName;
         this.version = version;
@@ -78,9 +80,12 @@ export class BaseAccessServer {
                     content: [
                         {
                             type: "text",
-                            text: `Error: ${errorMessage}`,
+                            text: JSON.stringify({
+                                error: errorMessage
+                            }),
                         },
                     ],
+                    isError: true,
                 };
             }
         });
@@ -132,13 +137,32 @@ export class BaseAccessServer {
      * Handle resource read requests - override in subclasses
      */
     async handleResourceRead(request) {
-        throw new Error("Resource reading not supported by this server");
+        throw new Error(`Resource reading not supported by this server: ${request.params.uri}`);
     }
     /**
      * Handle get prompt requests - override in subclasses
      */
     async handleGetPrompt(request) {
-        throw new Error("Prompt not found");
+        throw new Error(`Prompt not found: ${request.params.name}`);
+    }
+    /**
+     * 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
@@ -206,7 +230,7 @@ export class BaseAccessServer {
         }
     }
     /**
-     * Start HTTP service layer for inter-server communication
+     * Start HTTP service layer with SSE support for remote MCP connections
      */
     async startHttpService() {
         if (!this._httpPort)
@@ -222,7 +246,43 @@ export class BaseAccessServer {
                 timestamp: new Date().toISOString()
             });
         });
-        // List available tools endpoint
+        // SSE endpoint for MCP remote connections
+        this._httpServer.get('/sse', async (req, res) => {
+            console.log(`[${this.serverName}] New SSE connection`);
+            const transport = new SSEServerTransport('/messages', res);
+            const sessionId = transport.sessionId;
+            this._sseTransports.set(sessionId, transport);
+            // Clean up on disconnect
+            res.on('close', () => {
+                console.log(`[${this.serverName}] SSE connection closed: ${sessionId}`);
+                this._sseTransports.delete(sessionId);
+            });
+            // Create a new server instance for this SSE connection
+            const sseServer = new Server({
+                name: this.serverName,
+                version: this.version,
+            }, {
+                capabilities: {
+                    resources: {},
+                    tools: {},
+                    prompts: {},
+                },
+            });
+            // Set up handlers for the SSE server (same as main server)
+            this.setupServerHandlers(sseServer);
+            await sseServer.connect(transport);
+        });
+        // Messages endpoint for SSE POST messages
+        this._httpServer.post('/messages', async (req, res) => {
+            const sessionId = req.query.sessionId;
+            const transport = this._sseTransports.get(sessionId);
+            if (!transport) {
+                res.status(404).json({ error: 'Session not found' });
+                return;
+            }
+            await transport.handlePostMessage(req, res, req.body);
+        });
+        // List available tools endpoint (for inter-server communication)
         this._httpServer.get('/tools', (req, res) => {
             try {
                 const tools = this.getTools();
@@ -232,7 +292,7 @@ export class BaseAccessServer {
                 res.status(500).json({ error: 'Failed to list tools' });
             }
         });
-        // Tool execution endpoint
+        // Tool execution endpoint (for inter-server communication)
         this._httpServer.post('/tools/:toolName', async (req, res) => {
             try {
                 const { toolName } = req.params;
@@ -241,10 +301,12 @@ export class BaseAccessServer {
                 const tools = this.getTools();
                 const tool = tools.find(t => t.name === toolName);
                 if (!tool) {
-                    return res.status(404).json({ error: `Tool '${toolName}' not found` });
+                    res.status(404).json({ error: `Tool '${toolName}' not found` });
+                    return;
                 }
                 // Execute the tool
                 const request = {
+                    method: "tools/call",
                     params: {
                         name: toolName,
                         arguments: args
@@ -265,6 +327,83 @@ export class BaseAccessServer {
             }).on('error', reject);
         });
     }
+    /**
+     * Set up MCP handlers on a server instance
+     */
+    setupServerHandlers(server) {
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            try {
+                return { tools: this.getTools() };
+            }
+            catch (error) {
+                return { tools: [] };
+            }
+        });
+        server.setRequestHandler(ListResourcesRequestSchema, async () => {
+            try {
+                return { resources: this.getResources() };
+            }
+            catch (error) {
+                return { resources: [] };
+            }
+        });
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                return await this.handleToolCall(request);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error("Error handling tool call:", errorMessage);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: errorMessage
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+        server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            try {
+                return await this.handleResourceRead(request);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error("Error reading resource:", errorMessage);
+                return {
+                    contents: [
+                        {
+                            uri: request.params.uri,
+                            mimeType: "text/plain",
+                            text: `Error: ${errorMessage}`,
+                        },
+                    ],
+                };
+            }
+        });
+        server.setRequestHandler(ListPromptsRequestSchema, async () => {
+            try {
+                return { prompts: this.getPrompts() };
+            }
+            catch (error) {
+                return { prompts: [] };
+            }
+        });
+        server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            try {
+                return await this.handleGetPrompt(request);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error("Error getting prompt:", errorMessage);
+                throw error;
+            }
+        });
+    }
     /**
      * Call a tool on another ACCESS-CI MCP server via HTTP
      */

package/dist/drupal-auth.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Authentication provider for Drupal JSON:API using cookie-based auth.
+ *
+ * This is a temporary implementation for development/testing.
+ * Production should use Key Auth with the access_mcp_author module.
+ *
+ * @see ../../../access-qa-planning/06-mcp-authentication.md
+ */
+export declare class DrupalAuthProvider {
+    private baseUrl;
+    private username;
+    private password;
+    private sessionCookie?;
+    private csrfToken?;
+    private logoutToken?;
+    private userUuid?;
+    private httpClient;
+    private isAuthenticated;
+    constructor(baseUrl: string, username: string, password: string);
+    /**
+     * Ensure we have a valid session, logging in if necessary
+     */
+    ensureAuthenticated(): Promise<void>;
+    /**
+     * Login to Drupal and store session cookie + CSRF token
+     */
+    login(): Promise<void>;
+    /**
+     * Get headers required for authenticated JSON:API requests
+     */
+    getAuthHeaders(): Record<string, string>;
+    /**
+     * Get the authenticated user's UUID
+     */
+    getUserUuid(): string | undefined;
+    /**
+     * Invalidate the current session
+     */
+    invalidate(): void;
+    /**
+     * Make an authenticated GET request to JSON:API
+     */
+    get(path: string): Promise<any>;
+    /**
+     * Make an authenticated POST request to JSON:API
+     */
+    post(path: string, data: any): Promise<any>;
+    /**
+     * Make an authenticated PATCH request to JSON:API
+     */
+    patch(path: string, data: any): Promise<any>;
+    /**
+     * Make an authenticated DELETE request to JSON:API
+     */
+    delete(path: string): Promise<any>;
+    /**
+     * Handle JSON:API response, throwing on errors
+     */
+    private handleResponse;
+}

package/dist/drupal-auth.js

@@ -0,0 +1,188 @@
+import axios from "axios";
+/**
+ * Authentication provider for Drupal JSON:API using cookie-based auth.
+ *
+ * This is a temporary implementation for development/testing.
+ * Production should use Key Auth with the access_mcp_author module.
+ *
+ * @see ../../../access-qa-planning/06-mcp-authentication.md
+ */
+export class DrupalAuthProvider {
+    baseUrl;
+    username;
+    password;
+    sessionCookie;
+    csrfToken;
+    logoutToken;
+    userUuid;
+    httpClient;
+    isAuthenticated = false;
+    constructor(baseUrl, username, password) {
+        this.baseUrl = baseUrl;
+        this.username = username;
+        this.password = password;
+        this.httpClient = axios.create({
+            baseURL: this.baseUrl,
+            timeout: 30000,
+            validateStatus: () => true,
+        });
+    }
+    /**
+     * Ensure we have a valid session, logging in if necessary
+     */
+    async ensureAuthenticated() {
+        if (!this.isAuthenticated) {
+            await this.login();
+        }
+    }
+    /**
+     * Login to Drupal and store session cookie + CSRF token
+     */
+    async login() {
+        const response = await this.httpClient.post("/user/login?_format=json", {
+            name: this.username,
+            pass: this.password,
+        }, {
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+        if (response.status !== 200) {
+            throw new Error(`Drupal login failed: ${response.status} ${response.statusText}`);
+        }
+        // Extract session cookie from Set-Cookie header
+        const setCookie = response.headers["set-cookie"];
+        if (setCookie && setCookie.length > 0) {
+            // Parse the session cookie (format: SESS...=value; path=/; ...)
+            const cookieParts = setCookie[0].split(";")[0];
+            this.sessionCookie = cookieParts;
+        }
+        // Store CSRF token and logout token from response
+        this.csrfToken = response.data.csrf_token;
+        this.logoutToken = response.data.logout_token;
+        this.userUuid = response.data.current_user?.uuid;
+        if (!this.sessionCookie || !this.csrfToken) {
+            throw new Error("Login succeeded but missing session cookie or CSRF token");
+        }
+        this.isAuthenticated = true;
+    }
+    /**
+     * Get headers required for authenticated JSON:API requests
+     */
+    getAuthHeaders() {
+        if (!this.isAuthenticated || !this.sessionCookie || !this.csrfToken) {
+            throw new Error("Not authenticated. Call ensureAuthenticated() first.");
+        }
+        return {
+            "Cookie": this.sessionCookie,
+            "X-CSRF-Token": this.csrfToken,
+            "Content-Type": "application/vnd.api+json",
+            "Accept": "application/vnd.api+json",
+        };
+    }
+    /**
+     * Get the authenticated user's UUID
+     */
+    getUserUuid() {
+        return this.userUuid;
+    }
+    /**
+     * Invalidate the current session
+     */
+    invalidate() {
+        this.sessionCookie = undefined;
+        this.csrfToken = undefined;
+        this.logoutToken = undefined;
+        this.userUuid = undefined;
+        this.isAuthenticated = false;
+    }
+    /**
+     * Make an authenticated GET request to JSON:API
+     */
+    async get(path) {
+        await this.ensureAuthenticated();
+        const response = await this.httpClient.get(path, {
+            headers: this.getAuthHeaders(),
+        });
+        if (response.status === 401 || response.status === 403) {
+            // Session may have expired, try re-authenticating
+            this.invalidate();
+            await this.ensureAuthenticated();
+            const retryResponse = await this.httpClient.get(path, {
+                headers: this.getAuthHeaders(),
+            });
+            return this.handleResponse(retryResponse);
+        }
+        return this.handleResponse(response);
+    }
+    /**
+     * Make an authenticated POST request to JSON:API
+     */
+    async post(path, data) {
+        await this.ensureAuthenticated();
+        const response = await this.httpClient.post(path, data, {
+            headers: this.getAuthHeaders(),
+        });
+        if (response.status === 401 || response.status === 403) {
+            this.invalidate();
+            await this.ensureAuthenticated();
+            const retryResponse = await this.httpClient.post(path, data, {
+                headers: this.getAuthHeaders(),
+            });
+            return this.handleResponse(retryResponse);
+        }
+        return this.handleResponse(response);
+    }
+    /**
+     * Make an authenticated PATCH request to JSON:API
+     */
+    async patch(path, data) {
+        await this.ensureAuthenticated();
+        const response = await this.httpClient.patch(path, data, {
+            headers: this.getAuthHeaders(),
+        });
+        if (response.status === 401 || response.status === 403) {
+            this.invalidate();
+            await this.ensureAuthenticated();
+            const retryResponse = await this.httpClient.patch(path, data, {
+                headers: this.getAuthHeaders(),
+            });
+            return this.handleResponse(retryResponse);
+        }
+        return this.handleResponse(response);
+    }
+    /**
+     * Make an authenticated DELETE request to JSON:API
+     */
+    async delete(path) {
+        await this.ensureAuthenticated();
+        const response = await this.httpClient.delete(path, {
+            headers: this.getAuthHeaders(),
+        });
+        if (response.status === 401 || response.status === 403) {
+            this.invalidate();
+            await this.ensureAuthenticated();
+            const retryResponse = await this.httpClient.delete(path, {
+                headers: this.getAuthHeaders(),
+            });
+            return this.handleResponse(retryResponse);
+        }
+        return this.handleResponse(response);
+    }
+    /**
+     * Handle JSON:API response, throwing on errors
+     */
+    handleResponse(response) {
+        if (response.status >= 200 && response.status < 300) {
+            return response.data;
+        }
+        // JSON:API error format
+        if (response.data?.errors) {
+            const errors = response.data.errors
+                .map((e) => e.detail || e.title || "Unknown error")
+                .join("; ");
+            throw new Error(`Drupal API error (${response.status}): ${errors}`);
+        }
+        throw new Error(`Drupal API error: ${response.status} ${response.statusText}`);
+    }
+}

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from "./base-server.js";
 export * from "./types.js";
 export * from "./utils.js";
 export * from "./taxonomies.js";
+export * from "./drupal-auth.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export * from "./base-server.js";
 export * from "./types.js";
 export * from "./utils.js";
 export * from "./taxonomies.js";
+export * from "./drupal-auth.js";

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;
+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;
+    };
+};

package/dist/utils.js

@@ -1,15 +1,84 @@
 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) {
     return `/${version}/${endpoint}`;
 }
 export function handleApiError(error) {
-    if (error.response?.data?.message) {
-        return error.response.data.message;
+    const axiosError = error;
+    if (axiosError.response?.data?.message) {
+        return axiosError.response.data.message;
+    }
+    if (axiosError.response?.status) {
+        return `API error: ${axiosError.response.status} ${axiosError.response.statusText}`;
+    }
+    if (error instanceof Error) {
+        return error.message;
     }
-    if (error.response?.status) {
-        return `API error: ${error.response.status} ${error.response.statusText}`;
+    return "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 error.message || "Unknown API error";
+    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.5.0",
   "description": "Shared utilities for ACCESS-CI MCP servers",
   "type": "module",
   "main": "dist/index.js",