memory-journal-mcp 4.4.2 → 5.0.0

package/src/types/index.ts

@@ -1,63 +1,44 @@
 /**
  * Memory Journal MCP Server - Type Definitions
  *
- * Core types for the MCP server including tools, resources, prompts,
- * database entities, and filtering.
- */
-
-// ============================================================================
-// Tool Filtering Types
-// ============================================================================
-
-/**
- * Tool group identifiers for Memory Journal
- */
-export type ToolGroup =
-    | 'core' // Entry CRUD: create, get_by_id, get_recent, create_minimal, test_simple
-    | 'search' // Search: search_entries, search_by_date_range, semantic_search
-    | 'analytics' // Analytics: get_statistics, get_cross_project_insights
-    | 'relationships' // Relationships: link_entries, visualize_relationships
-    | 'export' // Export: export_entries
-    | 'admin' // Admin: update_entry, delete_entry
-    | 'github' // Reserved for future GitHub-specific tools
-    | 'backup' // Backup: backup_journal, list_backups, restore_backup
-
-/**
- * Meta-group identifiers for common multi-group selections
- */
-export type MetaGroup =
-    | 'starter' // core + search (~8 tools)
-    | 'essential' // core only (~5 tools)
-    | 'full' // all groups (~16 tools)
-    | 'readonly' // everything except admin
-
-/**
- * Tool filter rule
- */
-export interface ToolFilterRule {
-    /** Rule type: include or exclude */
-    type: 'include' | 'exclude'
-
-    /** Target: group name or tool name */
-    target: string
-
-    /** Whether target is a group (true) or individual tool (false) */
-    isGroup: boolean
-}
-
-/**
- * Parsed tool filter configuration
- */
-export interface ToolFilterConfig {
-    /** Original filter string */
-    raw: string
-
-    /** Parsed rules in order */
-    rules: ToolFilterRule[]
-
-    /** Set of enabled tool names after applying rules */
-    enabledTools: Set<string>
-}
+ * Barrel file re-exporting all types from sub-modules, plus types
+ * that depend on external imports (SqliteAdapter, VectorSearchManager, etc.).
+ */
+
+import type { SqliteAdapter } from '../database/SqliteAdapter.js'
+import type { VectorSearchManager } from '../vector/VectorSearchManager.js'
+import type { GitHubIntegration } from '../github/GitHubIntegration.js'
+import type { ProgressContext } from '../utils/progress-utils.js'
+
+// Re-export sub-module types
+export type { ToolGroup, MetaGroup, ToolFilterRule, ToolFilterConfig } from './filtering.js'
+export type {
+    EntryType,
+    SignificanceType,
+    RelationshipType,
+    JournalEntry,
+    Tag,
+    Relationship,
+    Embedding,
+    ImportanceBreakdown,
+    ImportanceResult,
+} from './entities.js'
+export type {
+    GitHubProject,
+    GitHubIssue,
+    GitHubPullRequest,
+    GitHubMilestone,
+    GitHubWorkflowRun,
+    ProjectContext,
+    RepoStats,
+    TrafficData,
+    TrafficReferrer,
+    PopularPath,
+    ProjectV2StatusOption,
+    ProjectV2Item,
+    KanbanColumn,
+    KanbanBoard,
+} from './github.js'
 
 // ============================================================================
 // MCP 2025-11-25 Annotations
