memory-journal-mcp 6.1.2 → 6.2.1

package/src/handlers/tools/index.ts

@@ -1,255 +0,0 @@
-/**
- * Tool Handler Barrel
- *
- * Composes all tool group modules and exposes the public API:
- * - getTools(): returns filtered tool definitions for the MCP server
- * - callTool(): dispatches a tool call by name
- *
- * Each group module owns its:
- * - Input/output Zod schemas
- * - Tool definitions (name, description, group, annotations)
- * - Handler implementations (with try/catch + formatHandlerError)
- */
-
-import type {
-    ToolFilterConfig,
-    ToolDefinition,
-    ToolRegistration,
-    ToolContext,
-    ToolHandlerConfig,
-} from '../../types/index.js'
-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'
-
-import { getCoreTools } from './core.js'
-import { getSearchTools } from './search.js'
-import { getAnalyticsTools } from './analytics.js'
-import { getRelationshipTools } from './relationships.js'
-import { getExportTools } from './export.js'
-import { getAdminTools } from './admin.js'
-import { getGitHubTools } from './github.js'
-import { getBackupTools } from './backup.js'
-import { getTeamTools } from './team/index.js'
-import { getCodeModeTools } from './codemode.js'
-
-// Re-export for backward compatibility (McpServer imports these)
-export type { ToolHandlerConfig }
-
-// ============================================================================
-// Icon Mapping
-// ============================================================================
-
-function getToolIcon(
-    group: string
-): { iconUrl: string; title: string; description: string } | undefined {
-    const iconMap: Record<string, { iconUrl: string; title: string; description: string }> = {
-        core: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/notebook.svg',
-            title: 'Journal Core',
-            description: 'Core journal operations',
-        },
-        search: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/magnify.svg',
-            title: 'Search',
-            description: 'Entry search operations',
-        },
-        analytics: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/chart-bar.svg',
-            title: 'Analytics',
-            description: 'Journal analytics',
-        },
-        relationships: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/graph-outline.svg',
-            title: 'Relationships',
-            description: 'Entry relationship management',
-        },
-        export: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/export.svg',
-            title: 'Export',
-            description: 'Data export operations',
-        },
-        admin: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/cog.svg',
-            title: 'Admin',
-            description: 'Administrative operations',
-        },
-        github: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/github.svg',
-            title: 'GitHub',
-            description: 'GitHub integration',
-        },
-        backup: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/backup-restore.svg',
-            title: 'Backup',
-            description: 'Backup and restore',
-        },
-        team: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/account-group.svg',
-            title: 'Team',
-            description: 'Team collaboration',
-        },
-        codemode: {
-            iconUrl: 'https://cdn.jsdelivr.net/npm/@mdi/svg@7.4.47/svg/code-braces.svg',
-            title: 'Code Mode',
-            description: 'Sandboxed code execution',
-        },
-    }
-    return iconMap[group]
-}
-
-// ============================================================================
-// Public API
-// ============================================================================
-
-/**
- * Get all tool definitions, optionally filtered by config
- */
-export function getTools(
-    db: IDatabaseAdapter,
-    filterConfig: ToolFilterConfig | null,
-    vectorManager?: VectorSearchManager,
-    github?: GitHubIntegration,
-    config?: ToolHandlerConfig,
-    teamDb?: IDatabaseAdapter,
-    teamVectorManager?: VectorSearchManager
-): ToolRegistration[] {
-    // Ensure tool map is built / up-to-date (shared cache with callTool)
-    ensureToolCache(db, vectorManager, github, config, teamDb, teamVectorManager)
-
-    const mapTool = (t: ToolDefinition): ToolRegistration => ({
-        name: t.name,
-        title: t.title,
-        description: t.description,
-        inputSchema: t.inputSchema,
-        // Only include outputSchema when defined — undefined values in the
-        // tools/list response break clients that process the JSON Schema field
-        ...(t.outputSchema !== undefined ? { outputSchema: t.outputSchema } : {}),
-        annotations: t.annotations,
-        icons: getToolIcon(t.group),
-    })
-
-    if (filterConfig) {
-        // Filtered lists are not cached — filter sets vary per call
-        return Array.from((toolMapCache ?? EMPTY_TOOL_MAP).values())
-            .filter((t) => filterConfig.enabledTools.has(t.name))
-            .map(mapTool)
-    }
-
-    // Return cached mapped output for unfiltered calls
-    mappedToolsCache ??= Array.from((toolMapCache ?? EMPTY_TOOL_MAP).values()).map(mapTool)
-    return mappedToolsCache
-}
-
-/**
- * Cached tool map for O(1) lookup in callTool and getTools.
- * Built lazily on first invocation. Invalidates when any
- * context parameter changes (happens in tests with different mocks;
- * in production, all instances are stable).
- */
-let toolMapCache: Map<string, ToolDefinition> | null = null
-/** Cached mapped tool output for unfiltered getTools calls */
-let mappedToolsCache: ToolRegistration[] | null = null
-/** Typed empty map for safe fallback (narrowing guard, never actually used) */
-const EMPTY_TOOL_MAP = new Map<string, ToolDefinition>()
-let cachedContextRefs: {
-    db: IDatabaseAdapter
-    github?: GitHubIntegration
-    vectorManager?: VectorSearchManager
-    config?: ToolHandlerConfig
-    teamDb?: IDatabaseAdapter
-    teamVectorManager?: VectorSearchManager
-} | null = null
-
-/**
- * Ensure the tool definition cache is populated and valid for the given context.
- * Shared by getTools() and callTool() to avoid redundant getAllToolDefinitions() calls.
- */
-function ensureToolCache(
-    db: IDatabaseAdapter,
-    vectorManager?: VectorSearchManager,
-    github?: GitHubIntegration,
-    config?: ToolHandlerConfig,
-    teamDb?: IDatabaseAdapter,
-    teamVectorManager?: VectorSearchManager
-): void {
-    if (
-        toolMapCache &&
-        cachedContextRefs?.db === db &&
-        cachedContextRefs.github === github &&
-        cachedContextRefs.vectorManager === vectorManager &&
-        cachedContextRefs.config === config &&
-        cachedContextRefs.teamDb === teamDb &&
-        cachedContextRefs.teamVectorManager === teamVectorManager
-    ) {
-        return // Cache is valid
-    }
-
-    const context: ToolContext = { db, teamDb, vectorManager, teamVectorManager, github, config }
-    toolMapCache = new Map(getAllToolDefinitions(context).map((t) => [t.name, t]))
-    mappedToolsCache = null // Invalidate mapped cache when definitions change
-    cachedContextRefs = { db, github, vectorManager, config, teamDb, teamVectorManager }
-}
-
-/**
- * Call a tool by name
- */
-export function callTool(
-    name: string,
-    args: Record<string, unknown>,
-    db: IDatabaseAdapter,
-    vectorManager?: VectorSearchManager,
-    github?: GitHubIntegration,
-    config?: ToolHandlerConfig,
-    progress?: ProgressContext,
-    teamDb?: IDatabaseAdapter,
-    teamVectorManager?: VectorSearchManager
-): Promise<unknown> {
-    ensureToolCache(db, vectorManager, github, config, teamDb, teamVectorManager)
-
-    const tool = (toolMapCache ?? EMPTY_TOOL_MAP).get(name)
-
-    if (!tool) {
-        return Promise.reject(new Error(`Unknown tool: ${name}`))
-    }
-
-    // When progress context is provided, rebuild the handler with it.
-    // This is rare (only MCP server calls with progress tokens, not benchmarked).
-    if (progress) {
-        const context: ToolContext = {
-            db,
-            teamDb,
-            vectorManager,
-            teamVectorManager,
-            github,
-            config,
-            progress,
-        }
-        const freshTools = getAllToolDefinitions(context)
-        const freshTool = freshTools.find((t) => t.name === name)
-        if (freshTool) {
-            return Promise.resolve(freshTool.handler(args))
-        }
-    }
-
-    return Promise.resolve(tool.handler(args))
-}
-
-/**
- * Compose all tool definitions from group modules
- */
-function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
-    return [
-        ...getCoreTools(context),
-        ...getSearchTools(context),
-        ...getAnalyticsTools(context),
-        ...getRelationshipTools(context),
-        ...getExportTools(context),
-        ...getAdminTools(context),
-        ...getGitHubTools(context),
-        ...getBackupTools(context),
-        ...getTeamTools(context),
-        ...getCodeModeTools(context),
-    ]
-}

