memory-journal-mcp 6.1.2 → 6.2.1

package/src/utils/mcp-logger.ts

@@ -1,155 +0,0 @@
-/**
- * Memory Journal MCP Server - MCP Protocol Logger
- *
- * Logging that sends structured messages via MCP notifications/message.
- * Falls back to stderr when MCP server is not connected.
- * Follows RFC 5424 severity levels as per MCP spec.
- */
-
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-
-/**
- * MCP log levels per RFC 5424
- */
-export type McpLogLevel =
-    | 'debug'
-    | 'info'
-    | 'notice'
-    | 'warning'
-    | 'error'
-    | 'critical'
-    | 'alert'
-    | 'emergency'
-
-const LOG_LEVEL_PRIORITY: Record<McpLogLevel, number> = {
-    emergency: 0,
-    alert: 1,
-    critical: 2,
-    error: 3,
-    warning: 4,
-    notice: 5,
-    info: 6,
-    debug: 7,
-}
-
-interface LogData {
-    message: string
-    module?: string
-    operation?: string
-    [key: string]: unknown
-}
-
-/**
- * MCP Protocol Logger
- *
- * Sends structured log messages via MCP notifications/message protocol.
- * Falls back to stderr when server not connected.
- */
-export class McpLogger {
-    private server: McpServer | null = null
-    private minLevel: McpLogLevel = 'info'
-
-    /**
-     * Connect to MCP server for protocol logging
-     */
-    setServer(server: McpServer): void {
-        this.server = server
-    }
-
-    /**
-     * Set minimum log level (from logging/setLevel request)
-     */
-    setLevel(level: McpLogLevel): void {
-        if (level in LOG_LEVEL_PRIORITY) {
-            this.minLevel = level
-        }
-    }
-
-    /**
-     * Get current minimum log level
-     */
-    getLevel(): McpLogLevel {
-        return this.minLevel
-    }
-
-    /**
-     * Check if a level should be logged
-     */
-    private shouldLog(level: McpLogLevel): boolean {
-        return LOG_LEVEL_PRIORITY[level] <= LOG_LEVEL_PRIORITY[this.minLevel]
-    }
-
-    /**
-     * Format message for stderr fallback
-     */
-    private formatForStderr(level: McpLogLevel, loggerName: string, data: LogData): string {
-        const timestamp = new Date().toISOString()
-        const levelUpper = level.toUpperCase().padEnd(9)
-        const module = loggerName ? `[${loggerName}]` : ''
-
-        let formatted = `[${timestamp}] [${levelUpper}] ${module} ${data.message}`
-
-        // Add extra context (filter out message and module)
-        const extras = Object.fromEntries(
-            Object.entries(data).filter(([key]) => key !== 'message' && key !== 'module')
-        )
-
-        if (Object.keys(extras).length > 0) {
-            formatted += ` ${JSON.stringify(extras)}`
-        }
-
-        return formatted
-    }
-
-    /**
-     * Send log message via MCP protocol or fallback to stderr
-     */
-    log(level: McpLogLevel, loggerName: string, data: LogData): void {
-        if (!this.shouldLog(level)) return
-
-        // Send via MCP protocol if server connected
-        if (this.server) {
-            try {
-                void this.server.sendLoggingMessage({
-                    level,
-                    logger: loggerName,
-                    data,
-                })
-            } catch {
-                // Fallback to stderr if MCP send fails
-                console.error(this.formatForStderr(level, loggerName, data))
-            }
-        }
-
-        // Always also log to stderr for local debugging
-        console.error(this.formatForStderr(level, loggerName, data))
-    }
-
-    // Convenience methods
-    debug(loggerName: string, message: string, context?: Record<string, unknown>): void {
-        this.log('debug', loggerName, { message, ...context })
-    }
-
-    info(loggerName: string, message: string, context?: Record<string, unknown>): void {
-        this.log('info', loggerName, { message, ...context })
-    }
-
-    notice(loggerName: string, message: string, context?: Record<string, unknown>): void {
-        this.log('notice', loggerName, { message, ...context })
-    }
-
-    warning(loggerName: string, message: string, context?: Record<string, unknown>): void {
-        this.log('warning', loggerName, { message, ...context })
-    }
-
-    error(loggerName: string, message: string, context?: Record<string, unknown>): void {
-        this.log('error', loggerName, { message, ...context })
-    }
-
-    critical(loggerName: string, message: string, context?: Record<string, unknown>): void {
-        this.log('critical', loggerName, { message, ...context })
-    }
-}
-
-// Singleton instance
-export const mcpLogger = new McpLogger()

