memory-journal-mcp 4.4.2 → 5.0.0

package/src/handlers/tools/export.ts

@@ -0,0 +1,115 @@
+/**
+ * Export Tool Group - 1 tool
+ *
+ * Tools: export_entries
+ */
+
+import { z } from 'zod'
+import type { ToolDefinition, ToolContext } from '../../types/index.js'
+import { formatHandlerError } from '../../utils/error-helpers.js'
+import { sendProgress } from '../../utils/progress-utils.js'
+import {
+    ENTRY_TYPES,
+    DATE_FORMAT_REGEX,
+    DATE_FORMAT_MESSAGE,
+    EntryOutputSchema,
+} from './schemas.js'
+
+// ============================================================================
+// Input Schemas
+// ============================================================================
+
+/** Strict schema — used inside handler for structured Zod errors */
+const ExportEntriesSchema = z.object({
+    format: z.enum(['json', 'markdown']).optional().default('json'),
+    start_date: z.string().regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE).optional(),
+    end_date: z.string().regex(DATE_FORMAT_REGEX, DATE_FORMAT_MESSAGE).optional(),
+    entry_types: z.array(z.enum(ENTRY_TYPES)).optional(),
+    tags: z.array(z.string()).optional(),
+    limit: z
+        .number()
+        .max(500)
+        .optional()
+        .default(100)
+        .describe('Maximum entries to export (default: 100)'),
+})
+
+/** Relaxed schema — passed to SDK inputSchema so Zod errors reach the handler */
+const ExportEntriesSchemaMcp = z.object({
+    format: z.string().optional().default('json'),
+    start_date: z.string().optional(),
+    end_date: z.string().optional(),
+    entry_types: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+    limit: z
+        .number()
+        .max(500)
+        .optional()
+        .default(100)
+        .describe('Maximum entries to export (default: 100)'),
+})
+
+// ============================================================================
+// Output Schemas
+// ============================================================================
+
+const ExportEntriesOutputSchema = z.object({
+    format: z.enum(['json', 'markdown']).optional(),
+    entries: z.array(EntryOutputSchema).optional(),
+    content: z.string().optional(),
+    success: z.boolean().optional(),
+    error: z.string().optional(),
+})
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export function getExportTools(context: ToolContext): ToolDefinition[] {
+    const { db, progress } = context
+    return [
+        {
+            name: 'export_entries',
+            title: 'Export Entries',
+            description: 'Export journal entries to JSON or Markdown format',
+            group: 'export',
+            inputSchema: ExportEntriesSchemaMcp,
+            outputSchema: ExportEntriesOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            handler: async (params: unknown) => {
+                try {
+                    const input = ExportEntriesSchema.parse(params)
+                    const limit = input.limit ?? 100
+
+                    await sendProgress(progress, 0, 2, 'Fetching entries...')
+
+                    const entries = db.getRecentEntries(limit)
+
+                    await sendProgress(
+                        progress,
+                        1,
+                        2,
+                        `Processing ${String(entries.length)} entries...`
+                    )
+
+                    if (input.format === 'markdown') {
+                        const md = entries
+                            .map(
+                                (e) =>
+                                    `## ${e.timestamp}\n\n**Type:** ${e.entryType}\n\n${e.content}\n\n---`
+                            )
+                            .join('\n\n')
+
+                        await sendProgress(progress, 2, 2, 'Export complete')
+                        return { format: 'markdown', content: md }
+                    }
+
+                    await sendProgress(progress, 2, 2, 'Export complete')
+                    return { format: 'json', entries }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+    ]
+}

package/src/handlers/tools/github/helpers.ts

@@ -0,0 +1,86 @@
+/**
+ * GitHub Tool Helpers - Shared owner/repo resolution
+ */
+
+import type { ToolContext } from '../../../types/index.js'
+import type { GitHubIntegration } from '../../../github/GitHubIntegration.js'
+
+/**
+ * Resolve owner (owner-only, no repo required)
+ */
+export async function resolveOwner(
+    context: ToolContext,
+    inputOwner?: string
+): Promise<
+    | {
+          owner: string
+          detectedOwner: string | null
+          repo: string | undefined
+          github: GitHubIntegration
+      }
+    | { error: true; response: Record<string, unknown> }
+> {
+    if (!context.github) {
+        return { error: true, response: { error: 'GitHub integration not available' } }
+    }
+
+    const repoInfo = await context.github.getRepoInfo()
+    const detectedOwner = repoInfo.owner
+    const owner = inputOwner ?? detectedOwner ?? undefined
+    const repo = repoInfo.repo ?? undefined
+
+    if (!owner) {
+        return {
+            error: true,
+            response: {
+                error: 'STOP: Could not auto-detect repository owner. DO NOT GUESS. You MUST ask the user to provide the GitHub owner.',
+                requiresUserInput: true,
+                detectedOwner,
+                instruction:
+                    'Ask the user: "What GitHub username or organization owns this project?"',
+            },
+        }
+    }
+
+    return { owner, detectedOwner, repo, github: context.github }
+}
+
+/**
+ * Resolve owner + repo (both required)
+ */
+export async function resolveOwnerRepo(
+    context: ToolContext,
+    input: { owner?: string; repo?: string }
+): Promise<
+    | {
+          owner: string
+          repo: string
+          detectedOwner: string | null
+          detectedRepo: string | null
+          github: GitHubIntegration
+      }
+    | { error: true; response: Record<string, unknown> }
+> {
+    if (!context.github) {
+        return { error: true, response: { error: 'GitHub integration not available' } }
+    }
+
+    const repoInfo = await context.github.getRepoInfo()
+    const detectedOwner = repoInfo.owner
+    const detectedRepo = repoInfo.repo
+    const owner = input.owner ?? detectedOwner ?? undefined
+    const repo = input.repo ?? detectedRepo ?? undefined
+
+    if (!owner || !repo) {
+        return {
+            error: true,
+            response: {
+                error: 'STOP: Could not auto-detect repository. DO NOT GUESS.',
+                requiresUserInput: true,
+                detected: { owner, repo },
+            },
+        }
+    }
+
+    return { owner, repo, detectedOwner, detectedRepo, github: context.github }
+}

package/src/handlers/tools/github/insights-tools.ts

@@ -0,0 +1,119 @@
+/**
+ * GitHub Insights Tools - 1 tool
+ *
+ * Tools: get_repo_insights
+ */
+
+import { z } from 'zod'
+import type { ToolDefinition, ToolContext } from '../../../types/index.js'
+import { formatHandlerError } from '../../../utils/error-helpers.js'
+import { RepoInsightsOutputSchema } from './schemas.js'
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export function getGitHubInsightsTools(context: ToolContext): ToolDefinition[] {
+    return [
+        {
+            name: 'get_repo_insights',
+            title: 'Repository Insights',
+            description:
+                'Get repository insights: stars, forks, traffic (clones/views), referrers, and popular paths. Use "sections" to control token usage: stars (~50 tokens), traffic (~100), referrers (~100), paths (~100), or all (~350).',
+            group: 'github',
+            inputSchema: z.object({
+                sections: z
+                    .enum(['stars', 'traffic', 'referrers', 'paths', 'all'])
+                    .optional()
+                    .default('stars')
+                    .describe(
+                        'Data section to return (default: stars). Use "all" for full payload.'
+                    ),
+                owner: z
+                    .string()
+                    .optional()
+                    .describe('Repository owner - LEAVE EMPTY to auto-detect'),
+                repo: z
+                    .string()
+                    .optional()
+                    .describe('Repository name - LEAVE EMPTY to auto-detect'),
+            }),
+            outputSchema: RepoInsightsOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            handler: async (params: unknown) => {
+                try {
+                    const input = z
+                        .object({
+                            sections: z
+                                .enum(['stars', 'traffic', 'referrers', 'paths', 'all'])
+                                .optional()
+                                .default('stars'),
+                            owner: z.string().optional(),
+                            repo: z.string().optional(),
+                        })
+                        .parse(params)
+
+                    if (!context.github) {
+                        return { error: 'GitHub integration not available' }
+                    }
+
+                    const repoInfo = await context.github.getRepoInfo()
+                    const owner = input.owner ?? repoInfo.owner ?? undefined
+                    const repo = input.repo ?? repoInfo.repo ?? undefined
+
+                    if (!owner || !repo) {
+                        return {
+                            error: 'STOP: Could not auto-detect repository. DO NOT GUESS. You MUST ask the user to provide the GitHub owner and repository name.',
+                            requiresUserInput: true,
+                            instruction:
+                                'Ask the user: "What GitHub repository should I get insights for? Please provide the owner and repo name (e.g., owner/repo)."',
+                        }
+                    }
+
+                    const section = input.sections
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- building response dynamically
+                    const result: Record<string, any> = {
+                        owner,
+                        repo,
+                        section,
+                    }
+
+                    if (section === 'stars' || section === 'all') {
+                        const stats = await context.github.getRepoStats(owner, repo)
+                        if (stats) {
+                            result['stars'] = stats.stars
+                            result['forks'] = stats.forks
+                            result['watchers'] = stats.watchers
+                            result['openIssues'] = stats.openIssues
+                            if (section === 'all') {
+                                result['size'] = stats.size
+                                result['defaultBranch'] = stats.defaultBranch
+                            }
+                        }
+                    }
+
+                    if (section === 'traffic' || section === 'all') {
+                        const traffic = await context.github.getTrafficData(owner, repo)
+                        if (traffic) {
+                            result['traffic'] = traffic
+                        }
+                    }
+
+                    if (section === 'referrers' || section === 'all') {
+                        const referrers = await context.github.getTopReferrers(owner, repo, 5)
+                        result['referrers'] = referrers
+                    }
+
+                    if (section === 'paths' || section === 'all') {
+                        const paths = await context.github.getPopularPaths(owner, repo, 5)
+                        result['paths'] = paths
+                    }
+
+                    return result
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+    ]
+}