@@ -117,6 +98,8 @@ export interface McpIcon {
 // Tool, Resource, Prompt Definitions
 // ============================================================================
 
+import type { ToolGroup } from './filtering.js'
+
 /**
  * Tool definition for registration
  */
@@ -143,7 +126,33 @@ export interface ToolDefinition {
     annotations: ToolAnnotations
 
     /** Tool handler function */
-    handler: (params: unknown) => Promise<unknown>
+    handler: (params: unknown) => unknown
+}
+
+/**
+ * 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: SqliteAdapter
+    /** Team database adapter (optional, requires TEAM_DB_PATH) */
+    teamDb?: SqliteAdapter
+    /** Vector search manager (optional) */
+    vectorManager?: VectorSearchManager
+    /** GitHub integration (optional) */
+    github?: GitHubIntegration
+    /** Handler configuration */
+    config?: ToolHandlerConfig
+    /** Progress reporting context */
+    progress?: ProgressContext
 }
 
 /**
@@ -193,323 +202,6 @@ export interface PromptDefinition {
     handler: (args: Record<string, string>) => Promise<unknown>
 }
 
-// ============================================================================
-// Database Entity Types
-// ============================================================================
-
-/**
- * Entry types for journal entries
- */
-export type EntryType =
-    | 'personal_reflection'
-    | 'project_decision'
-    | 'technical_achievement'
-    | 'bug_fix'
-    | 'feature_implementation'
-    | 'code_review'
-    | 'meeting_notes'
-    | 'learning'
-    | 'research'
-    | 'planning'
-    | 'retrospective'
-    | 'standup'
-    | 'other'
-
-/**
- * Significance types for important entries
- */
-export type SignificanceType =
-    | 'milestone'
-    | 'breakthrough'
-    | 'technical_breakthrough'
-    | 'decision'
-    | 'lesson_learned'
-    | 'blocker_resolved'
-    | 'release'
-    | null
-
-/**
- * Relationship types between entries
- *
- * Standard types:
- * - evolves_from: Entry builds upon previous work
- * - references: Entry mentions or links to another
- * - implements: Entry implements a spec/design
- * - clarifies: Entry explains or clarifies another
- * - response_to: Entry responds to a question/issue
- *
- * Causal types (for decision tracing):
- * - blocked_by: Entry was blocked by another (e.g., blocker → resolution)
- * - resolved: Entry resolved/fixed an issue from another
- * - caused: Entry caused or led to another outcome
- */
-export type RelationshipType =
-    | 'evolves_from'
-    | 'references'
-    | 'implements'
-    | 'clarifies'
-    | 'response_to'
-    | 'blocked_by'
-    | 'resolved'
-    | 'caused'
-
-/**
- * Journal entry entity
- */
-export interface JournalEntry {
-    id: number
-    entryType: EntryType
-    content: string
-    timestamp: string
-    isPersonal: boolean
-    significanceType: SignificanceType
-    autoContext: string | null
-    deletedAt: string | null
-    tags: string[]
-    // GitHub integration fields
-    projectNumber?: number | null
-    projectOwner?: string | null
-    issueNumber?: number | null
-    issueUrl?: string | null
-    prNumber?: number | null
-    prUrl?: string | null
-    prStatus?: string | null
-    workflowRunId?: number | null
-    workflowName?: string | null
-    workflowStatus?: string | null
-}
-
-/**
- * Tag entity
- */
-export interface Tag {
-    id: number
-    name: string
-    usageCount: number
-}
-
-/**
- * Relationship entity
- */
-export interface Relationship {
-    id: number
-    fromEntryId: number
-    toEntryId: number
-    relationshipType: RelationshipType
-    description: string | null
-    createdAt: string
-}
-
-/**
- * Embedding entity for vector search
- */
-export interface Embedding {
-    entryId: number
-    embedding: Float32Array
-    modelName: string
-}
-
-/**
- * Importance scoring breakdown showing weighted component contributions
- */
-export interface ImportanceBreakdown {
-    /** Significance type contribution (weight: 0.30) */
-    significance: number
-    /** Relationship count contribution (weight: 0.35) */
-    relationships: number
-    /** Causal relationship contribution (weight: 0.20) */
-    causal: number
-    /** Recency decay contribution (weight: 0.15) */
-    recency: number
-}
-
-/**
- * Importance calculation result with total score and component breakdown
- */
-export interface ImportanceResult {
-    /** Total importance score (0.0-1.0) */
-    score: number
-    /** Weighted component contributions */
-    breakdown: ImportanceBreakdown
-}
-
-// ============================================================================
-// GitHub Integration Types
-// ============================================================================
-
-/**
- * GitHub project information
- */
-export interface GitHubProject {
-    number: number
-    title: string
-    url: string
-    state: 'OPEN' | 'CLOSED'
-}
-
-/**
- * GitHub issue information
- */
-export interface GitHubIssue {
-    number: number
-    title: string
-    url: string
-    state: 'OPEN' | 'CLOSED'
-    milestone?: { number: number; title: string } | null
-}
-
-/**
- * GitHub pull request information
- */
-export interface GitHubPullRequest {
-    number: number
-    title: string
-    url: string
-    state: 'OPEN' | 'CLOSED' | 'MERGED'
-}
-
-/**
- * GitHub milestone information
- */
-export interface GitHubMilestone {
-    number: number
-    title: string
-    description: string | null
-    state: 'open' | 'closed'
-    url: string
-    dueOn: string | null
-    openIssues: number
-    closedIssues: number
-    createdAt: string
-    updatedAt: string
-    creator: string | null
-}
-
-/**
- * GitHub workflow run information
- */
-export interface GitHubWorkflowRun {
-    id: number
-    name: string
-    status: 'queued' | 'in_progress' | 'completed'
-    conclusion: 'success' | 'failure' | 'cancelled' | 'skipped' | null
-    url: string
-    headBranch: string
-    headSha: string
-    createdAt: string
-    updatedAt: string
-}
-
-/**
- * Auto-captured project context
- */
-export interface ProjectContext {
-    repoName: string | null
-    branch: string | null
-    commit: string | null
-    remoteUrl: string | null
-    projects: GitHubProject[]
-    issues: GitHubIssue[]
-    pullRequests: GitHubPullRequest[]
-    workflowRuns: GitHubWorkflowRun[]
-    milestones: GitHubMilestone[]
-}
-
-// ============================================================================
-// Repository Insights/Traffic Types
-// ============================================================================
-
-/**
- * Repository statistics (stars, forks, watchers)
- */
-export interface RepoStats {
-    stars: number
-    forks: number
-    watchers: number
-    openIssues: number
-    size: number // KB
-    defaultBranch: string
-}
-
-/**
- * Aggregated traffic data (14-day rolling)
- */
-export interface TrafficData {
-    clones: { total: number; unique: number; dailyAvg: number }
-    views: { total: number; unique: number; dailyAvg: number }
-    period: string // e.g. "14 days"
-}
-
-/**
- * Traffic referrer source
- */
-export interface TrafficReferrer {
-    referrer: string
-    count: number
-    uniques: number
-}
-
-/**
- * Popular repository path
- */
-export interface PopularPath {
-    path: string
-    title: string
-    count: number
-    uniques: number
-}
-
-// ============================================================================
-// GitHub Projects v2 Kanban Types
-// ============================================================================
-
-/**
- * Status option for single-select field in Projects v2
- */
-export interface ProjectV2StatusOption {
-    id: string
-    name: string
-    color?: string
-}
-
-/**
- * Project item in a Kanban board
- */
-export interface ProjectV2Item {
-    id: string
-    title: string
-    url: string
-    type: 'ISSUE' | 'PULL_REQUEST' | 'DRAFT_ISSUE'
-    status: string | null
-    number?: number
-    labels?: string[]
-    assignees?: string[]
-    createdAt: string
-    updatedAt: string
-}
-
-/**
- * Kanban column (grouped by Status)
- */
-export interface KanbanColumn {
-    status: string
-    statusOptionId: string
-    items: ProjectV2Item[]
-}
-
-/**
- * Full Kanban board response
- */
-export interface KanbanBoard {
-    projectId: string
-    projectNumber: number
-    projectTitle: string
-    statusFieldId: string
-    statusOptions: ProjectV2StatusOption[]
-    columns: KanbanColumn[]
-    totalItems: number
-}
-
 // ============================================================================
 // Configuration Types
 // ============================================================================