package/src/utils/progress-utils.ts

@@ -1,100 +0,0 @@
-/**
- * Memory Journal MCP Server - Progress Notification Utilities
- *
- * Utilities for sending MCP progress notifications during long-running operations.
- * Follows MCP 2025-11-25 specification for notifications/progress.
- */
-
-/**
- * Minimal interface for sending MCP notifications.
- * Uses structural typing to avoid importing the deprecated Server class.
- */
-interface NotificationSender {
-    notification(notification: {
-        method: 'notifications/progress'
-        params: {
-            progressToken: string | number
-            progress: number
-            total?: number
-            message?: string
-        }
-    }): Promise<void>
-}
-
-/** Progress token from client request _meta */
-export type ProgressToken = string | number
-
-/** Context required to send progress notifications */
-export interface ProgressContext {
-    /** Object with notification method for sending progress updates */
-    server: NotificationSender
-    /** Progress token from request _meta (if client requested progress) */
-    progressToken?: ProgressToken
-}
-
-/**
- * Send a progress notification to the client.
- *
- * Only sends if a progressToken was provided in the original request.
- * Silently no-ops if no token was provided.
- *
- * @param ctx - Progress context with server and optional token
- * @param progress - Current progress value (e.g., items processed)
- * @param total - Optional total value for percentage calculation
- * @param message - Optional human-readable status message
- */
-export async function sendProgress(
-    ctx: ProgressContext | undefined,
-    progress: number,
-    total?: number,
-    message?: string
-): Promise<void> {
-    // Early return if no context, no progressToken, or no server
-    if (ctx === undefined) return
-    if (ctx.progressToken === undefined) return
-
-    try {
-        // Use the underlying Protocol's notification method
-        // The server extends Protocol which has notification() method
-        const notification = {
-            method: 'notifications/progress' as const,
-            params: {
-                progressToken: ctx.progressToken,
-                progress,
-                ...(total !== undefined && { total }),
-                ...(message !== undefined && message !== '' && { message }),
-            },
-        }
-
-        // Access the notification sender through the server's protocol
-        // The Server class exposes notification() which we need to call directly
-        await ctx.server.notification(notification)
-    } catch {
-        // Non-critical: progress notifications are best-effort
-        // Don't let notification failures break the operation
-    }
-}
-
-/**
- * Create a progress reporter function for batch operations.
- *
- * @param ctx - Progress context
- * @param total - Total number of items to process
- * @param throttle - Report every N items (default: 10)
- * @returns Async function to call on each item processed
- */
-export function createBatchProgressReporter(
-    ctx: ProgressContext | undefined,
-    total: number,
-    throttle = 10
-): (current: number, message?: string) => Promise<void> {
-    let lastReported = 0
-
-    return async (current: number, message?: string) => {
-        // Report progress at throttle intervals or at completion
-        if (current - lastReported >= throttle || current === total) {
-            await sendProgress(ctx, current, total, message)
-            lastReported = current
-        }
-    }
-}

package/src/utils/query-helpers.ts

