memory-journal-mcp 4.4.2 → 5.0.0

package/src/handlers/resources/shared.ts

@@ -0,0 +1,103 @@
+/**
+ * Memory Journal MCP Server - Resource Shared Types & Helpers
+ *
+ * Shared types, helpers, and utilities used by all resource group modules.
+ */
+
+import type { SqliteAdapter } from '../../database/SqliteAdapter.js'
+import type { VectorSearchManager } from '../../vector/VectorSearchManager.js'
+import type { ToolFilterConfig } from '../../filtering/ToolFilter.js'
+import type { McpIcon } from '../../types/index.js'
+import type { GitHubIntegration } from '../../github/GitHubIntegration.js'
+import type { Scheduler } from '../../server/Scheduler.js'
+
+/**
+ * Resource context for handlers that need extended access
+ */
+export interface ResourceContext {
+    db: SqliteAdapter
+    teamDb?: SqliteAdapter
+    vectorManager?: VectorSearchManager
+    filterConfig?: ToolFilterConfig | null
+    github?: GitHubIntegration | null
+    scheduler?: Scheduler | null
+}
+
+/**
+ * Resource handler result with optional annotations for MCP 2025-11-25
+ */
+export interface ResourceResult {
+    data: unknown
+    annotations?: {
+        lastModified?: string // ISO 8601 timestamp
+    }
+}
+
+/**
+ * Internal resource definition with db handler
+ */
+export interface InternalResourceDef {
+    uri: string
+    name: string
+    title: string
+    description: string
+    mimeType: string
+    icons?: McpIcon[] // MCP 2025-11-25 icons
+    annotations?: {
+        audience?: ('user' | 'assistant')[]
+        priority?: number
+        lastModified?: string
+        autoRead?: boolean
+        sessionInit?: boolean
+    }
+    handler: (uri: string, context: ResourceContext) => unknown
+}
+
+/**
+ * Execute a raw SQL query on the database
+ */
+export function execQuery(
+    db: SqliteAdapter,
+    sql: string,
+    params: unknown[] = []
+): Record<string, unknown>[] {
+    const rawDb = db.getRawDb()
+    const result = rawDb.exec(sql, params)
+    if (result.length === 0) return []
+
+    const columns = result[0]?.columns ?? []
+    return (result[0]?.values ?? []).map((values: unknown[]) => {
+        const obj: Record<string, unknown> = {}
+        columns.forEach((col: string, i: number) => {
+            obj[col] = values[i]
+        })
+        return obj
+    })
+}
+
+/**
+ * Transform snake_case SQL row to camelCase entry object
+ * Ensures consistency with SqliteAdapter.getRecentEntries() output
+ */
+export function transformEntryRow(row: Record<string, unknown>): Record<string, unknown> {
+    return {
+        id: row['id'],
+        entryType: row['entry_type'],
+        content: row['content'],
+        timestamp: row['timestamp'],
+        isPersonal: row['is_personal'] === 1 || row['is_personal'] === true,
+        significanceType: row['significance_type'] ?? null,
+        autoContext: row['auto_context'] ?? null,
+        deletedAt: row['deleted_at'] ?? null,
+        projectNumber: row['project_number'] ?? null,
+        projectOwner: row['project_owner'] ?? null,
+        issueNumber: row['issue_number'] ?? null,
+        issueUrl: row['issue_url'] ?? null,
+        prNumber: row['pr_number'] ?? null,
+        prUrl: row['pr_url'] ?? null,
+        prStatus: row['pr_status'] ?? null,
+        workflowRunId: row['workflow_run_id'] ?? null,
+        workflowName: row['workflow_name'] ?? null,
+        workflowStatus: row['workflow_status'] ?? null,
+    }
+}

package/src/handlers/resources/team.ts

