memory-journal-mcp 4.4.2 → 5.0.0

package/src/handlers/tools/search.ts

@@ -0,0 +1,343 @@
+/**
+ * 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 {
+    ENTRY_TYPES,
+    DATE_FORMAT_REGEX,
+    DATE_FORMAT_MESSAGE,
+    EntryOutputSchema,
+    EntriesListOutputSchema,
+} from './schemas.js'
+
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+/** Strict schema — used inside handler for structured Zod errors */
+const SearchEntriesSchema = z.object({
+    query: z.string().optional(),
+    limit: z.number().max(500).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: z.number().max(500).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.string().optional(),
+    workflow_run_id: z.number().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(500).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: z.number().optional(),
+    issue_number: z.number().optional(),
+    pr_number: z.number().optional(),
+    workflow_run_id: z.number().optional(),
+    limit: z.number().max(500).optional().default(500),
+})
+
+const SemanticSearchSchema = z.object({
+    query: z.string(),
+    limit: z.number().max(500).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)'),
+})
+
+// ============================================================================
+// 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(),
+})
+
+const VectorStatsOutputSchema = z.object({
+    available: z.boolean(),
+    error: z.string().optional(),
+    entryCount: z.number().optional(),
+    indexSize: z.number().optional(),
+})
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export function getSearchTools(context: ToolContext): ToolDefinition[] {
+    const { db, teamDb, vectorManager } = context
+    return [
+        {
+            name: 'search_entries',
+            title: 'Search Entries',
+            description:
+                'Search journal entries with optional filters for GitHub Projects, Issues, PRs, and Actions',
+            group: 'search',
+            inputSchema: SearchEntriesSchemaMcp,
+            outputSchema: EntriesListOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (params: unknown) => {
+                try {
+                    const input = SearchEntriesSchema.parse(params)
+                    const hasFilters =
+                        input.project_number !== undefined ||
+                        input.issue_number !== undefined ||
+                        input.pr_number !== undefined ||
+                        input.is_personal !== undefined
+
+                    let personalEntries
+                    if (!input.query && !hasFilters) {
+                        personalEntries = db.getRecentEntries(input.limit, input.is_personal)
+                    } else {
+                        personalEntries = db.searchEntries(input.query || '', {
+                            limit: input.limit,
+                            isPersonal: input.is_personal,
+                            projectNumber: input.project_number,
+                            issueNumber: input.issue_number,
+                            prNumber: input.pr_number,
+                        })
+                    }
+
+                    // Cross-database merge when team DB is available
+                    if (teamDb) {
+                        let teamEntries
+                        if (!input.query && !hasFilters) {
+                            teamEntries = teamDb.getRecentEntries(input.limit)
+                        } else {
+                            teamEntries = teamDb.searchEntries(input.query || '', {
+                                limit: input.limit,
+                                projectNumber: input.project_number,
+                                issueNumber: input.issue_number,
+                                prNumber: input.pr_number,
+                            })
+                        }
+                        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 },
+            handler: (params: unknown) => {
+                try {
+                    const input = SearchByDateRangeSchema.parse(params)
+                    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,
+                        limit: input.limit,
+                    })
+
+                    // Cross-database merge when team DB is available
+                    if (teamDb) {
+                        const teamEntries = teamDb.searchByDateRange(
+                            input.start_date,
+                            input.end_date,
+                            {
+                                entryType: input.entry_type,
+                                tags: input.tags,
+                                projectNumber: input.project_number,
+                                limit: input.limit,
+                            }
+                        )
+                        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: SemanticSearchSchema,
+            outputSchema: SemanticSearchOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            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.',
+                            query: input.query,
+                            entries: [],
+                            count: 0,
+                        }
+                    }
+
+                    const results = await vectorManager.search(
+                        input.query,
+                        input.limit ?? 10,
+                        input.similarity_threshold ?? 0.25
+                    )
+
+                    const entries = results
+                        .map((r) => {
+                            const entry = db.getEntryById(r.entryId)
+                            if (!entry) return null
+                            return {
+                                ...entry,
+                                similarity: Math.round(r.score * 100) / 100,
+                            }
+                        })
+                        .filter((e): e is NonNullable<typeof e> => e !== null)
+
+                    const stats = await vectorManager.getStats()
+                    const isIndexEmpty = stats.itemCount === 0
+                    const includeHint = input.hint_on_empty ?? true
+
+                    return {
+                        query: input.query,
+                        entries,
+                        count: entries.length,
+                        ...(includeHint && isIndexEmpty
+                            ? {
+                                  hint: 'No entries in vector index. Use rebuild_vector_index to index existing entries.',
+                              }
+                            : includeHint && entries.length === 0
+                              ? {
+                                    hint: `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.`,
+                                }
+                              : {}),
+                    }
+                } 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({}),
+            outputSchema: VectorStatsOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: async (_params: unknown) => {
+                try {
+                    if (!vectorManager) {
+                        return { available: false, error: 'Vector search not available' }
+                    }
+                    const stats = await vectorManager.getStats()
+                    return { available: true, ...stats }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+    ]
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+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
+    const all = [...personal, ...team].sort(
+        (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()
+    )
+
+    for (const entry of all) {
+        // Deduplicate by content (same entry shared to team)
+        const key = entry.content.slice(0, 200)
+        if (!seen.has(key)) {
+            seen.add(key)
+            merged.push(entry)
+        }
+    }
+
+    return limit !== undefined ? merged.slice(0, limit) : merged
+}

package/src/handlers/tools/team.ts

@@ -0,0 +1,273 @@
+/**
+ * Team Tool Group - 3 tools
+ *
+ * Tools: team_create_entry, team_get_recent, team_search
+ *
+ * Requires TEAM_DB_PATH to be configured. All tools return structured
+ * errors when the team database is not available.
+ */
+
+import { z } from 'zod'
+import { execFileSync } from 'node:child_process'
+import type { ToolDefinition, ToolContext } from '../../types/index.js'
+import { formatHandlerError } from '../../utils/error-helpers.js'
+import { ENTRY_TYPES, SIGNIFICANCE_TYPES, EntryOutputSchema } from './schemas.js'
+
+// ============================================================================
+// Author Detection
+// ============================================================================
+
+/**
+ * Resolve the author name for team entries.
+ * Priority: TEAM_AUTHOR env > git config user.name > 'unknown'
+ */
+function resolveAuthor(): string {
+    // 1. Explicit env var
+    const envAuthor = process.env['TEAM_AUTHOR']?.trim().replace(/"/g, '')
+    if (envAuthor) return envAuthor
+
+    // 2. Git config
+    try {
+        const gitUser = execFileSync('git', ['config', 'user.name'], {
+            encoding: 'utf-8',
+            timeout: 3000,
+        })
+            .trim()
+            .replace(/"/g, '')
+        if (gitUser) return gitUser
+    } catch {
+        // Git not available or not configured
+    }
+
+    return 'unknown'
+}
+
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+/** Strict schema for team entry creation */
+const TeamCreateEntrySchema = z.object({
+    content: z.string().min(1).max(50000),
+    entry_type: z.enum(ENTRY_TYPES).optional().default('personal_reflection'),
+    tags: z.array(z.string()).optional().default([]),
+    significance_type: z.enum(SIGNIFICANCE_TYPES).optional(),
+    project_number: z.number().optional(),
+    project_owner: z.string().optional(),
+    issue_number: z.number().optional(),
+    issue_url: z.string().optional(),
+    pr_number: z.number().optional(),
+    pr_url: z.string().optional(),
+    pr_status: z.enum(['draft', 'open', 'merged', 'closed']).optional(),
+    author: z.string().optional(),
+})
+
+/** Relaxed schema for MCP SDK */
+const TeamCreateEntrySchemaMcp = z.object({
+    content: z.string().min(1).max(50000),
+    entry_type: z.string().optional().default('personal_reflection'),
+    tags: z.array(z.string()).optional().default([]),
+    significance_type: z.string().optional(),
+    project_number: z.number().optional(),
+    project_owner: z.string().optional(),
+    issue_number: z.number().optional(),
+    issue_url: z.string().optional(),
+    pr_number: z.number().optional(),
+    pr_url: z.string().optional(),
+    pr_status: z.string().optional(),
+    author: z.string().optional(),
+})
+
+const TeamGetRecentSchema = z.object({
+    limit: z.number().max(500).optional().default(10),
+})
+
+const TeamSearchSchema = z.object({
+    query: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    limit: z.number().max(500).optional().default(10),
+})
+
+// ============================================================================
+// Output Schemas
+// ============================================================================
+
+const TeamEntryOutputSchema = EntryOutputSchema.extend({
+    author: z.string().nullable().optional(),
+})
+
+const TeamCreateOutputSchema = z.object({
+    success: z.boolean().optional(),
+    entry: TeamEntryOutputSchema.optional(),
+    author: z.string().optional(),
+    error: z.string().optional(),
+})
+
+const TeamEntriesListOutputSchema = z.object({
+    entries: z.array(TeamEntryOutputSchema).optional(),
+    count: z.number().optional(),
+    success: z.boolean().optional(),
+    error: z.string().optional(),
+})
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const TEAM_DB_NOT_CONFIGURED =
+    'Team database not configured. Set TEAM_DB_PATH environment variable to enable team collaboration.'
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export function getTeamTools(context: ToolContext): ToolDefinition[] {
+    const { teamDb, github } = context
+
+    return [
+        {
+            name: 'team_create_entry',
+            title: 'Create Team Entry',
+            description:
+                'Create an entry in the team database for sharing with collaborators. Requires TEAM_DB_PATH.',
+            group: 'team',
+            inputSchema: TeamCreateEntrySchemaMcp,
+            outputSchema: TeamCreateOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false },
+            handler: (params: unknown) => {
+                try {
+                    if (!teamDb) {
+                        return { success: false, error: TEAM_DB_NOT_CONFIGURED }
+                    }
+
+                    const input = TeamCreateEntrySchema.parse(params)
+                    const author = input.author ?? resolveAuthor()
+
+                    // Auto-populate issueUrl if issue_number provided
+                    let resolvedIssueUrl = input.issue_url
+                    if (input.issue_number !== undefined && !input.issue_url && github) {
+                        const cachedRepo = github.getCachedRepoInfo()
+                        if (cachedRepo?.owner && cachedRepo?.repo) {
+                            resolvedIssueUrl = `https://github.com/${cachedRepo.owner}/${cachedRepo.repo}/issues/${String(input.issue_number)}`
+                        }
+                    }
+
+                    const entry = teamDb.createEntry({
+                        content: input.content,
+                        entryType: input.entry_type,
+                        tags: input.tags,
+                        isPersonal: false, // Team entries are always project-level
+                        significanceType: input.significance_type ?? null,
+                        autoContext: JSON.stringify({ author }),
+                        projectNumber: input.project_number,
+                        projectOwner: input.project_owner,
+                        issueNumber: input.issue_number,
+                        issueUrl: resolvedIssueUrl,
+                        prNumber: input.pr_number,
+                        prUrl: input.pr_url,
+                        prStatus: input.pr_status,
+                    })
+
+                    // Write author to the dedicated column
+                    const rawDb = teamDb.getRawDb()
+                    rawDb.run('UPDATE memory_journal SET author = ? WHERE id = ?', [
+                        author,
+                        entry.id,
+                    ])
+                    teamDb.flushSave()
+
+                    return {
+                        success: true,
+                        entry: { ...entry, author },
+                        author,
+                    }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'team_get_recent',
+            title: 'Get Recent Team Entries',
+            description: 'Get recent entries from the team database. Requires TEAM_DB_PATH.',
+            group: 'team',
+            inputSchema: TeamGetRecentSchema,
+            outputSchema: TeamEntriesListOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (params: unknown) => {
+                try {
+                    if (!teamDb) {
+                        return { success: false, error: TEAM_DB_NOT_CONFIGURED }
+                    }
+
+                    const { limit } = TeamGetRecentSchema.parse(params)
+                    const entries = teamDb.getRecentEntries(limit)
+
+                    // Enrich entries with author column
+                    const rawDb = teamDb.getRawDb()
+                    const enriched = entries.map((e) => {
+                        const authorResult = rawDb.exec(
+                            'SELECT author FROM memory_journal WHERE id = ?',
+                            [e.id]
+                        )
+                        const author = (authorResult[0]?.values[0]?.[0] as string) ?? null
+                        return { ...e, author }
+                    })
+
+                    return { entries: enriched, count: enriched.length }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'team_search',
+            title: 'Search Team Entries',
+            description:
+                'Search entries in the team database by text and/or tags. Requires TEAM_DB_PATH.',
+            group: 'team',
+            inputSchema: TeamSearchSchema,
+            outputSchema: TeamEntriesListOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: (params: unknown) => {
+                try {
+                    if (!teamDb) {
+                        return { success: false, error: TEAM_DB_NOT_CONFIGURED }
+                    }
+
+                    const { query, tags, limit } = TeamSearchSchema.parse(params)
+
+                    let entries
+                    if (query) {
+                        entries = teamDb.searchEntries(query, { limit })
+                    } else {
+                        entries = teamDb.getRecentEntries(limit)
+                    }
+
+                    // Filter by tags if provided
+                    if (tags && tags.length > 0) {
+                        entries = entries.filter((e) => {
+                            const entryTags = teamDb.getTagsForEntry(e.id)
+                            return tags.some((t) => entryTags.includes(t))
+                        })
+                    }
+
+                    // Enrich with author
+                    const rawDb = teamDb.getRawDb()
+                    const enriched = entries.map((e) => {
+                        const authorResult = rawDb.exec(
+                            'SELECT author FROM memory_journal WHERE id = ?',
+                            [e.id]
+                        )
+                        const author = (authorResult[0]?.values[0]?.[0] as string) ?? null
+                        return { ...e, author }
+                    })
+
+                    return { entries: enriched, count: enriched.length }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+    ]
+}