@@ -1,78 +0,0 @@
-/**
- * Query Helpers — Input Coercion Utilities
- *
- * Standard coercion helpers that safely convert MCP SDK inputs (which may
- * arrive as strings due to JSON serialization) into their expected types.
- *
- * Used with `z.preprocess()` to ensure bad input reaches the handler's
- * try/catch instead of causing raw -32602 protocol errors.
- */
-
-// =============================================================================
-// Constants
-// =============================================================================
-
-/** Default number of rows returned by query tools */
-export const DEFAULT_QUERY_LIMIT = 100
-
-// =============================================================================
-// Coercion Functions
-// =============================================================================
-
-/**
- * Coerce a value to a number. Returns `undefined` for non-numeric input
- * so Zod treats it as "not provided" instead of producing NaN.
- *
- * Usage: `z.preprocess(coerceNumber, z.number().optional())`
- */
-export function coerceNumber(val: unknown): unknown {
-    if (typeof val === 'number') return val
-    if (typeof val === 'string') {
-        const n = Number(val)
-        return Number.isNaN(n) ? undefined : n
-    }
-    return undefined
-}
-
-/**
- * Coerce a value to a boolean. Handles string "true"/"false" from
- * MCP SDK serialization.
- *
- * Usage: `z.preprocess(coerceBoolean, z.boolean().optional())`
- */
-export function coerceBoolean(val: unknown): unknown {
-    if (typeof val === 'boolean') return val
-    if (val === 'true') return true
-    if (val === 'false') return false
-    return undefined
-}
-
-/**
- * Coerce a raw limit value to a usable number.
- * - `undefined` → `defaultLimit`
- * - `NaN` → `defaultLimit`
- * - `0` → `null` (meaning "unlimited")
- * - negative → `defaultLimit`
- * - positive → the value itself
- *
- * Works with both `z.preprocess(coerceNumber, ...)` and `z.coerce.number()`
- * outputs, safely handling NaN and undefined.
- */
-export function coerceLimit(
-    raw: unknown,
-    defaultLimit: number = DEFAULT_QUERY_LIMIT
-): number | null {
-    if (raw === undefined || raw === null) return defaultLimit
-    const num = Number(raw)
-    if (Number.isNaN(num)) return defaultLimit
-    if (num === 0) return null
-    return num > 0 ? num : defaultLimit
-}
-
-/**
- * Build a SQL LIMIT clause from a coerced limit value.
- * `null` means "no limit" — returns an empty string.
- */
-export function buildLimitClause(limitVal: number | null): string {
-    return limitVal !== null ? ` LIMIT ${String(limitVal)}` : ''
-}

package/src/utils/resource-annotations.ts

@@ -1,75 +0,0 @@
-/**
- * Resource Annotation Presets
- *
- * Centralized annotation presets for MCP resources following
- * MCP 2025-11-25 spec. Use these instead of inline annotation
- * objects to ensure consistency across all resource definitions.
- */
-
-// =============================================================================
-// Preset Types
-// =============================================================================
-
-interface ResourceAnnotation {
-    audience?: ('user' | 'assistant')[]
-    priority?: number
-    autoRead?: boolean
-    sessionInit?: boolean
-}
-
-// =============================================================================
-// Standard Presets
-// =============================================================================
-
-/** Critical state resources (health, schema, activity) — priority 0.9 */
-export const HIGH_PRIORITY: ResourceAnnotation = {
-    priority: 0.9,
-    audience: ['user', 'assistant'],
-}
-
-/** Analysis/monitoring resources (stats, indexes) — priority 0.6 */
-export const MEDIUM_PRIORITY: ResourceAnnotation = {
-    priority: 0.6,
-    audience: ['user', 'assistant'],
-}
-
-/** Supplementary resources (pool stats, extension status) — priority 0.4 */
-export const LOW_PRIORITY: ResourceAnnotation = {
-    priority: 0.4,
-    audience: ['user', 'assistant'],
-}
-
-/** Agent-only resources (capabilities, settings, instructions) — priority 0.5 */
-export const ASSISTANT_FOCUSED: ResourceAnnotation = {
-    priority: 0.5,
-    audience: ['assistant'],
-}
-
-// =============================================================================
-// Helpers
-// =============================================================================
-
-/**
- * Create a custom-priority annotation, optionally extending a base preset.
- */
-export function withPriority(
-    priority: number,
-    base: ResourceAnnotation = MEDIUM_PRIORITY
-): ResourceAnnotation {
-    return { ...base, priority }
-}
-
-/**
- * Clone a base annotation with autoRead flag set.
- * Useful for session-init resources that should be auto-read.
- */
-export function withAutoRead(base: ResourceAnnotation = HIGH_PRIORITY): ResourceAnnotation {
-    return { ...base, autoRead: true }
-}
-
-/**
- * Clone a base annotation with sessionInit flag set.
- */
-export function withSessionInit(base: ResourceAnnotation = HIGH_PRIORITY): ResourceAnnotation {
-    return { ...base, sessionInit: true }
-}