@@ -0,0 +1,133 @@
+/**
+ * Team Resource Definitions - 2 resources
+ *
+ * Resources: memory://team/recent, memory://team/statistics
+ *
+ * Requires TEAM_DB_PATH to be configured.
+ */
+
+import { ICON_CLOCK, ICON_TEAM } from '../../constants/icons.js'
+import type { InternalResourceDef, ResourceContext, ResourceResult } from './shared.js'
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Enrich entries with author column from the team database
+ */
+function enrichWithAuthor<T extends { id: number }>(
+    entries: T[],
+    context: ResourceContext
+): (T & { author: string | null })[] {
+    if (!context.teamDb) return entries.map((e) => ({ ...e, author: null }))
+    const rawDb = context.teamDb.getRawDb()
+    return 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 }
+    })
+}
+
+// ============================================================================
+// Resource Definitions
+// ============================================================================
+
+/**
+ * Get team resource definitions
+ */
+export function getTeamResourceDefinitions(): InternalResourceDef[] {
+    return [
+        {
+            uri: 'memory://team/recent',
+            name: 'Recent Team Entries',
+            title: 'Recent Team-Shared Entries',
+            description:
+                'Recent entries from the team database. Requires TEAM_DB_PATH configuration.',
+            mimeType: 'application/json',
+            icons: [ICON_CLOCK],
+            annotations: {
+                audience: ['assistant'],
+                priority: 0.7,
+            },
+            handler: (_uri: string, context: ResourceContext): ResourceResult => {
+                if (!context.teamDb) {
+                    return {
+                        data: {
+                            error: 'Team database not configured. Set TEAM_DB_PATH to enable.',
+                            entries: [],
+                            count: 0,
+                        },
+                    }
+                }
+
+                const entries = context.teamDb.getRecentEntries(10)
+                const lastModified = entries[0]?.timestamp ?? new Date().toISOString()
+                const enriched = enrichWithAuthor(entries, context)
+
+                return {
+                    data: {
+                        entries: enriched,
+                        count: enriched.length,
+                        source: 'team',
+                    },
+                    annotations: { lastModified },
+                }
+            },
+        },
+        {
+            uri: 'memory://team/statistics',
+            name: 'Team Statistics',
+            title: 'Team Database Statistics',
+            description: 'Entry counts, types, and contributor breakdown for the team database.',
+            mimeType: 'application/json',
+            icons: [ICON_TEAM],
+            annotations: {
+                audience: ['assistant'],
+                priority: 0.6,
+            },
+            handler: (_uri: string, context: ResourceContext): ResourceResult => {
+                if (!context.teamDb) {
+                    return {
+                        data: {
+                            error: 'Team database not configured. Set TEAM_DB_PATH to enable.',
+                            configured: false,
+                        },
+                    }
+                }
+
+                const stats = context.teamDb.getStatistics('week')
+                const rawDb = context.teamDb.getRawDb()
+
+                // Author breakdown
+                let authors: { author: string; count: number }[] = []
+                try {
+                    const authorResult = rawDb.exec(
+                        `SELECT COALESCE(author, 'unknown') as author, COUNT(*) as count
+                         FROM memory_journal
+                         WHERE deleted_at IS NULL
+                         GROUP BY COALESCE(author, 'unknown')
+                         ORDER BY count DESC`
+                    )
+                    if (authorResult[0]) {
+                        authors = authorResult[0].values.map((row) => ({
+                            author: row[0] as string,
+                            count: row[1] as number,
+                        }))
+                    }
+                } catch {
+                    // Author column may not exist yet
+                }
+
+                return {
+                    data: {
+                        configured: true,
+                        ...stats,
+                        authors,
+                        source: 'team',
+                    },
+                }
+            },
+        },
+    ]
+}

package/src/handlers/resources/templates.ts

