memory-journal-mcp 6.1.2 → 6.2.1

package/src/handlers/tools/schemas.ts

@@ -1,165 +0,0 @@
-/**
- * Shared Zod Schemas for Tool Handlers
- *
- * Contains cross-group schemas used by multiple tool modules:
- * - EntryOutputSchema: used by core, search, export, admin
- * - EntriesListOutputSchema: used by search, core
- * - RelationshipOutputSchema: used by core, relationships
- * - TagOutputSchema: used by core, analytics
- * - ImportanceBreakdownSchema: used by core
- * - Shared constants: ENTRY_TYPES, SIGNIFICANCE_TYPES, DATE_FORMAT_REGEX
- *
- * Group-specific output schemas stay colocated with their group files.
- */
-
-import { z } from 'zod'
-import { ErrorFieldsMixin } from './error-fields-mixin.js'
-
-// ============================================================================
-// Shared Constants
-// ============================================================================
-
-/**
- * Valid entry types (matches EntryType union in types/index.ts)
- */
-export const ENTRY_TYPES = [
-    'personal_reflection',
-    'project_decision',
-    'technical_achievement',
-    'bug_fix',
-    'feature_implementation',
-    'code_review',
-    'meeting_notes',
-    'learning',
-    'research',
-    'planning',
-    'retrospective',
-    'standup',
-    'technical_note',
-    'development_note',
-    'enhancement',
-    'milestone',
-    'system_integration_test',
-    'test_entry',
-    'other',
-] as const
-
-/**
- * Valid significance types (matches SignificanceType union in types/index.ts)
- */
-export const SIGNIFICANCE_TYPES = [
-    'milestone',
-    'breakthrough',
-    'technical_breakthrough',
-    'decision',
-    'lesson_learned',
-    'blocker_resolved',
-    'release',
-] as const
-
-/** Maximum content length for journal entries (chars) */
-export const MAX_CONTENT_LENGTH = 50_000
-
-/** Date sentinels for "all time" date range queries */
-export const DATE_MIN_SENTINEL = '1970-01-01'
-export const DATE_MAX_SENTINEL = '2999-12-31'
-
-/** YYYY-MM-DD date format regex */
-export const DATE_FORMAT_REGEX = /^\d{4}-\d{2}-\d{2}$/
-export const DATE_FORMAT_MESSAGE = 'Date must be YYYY-MM-DD format'
-
-/**
- * Relaxed numeric schema for MCP SDK inputSchema registration.
- *
- * Uses `z.union([z.number(), z.string()])` so the SDK's Zod validation
- * accepts both native numbers and string-typed numbers (e.g., `"42"`).
- * The handler's strict schema (`z.number()`) then validates and coerces
- * the value, producing structured `{success: false, error}` responses
- * via `formatHandlerError()` for invalid input.
- *
- * NOTE: `z.preprocess()` was attempted but its `ZodEffects` return type
- * is too complex for ESLint's strict type resolver, causing cascading
- * `@typescript-eslint/no-unsafe-*` errors across all call sites.
- */
-export const relaxedNumber = (): z.ZodUnion<[z.ZodNumber, z.ZodString]> =>
-    z.union([z.number(), z.string()])
-
-// ============================================================================
-// Cross-Group Output Schemas
-// ============================================================================
-
-/**
- * Schema for a journal entry in output responses.
- * Uses camelCase to match actual database output format.
- */
-export const EntryOutputSchema = z
-    .object({
-        id: z.number(),
-        content: z.string(),
-        entryType: z.string(),
-        isPersonal: z.boolean(),
-        timestamp: z.string(),
-        tags: z.array(z.string()).optional(),
-        significanceType: z.string().nullable().optional(),
-        autoContext: z.string().nullable().optional(),
-        deletedAt: z.string().nullable().optional(),
-        projectNumber: z.number().nullable().optional(),
-        projectOwner: z.string().nullable().optional(),
-        issueNumber: z.number().nullable().optional(),
-        issueUrl: z.string().nullable().optional(),
-        prNumber: z.number().nullable().optional(),
-        prUrl: z.string().nullable().optional(),
-        prStatus: z.string().nullable().optional(),
-        workflowRunId: z.number().nullable().optional(),
-        workflowName: z.string().nullable().optional(),
-        workflowStatus: z.string().nullable().optional(),
-        source: z.enum(['personal', 'team']).optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-/**
- * Schema for list of entries with count.
- * Used by get_recent_entries, search_entries, search_by_date_range.
- */
-export const EntriesListOutputSchema = z
-    .object({
-        entries: z.array(EntryOutputSchema).optional(),
-        count: z.number().optional(),
-        success: z.boolean().optional(),
-        error: z.string().optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-/**
- * Schema for a relationship between entries.
- */
-export const RelationshipOutputSchema = z
-    .object({
-        id: z.number(),
-        fromEntryId: z.number(),
-        toEntryId: z.number(),
-        relationshipType: z.string(),
-        description: z.string().nullable().optional(),
-        createdAt: z.string(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-/**
- * Importance score breakdown schema.
- */
-export const ImportanceBreakdownSchema = z.object({
-    significance: z.number(),
-    relationships: z.number(),
-    causal: z.number(),
-    recency: z.number(),
-})
-
-/**
- * Tag with usage count.
- */
-export const TagOutputSchema = z
-    .object({
-        name: z.string(),
-        count: z.number().nullable(),
-    })
-    .extend(ErrorFieldsMixin.shape)

package/src/handlers/tools/search.ts

@@ -1,448 +0,0 @@
-/**
- * Search Tool Group - 4 tools
- *
- * Tools: search_entries, search_by_date_range, semantic_search, get_vector_index_stats
- */
-
-import { z } from 'zod'
-import type { ToolDefinition, ToolContext } from '../../types/index.js'
-import { formatHandlerError } from '../../utils/error-helpers.js'
-import { ErrorFieldsMixin } from './error-fields-mixin.js'
-import {
-    ENTRY_TYPES,
-    DATE_FORMAT_REGEX,
-    DATE_FORMAT_MESSAGE,
-    EntryOutputSchema,
-    EntriesListOutputSchema,
-    relaxedNumber,
-} from './schemas.js'
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-/** Maximum entries returned by any single search query */
-const MAX_QUERY_LIMIT = 500
-
-// ============================================================================
-// Input Schemas
-// ============================================================================
-
-/** Strict schema — used inside handler for structured Zod errors */
-const SearchEntriesSchema = z.object({
-    query: z.string().optional(),
-    limit: z.number().max(MAX_QUERY_LIMIT).optional().default(10),
-    is_personal: z.boolean().optional(),
-    project_number: z.number().optional(),
-    issue_number: z.number().optional(),
-    pr_number: z.number().optional(),
-    pr_status: z.enum(['draft', 'open', 'merged', 'closed']).optional(),
-    workflow_run_id: z.number().optional(),
-})
-
-/** Relaxed schema — passed to SDK inputSchema so Zod enum errors reach the handler */
-const SearchEntriesSchemaMcp = z.object({
-    query: z.string().optional(),
-    limit: relaxedNumber().optional().default(10),
-    is_personal: z.boolean().optional(),
-    project_number: relaxedNumber().optional(),
-    issue_number: relaxedNumber().optional(),
-    pr_number: relaxedNumber().optional(),
-    pr_status: z.string().optional(),
-    workflow_run_id: relaxedNumber().optional(),
-})
-
-/** Strict schema — used inside handler for structured Zod errors */
-const SearchByDateRangeSchema = z.object({
-    start_date: z.string().regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE),
-    end_date: z.string().regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE),
-    entry_type: z.enum(ENTRY_TYPES).optional(),
-    tags: z.array(z.string()).optional(),
-    is_personal: z.boolean().optional(),
-    project_number: z.number().optional(),
-    issue_number: z.number().optional(),
-    pr_number: z.number().optional(),
-    workflow_run_id: z.number().optional(),
-    limit: z.number().max(MAX_QUERY_LIMIT).optional().default(500),
-})
-
-/** Relaxed schema — passed to SDK inputSchema so Zod errors reach the handler */
-const SearchByDateRangeSchemaMcp = z.object({
-    start_date: z.string(),
-    end_date: z.string(),
-    entry_type: z.string().optional(),
-    tags: z.array(z.string()).optional(),
-    is_personal: z.boolean().optional(),
-    project_number: relaxedNumber().optional(),
-    issue_number: relaxedNumber().optional(),
-    pr_number: relaxedNumber().optional(),
-    workflow_run_id: relaxedNumber().optional(),
-    limit: relaxedNumber().optional().default(500),
-})
-
-/** Strict schema — used inside handler for structured Zod errors */
-const SemanticSearchSchema = z.object({
-    query: z.string(),
-    limit: z.number().max(MAX_QUERY_LIMIT).optional().default(10),
-    similarity_threshold: z.number().optional().default(0.25),
-    is_personal: z.boolean().optional(),
-    hint_on_empty: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe('Include hint when no results found (default: true)'),
-})
-
-/** Relaxed schema — passed to SDK inputSchema so Zod min/max errors reach the handler */
-const SemanticSearchSchemaMcp = z.object({
-    query: z.string(),
-    limit: relaxedNumber().optional().default(10),
-    similarity_threshold: relaxedNumber().optional().default(0.25),
-    is_personal: z.boolean().optional(),
-    hint_on_empty: z
-        .boolean()
-        .optional()
-        .default(true)
-        .describe('Include hint when no results found (default: true)'),
-})
-
-// ============================================================================
-// Output Schemas
-// ============================================================================
-
-const SemanticEntryOutputSchema = EntryOutputSchema.extend({
-    similarity: z.number(),
-})
-
-const SemanticSearchOutputSchema = z
-    .object({
-        query: z.string().optional(),
-        entries: z.array(SemanticEntryOutputSchema).optional(),
-        count: z.number().optional(),
-        hint: z.string().optional(),
-        success: z.boolean().optional(),
-        error: z.string().optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-const VectorStatsOutputSchema = z
-    .object({
-        available: z.boolean(),
-        error: z.string().optional(),
-        itemCount: z.number().optional(),
-        modelName: z.string().optional(),
-        dimensions: z.number().optional(),
-        success: z.boolean().optional(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-// ============================================================================
-// Tool Definitions
-// ============================================================================
-
-export function getSearchTools(context: ToolContext): ToolDefinition[] {
-    const { db, teamDb, vectorManager } = context
-    return [
-        {
-            name: 'search_entries',
-            title: 'Search Entries',
-            description:
-                'Full-text search journal entries using FTS5 (supports phrases "exact match", prefix auth*, boolean NOT/OR/AND, ranked by relevance). Optional filters for GitHub Projects, Issues, PRs, and Actions.',
-            group: 'search',
-            inputSchema: SearchEntriesSchemaMcp,
-            outputSchema: EntriesListOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-            handler: (params: unknown) => {
-                try {
-                    const input = SearchEntriesSchema.parse(params)
-                    const hasFilters =
-                        input.project_number !== undefined ||
-                        input.issue_number !== undefined ||
-                        input.pr_number !== undefined ||
-                        input.pr_status !== undefined ||
-                        input.workflow_run_id !== undefined ||
-                        input.is_personal !== undefined
-
-                    // When merging across DBs, fetch more per-DB so BM25 ranking
-                    // in one DB doesn't silently drop entries before the merge.
-                    // The actual user limit is applied by mergeAndDedup.
-                    const perDbLimit = calcPerDbLimit(input.limit, !!teamDb)
-
-                    let personalEntries
-                    if (!input.query && !hasFilters) {
-                        personalEntries = db.getRecentEntries(perDbLimit, input.is_personal)
-                    } else {
-                        personalEntries = db.searchEntries(input.query || '', {
-                            limit: perDbLimit,
-                            isPersonal: input.is_personal,
-                            projectNumber: input.project_number,
-                            issueNumber: input.issue_number,
-                            prNumber: input.pr_number,
-                            prStatus: input.pr_status,
-                            workflowRunId: input.workflow_run_id,
-                        })
-                    }
-
-                    // Cross-database merge when team DB is available
-                    // Skip team DB when is_personal is explicitly true (team entries are never personal)
-                    if (teamDb && input.is_personal !== true) {
-                        let teamEntries
-                        if (!input.query && !hasFilters) {
-                            teamEntries = teamDb.getRecentEntries(perDbLimit)
-                        } else {
-                            teamEntries = teamDb.searchEntries(input.query || '', {
-                                limit: perDbLimit,
-                                projectNumber: input.project_number,
-                                issueNumber: input.issue_number,
-                                prNumber: input.pr_number,
-                                prStatus: input.pr_status,
-                                workflowRunId: input.workflow_run_id,
-                            })
-                        }
-                        const merged = mergeAndDedup(
-                            personalEntries.map((e) => ({ ...e, source: 'personal' as const })),
-                            teamEntries.map((e) => ({ ...e, source: 'team' as const })),
-                            input.limit
-                        )
-                        return { entries: merged, count: merged.length }
-                    }
-
-                    return { entries: personalEntries, count: personalEntries.length }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-        {
-            name: 'search_by_date_range',
-            title: 'Search by Date Range',
-            description: 'Search journal entries within a date range with optional filters',
-            group: 'search',
-            inputSchema: SearchByDateRangeSchemaMcp,
-            outputSchema: EntriesListOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-            handler: (params: unknown) => {
-                try {
-                    const input = SearchByDateRangeSchema.parse(params)
-
-                    // Validate date range order (YYYY-MM-DD sorts lexicographically)
-                    if (input.start_date > input.end_date) {
-                        return {
-                            success: false,
-                            error: `Invalid date range: start_date (${input.start_date}) is after end_date (${input.end_date})`,
-                            code: 'VALIDATION_ERROR',
-                            category: 'validation',
-                            suggestion: 'Ensure start_date is before or equal to end_date',
-                            recoverable: true,
-                        }
-                    }
-
-                    const perDbLimit = calcPerDbLimit(input.limit, !!teamDb)
-                    const personalEntries = db.searchByDateRange(input.start_date, input.end_date, {
-                        entryType: input.entry_type,
-                        tags: input.tags,
-                        isPersonal: input.is_personal,
-                        projectNumber: input.project_number,
-                        issueNumber: input.issue_number,
-                        prNumber: input.pr_number,
-                        workflowRunId: input.workflow_run_id,
-                        limit: perDbLimit,
-                    })
-
-                    // Cross-database merge when team DB is available
-                    // Skip team DB when is_personal is explicitly true (team entries are never personal)
-                    if (teamDb && input.is_personal !== true) {
-                        const teamEntries = teamDb.searchByDateRange(
-                            input.start_date,
-                            input.end_date,
-                            {
-                                entryType: input.entry_type,
-                                tags: input.tags,
-                                projectNumber: input.project_number,
-                                issueNumber: input.issue_number,
-                                prNumber: input.pr_number,
-                                workflowRunId: input.workflow_run_id,
-                                limit: perDbLimit,
-                            }
-                        )
-                        const merged = mergeAndDedup(
-                            personalEntries.map((e) => ({ ...e, source: 'personal' as const })),
-                            teamEntries.map((e) => ({ ...e, source: 'team' as const })),
-                            input.limit
-                        )
-                        return { entries: merged, count: merged.length }
-                    }
-
-                    return { entries: personalEntries, count: personalEntries.length }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-        {
-            name: 'semantic_search',
-            title: 'Semantic Search',
-            description: 'Perform semantic/vector search on journal entries using AI embeddings',
-            group: 'search',
-            inputSchema: SemanticSearchSchemaMcp,
-            outputSchema: SemanticSearchOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-            handler: async (params: unknown) => {
-                try {
-                    const input = SemanticSearchSchema.parse(params)
-
-                    if (!vectorManager) {
-                        return {
-                            success: false,
-                            error: 'Semantic search not initialized. Vector search manager is not available.',
-                            code: 'CONFIGURATION_ERROR',
-                            category: 'configuration',
-                            suggestion:
-                                'Enable semantic search with --auto-rebuild-index or set up the vector manager',
-                            recoverable: false,
-                            query: input.query,
-                            entries: [],
-                            count: 0,
-                        }
-                    }
-
-                    const results = await vectorManager.search(
-                        input.query,
-                        input.limit ?? 10,
-                        input.similarity_threshold ?? 0.25
-                    )
-
-                    // Batch-fetch all entries in a single query (instead of N+1 getEntryById calls)
-                    const entryIds = results.map((r) => r.entryId)
-                    const entriesMap = db.getEntriesByIds(entryIds)
-
-                    const entries = results
-                        .map((r) => {
-                            const entry = entriesMap.get(r.entryId)
-                            if (!entry) return null
-                            // Apply is_personal filter if specified
-                            if (
-                                input.is_personal !== undefined &&
-                                entry.isPersonal !== input.is_personal
-                            )
-                                return null
-                            return {
-                                ...entry,
-                                similarity: Math.round(r.score * 100) / 100,
-                            }
-                        })
-                        .filter((e): e is NonNullable<typeof e> => e !== null)
-
-                    const stats = vectorManager.getStats()
-                    const isIndexEmpty = stats.itemCount === 0
-                    const includeHint = input.hint_on_empty ?? true
-
-                    // Quality gate: if the best match is below this floor,
-                    // treat all results as noise and include the hint
-                    const QUALITY_FLOOR = 0.5
-                    const bestSimilarity = entries[0]?.similarity ?? 0
-                    const allNoise = entries.length > 0 && bestSimilarity < QUALITY_FLOOR
-
-                    // Build hint: quality gate hint is always shown (not gated by hint_on_empty)
-                    // because noisy results ≠ empty results. hint_on_empty only controls
-                    // the "no results" and "empty index" advisory hints.
-                    const hint =
-                        isIndexEmpty && includeHint
-                            ? 'No entries in vector index. Use rebuild_vector_index to index existing entries.'
-                            : entries.length === 0 && includeHint
-                              ? `No entries matched your query above the similarity threshold (${String(input.similarity_threshold ?? 0.25)}). Try lowering similarity_threshold (e.g., 0.15) for broader matches.`
-                              : allNoise
-                                ? `Results may be noise — best similarity (${String(bestSimilarity)}) is below quality floor (${String(QUALITY_FLOOR)}). Try a more specific query or raise similarity_threshold to filter weak matches.`
-                                : undefined
-
-                    return {
-                        query: input.query,
-                        entries,
-                        count: entries.length,
-                        ...(hint !== undefined ? { hint } : {}),
-                    }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-        {
-            name: 'get_vector_index_stats',
-            title: 'Get Vector Index Stats',
-            description: 'Get statistics about the semantic search vector index',
-            group: 'search',
-            inputSchema: z.object({}).strict(),
-            outputSchema: VectorStatsOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-            handler: (_params: unknown) => {
-                try {
-                    if (!vectorManager) {
-                        return {
-                            success: false,
-                            available: false,
-                            error: 'Vector search not available',
-                            code: 'CONFIGURATION_ERROR',
-                            category: 'configuration',
-                            suggestion:
-                                'Enable semantic search with --auto-rebuild-index or set up the vector manager',
-                            recoverable: false,
-                        }
-                    }
-                    const stats = vectorManager.getStats()
-                    return { success: true, available: true, ...stats }
-                } catch (err) {
-                    return formatHandlerError(err)
-                }
-            },
-        },
-    ]
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-/** Number of leading characters used as deduplication key */
-const DEDUP_KEY_LENGTH = 200
-
-/**
- * When merging across personal + team DBs, fetch more per-DB so BM25
- * ranking in one DB doesn't silently drop entries before the merge.
- */
-function calcPerDbLimit(limit: number, hasTeamDb: boolean): number {
-    return hasTeamDb ? Math.min(limit * 2, MAX_QUERY_LIMIT) : limit
-}
-
-interface EntryWithSource {
-    content: string
-    timestamp: string
-    source: 'personal' | 'team'
-    [key: string]: unknown
-}
-
-/**
- * Merge personal and team results, deduplicate by content,
- * and sort by timestamp descending.
- */
-function mergeAndDedup(
-    personal: EntryWithSource[],
-    team: EntryWithSource[],
-    limit?: number
-): EntryWithSource[] {
-    const seen = new Set<string>()
-    const merged: EntryWithSource[] = []
-
-    // Concat and sort by timestamp descending (ISO 8601 sorts lexicographically)
-    const all = [...personal, ...team].sort((a, b) => b.timestamp.localeCompare(a.timestamp))
-
-    for (const entry of all) {
-        // Deduplicate by content (same entry shared to team)
-        const key = entry.content.slice(0, DEDUP_KEY_LENGTH)
-        if (!seen.has(key)) {
-            seen.add(key)
-            merged.push(entry)
-        }
-    }
-
-    return limit !== undefined ? merged.slice(0, limit) : merged
-}