package/src/utils/error-helpers.ts

@@ -0,0 +1,52 @@
+/**
+ * Centralized Error Helpers for Memory Journal MCP
+ *
+ * Provides consistent error formatting across all tool handlers.
+ * Follows the deterministic error handling standard from mysql-mcp:
+ * all errors return { success: false, error: "Human-readable message" }
+ * instead of throwing uncaught exceptions.
+ */
+
+import { ZodError } from 'zod'
+
+/**
+ * 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 a structured handler error response.
+ *
+ * Handles ZodError (validation) and general errors (runtime).
+ * 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): {
+    success: false
+    error: string
+} {
+    if (err instanceof ZodError) {
+        return { success: false, error: formatZodError(err) }
+    }
+    const message = err instanceof Error ? err.message : String(err)
+    return { success: false, error: message }
+}

package/src/utils/logger.ts

@@ -97,11 +97,14 @@ class Logger {
     }
 
     setLevel(level: LogLevel): void {
-        this.minLevel = LOG_LEVELS[level]
+        if (level in LOG_LEVELS) {
+            this.minLevel = LOG_LEVELS[level]
+        }
     }
 }
 
-// Get log level from environment
-const envLevel = (process.env['LOG_LEVEL'] ?? 'info') as LogLevel
+// 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)

package/src/utils/security-utils.ts

@@ -32,16 +32,6 @@ export class InvalidDateFormatError extends SecurityError {
     }
 }
 
-/**
- * Thrown when SQL injection patterns are detected in input
- */
-export class SqlInjectionError extends SecurityError {
-    constructor(pattern: string) {
-        super(`Potential SQL injection detected: '${pattern}'`, 'SQL_INJECTION')
-        this.name = 'SqlInjectionError'
-    }
-}
-
 /**
  * Thrown when path traversal is detected in input
  */
@@ -111,48 +101,6 @@ export function sanitizeSearchQuery(query: string): string {
     return query.replace(/\\/g, '\\\\').replace(/%/g, '\\%').replace(/_/g, '\\_')
 }
 
