memory-journal-mcp 6.1.2 → 6.2.1

package/src/types/index.ts

@@ -1,348 +0,0 @@
-/**
- * Memory Journal MCP Server - Type Definitions
- *
- * Barrel file re-exporting all types from sub-modules, plus types
- * that depend on external imports (SqliteAdapter, VectorSearchManager, etc.).
- */
-
-import type { IDatabaseAdapter } from '../database/core/interfaces.js'
-import type { VectorSearchManager } from '../vector/vector-search-manager.js'
-import type { GitHubIntegration } from '../github/github-integration/index.js'
-import type { ProgressContext } from '../utils/progress-utils.js'
-
-// Re-export sub-module types
-export type { ToolGroup, MetaGroup, ToolFilterRule, ToolFilterConfig } from './filtering.js'
-export { ErrorCategory } from './error-types.js'
-export type { ErrorResponse, ErrorContext } from './error-types.js'
-export {
-    MemoryJournalMcpError,
-    ConnectionError,
-    QueryError,
-    ValidationError,
-    ResourceNotFoundError,
-    ConfigurationError,
-    PermissionError,
-} from './errors.js'
-export type {
-    EntryType,
-    SignificanceType,
-    RelationshipType,
-    JournalEntry,
-    Tag,
-    Relationship,
-    Embedding,
-    ImportanceBreakdown,
-    ImportanceResult,
-} from './entities.js'
-export type {
-    GitHubProject,
-    GitHubIssue,
-    GitHubPullRequest,
-    GitHubMilestone,
-    GitHubWorkflowRun,
-    GitHubReview,
-    GitHubReviewComment,
-    CopilotReviewSummary,
-    ProjectContext,
-    RepoStats,
-    TrafficData,
-    TrafficReferrer,
-    PopularPath,
-    ProjectV2StatusOption,
-    ProjectV2Item,
-    KanbanColumn,
-    KanbanBoard,
-} from './github.js'
-
-// ============================================================================
-// MCP 2025-11-25 Annotations
-// ============================================================================
-
-/**
- * MCP Tool Annotations (MCP Spec 2025-11-25)
- *
- * Behavioral hints for AI clients to understand tool characteristics.
- */
-export interface ToolAnnotations {
-    /** Tool does not modify state (idempotent reads) */
-    readOnlyHint?: boolean
-
-    /** Tool may permanently delete/destroy data */
-    destructiveHint?: boolean
-
-    /** Repeated calls with same args produce same result */
-    idempotentHint?: boolean
-
-    /** Tool interacts with external services (network, APIs) */
-    openWorldHint?: boolean
-}
-
-/**
- * MCP Resource Annotations (MCP Spec 2025-11-25)
- */
-export interface ResourceAnnotations {
-    /** Intended audience: 'user' or 'assistant' */
-    audience?: ('user' | 'assistant')[]
-
-    /** Importance level from 0.0 (optional) to 1.0 (required) */
-    priority?: number
-
-    /** ISO 8601 timestamp of last modification */
-    lastModified?: string
-}
-
-/**
- * MCP Icon Definition (MCP Spec 2025-11-25)
- *
- * Icons can be added to servers, tools, resources, and prompts for
- * visual representation in client interfaces.
- */
-export interface McpIcon {
-    /** Icon source - URL or data URI */
-    src: string
-
-    /** MIME type (e.g., 'image/svg+xml', 'image/png') */
-    mimeType?: string
-
-    /** Size descriptors (e.g., ['48x48'], ['any']) */
-    sizes?: string[]
-}
-
-// ============================================================================
-// Tool, Resource, Prompt Definitions
-// ============================================================================
-
-import type { ToolGroup } from './filtering.js'
-
-/**
- * Tool definition for registration
- */
-export interface ToolDefinition {
-    /** Unique tool name */
-    name: string
-
-    /** Human-readable display title (MCP 2025-11-25) */
-    title: string
-
-    /** Human-readable description */
-    description: string
-
-    /** Tool group for filtering */
-    group: ToolGroup
-
-    /** Zod schema for input validation */
-    inputSchema: unknown
-
-    /** Zod schema for output validation (MCP 2025-11-25 outputSchema) */
-    outputSchema?: unknown
-
-    /** Behavioral hints for AI clients */
-    annotations: ToolAnnotations
-
-    /** Tool handler function */
-    handler: (params: unknown) => unknown
-}
-
-/**
- * Shape returned by `getTools()` for MCP SDK registration.
- * Derived from `ToolDefinition` but excludes internal fields (group, handler).
- */
-export interface ToolRegistration {
-    name: string
-    /** Human-readable display title (MCP 2025-11-25) */
-    title?: string
-    description: string
-    inputSchema: unknown
-    outputSchema?: unknown
-    annotations: ToolAnnotations
-    icons?: { iconUrl: string; title: string; description: string }
-}
-
-/**
- * Tool handler configuration options
- */
-export interface ToolHandlerConfig {
-    /** Default GitHub Project number for auto-assignment */
-    defaultProjectNumber?: number
-}
-
-/**
- * Tool execution context passed to all tool group modules
- */
-export interface ToolContext {
-    /** Database adapter */
-    db: IDatabaseAdapter
-    /** Team database adapter (optional, requires TEAM_DB_PATH) */
-    teamDb?: IDatabaseAdapter
-    /** Vector search manager (optional) */
-    vectorManager?: VectorSearchManager
-    /** Team vector search manager (optional, bound to team DB) */
-    teamVectorManager?: VectorSearchManager
-    /** GitHub integration (optional) */
-    github?: GitHubIntegration
-    /** Handler configuration */
-    config?: ToolHandlerConfig
-    /** Progress reporting context */
-    progress?: ProgressContext
-}
-
-/**
- * Resource definition for MCP
- */
-export interface ResourceDefinition {
-    /** Resource URI template */
-    uri: string
-
-    /** Human-readable name */
-    name: string
-
-    /** Human-readable display title */
-    title: string
-
-    /** Description */
-    description: string
-
-    /** MIME type */
-    mimeType: string
-
-    /** Resource metadata annotations */
-    annotations?: ResourceAnnotations
-
-    /** Resource handler - NOTE: db is passed at runtime, not in the definition */
-    handler: (uri: string) => Promise<unknown>
-}
-
-/**
- * Prompt definition for MCP
- */
-export interface PromptDefinition {
-    /** Prompt name */
-    name: string
-
-    /** Description */
-    description: string
-
-    /** Argument definitions */
-    arguments?: {
-        name: string
-        description: string
-        required?: boolean
-    }[]
-
-    /** Prompt handler */
-    handler: (args: Record<string, string>) => Promise<unknown>
-}
-
-// ============================================================================
-// Configuration Types
-// ============================================================================
-
-/**
- * Server configuration
- */
-export interface ServerConfig {
-    /** Path to SQLite database file */
-    dbPath: string
-
-    /** GitHub personal access token */
-    githubToken?: string
-
-    /** GitHub organization token (for org projects) */
-    githubOrgToken?: string
-
-    /** Default organization name */
-    defaultOrg?: string
-
-    /** Tool filter string */
-    toolFilter?: string
-
-    /** Default GitHub Project number for auto-assignment */
-    defaultProjectNumber?: number
-
-    /** Enable semantic search */
-    enableSemanticSearch: boolean
-
-    /** Sentence transformer model name */
-    modelName: string
-
-    /** Briefing depth for AI client instructions */
-    instructionLevel?: 'essential' | 'standard' | 'full'
-}
-
-/**
- * Default configuration values
- */
-export const DEFAULT_CONFIG: Partial<ServerConfig> = {
-    dbPath: './memory_journal.db',
-    enableSemanticSearch: true,
-    modelName: 'all-MiniLM-L6-v2',
-}
-
-// ============================================================================
-// Backup Types
-// ============================================================================
-
-/**
- * Backup file information
- */
-export interface BackupInfo {
-    /** Backup filename */
-    filename: string
-
-    /** Full path to backup file */
-    path: string
-
-    /** File size in bytes */
-    sizeBytes: number
-
-    /** Backup creation time (ISO 8601) */
-    createdAt: string
-}
-
-// ============================================================================
-// Health Status Types
-// ============================================================================
-
-/**
- * Server health and diagnostics status
- */
-export interface HealthStatus {
-    /** Database statistics */
-    database: {
-        path: string
-        sizeBytes: number
-        entryCount: number
-        deletedEntryCount: number
-        relationshipCount: number
-        tagCount: number
-    }
-
-    /** Backup information */
-    backups: {
-        directory: string
-        count: number
-        lastBackup: {
-            filename: string
-            createdAt: string
-            sizeBytes: number
-        } | null
-    }
-
-    /** Vector search index status */
-    vectorIndex: {
-        available: boolean
-        itemCount: number
-        modelName: string | null
-    } | null
-
-    /** Tool filter configuration */
-    toolFilter: {
-        active: boolean
-        enabledCount: number
-        totalCount: number
-        filterString: string | null
-    }
-
-    /** Health check timestamp (ISO 8601) */
-    timestamp: string
-}

