@access-mcp/shared 0.3.3 → 0.6.0

package/dist/base-server.js

@@ -1,21 +1,26 @@
 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";
+import { createLogger } from "./logger.js";
 export class BaseAccessServer {
     serverName;
     version;
     baseURL;
     server;
     transport;
+    logger;
     _httpClient;
     _httpServer;
     _httpPort;
+    _sseTransports = new Map();
     constructor(serverName, version, baseURL = "https://support.access-ci.org/api") {
         this.serverName = serverName;
         this.version = version;
         this.baseURL = baseURL;
+        this.logger = createLogger(serverName);
         this.server = new Server({
             name: serverName,
             version: version,
@@ -73,13 +78,13 @@ export class BaseAccessServer {
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                console.error("Error handling tool call:", errorMessage);
+                this.logger.error("Error handling tool call", { error: errorMessage });
                 return {
                     content: [
                         {
                             type: "text",
                             text: JSON.stringify({
-                                error: errorMessage
+                                error: errorMessage,
                             }),
                         },
                     ],
@@ -93,7 +98,7 @@ export class BaseAccessServer {
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                console.error("Error reading resource:", errorMessage);
+                this.logger.error("Error reading resource", { error: errorMessage });
                 return {
                     contents: [
                         {
@@ -120,7 +125,7 @@ export class BaseAccessServer {
             }
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
-                console.error("Error getting prompt:", errorMessage);
+                this.logger.error("Error getting prompt", { error: errorMessage });
                 throw error;
             }
         });
@@ -135,13 +140,13 @@ 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)
@@ -218,7 +223,7 @@ export class BaseAccessServer {
         if (options?.httpPort) {
             this._httpPort = options.httpPort;
             await this.startHttpService();
-            console.log(`${this.serverName} HTTP server running on port ${this._httpPort}`);
+            this.logger.info("HTTP server running", { port: this._httpPort });
         }
         else {
             // Only connect stdio transport when NOT in HTTP mode
@@ -228,7 +233,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)
@@ -236,41 +241,79 @@ export class BaseAccessServer {
         this._httpServer = express();
         this._httpServer.use(express.json());
         // Health check endpoint
-        this._httpServer.get('/health', (req, res) => {
+        this._httpServer.get("/health", (req, res) => {
             res.json({
                 server: this.serverName,
                 version: this.version,
-                status: 'healthy',
-                timestamp: new Date().toISOString()
+                status: "healthy",
+                timestamp: new Date().toISOString(),
             });
         });
-        // List available tools endpoint
-        this._httpServer.get('/tools', (req, res) => {
+        // SSE endpoint for MCP remote connections
+        this._httpServer.get("/sse", async (req, res) => {
+            this.logger.debug("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", () => {
+                this.logger.debug("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();
                 res.json({ tools });
             }
             catch (error) {
-                res.status(500).json({ error: 'Failed to list tools' });
+                res.status(500).json({ error: "Failed to list tools" });
             }
         });
-        // Tool execution endpoint
-        this._httpServer.post('/tools/:toolName', async (req, res) => {
+        // Tool execution endpoint (for inter-server communication)
+        this._httpServer.post("/tools/:toolName", async (req, res) => {
             try {
                 const { toolName } = req.params;
                 const { arguments: args = {} } = req.body;
                 // Validate that the tool exists
                 const tools = this.getTools();
-                const tool = tools.find(t => t.name === toolName);
+                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
-                    }
+                        arguments: args,
+                    },
                 };
                 const result = await this.handleToolCall(request);
                 res.json(result);
@@ -282,9 +325,86 @@ export class BaseAccessServer {
         });
         // Start HTTP server
         return new Promise((resolve, reject) => {
-            this._httpServer.listen(this._httpPort, '0.0.0.0', () => {
+            this._httpServer.listen(this._httpPort, "0.0.0.0", () => {
                 resolve();
-            }).on('error', reject);
+            }).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);
+                this.logger.error("Error handling tool call", { error: 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);
+                this.logger.error("Error reading resource", { error: 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);
+                this.logger.error("Error getting prompt", { error: errorMessage });
+                throw error;
+            }
         });
     }
     /**
@@ -296,10 +416,10 @@ export class BaseAccessServer {
             throw new Error(`Service '${serviceName}' not found. Check ACCESS_MCP_SERVICES environment variable.`);
         }
         const response = await axios.post(`${serviceUrl}/tools/${toolName}`, {
-            arguments: args
+            arguments: args,
         }, {
             timeout: 30000,
-            validateStatus: () => true
+            validateStatus: () => true,
         });
         if (response.status !== 200) {
             throw new Error(`Remote server call failed: ${response.status} ${response.data?.error || response.statusText}`);
@@ -315,8 +435,8 @@ export class BaseAccessServer {
         if (!services)
             return null;
         const serviceMap = {};
-        services.split(',').forEach(service => {
-            const [name, url] = service.split('=');
+        services.split(",").forEach((service) => {
+            const [name, url] = service.split("=");
             if (name && url) {
                 serviceMap[name.trim()] = url.trim();
             }

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,5 @@ export * from "./base-server.js";
 export * from "./types.js";
 export * from "./utils.js";
 export * from "./taxonomies.js";
+export * from "./drupal-auth.js";
+export * from "./logger.js";

package/dist/index.js

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

package/dist/logger.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Structured logger for ACCESS-CI MCP servers.
+ *
+ * This logger writes to stderr to avoid interfering with MCP's JSON-RPC
+ * communication on stdout. It supports log levels that can be controlled
+ * via the LOG_LEVEL environment variable.
+ *
+ * Log levels (in order of severity):
+ * - error: Always shown, for critical errors
+ * - warn: Warnings that don't prevent operation
+ * - info: Important informational messages
+ * - debug: Detailed debugging information (disabled by default)
+ *
+ * Usage:
+ *   import { createLogger } from "@access-mcp/shared";
+ *   const logger = createLogger("my-server");
+ *   logger.info("Server started");
+ *   logger.error("Failed to connect", { url: "http://..." });
+ */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+interface LogContext {
+    [key: string]: unknown;
+}
+export interface Logger {
+    error: (message: string, context?: LogContext) => void;
+    warn: (message: string, context?: LogContext) => void;
+    info: (message: string, context?: LogContext) => void;
+    debug: (message: string, context?: LogContext) => void;
+}
+/**
+ * Create a logger instance for a specific server.
+ *
+ * @param serverName - The name of the server (e.g., "access-mcp-events")
+ * @returns A logger instance with error, warn, info, and debug methods
+ */
+export declare function createLogger(serverName: string): Logger;
+/**
+ * A no-op logger that silently discards all log messages.
+ * Useful for testing or when logging should be completely disabled.
+ */
+export declare const silentLogger: Logger;
+export {};

package/dist/logger.js

@@ -0,0 +1,82 @@
+/**
+ * Structured logger for ACCESS-CI MCP servers.
+ *
+ * This logger writes to stderr to avoid interfering with MCP's JSON-RPC
+ * communication on stdout. It supports log levels that can be controlled
+ * via the LOG_LEVEL environment variable.
+ *
+ * Log levels (in order of severity):
+ * - error: Always shown, for critical errors
+ * - warn: Warnings that don't prevent operation
+ * - info: Important informational messages
+ * - debug: Detailed debugging information (disabled by default)
+ *
+ * Usage:
+ *   import { createLogger } from "@access-mcp/shared";
+ *   const logger = createLogger("my-server");
+ *   logger.info("Server started");
+ *   logger.error("Failed to connect", { url: "http://..." });
+ */
+const LOG_LEVELS = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+};
+function getLogLevel() {
+    const level = process.env.LOG_LEVEL?.toLowerCase();
+    if (level && level in LOG_LEVELS) {
+        return level;
+    }
+    // Default to 'warn' for production (errors and warnings only)
+    return "warn";
+}
+function shouldLog(level) {
+    const currentLevel = getLogLevel();
+    return LOG_LEVELS[level] <= LOG_LEVELS[currentLevel];
+}
+function formatMessage(serverName, level, message, context) {
+    const timestamp = new Date().toISOString();
+    const contextStr = context ? ` ${JSON.stringify(context)}` : "";
+    return `[${timestamp}] [${serverName}] [${level.toUpperCase()}] ${message}${contextStr}`;
+}
+/**
+ * Create a logger instance for a specific server.
+ *
+ * @param serverName - The name of the server (e.g., "access-mcp-events")
+ * @returns A logger instance with error, warn, info, and debug methods
+ */
+export function createLogger(serverName) {
+    return {
+        error: (message, context) => {
+            if (shouldLog("error")) {
+                console.error(formatMessage(serverName, "error", message, context));
+            }
+        },
+        warn: (message, context) => {
+            if (shouldLog("warn")) {
+                console.error(formatMessage(serverName, "warn", message, context));
+            }
+        },
+        info: (message, context) => {
+            if (shouldLog("info")) {
+                console.error(formatMessage(serverName, "info", message, context));
+            }
+        },
+        debug: (message, context) => {
+            if (shouldLog("debug")) {
+                console.error(formatMessage(serverName, "debug", message, context));
+            }
+        },
+    };
+}
+/**
+ * A no-op logger that silently discards all log messages.
+ * Useful for testing or when logging should be completely disabled.
+ */
+export const silentLogger = {
+    error: () => { },
+    warn: () => { },
+    info: () => { },
+    debug: () => { },
+};