-// ============================================================================
-// SQL Injection Detection
-// ============================================================================
-
-/**
- * Patterns that indicate SQL injection attempts.
- * Used for validation in edge cases where parameterized queries aren't possible.
- */
-const SQL_INJECTION_PATTERNS = [
-    /;\s*(DROP|DELETE|INSERT|UPDATE|CREATE|ALTER|TRUNCATE)/i,
-    /--\s*/,
-    /\/\*[\s\S]*?\*\//,
-    /UNION\s+(ALL\s+)?SELECT/i,
-    /'\s*OR\s+['"]?1['"]?\s*=\s*['"]?1/i,
-    /ATTACH\s+DATABASE/i,
-    /DETACH\s+DATABASE/i,
-    /load_extension\s*\(/i,
-] as const
-
-/**
- * Checks if a string contains potential SQL injection patterns.
- * This is a secondary defense layer; parameterized queries are the primary defense.
- *
- * @param input - The string to check
- * @returns true if injection patterns are detected, false otherwise
- */
-export function containsSqlInjection(input: string): boolean {
-    return SQL_INJECTION_PATTERNS.some((pattern) => pattern.test(input))
-}
-
-/**
- * Validates that input does not contain SQL injection patterns.
- *
- * @param input - The string to validate
- * @throws SqlInjectionError if injection patterns are detected
- */
-export function assertNoSqlInjection(input: string): void {
-    if (containsSqlInjection(input)) {
-        throw new SqlInjectionError(input.substring(0, 50))
-    }
-}
-
 // ============================================================================
 // Path Validation
 // ============================================================================

package/src/vector/VectorSearchManager.ts

@@ -247,49 +247,25 @@ export class VectorSearchManager {
 
         logger.info('Rebuilding vector index from database...', { module: 'VectorSearch' })
 
-        // Step 1: Get total entry count and build ID set for orphan detection
+        // Step 1: Get total entry count for progress reporting
         const totalEntries = db.getActiveEntryCount()
-        const dbIds = new Set<string>()
 
-        // Collect all active entry IDs via pagination (avoids loading all content at once)
-        for (let offset = 0; offset < totalEntries; offset += REBUILD_PAGE_SIZE) {
-            const page = db.getEntriesPage(offset, REBUILD_PAGE_SIZE)
-            for (const entry of page) {
-                dbIds.add(String(entry.id))
-            }
-        }
-
-        // Step 2: Clean up existing index items
-        // If the index is corrupted (e.g., from a process kill), recreate it
+        // Step 2: Clean up existing index — delete all items for clean re-index
+        // (No orphan detection needed since everything is re-inserted from scratch)
         try {
             const indexItems = await this.index.listItems()
-            let orphansRemoved = 0
             for (const item of indexItems) {
-                if (!dbIds.has(item.id)) {
-                    try {
-                        await this.index.deleteItem(item.id)
-                        orphansRemoved++
-                    } catch {
-                        // Ignore errors during cleanup
-                    }
-                }
-            }
-            if (orphansRemoved > 0) {
-                logger.info(`Cleaned up ${String(orphansRemoved)} orphaned vector entries`, {
-                    module: 'VectorSearch',
-                })
-            }
-
-            // Step 3: Delete all remaining items to prepare for clean re-index
-            // This avoids the double-delete overhead of calling addEntry (upsert) per item
-            const remainingItems = await this.index.listItems()
-            for (const item of remainingItems) {
                 try {
                     await this.index.deleteItem(item.id)
                 } catch {
-                    // Ignore
+                    // Ignore individual deletion errors
                 }
             }
+            if (indexItems.length > 0) {
+                logger.info(`Cleared ${String(indexItems.length)} items from vector index`, {
+                    module: 'VectorSearch',
+                })
+            }
         } catch (indexError) {
             // Index files are corrupted — recreate from scratch
             logger.warning('Vector index corrupted, recreating...', {

package/tests/constants/icons.test.ts

@@ -17,7 +17,6 @@ import {
     ICON_BRIEFING,
     ICON_CLOCK,
     ICON_TAG,
-    ICON_TEAM,
     ICON_STAR,
     ICON_ISSUE,
     ICON_PR,
@@ -57,7 +56,7 @@ describe('Resource icons', () => {
         { name: 'ICON_BRIEFING', icon: ICON_BRIEFING },
         { name: 'ICON_CLOCK', icon: ICON_CLOCK },
         { name: 'ICON_TAG', icon: ICON_TAG },
-        { name: 'ICON_TEAM', icon: ICON_TEAM },
+
         { name: 'ICON_STAR', icon: ICON_STAR },
         { name: 'ICON_ISSUE', icon: ICON_ISSUE },
         { name: 'ICON_PR', icon: ICON_PR },