package/src/utils/error-helpers.ts

@@ -1,78 +0,0 @@
-/**
- * Centralized Error Helpers for Memory Journal MCP
- *
- * Provides consistent error formatting across all tool handlers.
- * All errors return structured responses instead of throwing
- * uncaught exceptions.
- */
-
-import { ZodError } from 'zod'
-import { MemoryJournalMcpError } from '../types/errors.js'
-import { ErrorCategory, type ErrorResponse } from '../types/error-types.js'
-import { matchSuggestion } from './errors/suggestions.js'
-
-/**
- * Extract human-readable messages from a ZodError instead of raw JSON array.
- * Maps each Zod issue to its path + message for clear validation feedback.
- */
-export function formatZodError(error: ZodError): string {
-    return error.issues
-        .map((issue) => {
-            const path = issue.path.length > 0 ? `${issue.path.join('.')}: ` : ''
-            return `${path}${issue.message}`
-        })
-        .join('; ')
-}
-
-/**
- * Format any caught error into an enriched ErrorResponse.
- *
- * Returns structured error information including code, category,
- * suggestion, and recoverable flag. Handles MemoryJournalMcpError
- * (full context), ZodError (validation), and raw errors (internal
- * with pattern-matched suggestions from ERROR_SUGGESTIONS).
- *
- * Use as the single catch block for all tool handlers:
- *
- * ```typescript
- * handler: async (params) => {
- *   try {
- *     const parsed = Schema.parse(params);
- *     // ... domain logic ...
- *     return { success: true, ... };
- *   } catch (err) {
- *     return formatHandlerError(err);
- *   }
- * }
- * ```
- */
-export function formatHandlerError(err: unknown): ErrorResponse {
-    // MemoryJournalMcpError and subclasses (OAuthError, SecurityError, etc.)
-    if (err instanceof MemoryJournalMcpError) {
-        return err.toResponse()
-    }
-
-    // Zod validation errors
-    if (err instanceof ZodError) {
-        return {
-            success: false,
-            error: formatZodError(err),
-            code: 'VALIDATION_ERROR',
-            category: ErrorCategory.VALIDATION,
-            suggestion: 'Check input parameters against the tool schema',
-            recoverable: false,
-        }
-    }
-
-    // Unknown / raw errors — enrich via ERROR_SUGGESTIONS pattern matching
-    const message = err instanceof Error ? err.message : String(err)
-    const matched = matchSuggestion(message)
-    return {
-        success: false,
-        error: message,
-        code: matched?.code ?? 'INTERNAL_ERROR',
-        category: ErrorCategory.INTERNAL,
-        recoverable: false,
-        ...(matched?.suggestion ? { suggestion: matched.suggestion } : {}),
-    }
-}