@@ -0,0 +1,374 @@
+/**
+ * Memory Journal MCP Server - Template Resource Definitions
+ *
+ * Resources with URI templates (parameterized):
+ * projects/{number}/timeline, issues/{issue_number}/entries, prs/{pr_number}/entries,
+ * prs/{pr_number}/timeline, kanban/{project_number}, kanban/{project_number}/diagram
+ */
+
+import { ICON_ISSUE, ICON_PR } from '../../constants/icons.js'
+import type { InternalResourceDef, ResourceContext } from './shared.js'
+import { execQuery, transformEntryRow } from './shared.js'
+
+/**
+ * Get template resource definitions
+ */
+export function getTemplateResourceDefinitions(): InternalResourceDef[] {
+    return [
+        {
+            uri: 'memory://projects/{number}/timeline',
+            name: 'Project Timeline',
+            title: 'Project Activity Timeline',
+            description: 'Project activity timeline',
+            mimeType: 'application/json',
+            annotations: {
+                audience: ['assistant'],
+                priority: 0.6,
+            },
+            handler: (uri: string, context: ResourceContext) => {
+                const match = /memory:\/\/projects\/(\d+)\/timeline/.exec(uri)
+                const projectNumber = match?.[1] ? parseInt(match[1], 10) : null
+
+                if (projectNumber === null) {
+                    return { error: 'Invalid project number' }
+                }
+
+                const rows = execQuery(
+                    context.db,
+                    `
+                    SELECT * FROM memory_journal
+                    WHERE project_number = ?
+                    AND deleted_at IS NULL
+                    ORDER BY timestamp DESC
+                    LIMIT 50
+                `,
+                    [projectNumber]
+                )
+                const entries = rows.map(transformEntryRow)
+                return { projectNumber, entries, count: entries.length }
+            },
+        },
+        {
+            uri: 'memory://issues/{issue_number}/entries',
+            name: 'Issue Entries',
+            title: 'Entries Linked to Issue',
+            description: 'All entries linked to a specific issue',
+            mimeType: 'application/json',
+            icons: [ICON_ISSUE],
+            annotations: {
+                audience: ['assistant'],
+                priority: 0.6,
+            },
+            handler: (uri: string, context: ResourceContext) => {
+                const match = /memory:\/\/issues\/(\d+)\/entries/.exec(uri)
+                const issueNumber = match?.[1] ? parseInt(match[1], 10) : null
+
+                if (issueNumber === null) {
+                    return { error: 'Invalid issue number' }
+                }
+
+                const rows = execQuery(
+                    context.db,
+                    `
+                    SELECT * FROM memory_journal
+                    WHERE issue_number = ?
+                    AND deleted_at IS NULL
+                    ORDER BY timestamp DESC
+                `,
+                    [issueNumber]
+                )
+                const entries = rows.map(transformEntryRow)
+                return { issueNumber, entries, count: entries.length }
+            },
+        },
+        {
+            uri: 'memory://prs/{pr_number}/entries',
+            name: 'PR Entries',
+            title: 'Entries Linked to PR',
+            description: 'All entries linked to a specific pull request',
+            mimeType: 'application/json',
+            icons: [ICON_PR],
+            annotations: {
+                audience: ['assistant'],
+                priority: 0.6,
+            },
+            handler: (uri: string, context: ResourceContext) => {
+                const match = /memory:\/\/prs\/(\d+)\/entries/.exec(uri)
+                const prNumber = match?.[1] ? parseInt(match[1], 10) : null
+
+                if (prNumber === null) {
+                    return { error: 'Invalid PR number' }
+                }
+
+                const rows = execQuery(
+                    context.db,
+                    `
+                    SELECT * FROM memory_journal
+                    WHERE pr_number = ?
+                    AND deleted_at IS NULL
+                    ORDER BY timestamp DESC
+                `,
+                    [prNumber]
+                )
+                const entries = rows.map(transformEntryRow)
+                return {
+                    prNumber,
+                    entries,
+                    count: entries.length,
+                    ...(entries.length === 0
+                        ? {
+                              hint: 'No journal entries linked to this PR. Use create_entry with pr_number to link entries.',
+                          }
+                        : {}),
+                }
+            },
+        },
+        {
+            uri: 'memory://prs/{pr_number}/timeline',
+            name: 'PR Timeline',
+            title: 'Combined PR and Journal Timeline',
+            description: 'Combined PR + journal timeline with live PR metadata',
+            mimeType: 'application/json',
+            icons: [ICON_PR],
+            annotations: {
+                audience: ['assistant'],
+                priority: 0.5,
+            },
+            handler: async (uri: string, context: ResourceContext) => {
+                const match = /memory:\/\/prs\/(\d+)\/timeline/.exec(uri)
+                const prNumber = match?.[1] ? parseInt(match[1], 10) : null
+
+                if (prNumber === null) {
+                    return { error: 'Invalid PR number' }
+                }
+
+                // Fetch live PR metadata from GitHub if available
+                let prMetadata: {
+                    title: string
+                    state: string
+                    draft: boolean
+                    mergedAt: string | null
+                    closedAt: string | null
+                    author: string
+                    headBranch: string
+                    baseBranch: string
+                } | null = null
+
+                if (context.github) {
+                    try {
+                        const repoInfo = await context.github.getRepoInfo()
+                        if (repoInfo.owner && repoInfo.repo) {
+                            const pr = await context.github.getPullRequest(
+                                repoInfo.owner,
+                                repoInfo.repo,
+                                prNumber
+                            )
+                            if (pr) {
+                                prMetadata = {
+                                    title: pr.title,
+                                    state: pr.state,
+                                    draft: pr.draft,
+                                    mergedAt: pr.mergedAt,
+                                    closedAt: pr.closedAt,
+                                    author: pr.author,
+                                    headBranch: pr.headBranch,
+                                    baseBranch: pr.baseBranch,
+                                }
+                            }
+                        }
+                    } catch {
+                        // GitHub not available, proceed without metadata
+                    }
+                }
+
+                const rows = execQuery(
+                    context.db,
+                    `
+                    SELECT * FROM memory_journal
+                    WHERE pr_number = ?
+                    AND deleted_at IS NULL
+                    ORDER BY timestamp DESC
+                `,
+                    [prNumber]
+                )
+                const entries = rows.map(transformEntryRow)
+
+                let timelineNote: string
+                if (prMetadata) {
+                    const stateDesc = prMetadata.state.toLowerCase()
+                    const mergedNote = prMetadata.mergedAt ? ' (merged)' : ''
+                    const draftNote = prMetadata.draft ? ' [DRAFT]' : ''
+                    timelineNote = `PR #${String(prNumber)} is ${stateDesc}${mergedNote}${draftNote}`
+                } else {
+                    timelineNote =
+                        'GitHub integration unavailable for live PR status. Entry timestamps show journal activity.'
+                }
+
+                return {
+                    prNumber,
+                    prMetadata,
+                    entries,
+                    count: entries.length,
+                    timelineNote,
+                    ...(entries.length === 0
+                        ? {
+                              hint: 'No journal entries linked to this PR. Use create_entry with pr_number to link entries.',
+                          }
+                        : {}),
+                }
+            },
+        },
+        // Kanban board resources (GitHub Projects v2)
+        {
+            uri: 'memory://kanban/{project_number}',
+            name: 'Kanban Board',
+            title: 'GitHub Project Kanban Board',
+            description: 'View a GitHub Project v2 as a Kanban board with items grouped by Status',
+            mimeType: 'application/json',
+            annotations: {
+                audience: ['assistant'],
+                priority: 0.6,
+            },
+            handler: async (uri: string, context: ResourceContext) => {
+                const match = /memory:\/\/kanban\/(\d+)/.exec(uri)
+                const projectNumber = match?.[1] ? parseInt(match[1], 10) : null
+
+                if (projectNumber === null) {
+                    return { error: 'Invalid project number' }
+                }
+
+                if (!context.github) {
+                    return {
+                        error: 'GitHub integration not available',
+                        hint: 'Set GITHUB_TOKEN and GITHUB_REPO_PATH environment variables.',
+                    }
+                }
+
+                const repoInfo = await context.github.getRepoInfo()
+                const owner = repoInfo.owner
+                const repo = repoInfo.repo ?? undefined
+
+                if (!owner) {
+                    return {
+                        error: 'Could not detect repository owner',
+                        hint: 'Set GITHUB_REPO_PATH to your git repository.',
+                    }
+                }
+
+                const board = await context.github.getProjectKanban(owner, projectNumber, repo)
+                if (!board) {
+                    return {
+                        error: `Project #${String(projectNumber)} not found or Status field not configured`,
+                        projectNumber,
+                        owner,
+                        hint: 'Projects can be at user, repository, or organization level.',
+                    }
+                }
+
+                return board
+            },
+        },
+        {
+            uri: 'memory://kanban/{project_number}/diagram',
+            name: 'Kanban Diagram',
+            title: 'Kanban Board Mermaid Diagram',
+            description: 'Mermaid diagram visualization of a GitHub Project Kanban board',
+            mimeType: 'text/plain',
+            annotations: {
+                audience: ['user', 'assistant'],
+                priority: 0.5,
+            },
+            handler: async (uri: string, context: ResourceContext) => {
+                const match = /memory:\/\/kanban\/(\d+)\/diagram/.exec(uri)
+                const projectNumber = match?.[1] ? parseInt(match[1], 10) : null
+
+                if (projectNumber === null) {
+                    return { error: 'Invalid project number' }
+                }
+
+                if (!context.github) {
+                    return {
+                        format: 'mermaid',
+                        diagram: 'graph LR\n  NoGitHub[GitHub integration not available]',
+                        message: 'Set GITHUB_TOKEN and GITHUB_REPO_PATH environment variables.',
+                    }
+                }
+
+                const repoInfo = await context.github.getRepoInfo()
+                const owner = repoInfo.owner
+                const repo = repoInfo.repo ?? undefined
+
+                if (!owner) {
+                    return {
+                        format: 'mermaid',
+                        diagram: 'graph LR\n  NoOwner[Repository owner not detected]',
+                        message: 'Set GITHUB_REPO_PATH to your git repository.',
+                    }
+                }
+
+                const board = await context.github.getProjectKanban(owner, projectNumber, repo)
+                if (!board) {
+                    return {
+                        format: 'mermaid',
+                        diagram: `graph LR\n  NotFound[Project #${String(projectNumber)} not found]`,
+                        message: 'Ensure the project exists and has a Status field.',
+                    }
+                }
+
+                // Build Mermaid diagram with subgraphs for each column
+                const lines: string[] = ['graph LR']
+
+                lines.push('  classDef issue fill:#28a745,color:#fff')
+                lines.push('  classDef pr fill:#6f42c1,color:#fff')
+                lines.push('  classDef draft fill:#6c757d,color:#fff')
+
+                for (const column of board.columns) {
+                    const safeStatus = column.status.replace(/["\s]/g, '_')
+                    lines.push(
+                        `  subgraph ${safeStatus}["${column.status} (${String(column.items.length)})"]`
+                    )
+
+                    for (const item of column.items) {
+                        const safeId = item.id.replace(/[^a-zA-Z0-9]/g, '').slice(-8)
+                        const label = item.title.slice(0, 25).replace(/["[\]]/g, "'")
+                        const typeIcon =
+                            item.type === 'ISSUE'
+                                ? '🔵'
+                                : item.type === 'PULL_REQUEST'
+                                  ? '🟣'
+                                  : '⚪'
+                        const numberStr =
+                            item.number !== undefined && item.number !== 0
+                                ? `#${String(item.number)}`
+                                : ''
+                        lines.push(`    I${safeId}["${typeIcon} ${numberStr} ${label}..."]`)
+
+                        const typeClass =
+                            item.type === 'ISSUE'
+                                ? 'issue'
+                                : item.type === 'PULL_REQUEST'
+                                  ? 'pr'
+                                  : 'draft'
+                        lines.push(`    class I${safeId} ${typeClass}`)
+                    }
+
+                    lines.push('  end')
+                }
+
+                return {
+                    format: 'mermaid',
+                    diagram: lines.join('\n'),
+                    projectNumber,
+                    projectTitle: board.projectTitle,
+                    columnCount: board.columns.length,
+                    totalItems: board.totalItems,
+                    legend: {
+                        '🔵': 'Issue',
+                        '🟣': 'Pull Request',
+                        '⚪': 'Draft Issue',
+                    },
+                }
+            },
+        },
+    ]
+}