@access-mcp/shared 0.5.0 → 0.7.0

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

@@ -16,6 +16,7 @@ describe("Inter-server Communication Integration Tests", () => {
             env: {
                 ...process.env,
                 PORT: String(NSF_PORT),
+                LOG_LEVEL: "info", // Enable info logging to see startup message
             },
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -24,7 +25,8 @@ describe("Inter-server Communication Integration Tests", () => {
             const timeout = setTimeout(() => {
                 reject(new Error("Server startup timeout"));
             }, 10000);
-            nsfServer.stdout?.on("data", (data) => {
+            // Logger writes to stderr, not stdout
+            nsfServer.stderr?.on("data", (data) => {
                 if (data.toString().includes("HTTP server running")) {
                     clearTimeout(timeout);
                     resolve();

package/dist/base-server.d.ts

@@ -2,6 +2,7 @@ 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 { Logger } from "./logger.js";
 export type { Tool, Resource, Prompt, CallToolResult, ReadResourceResult, GetPromptResult };
 export declare abstract class BaseAccessServer {
     protected serverName: string;
@@ -9,6 +10,7 @@ export declare abstract class BaseAccessServer {
     protected baseURL: string;
     protected server: Server;
     protected transport: StdioServerTransport;
+    protected logger: Logger;
     private _httpClient?;
     private _httpServer?;
     private _httpPort?;

package/dist/base-server.js

@@ -4,12 +4,14 @@ 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;
@@ -18,6 +20,7 @@ export class BaseAccessServer {
         this.serverName = serverName;
         this.version = version;
         this.baseURL = baseURL;
+        this.logger = createLogger(serverName);
         this.server = new Server({
             name: serverName,
             version: version,
@@ -75,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,
                             }),
                         },
                     ],
@@ -95,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: [
                         {
@@ -122,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;
             }
         });
@@ -220,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
@@ -238,23 +241,23 @@ 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(),
             });
         });
         // 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);
+        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', () => {
-                console.log(`[${this.serverName}] SSE connection closed: ${sessionId}`);
+            res.on("close", () => {
+                this.logger.debug("SSE connection closed", { sessionId });
                 this._sseTransports.delete(sessionId);
             });
             // Create a new server instance for this SSE connection
@@ -273,33 +276,33 @@ export class BaseAccessServer {
             await sseServer.connect(transport);
         });
         // Messages endpoint for SSE POST messages
-        this._httpServer.post('/messages', async (req, res) => {
+        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' });
+                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) => {
+        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 (for inter-server communication)
-        this._httpServer.post('/tools/:toolName', async (req, res) => {
+        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) {
                     res.status(404).json({ error: `Tool '${toolName}' not found` });
                     return;
@@ -309,8 +312,8 @@ export class BaseAccessServer {
                     method: "tools/call",
                     params: {
                         name: toolName,
-                        arguments: args
-                    }
+                        arguments: args,
+                    },
                 };
                 const result = await this.handleToolCall(request);
                 res.json(result);
@@ -322,9 +325,9 @@ 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);
         });
     }
     /**
@@ -353,13 +356,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,
                             }),
                         },
                     ],
@@ -373,7 +376,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: [
                         {
@@ -399,7 +402,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;
             }
         });
@@ -413,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}`);
@@ -432,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.js

@@ -74,10 +74,10 @@ export class DrupalAuthProvider {
             throw new Error("Not authenticated. Call ensureAuthenticated() first.");
         }
         return {
-            "Cookie": this.sessionCookie,
+            Cookie: this.sessionCookie,
             "X-CSRF-Token": this.csrfToken,
             "Content-Type": "application/vnd.api+json",
-            "Accept": "application/vnd.api+json",
+            Accept: "application/vnd.api+json",
         };
     }
     /**

package/dist/index.d.ts

@@ -3,3 +3,4 @@ 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

@@ -3,3 +3,4 @@ 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: () => { },
+};

package/dist/taxonomies.js

@@ -75,7 +75,7 @@ export const FIELDS_OF_SCIENCE = {
             typical: 300000,
         },
     },
-    "Physics": {
+    Physics: {
         name: "Physics",
         description: "Research in high energy physics, astrophysics, condensed matter, and computational physics",
         keywords: [
@@ -106,7 +106,7 @@ export const FIELDS_OF_SCIENCE = {
             typical: 500000,
         },
     },
-    "Chemistry": {
+    Chemistry: {
         name: "Chemistry",
         description: "Research in computational chemistry, molecular modeling, and materials science",
         keywords: [
@@ -120,23 +120,14 @@ export const FIELDS_OF_SCIENCE = {
             "ab initio",
         ],
         typical_resources: ["CPU clusters", "high memory", "GPU acceleration", "fast storage"],
-        common_software: [
-            "Gaussian",
-            "GAMESS",
-            "NWChem",
-            "ORCA",
-            "AMBER",
-            "NAMD",
-            "LAMMPS",
-            "VMD",
-        ],
+        common_software: ["Gaussian", "GAMESS", "NWChem", "ORCA", "AMBER", "NAMD", "LAMMPS", "VMD"],
         allocation_range: {
             min: 75000,
             max: 1000000,
             typical: 300000,
         },
     },
-    "Engineering": {
+    Engineering: {
         name: "Engineering",
         description: "Research in computational engineering, CFD, structural analysis, and design optimization",
         keywords: [
@@ -151,15 +142,7 @@ export const FIELDS_OF_SCIENCE = {
             "aerospace",
         ],
         typical_resources: ["CPU clusters", "high memory", "GPU for visualization", "parallel I/O"],
-        common_software: [
-            "ANSYS",
-            "OpenFOAM",
-            "COMSOL",
-            "ABAQUS",
-            "LS-DYNA",
-            "SU2",
-            "ParaView",
-        ],
+        common_software: ["ANSYS", "OpenFOAM", "COMSOL", "ABAQUS", "LS-DYNA", "SU2", "ParaView"],
         allocation_range: {
             min: 100000,
             max: 1500000,
@@ -180,16 +163,7 @@ export const FIELDS_OF_SCIENCE = {
             "environmental science",
         ],
         typical_resources: ["large storage", "CPU clusters", "high I/O", "data analytics"],
-        common_software: [
-            "WRF",
-            "CESM",
-            "NCAR",
-            "netCDF",
-            "GDAL",
-            "Python",
-            "R",
-            "MATLAB",
-        ],
+        common_software: ["WRF", "CESM", "NCAR", "netCDF", "GDAL", "Python", "R", "MATLAB"],
         allocation_range: {
             min: 150000,
             max: 2000000,
@@ -210,16 +184,7 @@ export const FIELDS_OF_SCIENCE = {
             "computational mathematics",
         ],
         typical_resources: ["CPU clusters", "high memory", "GPU for linear algebra"],
-        common_software: [
-            "MATLAB",
-            "R",
-            "Python",
-            "Julia",
-            "Mathematica",
-            "SAS",
-            "SPSS",
-            "Octave",
-        ],
+        common_software: ["MATLAB", "R", "Python", "Julia", "Mathematica", "SAS", "SPSS", "Octave"],
         allocation_range: {
             min: 50000,
             max: 500000,
@@ -239,15 +204,7 @@ export const FIELDS_OF_SCIENCE = {
             "survey analysis",
         ],
         typical_resources: ["data analytics", "storage", "CPU clusters for simulations"],
-        common_software: [
-            "R",
-            "Python",
-            "Stata",
-            "SPSS",
-            "NetLogo",
-            "Gephi",
-            "Julia",
-        ],
+        common_software: ["R", "Python", "Stata", "SPSS", "NetLogo", "Gephi", "Julia"],
         allocation_range: {
             min: 25000,
             max: 300000,
@@ -268,16 +225,7 @@ export const FIELDS_OF_SCIENCE = {
             "simulation",
         ],
         typical_resources: ["large storage", "CPU clusters", "GPU for visualization", "data pipelines"],
-        common_software: [
-            "Gadget",
-            "FLASH",
-            "Enzo",
-            "Athena",
-            "IRAF",
-            "DS9",
-            "Python",
-            "astropy",
-        ],
+        common_software: ["Gadget", "FLASH", "Enzo", "Athena", "IRAF", "DS9", "Python", "astropy"],
         allocation_range: {
             min: 150000,
             max: 2500000,
@@ -365,12 +313,7 @@ export const RESOURCE_TYPES = {
             "Data processing",
             "Simulations",
         ],
-        key_features: [
-            "High core counts",
-            "Good memory bandwidth",
-            "MPI support",
-            "Long-running jobs",
-        ],
+        key_features: ["High core counts", "Good memory bandwidth", "MPI support", "Long-running jobs"],
     },
     GPU: {
         name: "GPU Accelerated",
@@ -382,12 +325,7 @@ export const RESOURCE_TYPES = {
             "Image processing",
             "CFD simulations",
         ],
-        key_features: [
-            "CUDA/ROCm support",
-            "High memory bandwidth",
-            "Tensor cores",
-            "Fast training",
-        ],
+        key_features: ["CUDA/ROCm support", "High memory bandwidth", "Tensor cores", "Fast training"],
     },
     "High Memory": {
         name: "High Memory Systems",
@@ -398,11 +336,7 @@ export const RESOURCE_TYPES = {
             "In-memory databases",
             "Large-scale graph analysis",
         ],
-        key_features: [
-            "1TB+ memory per node",
-            "Fast memory access",
-            "Large working sets",
-        ],
+        key_features: ["1TB+ memory per node", "Fast memory access", "Large working sets"],
     },
     Storage: {
         name: "Storage Resources",
@@ -430,12 +364,7 @@ export const RESOURCE_TYPES = {
             "Interactive computing",
             "Elastic workloads",
         ],
-        key_features: [
-            "On-demand resources",
-            "Virtual machines",
-            "Container support",
-            "API access",
-        ],
+        key_features: ["On-demand resources", "Virtual machines", "Container support", "API access"],
     },
 };
 /**
@@ -525,10 +454,10 @@ export function getFeatureName(featureCode) {
  * Get feature names for an array of codes
  */
 export function getFeatureNames(featureCodes) {
-    return featureCodes.map(code => getFeatureName(code));
+    return featureCodes.map((code) => getFeatureName(code));
 }
 export const ACCESS_SYSTEMS = {
-    "Delta": {
+    Delta: {
         name: "Delta",
         organization: "NCSA (University of Illinois)",
         description: "GPU-focused system with NVIDIA A100 and A40 GPUs",
@@ -562,7 +491,7 @@ export const ACCESS_SYSTEMS = {
         ],
         experience_level: ["Beginner", "Intermediate", "Advanced"],
     },
-    "Anvil": {
+    Anvil: {
         name: "Anvil",
         organization: "Purdue University",
         description: "Composable subsystem architecture with flexible resource allocation",
@@ -578,7 +507,7 @@ export const ACCESS_SYSTEMS = {
         ],
         experience_level: ["Beginner", "Intermediate", "Advanced"],
     },
-    "Expanse": {
+    Expanse: {
         name: "Expanse",
         organization: "SDSC (San Diego Supercomputing Center)",
         description: "Balanced CPU and GPU computing with excellent storage",
@@ -595,7 +524,7 @@ export const ACCESS_SYSTEMS = {
         ],
         experience_level: ["Intermediate", "Advanced"],
     },
-    "Stampede3": {
+    Stampede3: {
         name: "Stampede3",
         organization: "TACC (Texas Advanced Computing Center)",
         description: "Leadership-class supercomputer with NVIDIA Grace-Hopper",
@@ -611,7 +540,7 @@ export const ACCESS_SYSTEMS = {
         ],
         experience_level: ["Advanced", "Expert"],
     },
-    "Jetstream2": {
+    Jetstream2: {
         name: "Jetstream2",
         organization: "Indiana University",
         description: "Cloud computing platform for interactive science and gateways",

package/dist/utils.d.ts

@@ -72,3 +72,43 @@ export declare const CommonNextSteps: {
         description: string;
     };
 };
+/**
+ * Resource ID Resolution Utilities
+ *
+ * These utilities help resolve human-readable resource names (e.g., "Anvil", "Delta")
+ * to full resource IDs (e.g., "anvil.purdue.access-ci.org").
+ */
+export interface ResourceMatch {
+    id: string;
+    name: string;
+}
+export type ResolveResult = {
+    success: true;
+    id: string;
+} | {
+    success: false;
+    error: string;
+    suggestion?: string;
+};
+/**
+ * Resolve a human-readable name to a resource ID.
+ *
+ * @param input - The input string (name or ID)
+ * @param searchFn - A function that searches for resources by name and returns matches
+ * @returns ResolveResult with either the resolved ID or an error message
+ *
+ * @example
+ * ```ts
+ * const result = await resolveResourceId("Anvil", async (query) => {
+ *   const resources = await searchResources({ query });
+ *   return resources.map(r => ({ id: r.id, name: r.name }));
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.id); // "anvil.purdue.access-ci.org"
+ * } else {
+ *   console.log(result.error); // "Multiple resources match..."
+ * }
+ * ```
+ */
+export declare function resolveResourceId(input: string, searchFn: (query: string) => Promise<ResourceMatch[]>): Promise<ResolveResult>;

package/dist/utils.js

@@ -82,3 +82,62 @@ export const CommonNextSteps = {
         description: `Try these refinements: ${suggestions.join(", ")}`,
     }),
 };
+/**
+ * Resolve a human-readable name to a resource ID.
+ *
+ * @param input - The input string (name or ID)
+ * @param searchFn - A function that searches for resources by name and returns matches
+ * @returns ResolveResult with either the resolved ID or an error message
+ *
+ * @example
+ * ```ts
+ * const result = await resolveResourceId("Anvil", async (query) => {
+ *   const resources = await searchResources({ query });
+ *   return resources.map(r => ({ id: r.id, name: r.name }));
+ * });
+ *
+ * if (result.success) {
+ *   console.log(result.id); // "anvil.purdue.access-ci.org"
+ * } else {
+ *   console.log(result.error); // "Multiple resources match..."
+ * }
+ * ```
+ */
+export async function resolveResourceId(input, searchFn) {
+    // If it already looks like a full resource ID (contains dots), return as-is
+    if (input.includes(".")) {
+        return { success: true, id: input };
+    }
+    // Search for the resource by name
+    const items = await searchFn(input);
+    if (items.length === 0) {
+        return {
+            success: false,
+            error: `No resource found matching '${input}'`,
+            suggestion: "Use the search tool to find valid resource names.",
+        };
+    }
+    // Find exact name match first (case-insensitive)
+    const inputLower = input.toLowerCase();
+    const exactMatch = items.find((item) => item.name?.toLowerCase() === inputLower);
+    if (exactMatch && exactMatch.id) {
+        return { success: true, id: exactMatch.id };
+    }
+    // Multiple partial matches - ask user to be more specific
+    if (items.length > 1) {
+        const names = items.map((i) => i.name).join(", ");
+        return {
+            success: false,
+            error: `Multiple resources match '${input}': ${names}`,
+            suggestion: "Please specify the exact resource name.",
+        };
+    }
+    // Single partial match - use it
+    if (items[0].id) {
+        return { success: true, id: items[0].id };
+    }
+    return {
+        success: false,
+        error: `Could not resolve resource '${input}'`,
+    };
+}

package/package.json

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