package/src/utils/errors/error-response-fields.ts

@@ -1,29 +0,0 @@
-/**
- * Shared Error Response Fields for Output Schemas
- *
- * Defines the ErrorFieldsMixin Zod schema fragment that gets extended into
- * every output schema. This ensures formatHandlerError() responses pass
- * output schema validation (MCP SDK enforces additionalProperties: false).
- *
- * SSoT location: src/utils/errors/error-response-fields.ts
- * All output schemas should import from here.
- */
-
-import { z } from 'zod'
-
-/**
- * Standard error response fields returned by formatHandlerError().
- * Extend this into every output schema:
- *   export const MyOutputSchema = z.object({ ... }).extend(ErrorFieldsMixin.shape);
- */
-export const ErrorFieldsMixin = z.object({
-    error: z.string().optional().describe('Human-readable error message'),
-    code: z.string().optional().describe('Error code (e.g. VALIDATION_ERROR, INTERNAL_ERROR)'),
-    category: z
-        .string()
-        .optional()
-        .describe('Error category (validation, query, connection, internal)'),
-    recoverable: z.boolean().optional().describe('Whether the error is recoverable'),
-    suggestion: z.string().optional().describe('Suggested fix for the error'),
-    details: z.record(z.string(), z.unknown()).optional().describe('Additional error context'),
-})

