memory-journal-mcp 4.4.2 → 5.0.0

package/src/handlers/tools/relationships.ts

@@ -0,0 +1,358 @@
+/**
+ * Relationships Tool Group - 2 tools
+ *
+ * Tools: link_entries, visualize_relationships
+ */
+
+import { z } from 'zod'
+import type { ToolDefinition, ToolContext, RelationshipType } from '../../types/index.js'
+import { formatHandlerError } from '../../utils/error-helpers.js'
+import { RelationshipOutputSchema } from './schemas.js'
+
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+/** Strict schema — used inside handler for structured Zod errors */
+const LinkEntriesSchema = z.object({
+    from_entry_id: z.number(),
+    to_entry_id: z.number(),
+    relationship_type: z
+        .enum([
+            'evolves_from',
+            'references',
+            'implements',
+            'clarifies',
+            'response_to',
+            'blocked_by',
+            'resolved',
+            'caused',
+        ])
+        .optional()
+        .default('references'),
+    description: z.string().optional(),
+})
+
+/** Relaxed schema — passed to SDK inputSchema so Zod enum errors reach the handler */
+const LinkEntriesSchemaMcp = z.object({
+    from_entry_id: z.number(),
+    to_entry_id: z.number(),
+    relationship_type: z.string().optional().default('references'),
+    description: z.string().optional(),
+})
+
+const VisualizeInputSchema = z.object({
+    entry_id: z
+        .number()
+        .optional()
+        .describe('Specific entry ID to visualize (shows connected entries)'),
+    tags: z.array(z.string()).optional().describe('Filter entries by tags'),
+    depth: z.number().min(1).max(3).optional().default(2).describe('Relationship traversal depth'),
+    limit: z.number().max(500).optional().default(20).describe('Maximum entries to include'),
+})
+
+// ============================================================================
+// Output Schemas
+// ============================================================================
+
+const LinkEntriesOutputSchema = z.object({
+    success: z.boolean().optional(),
+    relationship: RelationshipOutputSchema.optional(),
+    duplicate: z.boolean().optional().describe('True if relationship already existed'),
+    message: z.string().optional().describe('Additional context about the operation'),
+    error: z.string().optional(),
+})
+
+const VisualizationOutputSchema = z.object({
+    entry_count: z.number().optional(),
+    relationship_count: z.number().optional(),
+    root_entry: z.number().nullable().optional(),
+    depth: z.number().optional(),
+    mermaid: z.string().nullable().optional(),
+    message: z.string().optional(),
+    legend: z
+        .object({
+            blue: z.string(),
+            orange: z.string(),
+            arrows: z.record(z.string(), z.string()),
+        })
+        .optional(),
+    success: z.boolean().optional(),
+    error: z.string().optional(),
+})
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export function getRelationshipTools(context: ToolContext): ToolDefinition[] {
+    const { db } = context
+    return [
+        {
+            name: 'link_entries',
+            title: 'Link Entries',
+            description: 'Create a relationship between two journal entries',
+            group: 'relationships',
+            inputSchema: LinkEntriesSchemaMcp,
+            outputSchema: LinkEntriesOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false },
+            handler: (params: unknown) => {
+                try {
+                    const input = LinkEntriesSchema.parse(params)
+
+                    // Check for existing duplicate relationship
+                    const existingRelationships = db.getRelationships(input.from_entry_id)
+                    const existing = existingRelationships.find(
+                        (r) =>
+                            r.toEntryId === input.to_entry_id &&
+                            r.relationshipType === input.relationship_type
+                    )
+
+                    if (existing) {
+                        return {
+                            success: true,
+                            relationship: existing,
+                            duplicate: true,
+                            message: 'Relationship already exists',
+                        }
+                    }
+
+                    // linkEntries throws for nonexistent entries
+                    const relationship = db.linkEntries(
+                        input.from_entry_id,
+                        input.to_entry_id,
+                        input.relationship_type as RelationshipType,
+                        input.description
+                    )
+                    return { success: true, relationship }
+                } catch (error) {
+                    // Domain errors from db.linkEntries (nonexistent entries)
+                    const input = (() => {
+                        try {
+                            return LinkEntriesSchema.parse(params)
+                        } catch {
+                            // If parse itself failed, use formatHandlerError
+                            return null
+                        }
+                    })()
+
+                    if (input) {
+                        return {
+                            success: false,
+                            relationship: {
+                                id: 0,
+                                fromEntryId: input.from_entry_id,
+                                toEntryId: input.to_entry_id,
+                                relationshipType: input.relationship_type,
+                                description: input.description ?? null,
+                                createdAt: '',
+                            },
+                            message: error instanceof Error ? error.message : 'Unknown error',
+                        }
+                    }
+                    return formatHandlerError(error)
+                }
+            },
+        },
+        {
+            name: 'visualize_relationships',
+            title: 'Visualize Relationships',
+            description: 'Generate a Mermaid diagram visualization of entry relationships',
+            group: 'relationships',
+            inputSchema: VisualizeInputSchema,
+            outputSchema: VisualizationOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (params: unknown) => {
+                try {
+                    const input = VisualizeInputSchema.parse(params)
+
+                    const rawDb = db.getRawDb()
+                    let entriesResult
+
+                    if (input.entry_id !== undefined) {
+                        const entry = db.getEntryById(input.entry_id)
+                        if (!entry) {
+                            return {
+                                entry_count: 0,
+                                relationship_count: 0,
+                                root_entry: input.entry_id,
+                                depth: input.depth,
+                                mermaid: null,
+                                message: `Entry ${String(input.entry_id)} not found`,
+                            }
+                        }
+
+                        entriesResult = rawDb.exec(
+                            `
+                            WITH RECURSIVE connected_entries(id, distance) AS (
+                                SELECT id, 0 FROM memory_journal WHERE id = ? AND deleted_at IS NULL
+                                UNION
+                                SELECT DISTINCT
+                                    CASE
+                                        WHEN r.from_entry_id = ce.id THEN r.to_entry_id
+                                        ELSE r.from_entry_id
+                                    END,
+                                    ce.distance + 1
+                                FROM connected_entries ce
+                                JOIN relationships r ON r.from_entry_id = ce.id OR r.to_entry_id = ce.id
+                                WHERE ce.distance < ?
+                            )
+                            SELECT DISTINCT mj.id, mj.entry_type, mj.content, mj.is_personal
+                            FROM memory_journal mj
+                            JOIN connected_entries ce ON mj.id = ce.id
+                            WHERE mj.deleted_at IS NULL
+                            LIMIT ?
+                        `,
+                            [input.entry_id, input.depth, input.limit]
+                        )
+                    } else if (input.tags && input.tags.length > 0) {
+                        const placeholders = input.tags.map(() => '?').join(',')
+                        entriesResult = rawDb.exec(
+                            `
+                            SELECT DISTINCT mj.id, mj.entry_type, mj.content, mj.is_personal
+                            FROM memory_journal mj
+                            WHERE mj.deleted_at IS NULL
+                              AND mj.id IN (
+                                  SELECT et.entry_id FROM entry_tags et
+                                  JOIN tags t ON et.tag_id = t.id
+                                  WHERE t.name IN (${placeholders})
+                              )
+                            LIMIT ?
+                        `,
+                            [...input.tags, input.limit]
+                        )
+                    } else {
+                        entriesResult = rawDb.exec(
+                            `
+                            SELECT DISTINCT mj.id, mj.entry_type, mj.content, mj.is_personal
+                            FROM memory_journal mj
+                            WHERE mj.deleted_at IS NULL
+                              AND mj.id IN (
+                                  SELECT DISTINCT from_entry_id FROM relationships
+                                  UNION
+                                  SELECT DISTINCT to_entry_id FROM relationships
+                              )
+                            ORDER BY mj.id DESC
+                            LIMIT ?
+                        `,
+                            [input.limit]
+                        )
+                    }
+
+                    if (!entriesResult[0] || entriesResult[0].values.length === 0) {
+                        return {
+                            entry_count: 0,
+                            relationship_count: 0,
+                            root_entry: input.entry_id ?? null,
+                            depth: input.depth,
+                            mermaid: null,
+                            message: 'No entries found with relationships matching your criteria',
+                        }
+                    }
+
+                    // Build entries map
+                    const entries: Record<
+                        number,
+                        {
+                            id: number
+                            entry_type: string
+                            content: string
+                            is_personal: boolean
+                        }
+                    > = {}
+                    const cols = entriesResult[0].columns
+                    for (const row of entriesResult[0].values) {
+                        const id = row[cols.indexOf('id')] as number
+                        entries[id] = {
+                            id,
+                            entry_type: row[cols.indexOf('entry_type')] as string,
+                            content: row[cols.indexOf('content')] as string,
+                            is_personal: Boolean(row[cols.indexOf('is_personal')]),
+                        }
+                    }
+
+                    const entryIds = Object.keys(entries).map(Number)
+                    const placeholders = entryIds.map(() => '?').join(',')
+
+                    const relsResult = rawDb.exec(
+                        `
+                        SELECT from_entry_id, to_entry_id, relationship_type
+                        FROM relationships
+                        WHERE from_entry_id IN (${placeholders})
+                          AND to_entry_id IN (${placeholders})
+                    `,
+                        [...entryIds, ...entryIds]
+                    )
+
+                    const relationships = relsResult[0]?.values ?? []
+
+                    // Generate Mermaid diagram
+                    let mermaid = '```mermaid\\ngraph TD\\n'
+
+                    for (const [idStr, entry] of Object.entries(entries)) {
+                        let contentPreview = entry.content.slice(0, 40).replace(/\\n/g, ' ')
+                        if (entry.content.length > 40) contentPreview += '...'
+                        contentPreview = contentPreview
+                            .replace(/"/g, "'")
+                            .replace(/\[/g, '(')
+                            .replace(/\]/g, ')')
+                        const entryTypeShort = entry.entry_type.slice(0, 20)
+                        mermaid += `    E${idStr}["#${idStr}: ${contentPreview}<br/>${entryTypeShort}"]\\n`
+                    }
+
+                    mermaid += '\\n'
+
+                    const relSymbols: Record<string, string> = {
+                        references: '-->',
+                        implements: '==>',
+                        clarifies: '-.->',
+                        evolves_from: '-->',
+                        response_to: '<-->',
+                        blocked_by: '--x',
+                        resolved: '==>',
+                        caused: '-.->',
+                    }
+
+                    for (const rel of relationships) {
+                        const fromId = rel[0] as number
+                        const toId = rel[1] as number
+                        const relType = rel[2] as string
+                        const arrow = relSymbols[relType] ?? '-->'
+                        mermaid += `    E${String(fromId)} ${arrow}|${relType}| E${String(toId)}\\n`
+                    }
+
+                    mermaid += '\\n'
+                    for (const [idStr, entry] of Object.entries(entries)) {
+                        if (entry.is_personal) {
+                            mermaid += `    style E${idStr} fill:#E3F2FD\\n`
+                        } else {
+                            mermaid += `    style E${idStr} fill:#FFF3E0\\n`
+                        }
+                    }
+                    mermaid += '```'
+
+                    return {
+                        entry_count: Object.keys(entries).length,
+                        relationship_count: relationships.length,
+                        root_entry: input.entry_id ?? null,
+                        depth: input.depth,
+                        mermaid,
+                        legend: {
+                            blue: 'Personal entries',
+                            orange: 'Project entries',
+                            arrows: {
+                                '-->': 'references / evolves_from',
+                                '==>': 'implements / resolved',
+                                '-.->': 'clarifies / caused',
+                                '<-->': 'response_to',
+                                '--x': 'blocked_by',
+                            },
+                        },
+                    }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+    ]
+}

package/src/handlers/tools/schemas.ts

@@ -0,0 +1,132 @@
+/**
+ * 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'
+
+// ============================================================================
+// 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
+
+/** 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'
+
+// ============================================================================
+// 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(),
+})
+
+/**
+ * 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(),
+})
+
+/**
+ * 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(),
+})
+
+/**
+ * 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(),
+})