@access-mcp/shared 0.7.0 → 0.7.1

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

@@ -1,7 +1,9 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { BaseAccessServer } from "../base-server.js";
+import { BaseAccessServer, getRequestContext, getActingUser, getActingUserUid, requestContextStorage, } from "../base-server.js";
 // Concrete implementation for testing
 class TestServer extends BaseAccessServer {
+    // Store the last captured context for verification
+    lastCapturedContext;
     constructor() {
         super("test-server", "1.0.0", "https://api.example.com");
     }
@@ -17,6 +19,14 @@ class TestServer extends BaseAccessServer {
                     },
                 },
             },
+            {
+                name: "get_context",
+                description: "Returns the current request context",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
         ];
     }
     getResources() {
@@ -29,6 +39,23 @@ class TestServer extends BaseAccessServer {
         ];
     }
     async handleToolCall(request) {
+        // Capture the context for verification
+        this.lastCapturedContext = getRequestContext();
+        if (request.params.name === "get_context") {
+            const context = getRequestContext();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            actingUser: context?.actingUser,
+                            actingUserUid: context?.actingUserUid,
+                            requestId: context?.requestId,
+                        }),
+                    },
+                ],
+            };
+        }
         if (request.params.name === "test_tool") {
             const args = request.params.arguments;
             return {
@@ -72,8 +99,9 @@ describe("BaseAccessServer HTTP Mode", () => {
             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");
+            expect(data.tools).toHaveLength(2);
+            expect(data.tools.map((t) => t.name)).toContain("test_tool");
+            expect(data.tools.map((t) => t.name)).toContain("get_context");
         });
     });
     describe("Tool execution endpoint", () => {
@@ -174,3 +202,288 @@ describe("BaseAccessServer helper methods", () => {
         });
     });
 });