package/src/utils/errors/suggestions.ts

@@ -1,94 +0,0 @@
-/**
- * Error Suggestions — Fuzzy Pattern Matching for Error Messages
- *
- * Maps common error message patterns to actionable suggestions and
- * specific error codes. Used by:
- * 1. MemoryJournalMcpError constructor — auto-refines generic codes
- * 2. formatHandlerError() — enriches raw Error responses
- */
-
-// =============================================================================
-// Types
-// =============================================================================
-
-interface ErrorSuggestion {
-    /** RegExp to test against error messages (case-insensitive) */
-    pattern: RegExp
-    /** Human-readable suggestion for resolving the error */
-    suggestion: string
-    /** Optional specific code to auto-refine generic codes into */
-    code?: string
-}
-
-// =============================================================================
-// Generic codes eligible for auto-refinement
-// =============================================================================
-
-/** Codes that can be refined to a more specific code when a pattern matches */
-export const GENERIC_CODES = new Set(['QUERY_FAILED', 'INTERNAL_ERROR', 'UNKNOWN_ERROR'])
-
-// =============================================================================
-// Suggestion Table
-// =============================================================================
-
-export const ERROR_SUGGESTIONS: ErrorSuggestion[] = [
-    // Resource not found patterns
-    {
-        pattern: /not found/i,
-        suggestion: 'Verify the resource identifier and try again',
-        code: 'RESOURCE_NOT_FOUND',
-    },
-    {
-        pattern: /no such table/i,
-        suggestion: 'The database table does not exist. Run database initialization.',
-        code: 'TABLE_NOT_FOUND',
-    },
-    // Permission / access patterns
-    {
-        pattern: /permission denied|SQLITE_READONLY/i,
-        suggestion: 'Check file permissions and database access rights',
-        code: 'PERMISSION_DENIED',
-    },
-    // Connection / lock patterns
-    {
-        pattern: /database is locked/i,
-        suggestion: 'The database is locked by another process. Retry after a short delay.',
-        code: 'CONNECTION_FAILED',
-    },
-    // Constraint patterns
-    {
-        pattern: /SQLITE_CONSTRAINT|unique constraint/i,
-        suggestion: 'A uniqueness or integrity constraint was violated. Check input values.',
-        code: 'VALIDATION_FAILED',
-    },
-    // Disk / space patterns
-    {
-        pattern: /disk I\/O|SQLITE_FULL/i,
-        suggestion: 'The disk may be full or the filesystem is read-only.',
-    },
-    // Malformed input patterns
-    {
-        pattern: /malformed|invalid json|unexpected token/i,
-        suggestion: 'The input appears malformed. Check the format and try again.',
-        code: 'VALIDATION_FAILED',
-    },
-]
-
-// =============================================================================
-// Matching
-// =============================================================================
-
-/**
- * Find the first matching suggestion for an error message.
- * Returns `undefined` if no pattern matches.
- */
-export function matchSuggestion(
-    message: string
-): { suggestion: string; code?: string } | undefined {
-    for (const entry of ERROR_SUGGESTIONS) {
-        if (entry.pattern.test(message)) {
-            return { suggestion: entry.suggestion, code: entry.code }
-        }
-    }
-    return undefined
-}

package/src/utils/github-helpers.ts