package/src/handlers/tools/relationships.ts

@@ -1,390 +0,0 @@
-/**
- * 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, relaxedNumber } from './schemas.js'
-import { ErrorFieldsMixin } from './error-fields-mixin.js'
-import type { QueryResult } from '../../database/core/interfaces.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: relaxedNumber(),
-    to_entry_id: relaxedNumber(),
-    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'),
-})
-
-/** Relaxed schema — passed to SDK inputSchema so Zod min/max errors reach the handler */
-const VisualizeInputSchemaMcp = z.object({
-    entry_id: relaxedNumber()
-        .optional()
-        .describe('Specific entry ID to visualize (shows connected entries)'),
-    tags: z.array(z.string()).optional().describe('Filter entries by tags'),
-    depth: relaxedNumber().optional().default(2).describe('Relationship traversal depth'),
-    limit: relaxedNumber().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(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-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(),
-    })
-    .extend(ErrorFieldsMixin.shape)
-
-// ============================================================================
-// 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, openWorldHint: false },
-            handler: (params: unknown) => {
-                try {
-                    const input = LinkEntriesSchema.parse(params)
-
-                    // Guard: self-referential links are not meaningful
-                    if (input.from_entry_id === input.to_entry_id) {
-                        return {
-                            success: false,
-                            error: 'Cannot link an entry to itself',
-                            code: 'VALIDATION_ERROR',
-                            category: 'validation',
-                        }
-                    }
-
-                    // Check for existing duplicate relationship (exact direction only).
-                    // Reverse direction (B→A when A→B exists) is intentionally allowed
-                    // so agents can model bidirectional relationships explicitly.
-                    const existingRelationships = db.getRelationships(input.from_entry_id)
-                    const existing = existingRelationships.find(
-                        (r) =>
-                            r.fromEntryId === input.from_entry_id &&
-                            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) {
-                        const errMsg = error instanceof Error ? error.message : 'Unknown error'
-                        const isFkError = errMsg.includes('FOREIGN KEY constraint failed')
-                        if (isFkError) {
-                            return {
-                                success: false,
-                                error: `One or both entries not found (from: ${String(input.from_entry_id)}, to: ${String(input.to_entry_id)})`,
-                                code: 'RESOURCE_NOT_FOUND',
-                                category: 'resource',
-                                suggestion: 'Verify both entry IDs exist before linking',
-                                recoverable: true,
-                            }
-                        }
-                    }
-                    return formatHandlerError(error)
-                }
-            },
-        },
-        {
-            name: 'visualize_relationships',
-            title: 'Visualize Relationships',
-            description: 'Generate a Mermaid diagram visualization of entry relationships',
-            group: 'relationships',
-            inputSchema: VisualizeInputSchemaMcp,
-            outputSchema: VisualizationOutputSchema,
-            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
-            handler: (params: unknown) => {
-                try {
-                    const input = VisualizeInputSchema.parse(params)
-                    let entriesResult: QueryResult[]
-
-                    if (input.entry_id !== undefined) {
-                        const entry = db.getEntryById(input.entry_id)
-                        if (!entry) {
-                            return {
-                                success: false,
-                                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 = db.executeRawQuery(
-                            `
-                            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 = db.executeRawQuery(
-                            `
-                            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 = db.executeRawQuery(
-                            `
-                            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 = db.executeRawQuery(
-                        `
-                        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
-                    const MERMAID_CONTENT_PREVIEW_LENGTH = 40
-                    let mermaid = '```mermaid\\ngraph TD\\n'
-
-                    for (const [idStr, entry] of Object.entries(entries)) {
-                        let contentPreview = entry.content
-                            .slice(0, MERMAID_CONTENT_PREVIEW_LENGTH)
-                            .replace(/\\n/g, ' ')
-                        if (entry.content.length > MERMAID_CONTENT_PREVIEW_LENGTH)
-                            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)
-                }
-            },
-        },
-    ]
-}