+describe("Request Context", () => {
+    describe("getRequestContext", () => {
+        it("should return undefined outside of request context", () => {
+            const context = getRequestContext();
+            expect(context).toBeUndefined();
+        });
+        it("should return context when inside requestContextStorage.run", () => {
+            const testContext = {
+                actingUser: "testuser@access-ci.org",
+                actingUserUid: 12345,
+                requestId: "req-123",
+            };
+            requestContextStorage.run(testContext, () => {
+                const context = getRequestContext();
+                expect(context).toBeDefined();
+                expect(context?.actingUser).toBe("testuser@access-ci.org");
+                expect(context?.actingUserUid).toBe(12345);
+                expect(context?.requestId).toBe("req-123");
+            });
+        });
+    });
+    describe("getActingUser", () => {
+        it("should throw when no acting user is set", () => {
+            expect(() => getActingUser()).toThrow("No acting user specified");
+        });
+        it("should throw when context exists but actingUser is undefined", () => {
+            const testContext = {
+                requestId: "req-123",
+            };
+            requestContextStorage.run(testContext, () => {
+                expect(() => getActingUser()).toThrow("No acting user specified");
+            });
+        });
+        it("should return acting user when set", () => {
+            const testContext = {
+                actingUser: "researcher@access-ci.org",
+            };
+            requestContextStorage.run(testContext, () => {
+                expect(getActingUser()).toBe("researcher@access-ci.org");
+            });
+        });
+    });
+    describe("getActingUserUid", () => {
+        it("should throw when no acting user UID is set", () => {
+            expect(() => getActingUserUid()).toThrow("No acting user UID specified");
+        });
+        it("should throw when context exists but actingUserUid is undefined", () => {
+            const testContext = {
+                actingUser: "testuser@access-ci.org",
+            };
+            requestContextStorage.run(testContext, () => {
+                expect(() => getActingUserUid()).toThrow("No acting user UID specified");
+            });
+        });
+        it("should return acting user UID when set", () => {
+            const testContext = {
+                actingUserUid: 98765,
+            };
+            requestContextStorage.run(testContext, () => {
+                expect(getActingUserUid()).toBe(98765);
+            });
+        });
+    });
+});
+describe("HTTP Mode - Acting User Headers", () => {
+    let server;
+    let port;
+    let baseUrl;
+    beforeEach(async () => {
+        server = new TestServer();
+        port = 3200 + Math.floor(Math.random() * 100);
+        baseUrl = `http://localhost:${port}`;
+        await server.start({ httpPort: port });
+    });
+    describe("X-Acting-User header", () => {
+        it("should extract X-Acting-User header and make it available in context", async () => {
+            const response = await fetch(`${baseUrl}/tools/get_context`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Acting-User": "researcher@access-ci.org",
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(200);
+            const data = await response.json();
+            const result = JSON.parse(data.content[0].text);
+            expect(result.actingUser).toBe("researcher@access-ci.org");
+        });
+        it("should extract X-Acting-User-Uid header and parse as number", async () => {
+            const response = await fetch(`${baseUrl}/tools/get_context`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Acting-User-Uid": "12345",
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(200);
+            const data = await response.json();
+            const result = JSON.parse(data.content[0].text);
+            expect(result.actingUserUid).toBe(12345);
+        });
+        it("should extract X-Request-ID header", async () => {
+            const response = await fetch(`${baseUrl}/tools/get_context`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Request-ID": "req-abc-123",
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(200);
+            const data = await response.json();
+            const result = JSON.parse(data.content[0].text);
+            expect(result.requestId).toBe("req-abc-123");
+        });
+        it("should extract all headers together", async () => {
+            const response = await fetch(`${baseUrl}/tools/get_context`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Acting-User": "admin@access-ci.org",
+                    "X-Acting-User-Uid": "999",
+                    "X-Request-ID": "full-context-test",
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(200);
+            const data = await response.json();
+            const result = JSON.parse(data.content[0].text);
+            expect(result.actingUser).toBe("admin@access-ci.org");
+            expect(result.actingUserUid).toBe(999);
+            expect(result.requestId).toBe("full-context-test");
+        });
+        it("should handle missing headers gracefully", async () => {
+            const response = await fetch(`${baseUrl}/tools/get_context`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(200);
+            const data = await response.json();
+            const result = JSON.parse(data.content[0].text);
+            expect(result.actingUser).toBeUndefined();
+            expect(result.actingUserUid).toBeUndefined();
+            expect(result.requestId).toBeUndefined();
+        });
+        it("should handle invalid UID header gracefully", async () => {
+            const response = await fetch(`${baseUrl}/tools/get_context`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Acting-User-Uid": "not-a-number",
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(200);
+            const data = await response.json();
+            const result = JSON.parse(data.content[0].text);
+            // NaN becomes null when JSON serialized
+            expect(result.actingUserUid).toBeNull();
+        });
+    });
+});
+// Server that requires API key
+class ApiKeyRequiredServer extends BaseAccessServer {
+    constructor() {
+        super("apikey-server", "1.0.0", "https://api.example.com", {
+            requireApiKey: true,
+        });
+    }
+    getTools() {
+        return [
+            {
+                name: "protected_tool",
+                description: "A tool that requires API key",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+        ];
+    }
+    getResources() {
+        return [];
+    }
+    async handleToolCall(request) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ success: true, tool: request.params.name }),
+                },
+            ],
+        };
+    }
+}
+describe("API Key Authentication", () => {
+    let server;
+    let port;
+    let baseUrl;
+    const TEST_API_KEY = "test-secret-api-key-12345";
+    beforeEach(async () => {
+        server = new ApiKeyRequiredServer();
+        port = 3300 + Math.floor(Math.random() * 100);
+        baseUrl = `http://localhost:${port}`;
+        // Set the API key environment variable
+        process.env.MCP_API_KEY = TEST_API_KEY;
+        await server.start({ httpPort: port });
+    });
+    afterEach(() => {
+        delete process.env.MCP_API_KEY;
+    });
+    describe("Tool endpoints with requireApiKey", () => {
+        it("should reject requests without API key", async () => {
+            const response = await fetch(`${baseUrl}/tools/protected_tool`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(401);
+            const data = await response.json();
+            expect(data.error).toContain("Invalid or missing API key");
+        });
+        it("should reject requests with incorrect API key", async () => {
+            const response = await fetch(`${baseUrl}/tools/protected_tool`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Api-Key": "wrong-key",
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(401);
+            const data = await response.json();
+            expect(data.error).toContain("Invalid or missing API key");
+        });
+        it("should accept requests with correct API key", async () => {
+            const response = await fetch(`${baseUrl}/tools/protected_tool`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Api-Key": TEST_API_KEY,
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(200);
+            const data = await response.json();
+            const result = JSON.parse(data.content[0].text);
+            expect(result.success).toBe(true);
+        });
+        it("should allow health endpoint without API key", async () => {
+            const response = await fetch(`${baseUrl}/health`);
+            expect(response.status).toBe(200);
+        });
+        it("should allow tools listing without API key", async () => {
+            const response = await fetch(`${baseUrl}/tools`);
+            expect(response.status).toBe(200);
+            const data = await response.json();
+            expect(data.tools).toHaveLength(1);
+        });
+    });
+    describe("Server misconfiguration", () => {
+        it("should return 500 when MCP_API_KEY is not configured", async () => {
+            // Remove the API key
+            delete process.env.MCP_API_KEY;
+            const response = await fetch(`${baseUrl}/tools/protected_tool`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Api-Key": "some-key",
+                },
+                body: JSON.stringify({ arguments: {} }),
+            });
+            expect(response.status).toBe(500);
+            const data = await response.json();
+            expect(data.error).toContain("Server misconfiguration");
+        });
+    });
+});

package/dist/base-server.d.ts

@@ -2,8 +2,58 @@ 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";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Logger } from "./logger.js";
 export type { Tool, Resource, Prompt, CallToolResult, ReadResourceResult, GetPromptResult };
+/**
+ * Request context passed via AsyncLocalStorage for per-request data.
+ * This allows tool handlers to access request-scoped data like the acting user
+ * without needing to thread it through every function call.
+ */
+export interface RequestContext {
+    /**
+     * The ACCESS ID of the user performing the action.
+     * Passed via X-Acting-User header from the agent.
+     * Format: "username@access-ci.org"
+     */
+    actingUser?: string;
+    /**
+     * The Drupal user ID of the acting user.
+     * Passed via X-Acting-User-Uid header from the agent.
+     * Used for content attribution in Drupal.
+     */
+    actingUserUid?: number;
+    /** Unique request ID for tracing (from X-Request-ID header) */
+    requestId?: string;
+}
+/** AsyncLocalStorage instance for request context */
+export declare const requestContextStorage: AsyncLocalStorage<RequestContext>;
+/**
+ * Get the current request context. Returns undefined if called outside a request.
+ */
+export declare function getRequestContext(): RequestContext | undefined;
+/**
+ * Get the acting user's ACCESS ID from the current request context.
+ * Throws an error if no acting user is set - use this for operations that require attribution.
+ */
+export declare function getActingUser(): string;
+/**
+ * Get the acting user's Drupal UID from the current request context.
+ * Throws an error if no acting user UID is set - use this for Drupal content attribution.
+ */
+export declare function getActingUserUid(): number;
+/**
+ * Options for BaseAccessServer constructor
+ */
+export interface BaseAccessServerOptions {
+    /**
+     * Require API key authentication for tool execution endpoints.
+     * When enabled, requests to /tools/:toolName must include a valid
+     * X-Api-Key header matching the MCP_API_KEY environment variable.
+     * Enable this for servers that perform write operations on behalf of users.
+     */
+    requireApiKey?: boolean;
+}
 export declare abstract class BaseAccessServer {
     protected serverName: string;
     protected version: string;
@@ -15,7 +65,8 @@ export declare abstract class BaseAccessServer {
     private _httpServer?;
     private _httpPort?;
     private _sseTransports;
-    constructor(serverName: string, version: string, baseURL?: string);
+    private _requireApiKey;
+    constructor(serverName: string, version: string, baseURL?: string, options?: BaseAccessServerOptions);
     protected get httpClient(): AxiosInstance;
     private setupHandlers;
     protected abstract getTools(): Tool[];
@@ -90,7 +141,8 @@ export declare abstract class BaseAccessServer {
      */
     private setupServerHandlers;
     /**
-     * Call a tool on another ACCESS-CI MCP server via HTTP
+     * Call a tool on another ACCESS-CI MCP server via HTTP.
+     * Automatically forwards acting user context from the current request.
      */
     protected callRemoteServer(serviceName: string, toolName: string, args?: Record<string, unknown>): Promise<unknown>;
     /**

package/dist/base-server.js

@@ -4,7 +4,41 @@ 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 { AsyncLocalStorage } from "node:async_hooks";
 import { createLogger } from "./logger.js";
+import { traceMcpToolCall } from "./telemetry.js";
+/** AsyncLocalStorage instance for request context */
+export const requestContextStorage = new AsyncLocalStorage();
+/**
+ * Get the current request context. Returns undefined if called outside a request.
+ */
+export function getRequestContext() {
+    return requestContextStorage.getStore();
+}
+/**
+ * Get the acting user's ACCESS ID from the current request context.
+ * Throws an error if no acting user is set - use this for operations that require attribution.
+ */
+export function getActingUser() {
+    const context = getRequestContext();
+    if (!context?.actingUser) {
+        throw new Error("No acting user specified. The X-Acting-User header must be set to the ACCESS ID " +
+            "(username@access-ci.org) of the person performing this action.");
+    }
+    return context.actingUser;
+}
+/**
+ * Get the acting user's Drupal UID from the current request context.
+ * Throws an error if no acting user UID is set - use this for Drupal content attribution.
+ */
+export function getActingUserUid() {
+    const context = getRequestContext();
+    if (!context?.actingUserUid) {
+        throw new Error("No acting user UID specified. The X-Acting-User-Uid header must be set to the Drupal user ID " +
+            "of the person performing this action.");
+    }
+    return context.actingUserUid;
+}
 export class BaseAccessServer {
     serverName;
     version;
@@ -16,10 +50,15 @@ export class BaseAccessServer {
     _httpServer;
     _httpPort;
     _sseTransports = new Map();
-    constructor(serverName, version, baseURL = "https://support.access-ci.org/api") {
+    _requireApiKey;
+    constructor(serverName, version, baseURL = "https://support.access-ci.org/api", options = {}) {
         this.serverName = serverName;
         this.version = version;
         this.baseURL = baseURL;
+        this._requireApiKey = options.requireApiKey ?? false;
+        // Note: Telemetry is initialized via --import flag in the Dockerfile
+        // This ensures OpenTelemetry is set up BEFORE express/http are imported
+        // See packages/shared/src/telemetry-bootstrap.ts
         this.logger = createLogger(serverName);
         this.server = new Server({
             name: serverName,
@@ -297,31 +336,74 @@ export class BaseAccessServer {
         });
         // 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);
-                if (!tool) {
-                    res.status(404).json({ error: `Tool '${toolName}' not found` });
+            // Validate API key if required
+            if (this._requireApiKey) {
+                const expectedApiKey = process.env.MCP_API_KEY;
+                const providedApiKey = req.header("X-Api-Key");
+                if (!expectedApiKey) {
+                    this.logger.error("MCP_API_KEY environment variable not set but requireApiKey is enabled");
+                    res.status(500).json({ error: "Server misconfiguration: API key not configured" });
+                    return;
+                }
+                if (!providedApiKey || providedApiKey !== expectedApiKey) {
+                    this.logger.warn("Unauthorized tool call attempt", {
+                        tool: req.params.toolName,
+                        hasKey: !!providedApiKey,
+                    });
+                    res.status(401).json({ error: "Invalid or missing API key" });
                     return;
                 }
-                // Execute the tool
-                const request = {
-                    method: "tools/call",
-                    params: {
-                        name: toolName,
-                        arguments: args,
-                    },
-                };
-                const result = await this.handleToolCall(request);
-                res.json(result);
             }
-            catch (error) {
-                const errorMessage = error instanceof Error ? error.message : String(error);
-                res.status(500).json({ error: errorMessage });
+            // Extract request context from headers
+            const uidHeader = req.header("X-Acting-User-Uid");
+            const context = {
+                actingUser: req.header("X-Acting-User"),
+                actingUserUid: uidHeader ? parseInt(uidHeader, 10) : undefined,
+                requestId: req.header("X-Request-ID"),
+            };
+            const { toolName } = req.params;
+            const { arguments: args = {} } = req.body;
+            // Validate that the tool exists (before tracing to avoid noisy spans)
+            const tools = this.getTools();
+            const tool = tools.find((t) => t.name === toolName);
+            if (!tool) {
+                res.status(404).json({ error: `Tool '${toolName}' not found` });
+                return;
             }
+            // Run the handler within the request context
+            await requestContextStorage.run(context, async () => {
+                // Wrap tool execution with OpenTelemetry tracing
+                try {
+                    const result = await traceMcpToolCall(toolName, args, async (span) => {
+                        // Add server info to span
+                        span.setAttribute("mcp.server.name", this.serverName);
+                        span.setAttribute("mcp.server.version", this.version);
+                        // Add request context if available
+                        if (context.requestId) {
+                            span.setAttribute("mcp.request.id", context.requestId);
+                        }
+                        // Execute the tool
+                        const request = {
+                            method: "tools/call",
+                            params: {
+                                name: toolName,
+                                arguments: args,
+                            },
+                        };
+                        const toolResult = await this.handleToolCall(request);
+                        // Record result info on span
+                        if (toolResult.isError) {
+                            span.setAttribute("mcp.result.is_error", true);
+                        }
+                        return toolResult;
+                    });
+                    res.json(result);
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    res.status(500).json({ error: errorMessage });
+                }
+            });
         });
         // Start HTTP server
         return new Promise((resolve, reject) => {
@@ -408,18 +490,32 @@ export class BaseAccessServer {
         });
     }
     /**
-     * Call a tool on another ACCESS-CI MCP server via HTTP
+     * Call a tool on another ACCESS-CI MCP server via HTTP.
+     * Automatically forwards acting user context from the current request.
      */
     async callRemoteServer(serviceName, toolName, args = {}) {
         const serviceUrl = this.getServiceEndpoint(serviceName);
         if (!serviceUrl) {
             throw new Error(`Service '${serviceName}' not found. Check ACCESS_MCP_SERVICES environment variable.`);
         }
+        // Forward acting user context to the remote server
+        const context = getRequestContext();
+        const headers = {};
+        if (context?.actingUser) {
+            headers["X-Acting-User"] = context.actingUser;
+        }
+        if (context?.actingUserUid) {
+            headers["X-Acting-User-Uid"] = String(context.actingUserUid);
+        }
+        if (context?.requestId) {
+            headers["X-Request-ID"] = context.requestId;
+        }
         const response = await axios.post(`${serviceUrl}/tools/${toolName}`, {
             arguments: args,
         }, {
             timeout: 30000,
             validateStatus: () => true,
+            headers,
         });
         if (response.status !== 200) {
             throw new Error(`Remote server call failed: ${response.status} ${response.data?.error || response.statusText}`);

package/dist/drupal-auth.d.ts

@@ -16,7 +16,17 @@ export declare class DrupalAuthProvider {
     private userUuid?;
     private httpClient;
     private isAuthenticated;
-    constructor(baseUrl: string, username: string, password: string);
+    private actingUser?;
+    constructor(baseUrl: string, username: string, password: string, actingUser?: string);
+    /**
+     * Set the acting user (ACCESS ID) for attribution.
+     * This user will be set as the author of created content.
+     */
+    setActingUser(accessId: string): void;
+    /**
+     * Get the current acting user
+     */
+    getActingUser(): string | undefined;
     /**
      * Ensure we have a valid session, logging in if necessary
      */

package/dist/drupal-auth.js

@@ -1,4 +1,6 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- Generic HTTP client for untyped JSON:API responses */
 import axios from "axios";
+import { randomUUID } from "crypto";
 /**
  * Authentication provider for Drupal JSON:API using cookie-based auth.
  *
@@ -17,16 +19,31 @@ export class DrupalAuthProvider {
     userUuid;
     httpClient;
     isAuthenticated = false;
-    constructor(baseUrl, username, password) {
+    actingUser;
+    constructor(baseUrl, username, password, actingUser) {
         this.baseUrl = baseUrl;
         this.username = username;
         this.password = password;
+        this.actingUser = actingUser;
         this.httpClient = axios.create({
             baseURL: this.baseUrl,
             timeout: 30000,
             validateStatus: () => true,
         });
     }
+    /**
+     * Set the acting user (ACCESS ID) for attribution.
+     * This user will be set as the author of created content.
+     */
+    setActingUser(accessId) {
+        this.actingUser = accessId;
+    }
+    /**
+     * Get the current acting user
+     */
+    getActingUser() {
+        return this.actingUser;
+    }
     /**
      * Ensure we have a valid session, logging in if necessary
      */
@@ -73,12 +90,18 @@ export class DrupalAuthProvider {
         if (!this.isAuthenticated || !this.sessionCookie || !this.csrfToken) {
             throw new Error("Not authenticated. Call ensureAuthenticated() first.");
         }
-        return {
+        const headers = {
             Cookie: this.sessionCookie,
             "X-CSRF-Token": this.csrfToken,
             "Content-Type": "application/vnd.api+json",
             Accept: "application/vnd.api+json",
+            "X-Request-ID": randomUUID(),
         };
+        // Include acting user header if set - Drupal will use this for attribution
+        if (this.actingUser) {
+            headers["X-Acting-User"] = this.actingUser;
+        }
+        return headers;
     }
     /**
      * Get the authenticated user's UUID

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from "./utils.js";
 export * from "./taxonomies.js";
 export * from "./drupal-auth.js";
 export * from "./logger.js";
+export * from "./telemetry.js";

package/dist/index.js

@@ -4,3 +4,4 @@ export * from "./utils.js";
 export * from "./taxonomies.js";
 export * from "./drupal-auth.js";
 export * from "./logger.js";
+export * from "./telemetry.js";

package/dist/telemetry-bootstrap.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Early telemetry bootstrap for OpenTelemetry auto-instrumentation.
+ *
+ * IMPORTANT: This file must be loaded BEFORE the main server script.
+ * OpenTelemetry auto-instrumentation only works if the SDK is initialized before
+ * the modules it instruments (express, http) are loaded.
+ *
+ * Usage: Load via Node.js --import flag in Dockerfile:
+ *   CMD ["node", "--import", "./packages/shared/dist/telemetry-bootstrap.js", "packages/${PACKAGE}/dist/index.js"]
+ *
+ * The bootstrap automatically reads the server's package.json to get name/version.
+ */
+export {};

package/dist/telemetry-bootstrap.js

@@ -0,0 +1,101 @@
+/**
+ * Early telemetry bootstrap for OpenTelemetry auto-instrumentation.
+ *
+ * IMPORTANT: This file must be loaded BEFORE the main server script.
+ * OpenTelemetry auto-instrumentation only works if the SDK is initialized before
+ * the modules it instruments (express, http) are loaded.
+ *
+ * Usage: Load via Node.js --import flag in Dockerfile:
+ *   CMD ["node", "--import", "./packages/shared/dist/telemetry-bootstrap.js", "packages/${PACKAGE}/dist/index.js"]
+ *
+ * The bootstrap automatically reads the server's package.json to get name/version.
+ */
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION, SEMRESATTRS_DEPLOYMENT_ENVIRONMENT, } from "@opentelemetry/semantic-conventions";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Read the package.json for the target package.
+ * Uses the PACKAGE env var set by the Dockerfile to locate the package.
+ */
+function getPackageInfo() {
+    const packageName = process.env.PACKAGE;
+    if (!packageName) {
+        return { name: "unknown-mcp-server", version: "0.0.0" };
+    }
+    try {
+        // In Docker, packages are at /app/packages/${PACKAGE}
+        const pkgPath = join(process.cwd(), "packages", packageName, "package.json");
+        const content = readFileSync(pkgPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return { name: `mcp-${packageName}`, version: "0.0.0" };
+    }
+}
+function bootstrap() {
+    const pkg = getPackageInfo();
+    const serviceName = pkg.name;
+    const serviceVersion = pkg.version;
+    // Check if telemetry is disabled
+    if (process.env.OTEL_ENABLED === "false") {
+        console.log(`[${serviceName}] OpenTelemetry disabled via OTEL_ENABLED=false`);
+        return;
+    }
+    const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    if (!endpoint) {
+        console.log(`[${serviceName}] OpenTelemetry disabled: no OTEL_EXPORTER_OTLP_ENDPOINT`);
+        return;
+    }
+    // Parse headers from environment (format: "key1=value1,key2=value2")
+    // Note: Values may contain '=' (e.g., base64), so only split on first '='
+    const headersStr = process.env.OTEL_EXPORTER_OTLP_HEADERS || "";
+    const headers = {};
+    headersStr.split(",").forEach((pair) => {
+        const eqIndex = pair.indexOf("=");
+        if (eqIndex > 0) {
+            const key = pair.slice(0, eqIndex).trim();
+            const value = pair.slice(eqIndex + 1).trim();
+            if (key && value) {
+                headers[key] = value;
+            }
+        }
+    });
+    // Set Honeycomb dataset header
+    const dataset = process.env.HONEYCOMB_DATASET || "access-ci";
+    headers["x-honeycomb-dataset"] = dataset;
+    const traceExporter = new OTLPTraceExporter({
+        url: `${endpoint}/v1/traces`,
+        headers,
+    });
+    const resource = resourceFromAttributes({
+        [SEMRESATTRS_SERVICE_NAME]: dataset,
+        [SEMRESATTRS_SERVICE_VERSION]: serviceVersion,
+        [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT]: process.env.ENVIRONMENT || "local",
+        "service.component": serviceName,
+    });
+    const sdk = new NodeSDK({
+        resource,
+        traceExporter,
+        instrumentations: [new HttpInstrumentation(), new ExpressInstrumentation()],
+    });
+    sdk.start();
+    console.log(`[${serviceName}] OpenTelemetry initialized: exporting to ${endpoint}`);
+    // Graceful shutdown - flush spans before exit
+    const shutdown = (signal) => {
+        console.log(`[${serviceName}] Received ${signal}, shutting down OpenTelemetry...`);
+        sdk
+            .shutdown()
+            .then(() => console.log(`[${serviceName}] OpenTelemetry shutdown complete`))
+            .catch((err) => console.error(`[${serviceName}] OpenTelemetry shutdown error`, err));
+        // Don't call process.exit() - let the main process handle termination
+    };
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+}
+// Run bootstrap immediately on import
+bootstrap();

package/dist/telemetry.d.ts

@@ -0,0 +1,69 @@
+/**
+ * OpenTelemetry instrumentation for ACCESS-CI MCP servers.
+ *
+ * Provides distributed tracing with OTLP export to Honeycomb.
+ */
+import { Span, SpanStatusCode, context as otelContext } from "@opentelemetry/api";
+export interface TelemetryConfig {
+    serviceName: string;
+    serviceVersion: string;
+    environment?: string;
+}
+/**
+ * Initialize OpenTelemetry SDK with OTLP export to Honeycomb.
+ *
+ * Environment variables:
+ * - OTEL_ENABLED: Set to "false" to disable telemetry (default: true)
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint URL (e.g., https://api.honeycomb.io)
+ * - OTEL_EXPORTER_OTLP_HEADERS: Headers for auth (e.g., "x-honeycomb-team=your-api-key")
+ * - HONEYCOMB_DATASET: Dataset name (default: "access-ci")
+ */
+export declare function initTelemetry(config: TelemetryConfig): void;
+/**
+ * Shutdown OpenTelemetry SDK and flush pending spans.
+ */
+export declare function shutdownTelemetry(): Promise<void>;
+/**
+ * Get a tracer for creating custom spans.
+ */
+export declare function getTracer(name: string): import("@opentelemetry/api").Tracer;
+/**
+ * Get the current active span.
+ */
+export declare function getCurrentSpan(): Span | undefined;
+/**
+ * Set an attribute on the current span.
+ */
+export declare function setSpanAttribute(key: string, value: string | number | boolean): void;
+/**
+ * Add an event to the current span.
+ */
+export declare function addSpanEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
+/**
+ * Record an error on the current span.
+ */
+export declare function recordSpanError(error: Error): void;
+/**
+ * Create a child span for tracing a specific operation.
+ *
+ * @example
+ * await withSpan("tool.get_events", { "tool.args": JSON.stringify(args) }, async (span) => {
+ *   const result = await fetchEvents(args);
+ *   span.setAttribute("tool.result_count", result.length);
+ *   return result;
+ * });
+ */
+export declare function withSpan<T>(name: string, attributes: Record<string, string | number | boolean>, fn: (span: Span) => Promise<T>): Promise<T>;
+/**
+ * Trace an MCP tool call following OpenTelemetry MCP semantic conventions.
+ * https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/
+ *
+ * @example
+ * const result = await traceMcpToolCall("get_events", args, async (span) => {
+ *   const events = await fetchEvents(args);
+ *   span.setAttribute("mcp.result.count", events.length);
+ *   return events;
+ * });
+ */
+export declare function traceMcpToolCall<T>(toolName: string, args: Record<string, unknown>, fn: (span: Span) => Promise<T>): Promise<T>;
+export { Span, SpanStatusCode, otelContext };

package/dist/telemetry.js

@@ -0,0 +1,219 @@
+/**
+ * OpenTelemetry instrumentation for ACCESS-CI MCP servers.
+ *
+ * Provides distributed tracing with OTLP export to Honeycomb.
+ */
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_SERVICE_VERSION, SEMRESATTRS_DEPLOYMENT_ENVIRONMENT, } from "@opentelemetry/semantic-conventions";
+import { trace, SpanStatusCode, context as otelContext } from "@opentelemetry/api";
+let sdk = null;
+/**
+ * Initialize OpenTelemetry SDK with OTLP export to Honeycomb.
+ *
+ * Environment variables:
+ * - OTEL_ENABLED: Set to "false" to disable telemetry (default: true)
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint URL (e.g., https://api.honeycomb.io)
+ * - OTEL_EXPORTER_OTLP_HEADERS: Headers for auth (e.g., "x-honeycomb-team=your-api-key")
+ * - HONEYCOMB_DATASET: Dataset name (default: "access-ci")
+ */
+export function initTelemetry(config) {
+    // Only initialize once
+    if (sdk !== null) {
+        return;
+    }
+    // Check if telemetry is disabled
+    if (process.env.OTEL_ENABLED === "false") {
+        console.log(`[${config.serviceName}] OpenTelemetry disabled via OTEL_ENABLED=false`);
+        return;
+    }
+    const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    if (!endpoint) {
+        console.log(`[${config.serviceName}] OpenTelemetry disabled: no OTEL_EXPORTER_OTLP_ENDPOINT`);
+        return;
+    }
+    // Parse headers from environment
+    const headersStr = process.env.OTEL_EXPORTER_OTLP_HEADERS || "";
+    const headers = {};
+    headersStr.split(",").forEach((pair) => {
+        const [key, value] = pair.split("=");
+        if (key && value) {
+            headers[key.trim()] = value.trim();
+        }
+    });
+    // Set Honeycomb dataset header to group all services together
+    const dataset = process.env.HONEYCOMB_DATASET || "access-ci";
+    headers["x-honeycomb-dataset"] = dataset;
+    const traceExporter = new OTLPTraceExporter({
+        url: `${endpoint}/v1/traces`,
+        headers,
+    });
+    // Use a common service.name for the Honeycomb dataset, with component to distinguish servers
+    const datasetName = process.env.HONEYCOMB_DATASET || "access-ci";
+    const resource = resourceFromAttributes({
+        [SEMRESATTRS_SERVICE_NAME]: datasetName,
+        [SEMRESATTRS_SERVICE_VERSION]: config.serviceVersion,
+        [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT]: config.environment || process.env.ENVIRONMENT || "local",
+        "service.component": config.serviceName,
+    });
+    sdk = new NodeSDK({
+        resource,
+        traceExporter,
+        instrumentations: [new HttpInstrumentation(), new ExpressInstrumentation()],
+    });
+    sdk.start();
+    console.log(`[${config.serviceName}] OpenTelemetry initialized: exporting to ${endpoint}`);
+    // Graceful shutdown
+    process.on("SIGTERM", () => {
+        sdk
+            ?.shutdown()
+            .then(() => console.log(`[${config.serviceName}] OpenTelemetry shutdown complete`))
+            .catch((err) => console.error(`[${config.serviceName}] OpenTelemetry shutdown error`, err));
+    });
+}
+/**
+ * Shutdown OpenTelemetry SDK and flush pending spans.
+ */
+export async function shutdownTelemetry() {
+    if (sdk) {
+        await sdk.shutdown();
+        sdk = null;
+    }
+}
+/**
+ * Get a tracer for creating custom spans.
+ */
+export function getTracer(name) {
+    return trace.getTracer(name);
+}
+/**
+ * Get the current active span.
+ */
+export function getCurrentSpan() {
+    return trace.getActiveSpan();
+}
+/**
+ * Set an attribute on the current span.
+ */
+export function setSpanAttribute(key, value) {
+    const span = trace.getActiveSpan();
+    if (span) {
+        span.setAttribute(key, value);
+    }
+}
+/**
+ * Add an event to the current span.
+ */
+export function addSpanEvent(name, attributes) {
+    const span = trace.getActiveSpan();
+    if (span) {
+        span.addEvent(name, attributes);
+    }
+}
+/**
+ * Record an error on the current span.
+ */
+export function recordSpanError(error) {
+    const span = trace.getActiveSpan();
+    if (span) {
+        span.recordException(error);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+    }
+}
+/**
+ * Create a child span for tracing a specific operation.
+ *
+ * @example
+ * await withSpan("tool.get_events", { "tool.args": JSON.stringify(args) }, async (span) => {
+ *   const result = await fetchEvents(args);
+ *   span.setAttribute("tool.result_count", result.length);
+ *   return result;
+ * });
+ */
+export async function withSpan(name, attributes, fn) {
+    const tracer = getTracer("access-mcp");
+    return tracer.startActiveSpan(name, { attributes }, async (span) => {
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                span.recordException(error);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+            }
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Trace an MCP tool call following OpenTelemetry MCP semantic conventions.
+ * https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/
+ *
+ * @example
+ * const result = await traceMcpToolCall("get_events", args, async (span) => {
+ *   const events = await fetchEvents(args);
+ *   span.setAttribute("mcp.result.count", events.length);
+ *   return events;
+ * });
+ */
+export async function traceMcpToolCall(toolName, args, fn) {
+    const tracer = getTracer("access-mcp.tools");
+    // Follow MCP semantic conventions: "tools/call {tool_name}"
+    const spanName = `tools/call ${toolName}`;
+    const attributes = {
+        "mcp.method.name": "tools/call",
+        "gen_ai.operation.name": "execute_tool",
+        "gen_ai.tool.name": toolName,
+    };
+    // Add safe argument attributes (redact sensitive values)
+    const safeArgs = redactSensitive(args);
+    attributes["mcp.tool.arguments"] = JSON.stringify(safeArgs);
+    return tracer.startActiveSpan(spanName, { attributes }, async (span) => {
+        try {
+            const result = await fn(span);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                span.recordException(error);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+                span.setAttribute("error.type", error.name || "Error");
+            }
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+/**
+ * Redact sensitive values from arguments before logging.
+ */
+function redactSensitive(data) {
+    const sensitiveKeys = ["password", "token", "secret", "key", "auth", "credential", "api_key"];
+    const redacted = {};
+    for (const [key, value] of Object.entries(data)) {
+        const keyLower = key.toLowerCase();
+        if (sensitiveKeys.some((s) => keyLower.includes(s))) {
+            redacted[key] = "[REDACTED]";
+        }
+        else if (value && typeof value === "object" && !Array.isArray(value)) {
+            redacted[key] = redactSensitive(value);
+        }
+        else {
+            redacted[key] = value;
+        }
+    }
+    return redacted;
+}
+// Re-export for convenience
+export { SpanStatusCode, otelContext };

package/dist/utils.js

@@ -104,6 +104,14 @@ export const CommonNextSteps = {
  * ```
  */
 export async function resolveResourceId(input, searchFn) {
+    // Guard against undefined/null input
+    if (!input) {
+        return {
+            success: false,
+            error: "Resource ID is required",
+            suggestion: "Use search_resources to find valid resource names.",
+        };
+    }
     // If it already looks like a full resource ID (contains dots), return as-is
     if (input.includes(".")) {
         return { success: true, id: input };

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "@access-mcp/shared",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Shared utilities for ACCESS-CI MCP servers",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./telemetry-bootstrap": {
+      "import": "./dist/telemetry-bootstrap.js",
+      "types": "./dist/telemetry-bootstrap.d.ts"
+    }
+  },
   "files": [
     "dist/**/*",
     "README.md"
@@ -33,8 +43,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.16.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.210.0",
+    "@opentelemetry/instrumentation-express": "^0.57.1",
+    "@opentelemetry/instrumentation-http": "^0.210.0",
+    "@opentelemetry/resources": "^2.4.0",
+    "@opentelemetry/sdk-node": "^0.210.0",
+    "@opentelemetry/sdk-trace-node": "^2.4.0",
+    "@opentelemetry/semantic-conventions": "^1.38.0",
     "axios": "^1.6.0",
     "express": "^5.1.0",
+    "router": "^2.2.0",
     "zod": "^3.22.0"
   },
   "devDependencies": {