memory-journal-mcp 4.4.2 → 5.0.0

package/src/handlers/tools/admin.ts

@@ -0,0 +1,285 @@
+/**
+ * Admin Tool Group - 5 tools
+ *
+ * Tools: update_entry, delete_entry, merge_tags, rebuild_vector_index, add_to_vector_index
+ */
+
+import { z } from 'zod'
+import type { ToolDefinition, ToolContext } from '../../types/index.js'
+import { formatHandlerError } from '../../utils/error-helpers.js'
+import { ENTRY_TYPES, EntryOutputSchema } from './schemas.js'
+
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+/** Strict schema — used inside handler for structured Zod errors */
+const UpdateEntrySchema = z.object({
+    entry_id: z.number(),
+    content: z.string().optional(),
+    entry_type: z.enum(ENTRY_TYPES).optional(),
+    is_personal: z.boolean().optional(),
+    tags: z.array(z.string()).optional(),
+})
+
+/** Relaxed schema — passed to SDK inputSchema so Zod enum errors reach the handler */
+const UpdateEntrySchemaMcp = z.object({
+    entry_id: z.number(),
+    content: z.string().optional(),
+    entry_type: z.string().optional(),
+    is_personal: z.boolean().optional(),
+    tags: z.array(z.string()).optional(),
+})
+
+const DeleteEntrySchema = z.object({
+    entry_id: z.number(),
+    permanent: z.boolean().optional().default(false),
+})
+
+// ============================================================================
+// Output Schemas
+// ============================================================================
+
+const UpdateEntryOutputSchema = z.object({
+    success: z.boolean().optional(),
+    entry: EntryOutputSchema.optional(),
+    error: z.string().optional(),
+})
+
+const DeleteEntryOutputSchema = z.object({
+    success: z.boolean().optional(),
+    entryId: z.number().optional(),
+    permanent: z.boolean().optional(),
+    error: z.string().optional(),
+})
+
+const MergeTagsOutputSchema = z.object({
+    success: z.boolean().optional(),
+    sourceTag: z.string().optional(),
+    targetTag: z.string().optional(),
+    entriesUpdated: z.number().optional(),
+    sourceDeleted: z.boolean().optional(),
+    message: z.string().optional(),
+    error: z.string().optional(),
+})
+
+const RebuildVectorIndexOutputSchema = z.object({
+    success: z.boolean().optional(),
+    entriesIndexed: z.number().optional(),
+    error: z.string().optional(),
+})
+
+const AddToVectorIndexOutputSchema = z.object({
+    success: z.boolean().optional(),
+    entryId: z.number().optional(),
+    error: z.string().optional(),
+})
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export function getAdminTools(context: ToolContext): ToolDefinition[] {
+    const { db, vectorManager, progress } = context
+    return [
+        {
+            name: 'update_entry',
+            title: 'Update Entry',
+            description: 'Update an existing journal entry',
+            group: 'admin',
+            inputSchema: UpdateEntrySchemaMcp,
+            outputSchema: UpdateEntryOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false },
+            handler: (params: unknown) => {
+                try {
+                    const input = UpdateEntrySchema.parse(params)
+                    const entry = db.updateEntry(input.entry_id, {
+                        content: input.content,
+                        entryType: input.entry_type,
+                        isPersonal: input.is_personal,
+                        tags: input.tags,
+                    })
+                    if (!entry) {
+                        return {
+                            success: false,
+                            error: `Entry ${String(input.entry_id)} not found`,
+                        }
+                    }
+
+                    // Re-index if content changed
+                    if (input.content && vectorManager) {
+                        vectorManager.addEntry(entry.id, entry.content).catch(() => {
+                            // Non-critical failure, entry already updated in DB
+                        })
+                    }
+
+                    return { success: true, entry }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'delete_entry',
+            title: 'Delete Entry',
+            description: 'Delete a journal entry (soft delete with timestamp)',
+            group: 'admin',
+            inputSchema: DeleteEntrySchema,
+            outputSchema: DeleteEntryOutputSchema,
+            annotations: { readOnlyHint: false, destructiveHint: true },
+            handler: (params: unknown) => {
+                try {
+                    const { entry_id, permanent } = DeleteEntrySchema.parse(params)
+                    const success = db.deleteEntry(entry_id, permanent)
+
+                    if (!success) {
+                        return {
+                            success: false,
+                            entryId: entry_id,
+                            permanent,
+                            error: `Entry ${String(entry_id)} not found`,
+                        }
+                    }
+
+                    // Remove from vector index (non-critical if fails)
+                    if (vectorManager) {
+                        vectorManager.removeEntry(entry_id).catch(() => {
+                            // Non-critical failure, entry already deleted from DB
+                        })
+                    }
+
+                    return { success, entryId: entry_id, permanent }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'merge_tags',
+            title: 'Merge Tags',
+            description:
+                'Merge one tag into another to consolidate similar tags (e.g., merge "phase-2" into "phase2"). The source tag is deleted after merge.',
+            group: 'admin',
+            inputSchema: z.object({
+                source_tag: z.string().min(1).describe('Tag to merge from (will be deleted)'),
+                target_tag: z
+                    .string()
+                    .min(1)
+                    .describe('Tag to merge into (will be created if not exists)'),
+            }),
+            outputSchema: MergeTagsOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false },
+            handler: (params: unknown) => {
+                try {
+                    const { source_tag, target_tag } = z
+                        .object({
+                            source_tag: z.string().min(1),
+                            target_tag: z.string().min(1),
+                        })
+                        .parse(params)
+
+                    if (source_tag === target_tag) {
+                        return {
+                            success: false,
+                            sourceTag: source_tag,
+                            targetTag: target_tag,
+                            entriesUpdated: 0,
+                            sourceDeleted: false,
+                            message: 'Source and target tags cannot be the same',
+                            error: 'Source and target tags must be different',
+                        }
+                    }
+
+                    const result = db.mergeTags(source_tag, target_tag)
+                    return {
+                        success: true,
+                        sourceTag: source_tag,
+                        targetTag: target_tag,
+                        entriesUpdated: result.entriesUpdated,
+                        sourceDeleted: result.sourceDeleted,
+                        message: `Merged "${source_tag}" into "${target_tag}". Updated ${String(result.entriesUpdated)} entries.`,
+                    }
+                } catch (error) {
+                    // Zod or domain error
+                    if (error instanceof z.ZodError) {
+                        return formatHandlerError(error)
+                    }
+                    // Domain error from db.mergeTags — try to preserve schema shape
+                    try {
+                        const parsed = z
+                            .object({ source_tag: z.string(), target_tag: z.string() })
+                            .parse(params)
+                        return {
+                            success: false,
+                            sourceTag: parsed.source_tag,
+                            targetTag: parsed.target_tag,
+                            entriesUpdated: 0,
+                            sourceDeleted: false,
+                            message: 'Tag merge failed',
+                            error: error instanceof Error ? error.message : 'Unknown error',
+                        }
+                    } catch {
+                        return formatHandlerError(error)
+                    }
+                }
+            },
+        },
+        {
+            name: 'rebuild_vector_index',
+            title: 'Rebuild Vector Index',
+            description: 'Rebuild the semantic search vector index from all existing entries',
+            group: 'admin',
+            inputSchema: z.object({}),
+            outputSchema: RebuildVectorIndexOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false },
+            handler: async (_params: unknown) => {
+                try {
+                    if (!vectorManager) {
+                        return {
+                            success: false,
+                            entriesIndexed: 0,
+                            error: 'Vector search not available',
+                        }
+                    }
+                    const indexed = await vectorManager.rebuildIndex(db, progress)
+                    return { success: true, entriesIndexed: indexed }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'add_to_vector_index',
+            title: 'Add Entry to Vector Index',
+            description: 'Add a specific entry to the semantic search vector index',
+            group: 'admin',
+            inputSchema: z.object({ entry_id: z.number() }),
+            outputSchema: AddToVectorIndexOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: true },
+            handler: async (params: unknown) => {
+                try {
+                    const { entry_id } = z.object({ entry_id: z.number() }).parse(params)
+                    if (!vectorManager) {
+                        return {
+                            success: false,
+                            entryId: entry_id,
+                            error: 'Vector search not available',
+                        }
+                    }
+                    const entry = db.getEntryById(entry_id)
+                    if (!entry) {
+                        return {
+                            success: false,
+                            entryId: entry_id,
+                            error: `Entry ${String(entry_id)} not found`,
+                        }
+                    }
+                    const success = await vectorManager.addEntry(entry_id, entry.content)
+                    return { success, entryId: entry_id }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+    ]
+}

package/src/handlers/tools/analytics.ts

@@ -0,0 +1,301 @@
+/**
+ * Analytics Tool Group - 2 tools
+ *
+ * Tools: get_statistics, get_cross_project_insights
+ */
+
+import { z } from 'zod'
+import type { ToolDefinition, ToolContext } from '../../types/index.js'
+import { formatHandlerError } from '../../utils/error-helpers.js'
+import { DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE, TagOutputSchema } from './schemas.js'
+
+// ============================================================================
+// Output Schemas
+// ============================================================================
+
+const StatisticsOutputSchema = z.object({
+    groupBy: z.string().optional(),
+    totalEntries: z.number().optional(),
+    entriesByType: z.record(z.string(), z.number()).optional(),
+    entriesByPeriod: z
+        .array(
+            z.object({
+                period: z.string(),
+                count: z.number(),
+            })
+        )
+        .optional(),
+    decisionDensity: z
+        .array(
+            z.object({
+                period: z.string(),
+                significantCount: z.number(),
+            })
+        )
+        .optional(),
+    relationshipComplexity: z
+        .object({
+            totalRelationships: z.number(),
+            avgPerEntry: z.number(),
+        })
+        .optional(),
+    activityTrend: z
+        .object({
+            currentPeriod: z.string(),
+            previousPeriod: z.string(),
+            growthPercent: z.number().nullable(),
+        })
+        .optional(),
+    causalMetrics: z
+        .object({
+            blocked_by: z.number(),
+            resolved: z.number(),
+            caused: z.number(),
+        })
+        .optional(),
+    success: z.boolean().optional(),
+    error: z.string().optional(),
+})
+
+const ProjectSummaryOutputSchema = z.object({
+    project_number: z.number(),
+    entry_count: z.number(),
+    first_entry: z.string(),
+    last_entry: z.string(),
+    active_days: z.number(),
+    top_tags: z.array(TagOutputSchema),
+})
+
+const CrossProjectInsightsOutputSchema = z.object({
+    project_count: z.number().optional(),
+    total_entries: z.number().optional(),
+    projects: z.array(ProjectSummaryOutputSchema).optional(),
+    inactive_projects: z
+        .array(
+            z.object({
+                project_number: z.number(),
+                last_entry_date: z.string(),
+            })
+        )
+        .optional(),
+    inactiveThresholdDays: z.number().optional(),
+    time_distribution: z
+        .array(
+            z.object({
+                project_number: z.number(),
+                percentage: z.string(),
+            })
+        )
+        .optional(),
+    message: z.string().optional(),
+    success: z.boolean().optional(),
+    error: z.string().optional(),
+})
+
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+/** Strict schema — used inside handler for structured Zod errors */
+const GetStatisticsSchema = z.object({
+    group_by: z.enum(['day', 'week', 'month']).optional().default('week'),
+    start_date: z.string().regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE).optional(),
+    end_date: z.string().regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE).optional(),
+    project_breakdown: z.boolean().optional().default(false),
+})
+
+/** Relaxed schema — passed to SDK inputSchema so Zod errors reach the handler */
+const GetStatisticsSchemaMcp = z.object({
+    group_by: z.string().optional().default('week'),
+    start_date: z.string().optional(),
+    end_date: z.string().optional(),
+    project_breakdown: z.boolean().optional().default(false),
+})
+
+/** Strict schema — used inside handler for structured Zod errors */
+const CrossProjectInsightsInputSchema = z.object({
+    start_date: z
+        .string()
+        .regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE)
+        .optional()
+        .describe('Start date (YYYY-MM-DD)'),
+    end_date: z
+        .string()
+        .regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE)
+        .optional()
+        .describe('End date (YYYY-MM-DD)'),
+    min_entries: z.number().optional().default(3).describe('Minimum entries to include project'),
+})
+
+/** Relaxed schema — passed to SDK inputSchema so Zod errors reach the handler */
+const CrossProjectInsightsInputSchemaMcp = z.object({
+    start_date: z.string().optional().describe('Start date (YYYY-MM-DD)'),
+    end_date: z.string().optional().describe('End date (YYYY-MM-DD)'),
+    min_entries: z.number().optional().default(3).describe('Minimum entries to include project'),
+})
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export function getAnalyticsTools(context: ToolContext): ToolDefinition[] {
+    const { db } = context
+    return [
+        {
+            name: 'get_statistics',
+            title: 'Get Statistics',
+            description:
+                'Get journal statistics and analytics (Phase 2: includes project breakdown)',
+            group: 'analytics',
+            inputSchema: GetStatisticsSchemaMcp,
+            outputSchema: StatisticsOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (params: unknown) => {
+                try {
+                    const { group_by } = GetStatisticsSchema.parse(params)
+                    const stats = db.getStatistics(group_by)
+                    return { ...stats, groupBy: group_by }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'get_cross_project_insights',
+            title: 'Get Cross-Project Insights',
+            description: 'Analyze patterns across all GitHub Projects tracked in journal entries',
+            group: 'analytics',
+            inputSchema: CrossProjectInsightsInputSchemaMcp,
+            outputSchema: CrossProjectInsightsOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (params: unknown) => {
+                try {
+                    const input = CrossProjectInsightsInputSchema.parse(params)
+
+                    const rawDb = db.getRawDb()
+
+                    // Build WHERE clause
+                    let where = 'WHERE deleted_at IS NULL AND project_number IS NOT NULL'
+                    const sqlParams: unknown[] = []
+
+                    if (input.start_date) {
+                        where += ' AND DATE(timestamp) >= DATE(?)'
+                        sqlParams.push(input.start_date)
+                    }
+                    if (input.end_date) {
+                        where += ' AND DATE(timestamp) <= DATE(?)'
+                        sqlParams.push(input.end_date)
+                    }
+
+                    // Get active projects with stats
+                    const projectsResult = rawDb.exec(
+                        `
+                        SELECT project_number, COUNT(*) as entry_count,
+                               MIN(DATE(timestamp)) as first_entry,
+                               MAX(DATE(timestamp)) as last_entry,
+                               COUNT(DISTINCT DATE(timestamp)) as active_days
+                        FROM memory_journal ${where}
+                        GROUP BY project_number
+                        HAVING entry_count >= ?
+                        ORDER BY entry_count DESC
+                    `,
+                        [...sqlParams, input.min_entries]
+                    )
+
+                    if (!projectsResult[0] || projectsResult[0].values.length === 0) {
+                        return {
+                            project_count: 0,
+                            total_entries: 0,
+                            projects: [],
+                            inactive_projects: [],
+                            inactiveThresholdDays: 7,
+                            time_distribution: [],
+                            message: `No projects found with at least ${String(input.min_entries)} entries`,
+                        }
+                    }
+
+                    const columns = projectsResult[0].columns
+                    const projects = projectsResult[0].values.map((row) => {
+                        const obj: Record<string, unknown> = {}
+                        columns.forEach((col, i) => {
+                            obj[col] = row[i]
+                        })
+                        return obj
+                    })
+
+                    // Get top tags per project
+                    const projectTags: Record<number, { name: string; count: number }[]> = {}
+                    for (const proj of projects) {
+                        const projNum = proj['project_number'] as number
+                        const tagsResult = rawDb.exec(
+                            `
+                            SELECT t.name, COUNT(*) as count
+                            FROM tags t
+                            JOIN entry_tags et ON t.id = et.tag_id
+                            JOIN memory_journal m ON et.entry_id = m.id
+                            WHERE m.project_number = ? AND m.deleted_at IS NULL
+                            GROUP BY t.name
+                            ORDER BY count DESC
+                            LIMIT 5
+                        `,
+                            [projNum]
+                        )
+                        if (tagsResult[0]) {
+                            projectTags[projNum] = tagsResult[0].values.map((row) => ({
+                                name: row[0] as string,
+                                count: row[1] as number,
+                            }))
+                        }
+                    }
+
+                    // Find inactive projects (last entry > 7 days ago)
+                    const cutoffDate = new Date(Date.now() - 7 * 86400000)
+                        .toISOString()
+                        .split('T')[0]
+                    const inactiveResult = rawDb.exec(
+                        `
+                        SELECT project_number, MAX(DATE(timestamp)) as last_entry_date
+                        FROM memory_journal
+                        WHERE deleted_at IS NULL AND project_number IS NOT NULL
+                        GROUP BY project_number
+                        HAVING last_entry_date < ?
+                    `,
+                        [cutoffDate]
+                    )
+
+                    const inactiveProjects =
+                        inactiveResult[0]?.values.map((row) => ({
+                            project_number: row[0] as number,
+                            last_entry_date: row[1] as string,
+                        })) ?? []
+
+                    // Calculate time distribution
+                    const totalEntries = projects.reduce(
+                        (sum, p) => sum + (p['entry_count'] as number),
+                        0
+                    )
+                    const distribution = projects.slice(0, 5).map((p) => ({
+                        project_number: p['project_number'],
+                        percentage: (((p['entry_count'] as number) / totalEntries) * 100).toFixed(
+                            1
+                        ),
+                    }))
+
+                    return {
+                        project_count: projects.length,
+                        total_entries: totalEntries,
+                        projects: projects.map((p) => ({
+                            ...p,
+                            top_tags: projectTags[p['project_number'] as number] ?? [],
+                        })),
+                        inactive_projects: inactiveProjects,
+                        inactiveThresholdDays: 7,
+                        time_distribution: distribution,
+                    }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+    ]
+}