@@ -1,33 +0,0 @@
-/**
- * GitHub URL Helpers
- *
- * Shared utilities for resolving GitHub URLs from cached repo info.
- * Eliminates duplication between core and team tool handlers.
- */
-
-import type { GitHubIntegration } from '../github/github-integration/index.js'
-
-/**
- * Resolve a GitHub issue URL from the cached repo info.
- *
- * If `existingUrl` is already provided, returns it unchanged.
- * If `issueNumber` is provided without a URL and GitHub is available
- * with cached repo info, constructs the URL automatically.
- *
- * @returns The resolved issue URL, or undefined if not resolvable
- */
-export function resolveIssueUrl(
-    github: GitHubIntegration | undefined,
-    issueNumber: number | undefined,
-    existingUrl: string | undefined
-): string | undefined {
-    if (existingUrl) return existingUrl
-    if (issueNumber === undefined || !github) return undefined
-
-    const cachedRepo = github.getCachedRepoInfo()
-    if (cachedRepo?.owner && cachedRepo?.repo) {
-        return `https://github.com/${cachedRepo.owner}/${cachedRepo.repo}/issues/${String(issueNumber)}`
-    }
-
-    return undefined
-}

package/src/utils/logger.ts

@@ -1,107 +0,0 @@
-/**
- * Memory Journal MCP Server - Logger
- *
- * Centralized logging to stderr only (stdout reserved for MCP protocol).
- * Follows RFC 5424 severity levels.
- * Automatically sanitizes error fields to prevent token leakage.
- */
-
-import { sanitizeErrorForLogging } from './security-utils.js'
-
-type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical'
-
-interface LogContext {
-    module?: string
-    operation?: string
-    entityId?: string | number
-    [key: string]: unknown
-}
-
-const LOG_LEVELS: Record<LogLevel, number> = {
-    debug: 7,
-    info: 6,
-    notice: 5,
-    warning: 4,
-    error: 3,
-    critical: 2,
-}
-
-class Logger {
-    private minLevel: number
-
-    constructor(level: LogLevel = 'info') {
-        this.minLevel = LOG_LEVELS[level]
-    }
-
-    private shouldLog(level: LogLevel): boolean {
-        return LOG_LEVELS[level] <= this.minLevel
-    }
-
-    private log(level: LogLevel, message: string, context?: LogContext): void {
-        if (!this.shouldLog(level)) return
-
-        // Sanitize all user-controlled inputs to prevent log injection (CodeQL js/log-injection).
-        // Each .replace() must be applied inline — CodeQL cannot track sanitization through method calls.
-        const safeMessage = message.replace(/\n|\r/g, '')
-        const timestamp = new Date().toISOString()
-        const levelUpper = level.toUpperCase().padEnd(8)
-
-        const mod = context?.module ? `[${context.module.replace(/\n|\r/g, '')}]` : ''
-        const op = context?.operation ? `[${context.operation.replace(/\n|\r/g, '')}]` : ''
-
-        let line = `[${timestamp}] [${levelUpper}] ${mod}${op} ${safeMessage}`
-
-        // Add context as JSON if there are additional fields
-        const extras: Record<string, unknown> = { ...context }
-        delete extras['module']
-        delete extras['operation']
-
-        // Sanitize error fields to prevent token leakage
-        if (extras['error'] != null && typeof extras['error'] === 'string') {
-            extras['error'] = sanitizeErrorForLogging(extras['error'])
-        }
-
-        if (Object.keys(extras).length > 0) {
-            line += ` ${JSON.stringify(extras).replace(/\n|\r/g, '')}`
-        }
-
-        // Always write to stderr (stdout is reserved for MCP protocol)
-        console.error(line)
-    }
-
-    debug(message: string, context?: LogContext): void {
-        this.log('debug', message, context)
-    }
-
-    info(message: string, context?: LogContext): void {
-        this.log('info', message, context)
-    }
-
-    notice(message: string, context?: LogContext): void {
-        this.log('notice', message, context)
-    }
-
-    warning(message: string, context?: LogContext): void {
-        this.log('warning', message, context)
-    }
-
-    error(message: string, context?: LogContext): void {
-        this.log('error', message, context)
-    }
-
-    critical(message: string, context?: LogContext): void {
-        this.log('critical', message, context)
-    }
-
-    setLevel(level: LogLevel): void {
-        if (level in LOG_LEVELS) {
-            this.minLevel = LOG_LEVELS[level]
-        }
-    }
-}
-
-// Get log level from environment (validated against known levels)
-const rawLevel = process.env['LOG_LEVEL'] ?? 'info'
-const envLevel: LogLevel = rawLevel in LOG_LEVELS ? (rawLevel as LogLevel) : 'info'
-
-export const logger = new Logger(envLevel)