package/src/utils/security-utils.ts

@@ -1,198 +0,0 @@
-import { execFileSync } from 'node:child_process'
-import { MemoryJournalMcpError } from '../types/errors.js'
-import { ErrorCategory } from '../types/error-types.js'
-
-/** Timeout for shelling out to git commands (ms) */
-const GIT_COMMAND_TIMEOUT_MS = 3000
-
-// ============================================================================
-// Typed Security Errors
-// ============================================================================
-
-/**
- * Base class for security-related errors.
- * Extends MemoryJournalMcpError with VALIDATION category.
- */
-export class SecurityError extends MemoryJournalMcpError {
-    constructor(message: string, code: string) {
-        super(message, code, ErrorCategory.VALIDATION, {
-            suggestion: 'Check input for security violations',
-            recoverable: false,
-        })
-        this.name = 'SecurityError'
-    }
-}
-
-/**
- * Thrown when an invalid date format pattern is detected
- */
-export class InvalidDateFormatError extends SecurityError {
-    constructor(value: string) {
-        super(`Invalid date format pattern: '${value}'`, 'INVALID_DATE_FORMAT')
-        this.name = 'InvalidDateFormatError'
-    }
-}
-
-/**
- * Thrown when path traversal is detected in input
- */
-export class PathTraversalError extends SecurityError {
-    constructor(path: string) {
-        super(`Path traversal detected: '${path}'`, 'PATH_TRAVERSAL')
-        this.name = 'PathTraversalError'
-    }
-}
-
-// ============================================================================
-// Date Format Validation
-// ============================================================================
-
-/**
- * Whitelist of allowed strftime format patterns for SQLite.
- * These are the only patterns allowed to be interpolated into SQL.
- */
-const ALLOWED_DATE_FORMATS: Record<string, string> = {
-    day: '%Y-%m-%d',
-    week: '%Y-W%W',
-    month: '%Y-%m',
-} as const
-
-export type DateGroupBy = 'day' | 'week' | 'month'
-
-/**
- * Validates and returns a safe strftime format pattern.
- *
- * @param groupBy - The grouping period ('day', 'week', or 'month')
- * @returns The validated strftime format pattern
- * @throws InvalidDateFormatError if the groupBy value is invalid
- *
- * @example
- * ```typescript
- * const format = validateDateFormatPattern('day') // Returns '%Y-%m-%d'
- * const format = validateDateFormatPattern('invalid') // Throws InvalidDateFormatError
- * ```
- */
-export function validateDateFormatPattern(groupBy: string): string {
-    const format = ALLOWED_DATE_FORMATS[groupBy]
-    if (!format) {
-        throw new InvalidDateFormatError(groupBy)
-    }
-    return format
-}
-
-// ============================================================================
-// Search Query Sanitization
-// ============================================================================
-
-/**
- * Escapes special characters in LIKE patterns to prevent injection.
- * SQLite LIKE uses % and _ as wildcards.
- *
- * @param query - The user-provided search query
- * @returns Escaped query safe for use in LIKE patterns
- *
- * @example
- * ```typescript
- * sanitizeSearchQuery('100%') // Returns '100\\%'
- * sanitizeSearchQuery('test_value') // Returns 'test\\_value'
- * ```
- */
-export function sanitizeSearchQuery(query: string): string {
-    // Escape backslashes first, then LIKE wildcards
-    return query.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_')
-}
-
-// ============================================================================
-// Path Validation
-// ============================================================================
-
-/**
- * Validates that a filename does not contain path traversal characters.
- *
- * @param filename - The filename to validate
- * @throws PathTraversalError if path traversal is detected
- */
-export function assertNoPathTraversal(filename: string): void {
-    if (filename.includes('/') || filename.includes('\\') || filename.includes('..')) {
-        throw new PathTraversalError(filename)
-    }
-}
-
-// ============================================================================
-// Error Message Sanitization
-// ============================================================================
-
-/**
- * Patterns that may contain sensitive tokens in error messages.
- * Used to scrub error output before logging.
- */
-const TOKEN_PATTERNS = [
-    // GitHub personal access tokens (classic and fine-grained)
-    /ghp_[A-Za-z0-9_]{36,}/g,
-    /github_pat_[A-Za-z0-9_]{82,}/g,
-    // Authorization headers in error dumps
-    /Authorization:\s*(?:token|Bearer)\s+\S+/gi,
-    // Generic Bearer tokens
-    /Bearer\s+[A-Za-z0-9._\-~+/]+=*/gi,
-] as const
-
-/**
- * Sanitizes an error message by replacing any detected tokens with '[REDACTED]'.
- * This is a defense-in-depth measure for error logging paths.
- *
- * @param message - The error message to sanitize
- * @returns The sanitized message with tokens replaced
- */
-export function sanitizeErrorForLogging(message: string): string {
-    let sanitized = message
-    for (const pattern of TOKEN_PATTERNS) {
-        // Reset lastIndex for global regex patterns
-        pattern.lastIndex = 0
-        sanitized = sanitized.replace(pattern, '[REDACTED]')
-    }
-    return sanitized
-}
-
-// ============================================================================
-// Author Sanitization
-// ============================================================================
-
-/**
- * Sanitize an author string: strip control characters and cap length.
- * Prevents crafted git config or TEAM_AUTHOR values from injecting
- * control characters into the database or JSON payloads.
- *
- * @param raw - The raw author string from git config or environment
- * @returns Sanitized string with control characters removed and length capped at 100
- */
-export function sanitizeAuthor(raw: string): string {
-    // eslint-disable-next-line no-control-regex
-    return raw.replace(/[\x00-\x1f\x7f]/g, '').slice(0, 100)
-}
-
-// ============================================================================
-// Author Resolution
-// ============================================================================
-
-/**
- * Resolve the author name for team-shared entries.
- * Priority: TEAM_AUTHOR env → git config user.name → 'unknown'
- *
- * Uses sanitizeAuthor() to strip control characters and cap length.
- */
-export function resolveAuthor(): string {
-    const envAuthor = process.env['TEAM_AUTHOR']?.trim().replace(/"/g, '')
-    if (envAuthor) return sanitizeAuthor(envAuthor)
-    try {
-        const gitUser = execFileSync('git', ['config', 'user.name'], {
-            encoding: 'utf-8',
-            timeout: GIT_COMMAND_TIMEOUT_MS,
-        })
-            .trim()
-            .replace(/"/g, '')
-        if (gitUser) return sanitizeAuthor(gitUser)
-    } catch {
-        // Git not available
-    }
-    return 'unknown'
-}

package/src/utils/vector-index-helpers.ts

@@ -1,24 +0,0 @@
-/**
- * Vector Index Helpers
- *
- * Shared fire-and-forget vector indexing logic used by entry-creation
- * handlers (create_entry, create_entry_minimal, restore_entry, etc.).
- */
-
-import type { VectorSearchManager } from '../vector/vector-search-manager.js'
-
-/**
- * Auto-index an entry to the vector store for semantic search.
- * Non-critical — failures are silently ignored because the entry
- * is already persisted in the database.
- */
-export function autoIndexEntry(
-    vectorManager: VectorSearchManager | undefined,
-    entryId: number,
-    content: string
-): void {
-    if (vectorManager === undefined) return
-    vectorManager.addEntry(entryId, content).catch(() => {
-        // Non-critical failure — entry already saved to DB
-    })
-}