@danielsimonjr/memory-mcp 0.41.0 → 0.47.1

package/dist/server/toolHandlers.js

@@ -0,0 +1,117 @@
+/**
+ * MCP Tool Handlers
+ *
+ * Extracted from MCPServer.ts to reduce file size and improve maintainability.
+ * Contains handler functions for all 45 Knowledge Graph tools.
+ *
+ * @module server/toolHandlers
+ */
+import { formatToolResponse, formatTextResponse, formatRawResponse } from '../utils/responseFormatter.js';
+/**
+ * Registry of all tool handlers keyed by tool name.
+ */
+export const toolHandlers = {
+    // ==================== ENTITY HANDLERS ====================
+    create_entities: async (manager, args) => formatToolResponse(await manager.createEntities(args.entities)),
+    delete_entities: async (manager, args) => {
+        await manager.deleteEntities(args.entityNames);
+        return formatTextResponse(`Deleted ${args.entityNames.length} entities`);
+    },
+    read_graph: async (manager) => formatToolResponse(await manager.readGraph()),
+    open_nodes: async (manager, args) => formatToolResponse(await manager.openNodes(args.names)),
+    // ==================== RELATION HANDLERS ====================
+    create_relations: async (manager, args) => formatToolResponse(await manager.createRelations(args.relations)),
+    delete_relations: async (manager, args) => {
+        await manager.deleteRelations(args.relations);
+        return formatTextResponse(`Deleted ${args.relations.length} relations`);
+    },
+    // ==================== OBSERVATION HANDLERS ====================
+    add_observations: async (manager, args) => formatToolResponse(await manager.addObservations(args.observations)),
+    delete_observations: async (manager, args) => {
+        await manager.deleteObservations(args.deletions);
+        return formatTextResponse('Observations deleted successfully');
+    },
+    // ==================== SEARCH HANDLERS ====================
+    search_nodes: async (manager, args) => formatToolResponse(await manager.searchNodes(args.query, args.tags, args.minImportance, args.maxImportance)),
+    search_by_date_range: async (manager, args) => formatToolResponse(await manager.searchByDateRange(args.startDate, args.endDate, args.entityType, args.tags)),
+    search_nodes_ranked: async (manager, args) => formatToolResponse(await manager.searchNodesRanked(args.query, args.tags, args.minImportance, args.maxImportance, args.limit)),
+    boolean_search: async (manager, args) => formatToolResponse(await manager.booleanSearch(args.query, args.tags, args.minImportance, args.maxImportance)),
+    fuzzy_search: async (manager, args) => formatToolResponse(await manager.fuzzySearch(args.query, args.threshold, args.tags, args.minImportance, args.maxImportance)),
+    get_search_suggestions: async (manager, args) => formatToolResponse(await manager.getSearchSuggestions(args.query, args.maxSuggestions)),
+    // ==================== SAVED SEARCH HANDLERS ====================
+    save_search: async (manager, args) => formatToolResponse(await manager.saveSearch(args)),
+    execute_saved_search: async (manager, args) => formatToolResponse(await manager.executeSavedSearch(args.name)),
+    list_saved_searches: async (manager) => formatToolResponse(await manager.listSavedSearches()),
+    delete_saved_search: async (manager, args) => {
+        const deleted = await manager.deleteSavedSearch(args.name);
+        return formatTextResponse(deleted
+            ? `Saved search "${args.name}" deleted successfully`
+            : `Saved search "${args.name}" not found`);
+    },
+    update_saved_search: async (manager, args) => formatToolResponse(await manager.updateSavedSearch(args.name, args.updates)),
+    // ==================== TAG HANDLERS ====================
+    add_tags: async (manager, args) => formatToolResponse(await manager.addTags(args.entityName, args.tags)),
+    remove_tags: async (manager, args) => formatToolResponse(await manager.removeTags(args.entityName, args.tags)),
+    set_importance: async (manager, args) => formatToolResponse(await manager.setImportance(args.entityName, args.importance)),
+    add_tags_to_multiple_entities: async (manager, args) => formatToolResponse(await manager.addTagsToMultipleEntities(args.entityNames, args.tags)),
+    replace_tag: async (manager, args) => formatToolResponse(await manager.replaceTag(args.oldTag, args.newTag)),
+    merge_tags: async (manager, args) => formatToolResponse(await manager.mergeTags(args.tag1, args.tag2, args.targetTag)),
+    // ==================== TAG ALIAS HANDLERS ====================
+    add_tag_alias: async (manager, args) => formatToolResponse(await manager.addTagAlias(args.alias, args.canonical, args.description)),
+    list_tag_aliases: async (manager) => formatToolResponse(await manager.listTagAliases()),
+    remove_tag_alias: async (manager, args) => {
+        const removed = await manager.removeTagAlias(args.alias);
+        return formatTextResponse(removed
+            ? `Tag alias "${args.alias}" removed successfully`
+            : `Tag alias "${args.alias}" not found`);
+    },
+    get_aliases_for_tag: async (manager, args) => formatToolResponse(await manager.getAliasesForTag(args.canonicalTag)),
+    resolve_tag: async (manager, args) => formatToolResponse({
+        tag: args.tag,
+        resolved: await manager.resolveTag(args.tag),
+    }),
+    // ==================== HIERARCHY HANDLERS ====================
+    set_entity_parent: async (manager, args) => formatToolResponse(await manager.setEntityParent(args.entityName, args.parentName)),
+    get_children: async (manager, args) => formatToolResponse(await manager.getChildren(args.entityName)),
+    get_parent: async (manager, args) => formatToolResponse(await manager.getParent(args.entityName)),
+    get_ancestors: async (manager, args) => formatToolResponse(await manager.getAncestors(args.entityName)),
+    get_descendants: async (manager, args) => formatToolResponse(await manager.getDescendants(args.entityName)),
+    get_subtree: async (manager, args) => formatToolResponse(await manager.getSubtree(args.entityName)),
+    get_root_entities: async (manager) => formatToolResponse(await manager.getRootEntities()),
+    get_entity_depth: async (manager, args) => formatToolResponse({
+        entityName: args.entityName,
+        depth: await manager.getEntityDepth(args.entityName),
+    }),
+    move_entity: async (manager, args) => formatToolResponse(await manager.moveEntity(args.entityName, args.newParentName)),
+    // ==================== ANALYTICS HANDLERS ====================
+    get_graph_stats: async (manager) => formatToolResponse(await manager.getGraphStats()),
+    validate_graph: async (manager) => formatToolResponse(await manager.validateGraph()),
+    // ==================== COMPRESSION HANDLERS ====================
+    find_duplicates: async (manager, args) => formatToolResponse(await manager.findDuplicates(args.threshold)),
+    merge_entities: async (manager, args) => formatToolResponse(await manager.mergeEntities(args.entityNames, args.targetName)),
+    compress_graph: async (manager, args) => formatToolResponse(await manager.compressGraph(args.threshold, args.dryRun)),
+    archive_entities: async (manager, args) => formatToolResponse(await manager.archiveEntities({
+        olderThan: args.olderThan,
+        importanceLessThan: args.importanceLessThan,
+        tags: args.tags,
+    }, args.dryRun)),
+    // ==================== IMPORT/EXPORT HANDLERS ====================
+    import_graph: async (manager, args) => formatToolResponse(await manager.importGraph(args.format, args.data, args.mergeStrategy, args.dryRun)),
+    export_graph: async (manager, args) => formatRawResponse(await manager.exportGraph(args.format, args.filter)),
+};
+/**
+ * Handle a tool call by dispatching to the appropriate handler.
+ *
+ * @param name - Tool name to call
+ * @param args - Tool arguments
+ * @param manager - Knowledge graph manager instance
+ * @returns Tool response
+ * @throws Error if tool name is unknown
+ */
+export async function handleToolCall(name, args, manager) {
+    const handler = toolHandlers[name];
+    if (!handler) {
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    return handler(manager, args);
+}

package/dist/utils/constants.js

@@ -59,6 +59,7 @@ export const LOG_PREFIXES = {
  * Similarity scoring weights for duplicate detection.
  * These weights determine the relative importance of each factor
  * when calculating entity similarity for duplicate detection.
+ * Total weights must sum to 1.0 (100%).
  */
 export const SIMILARITY_WEIGHTS = {
     /** Name similarity weight (40%) - Uses Levenshtein distance */
@@ -66,9 +67,9 @@ export const SIMILARITY_WEIGHTS = {
     /** Entity type match weight (20%) - Exact match required */
     TYPE: 0.2,
     /** Observation overlap weight (30%) - Uses Jaccard similarity */
-    OBSERVATION: 0.3,
+    OBSERVATIONS: 0.3,
     /** Tag overlap weight (10%) - Uses Jaccard similarity */
-    TAG: 0.1,
+    TAGS: 0.1,
 };
 /**
  * Default threshold for duplicate detection (80% similarity required).

package/dist/utils/entityUtils.js

@@ -0,0 +1,108 @@
+/**
+ * Entity Lookup and Utility Functions
+ *
+ * Centralizes entity lookup patterns to eliminate redundant code across managers.
+ * Provides type-safe entity finding with optional error throwing.
+ */
+import { EntityNotFoundError } from './errors.js';
+export function findEntityByName(graph, name, throwIfNotFound = true) {
+    const entity = graph.entities.find(e => e.name === name);
+    if (!entity && throwIfNotFound) {
+        throw new EntityNotFoundError(name);
+    }
+    return entity ?? null;
+}
+/**
+ * Finds multiple entities by name.
+ *
+ * @param graph - The knowledge graph to search
+ * @param names - Array of entity names to find
+ * @param throwIfAnyNotFound - Whether to throw if any entity doesn't exist (default: true)
+ * @returns Array of found entities (may be shorter than names if throwIfAnyNotFound is false)
+ * @throws EntityNotFoundError if any entity not found and throwIfAnyNotFound is true
+ */
+export function findEntitiesByNames(graph, names, throwIfAnyNotFound = true) {
+    const entities = [];
+    for (const name of names) {
+        const entity = findEntityByName(graph, name, false);
+        if (entity) {
+            entities.push(entity);
+        }
+        else if (throwIfAnyNotFound) {
+            throw new EntityNotFoundError(name);
+        }
+    }
+    return entities;
+}
+/**
+ * Checks if an entity exists in the graph.
+ *
+ * @param graph - The knowledge graph to search
+ * @param name - The entity name to check
+ * @returns true if entity exists, false otherwise
+ */
+export function entityExists(graph, name) {
+    return graph.entities.some(e => e.name === name);
+}
+/**
+ * Gets the index of an entity in the graph's entities array.
+ *
+ * @param graph - The knowledge graph to search
+ * @param name - The entity name to find
+ * @returns The index if found, -1 otherwise
+ */
+export function getEntityIndex(graph, name) {
+    return graph.entities.findIndex(e => e.name === name);
+}
+/**
+ * Removes an entity from the graph by name.
+ * Mutates the graph's entities array in place.
+ *
+ * @param graph - The knowledge graph to modify
+ * @param name - The entity name to remove
+ * @returns true if entity was removed, false if not found
+ */
+export function removeEntityByName(graph, name) {
+    const index = getEntityIndex(graph, name);
+    if (index === -1)
+        return false;
+    graph.entities.splice(index, 1);
+    return true;
+}
+/**
+ * Gets all entity names as a Set for fast lookup.
+ *
+ * @param graph - The knowledge graph
+ * @returns Set of all entity names
+ */
+export function getEntityNameSet(graph) {
+    return new Set(graph.entities.map(e => e.name));
+}
+/**
+ * Groups entities by their type.
+ *
+ * @param entities - Array of entities to group
+ * @returns Map of entity type to array of entities
+ */
+export function groupEntitiesByType(entities) {
+    const groups = new Map();
+    for (const entity of entities) {
+        const type = entity.entityType;
+        if (!groups.has(type)) {
+            groups.set(type, []);
+        }
+        groups.get(type).push(entity);
+    }
+    return groups;
+}
+/**
+ * Updates the lastModified timestamp on an entity.
+ * Mutates the entity in place.
+ *
+ * @param entity - The entity to update
+ * @returns The updated entity (same reference)
+ */
+export function touchEntity(entity) {
+    entity.lastModified = new Date().toISOString();
+    return entity;
+}

package/dist/utils/filterUtils.js

@@ -0,0 +1,155 @@
+/**
+ * Entity Filtering Utilities
+ *
+ * Centralizes common filtering logic for importance, date ranges, and other
+ * entity properties to eliminate duplicate patterns across search implementations.
+ */
+/**
+ * Checks if an entity's importance is within the specified range.
+ * Entities without importance are treated as not matching if any filter is set.
+ *
+ * @param importance - The entity's importance value (may be undefined)
+ * @param minImportance - Minimum importance filter (inclusive)
+ * @param maxImportance - Maximum importance filter (inclusive)
+ * @returns true if importance is within range or no filters are set
+ *
+ * @example
+ * ```typescript
+ * // Check if entity passes importance filter
+ * if (isWithinImportanceRange(entity.importance, 5, 10)) {
+ *   // Entity has importance between 5 and 10
+ * }
+ * ```
+ */
+export function isWithinImportanceRange(importance, minImportance, maxImportance) {
+    // If no filters set, always pass
+    if (minImportance === undefined && maxImportance === undefined) {
+        return true;
+    }
+    // Check minimum importance
+    if (minImportance !== undefined) {
+        if (importance === undefined || importance < minImportance) {
+            return false;
+        }
+    }
+    // Check maximum importance
+    if (maxImportance !== undefined) {
+        if (importance === undefined || importance > maxImportance) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Filters entities by importance range.
+ * Returns all entities if no importance filters are specified.
+ *
+ * @param entities - Array of entities to filter
+ * @param minImportance - Minimum importance filter (inclusive)
+ * @param maxImportance - Maximum importance filter (inclusive)
+ * @returns Filtered entities within the importance range
+ */
+export function filterByImportance(entities, minImportance, maxImportance) {
+    if (minImportance === undefined && maxImportance === undefined) {
+        return entities;
+    }
+    return entities.filter(e => isWithinImportanceRange(e.importance, minImportance, maxImportance));
+}
+/**
+ * Checks if a date value is within the specified range.
+ * Handles undefined values appropriately.
+ *
+ * @param dateValue - ISO 8601 date string to check (may be undefined)
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns true if date is within range or no filters are set
+ */
+export function isWithinDateRange(dateValue, startDate, endDate) {
+    // If no filters set, always pass
+    if (!startDate && !endDate) {
+        return true;
+    }
+    // If date value is undefined but we have filters, fail
+    if (!dateValue) {
+        return false;
+    }
+    const date = new Date(dateValue);
+    if (startDate && date < new Date(startDate)) {
+        return false;
+    }
+    if (endDate && date > new Date(endDate)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Filters entities by creation date range.
+ *
+ * @param entities - Array of entities to filter
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns Filtered entities created within the date range
+ */
+export function filterByCreatedDate(entities, startDate, endDate) {
+    if (!startDate && !endDate) {
+        return entities;
+    }
+    return entities.filter(e => isWithinDateRange(e.createdAt, startDate, endDate));
+}
+/**
+ * Filters entities by last modified date range.
+ *
+ * @param entities - Array of entities to filter
+ * @param startDate - Start of date range (inclusive)
+ * @param endDate - End of date range (inclusive)
+ * @returns Filtered entities modified within the date range
+ */
+export function filterByModifiedDate(entities, startDate, endDate) {
+    if (!startDate && !endDate) {
+        return entities;
+    }
+    return entities.filter(e => isWithinDateRange(e.lastModified, startDate, endDate));
+}
+/**
+ * Filters entities by entity type.
+ *
+ * @param entities - Array of entities to filter
+ * @param entityType - Entity type to filter by (case-sensitive)
+ * @returns Filtered entities of the specified type
+ */
+export function filterByEntityType(entities, entityType) {
+    if (!entityType) {
+        return entities;
+    }
+    return entities.filter(e => e.entityType === entityType);
+}
+/**
+ * Checks if an entity passes all the specified filters.
+ * Short-circuits on first failing filter for performance.
+ *
+ * Note: Tag filtering should be handled separately using tagUtils.hasMatchingTag
+ * as it requires special normalization logic.
+ *
+ * @param entity - Entity to check
+ * @param filters - Filters to apply
+ * @returns true if entity passes all filters
+ */
+export function entityPassesFilters(entity, filters) {
+    // Importance filter
+    if (!isWithinImportanceRange(entity.importance, filters.minImportance, filters.maxImportance)) {
+        return false;
+    }
+    // Entity type filter
+    if (filters.entityType && entity.entityType !== filters.entityType) {
+        return false;
+    }
+    // Created date filter
+    if (!isWithinDateRange(entity.createdAt, filters.createdAfter, filters.createdBefore)) {
+        return false;
+    }
+    // Modified date filter
+    if (!isWithinDateRange(entity.lastModified, filters.modifiedAfter, filters.modifiedBefore)) {
+        return false;
+    }
+    return true;
+}

package/dist/utils/index.js

@@ -1,13 +1,39 @@
 /**
  * Utilities Module Barrel Export
+ *
+ * Centralizes all utility exports for convenient importing.
+ * Sprint 1 additions: responseFormatter, tagUtils, entityUtils,
+ * validationHelper, paginationUtils, filterUtils
  */
+// Error types
 export { KnowledgeGraphError, EntityNotFoundError, RelationNotFoundError, DuplicateEntityError, ValidationError, CycleDetectedError, InvalidImportanceError, FileOperationError, ImportError, ExportError, InsufficientEntitiesError, } from './errors.js';
+// String utilities
 export { levenshteinDistance } from './levenshtein.js';
 export { calculateTF, calculateIDF, calculateTFIDF, tokenize } from './tfidf.js';
+// Logging
 export { logger } from './logger.js';
+// Date utilities
 export { isWithinDateRange, parseDateRange, isValidISODate, getCurrentTimestamp } from './dateUtils.js';
+// Validation utilities
 export { validateEntity, validateRelation, validateImportance, validateTags } from './validationUtils.js';
+// Path utilities
 export { defaultMemoryPath, ensureMemoryFilePath, validateFilePath } from './pathUtils.js';
+// Constants
 export { FILE_EXTENSIONS, FILE_SUFFIXES, DEFAULT_FILE_NAMES, ENV_VARS, DEFAULT_BASE_DIR, LOG_PREFIXES, SIMILARITY_WEIGHTS, DEFAULT_DUPLICATE_THRESHOLD, SEARCH_LIMITS, IMPORTANCE_RANGE, } from './constants.js';
+// Zod schemas
 export { EntitySchema, CreateEntitySchema, UpdateEntitySchema, RelationSchema, CreateRelationSchema, SearchQuerySchema, DateRangeSchema, TagAliasSchema, ExportFormatSchema, BatchCreateEntitiesSchema, BatchCreateRelationsSchema, EntityNamesSchema, DeleteRelationsSchema, } from './schemas.js';
+// Search cache
 export { SearchCache, searchCaches, clearAllSearchCaches, getAllCacheStats, cleanupAllCaches, } from './searchCache.js';
+// === Sprint 1: New Utility Exports ===
+// MCP Response formatting (Task 1.1)
+export { formatToolResponse, formatTextResponse, formatRawResponse, formatErrorResponse, } from './responseFormatter.js';
+// Tag utilities (Task 1.2)
+export { normalizeTag, normalizeTags, hasMatchingTag, hasAllTags, filterByTags, addUniqueTags, removeTags, } from './tagUtils.js';
+// Entity utilities (Task 1.3)
+export { findEntityByName, findEntitiesByNames, entityExists, getEntityIndex, removeEntityByName, getEntityNameSet, groupEntitiesByType, touchEntity, } from './entityUtils.js';
+// Zod validation helpers (Task 1.4)
+export { formatZodErrors, validateWithSchema, validateSafe, validateArrayWithSchema, } from './validationHelper.js';
+// Pagination utilities (Task 1.5)
+export { validatePagination, applyPagination, paginateArray, getPaginationMeta, } from './paginationUtils.js';
+// Filter utilities (Task 1.6)
+export { isWithinImportanceRange, filterByImportance, filterByCreatedDate, filterByModifiedDate, filterByEntityType, entityPassesFilters, } from './filterUtils.js';

package/dist/utils/paginationUtils.js

@@ -0,0 +1,81 @@
+/**
+ * Pagination Utilities
+ *
+ * Centralizes pagination validation and application logic
+ * to eliminate duplicate patterns across search implementations.
+ */
+import { SEARCH_LIMITS } from './constants.js';
+/**
+ * Validates and normalizes pagination parameters.
+ * Ensures offset is non-negative and limit is within configured bounds.
+ *
+ * @param offset - Starting position (default: 0)
+ * @param limit - Maximum results to return (default: SEARCH_LIMITS.DEFAULT)
+ * @returns Validated pagination parameters with helper methods
+ *
+ * @example
+ * ```typescript
+ * const pagination = validatePagination(10, 50);
+ * const results = items.slice(pagination.offset, pagination.offset + pagination.limit);
+ * if (pagination.hasMore(items.length)) {
+ *   console.log('More results available');
+ * }
+ * ```
+ */
+export function validatePagination(offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+    const validatedOffset = Math.max(0, offset);
+    const validatedLimit = Math.min(Math.max(SEARCH_LIMITS.MIN, limit), SEARCH_LIMITS.MAX);
+    return {
+        offset: validatedOffset,
+        limit: validatedLimit,
+        hasMore: (totalCount) => validatedOffset + validatedLimit < totalCount,
+    };
+}
+/**
+ * Applies pagination to an array of items.
+ *
+ * @param items - Array to paginate
+ * @param pagination - Validated pagination parameters
+ * @returns Paginated slice of the array
+ *
+ * @example
+ * ```typescript
+ * const pagination = validatePagination(offset, limit);
+ * const pageResults = applyPagination(allResults, pagination);
+ * ```
+ */
+export function applyPagination(items, pagination) {
+    return items.slice(pagination.offset, pagination.offset + pagination.limit);
+}
+/**
+ * Applies pagination using raw offset and limit values.
+ * Combines validation and application in one call.
+ *
+ * @param items - Array to paginate
+ * @param offset - Starting position
+ * @param limit - Maximum results
+ * @returns Paginated slice of the array
+ */
+export function paginateArray(items, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+    const pagination = validatePagination(offset, limit);
+    return applyPagination(items, pagination);
+}
+/**
+ * Calculates pagination metadata for a result set.
+ *
+ * @param totalCount - Total number of items
+ * @param offset - Current offset
+ * @param limit - Current limit
+ * @returns Pagination metadata
+ */
+export function getPaginationMeta(totalCount, offset = 0, limit = SEARCH_LIMITS.DEFAULT) {
+    const pagination = validatePagination(offset, limit);
+    return {
+        totalCount,
+        offset: pagination.offset,
+        limit: pagination.limit,
+        hasMore: pagination.hasMore(totalCount),
+        pageNumber: Math.floor(pagination.offset / pagination.limit) + 1,
+        totalPages: Math.ceil(totalCount / pagination.limit),
+    };
+}

package/dist/utils/responseFormatter.js

@@ -0,0 +1,55 @@
+/**
+ * MCP Tool Response Formatter Utilities
+ *
+ * Centralizes response formatting for MCP tool calls to eliminate
+ * redundant JSON.stringify patterns across the codebase.
+ */
+/**
+ * Formats data as an MCP tool response with JSON content.
+ * Centralizes the response format to ensure consistency and reduce duplication.
+ *
+ * @param data - Any data to be JSON stringified
+ * @returns Formatted MCP tool response
+ */
+export function formatToolResponse(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * Formats a simple text message as an MCP tool response.
+ * Use for success messages that don't need JSON formatting.
+ *
+ * @param message - Plain text message
+ * @returns Formatted MCP tool response
+ */
+export function formatTextResponse(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+    };
+}
+/**
+ * Formats raw string content as an MCP tool response.
+ * Use for export formats that return pre-formatted strings (markdown, CSV, etc.)
+ *
+ * @param content - Raw string content
+ * @returns Formatted MCP tool response
+ */
+export function formatRawResponse(content) {
+    return {
+        content: [{ type: 'text', text: content }],
+    };
+}
+/**
+ * Formats an error as an MCP tool response with isError flag.
+ *
+ * @param error - Error object or message string
+ * @returns Formatted MCP tool error response
+ */
+export function formatErrorResponse(error) {
+    const message = error instanceof Error ? error.message : error;
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}

package/dist/utils/tagUtils.js

@@ -0,0 +1,107 @@
+/**
+ * Tag Normalization and Matching Utilities
+ *
+ * Centralizes tag operations to eliminate duplicate normalization logic
+ * across the codebase. All tags are normalized to lowercase for consistent matching.
+ */
+/**
+ * Normalizes a single tag to lowercase and trimmed.
+ *
+ * @param tag - Tag to normalize
+ * @returns Normalized tag
+ */
+export function normalizeTag(tag) {
+    return tag.toLowerCase().trim();
+}
+/**
+ * Normalizes an array of tags to lowercase.
+ * Handles undefined/null input gracefully.
+ *
+ * @param tags - Array of tags to normalize, or undefined
+ * @returns Normalized tags array, or empty array if input is undefined/null
+ */
+export function normalizeTags(tags) {
+    if (!tags || tags.length === 0)
+        return [];
+    return tags.map(tag => tag.toLowerCase());
+}
+/**
+ * Checks if an entity's tags include any of the specified search tags.
+ * Both inputs are normalized before comparison.
+ *
+ * @param entityTags - Tags on the entity (may be undefined)
+ * @param searchTags - Tags to search for (may be undefined)
+ * @returns true if any search tag matches any entity tag, false if no match or either is empty
+ */
+export function hasMatchingTag(entityTags, searchTags) {
+    if (!entityTags || entityTags.length === 0)
+        return false;
+    if (!searchTags || searchTags.length === 0)
+        return false;
+    const normalizedEntity = normalizeTags(entityTags);
+    const normalizedSearch = normalizeTags(searchTags);
+    return normalizedSearch.some(tag => normalizedEntity.includes(tag));
+}
+/**
+ * Checks if entity tags include ALL of the specified required tags.
+ *
+ * @param entityTags - Tags on the entity (may be undefined)
+ * @param requiredTags - All tags that must be present
+ * @returns true if all required tags are present
+ */
+export function hasAllTags(entityTags, requiredTags) {
+    if (!entityTags || entityTags.length === 0)
+        return false;
+    if (requiredTags.length === 0)
+        return true;
+    const normalizedEntity = normalizeTags(entityTags);
+    return normalizeTags(requiredTags).every(tag => normalizedEntity.includes(tag));
+}
+/**
+ * Filters entities by tag match.
+ * Returns all entities if searchTags is empty or undefined.
+ *
+ * @param entities - Array of entities with optional tags property
+ * @param searchTags - Tags to filter by
+ * @returns Filtered entities that have at least one matching tag
+ */
+export function filterByTags(entities, searchTags) {
+    if (!searchTags || searchTags.length === 0) {
+        return entities;
+    }
+    const normalizedSearch = normalizeTags(searchTags);
+    return entities.filter(entity => {
+        if (!entity.tags || entity.tags.length === 0)
+            return false;
+        const normalizedEntity = normalizeTags(entity.tags);
+        return normalizedSearch.some(tag => normalizedEntity.includes(tag));
+    });
+}
+/**
+ * Adds new tags to an existing tag array, avoiding duplicates.
+ * All tags are normalized to lowercase.
+ *
+ * @param existingTags - Current tags (may be undefined)
+ * @param newTags - Tags to add
+ * @returns Combined tags array with no duplicates
+ */
+export function addUniqueTags(existingTags, newTags) {
+    const existing = normalizeTags(existingTags);
+    const toAdd = normalizeTags(newTags);
+    const uniqueNew = toAdd.filter(tag => !existing.includes(tag));
+    return [...existing, ...uniqueNew];
+}
+/**
+ * Removes specified tags from an existing tag array.
+ * Comparison is case-insensitive.
+ *
+ * @param existingTags - Current tags (may be undefined)
+ * @param tagsToRemove - Tags to remove
+ * @returns Tags array with specified tags removed
+ */
+export function removeTags(existingTags, tagsToRemove) {
+    if (!existingTags || existingTags.length === 0)
+        return [];
+    const toRemoveNormalized = normalizeTags(tagsToRemove);
+    return existingTags.filter(tag => !toRemoveNormalized.includes(tag.toLowerCase()));
+}