memory-journal-mcp 4.3.0 → 4.4.0

package/dist/handlers/tools/index.js

@@ -168,10 +168,17 @@ const RelationshipOutputSchema = z.object({
  * Schema for get_entry_by_id output (entry with optional relationships).
  * Handles both success (entry found) and error (entry not found) cases.
  */
+const ImportanceBreakdownSchema = z.object({
+    significance: z.number(),
+    relationships: z.number(),
+    causal: z.number(),
+    recency: z.number(),
+});
 const EntryByIdOutputSchema = z.object({
     entry: EntryOutputSchema.optional(),
     relationships: z.array(RelationshipOutputSchema).optional(),
     importance: z.number().nullable().optional(), // Computed importance score (0.0-1.0)
+    importanceBreakdown: ImportanceBreakdownSchema.optional(), // Weighted component contributions
     error: z.string().optional(),
 });
 /**
@@ -300,6 +307,7 @@ const CrossProjectInsightsOutputSchema = z.object({
         project_number: z.number(),
         last_entry_date: z.string(),
     })),
+    inactiveThresholdDays: z.number(), // Cutoff for inactive classification
     time_distribution: z.array(z.object({
         project_number: z.number(),
         percentage: z.string(),
@@ -331,6 +339,7 @@ const DeleteEntryOutputSchema = z.object({
     success: z.boolean(),
     entryId: z.number(),
     permanent: z.boolean(),
+    error: z.string().optional(),
 });
 /**
  * Schema for link_entries output.
@@ -352,6 +361,13 @@ const GitHubIssueOutputSchema = z.object({
     title: z.string(),
     url: z.string(),
     state: z.enum(['OPEN', 'CLOSED']),
+    milestone: z
+        .object({
+        number: z.number(),
+        title: z.string(),
+    })
+        .nullable()
+        .optional(),
 });
 /**
  * GitHub issue details schema (extended).
@@ -510,6 +526,57 @@ const KanbanBoardOutputSchema = z.object({
     instruction: z.string().optional(),
 });
 // ============================================================================
+// Phase 3b: Repository Insights Output Schema
+// ============================================================================
+/**
+ * Schema for get_repo_insights output.
+ * Uses optional sections to minimize token usage.
+ */
+const RepoInsightsOutputSchema = z.object({
+    owner: z.string().optional(),
+    repo: z.string().optional(),
+    section: z.string().optional(),
+    stars: z.number().optional(),
+    forks: z.number().optional(),
+    watchers: z.number().optional(),
+    openIssues: z.number().optional(),
+    size: z.number().optional(),
+    defaultBranch: z.string().optional(),
+    traffic: z
+        .object({
+        clones: z.object({
+            total: z.number(),
+            unique: z.number(),
+            dailyAvg: z.number(),
+        }),
+        views: z.object({
+            total: z.number(),
+            unique: z.number(),
+            dailyAvg: z.number(),
+        }),
+        period: z.string(),
+    })
+        .optional(),
+    referrers: z
+        .array(z.object({
+        referrer: z.string(),
+        count: z.number(),
+        uniques: z.number(),
+    }))
+        .optional(),
+    paths: z
+        .array(z.object({
+        path: z.string(),
+        title: z.string(),
+        count: z.number(),
+        uniques: z.number(),
+    }))
+        .optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+});
+// ============================================================================
 // Phase 4: Backup Tool Output Schemas
 // ============================================================================
 /**
@@ -673,6 +740,86 @@ const CloseGitHubIssueWithEntryOutputSchema = z.object({
     requiresUserInput: z.boolean().optional(),
     instruction: z.string().optional(),
 });
+// ============================================================================
+// GitHub Milestone Output Schemas
+// ============================================================================
+/**
+ * GitHub milestone schema.
+ */
+const GitHubMilestoneOutputSchema = z.object({
+    number: z.number(),
+    title: z.string(),
+    description: z.string().nullable(),
+    state: z.enum(['open', 'closed']),
+    url: z.string(),
+    dueOn: z.string().nullable(),
+    openIssues: z.number(),
+    closedIssues: z.number(),
+    completionPercentage: z.number().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    creator: z.string().nullable(),
+});
+/**
+ * Schema for get_github_milestones output.
+ */
+const GitHubMilestonesListOutputSchema = z.object({
+    owner: z.string().optional(),
+    repo: z.string().optional(),
+    detectedOwner: z.string().nullable().optional(),
+    detectedRepo: z.string().nullable().optional(),
+    milestones: z.array(GitHubMilestoneOutputSchema).optional(),
+    count: z.number().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+});
+/**
+ * Schema for get_github_milestone output.
+ */
+const GitHubMilestoneResultOutputSchema = z.object({
+    milestone: GitHubMilestoneOutputSchema.optional(),
+    owner: z.string().optional(),
+    repo: z.string().optional(),
+    detectedOwner: z.string().nullable().optional(),
+    detectedRepo: z.string().nullable().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+});
+/**
+ * Schema for create_github_milestone output.
+ */
+const CreateMilestoneOutputSchema = z.object({
+    success: z.boolean().optional(),
+    milestone: GitHubMilestoneOutputSchema.optional(),
+    message: z.string().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+});
+/**
+ * Schema for update_github_milestone output.
+ */
+const UpdateMilestoneOutputSchema = z.object({
+    success: z.boolean().optional(),
+    milestone: GitHubMilestoneOutputSchema.optional(),
+    message: z.string().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+});
+/**
+ * Schema for delete_github_milestone output.
+ */
+const DeleteMilestoneOutputSchema = z.object({
+    success: z.boolean().optional(),
+    milestoneNumber: z.number().optional(),
+    message: z.string().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+});
 /**
  * Schema for cleanup_backups output.
  */
@@ -791,8 +938,12 @@ function getAllToolDefinitions(context) {
                 if (!entry) {
                     return Promise.resolve({ error: `Entry ${entry_id} not found` });
                 }
-                const importance = db.calculateImportance(entry_id);
-                const result = { entry, importance };
+                const { score: importance, breakdown: importanceBreakdown } = db.calculateImportance(entry_id);
+                const result = {
+                    entry,
+                    importance,
+                    importanceBreakdown,
+                };
                 if (include_relationships) {
                     result['relationships'] = db.getRelationships(entry_id);
                 }
@@ -1014,8 +1165,13 @@ function getAllToolDefinitions(context) {
                 `, [...sqlParams, input.min_entries]);
                 if (!projectsResult[0] || projectsResult[0].values.length === 0) {
                     return Promise.resolve({
-                        message: `No projects found with at least ${String(input.min_entries)} entries`,
+                        project_count: 0,
+                        total_entries: 0,
                         projects: [],
+                        inactive_projects: [],
+                        inactiveThresholdDays: 7,
+                        time_distribution: [],
+                        message: `No projects found with at least ${String(input.min_entries)} entries`,
                     });
                 }
                 const columns = projectsResult[0].columns;
@@ -1074,6 +1230,7 @@ function getAllToolDefinitions(context) {
                         top_tags: projectTags[p['project_number']] ?? [],
                     })),
                     inactive_projects: inactiveProjects,
+                    inactiveThresholdDays: 7,
                     time_distribution: distribution,
                 });
             },
@@ -1101,8 +1258,25 @@ function getAllToolDefinitions(context) {
                         message: 'Relationship already exists',
                     });
                 }
-                const relationship = db.linkEntries(input.from_entry_id, input.to_entry_id, input.relationship_type, input.description);
-                return Promise.resolve({ success: true, relationship });
+                // P154: linkEntries throws for nonexistent entries
+                try {
+                    const relationship = db.linkEntries(input.from_entry_id, input.to_entry_id, input.relationship_type, input.description);
+                    return Promise.resolve({ success: true, relationship });
+                }
+                catch (error) {
+                    return Promise.resolve({
+                        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',
+                    });
+                }
             },
         },
         {
@@ -1139,6 +1313,18 @@ function getAllToolDefinitions(context) {
                 const rawDb = db.getRawDb();
                 let entriesResult;
                 if (input.entry_id !== undefined) {
+                    // P154: Pre-check entry existence to disambiguate responses
+                    const entry = db.getEntryById(input.entry_id);
+                    if (!entry) {
+                        return Promise.resolve({
+                            entry_count: 0,
+                            relationship_count: 0,
+                            root_entry: input.entry_id,
+                            depth: input.depth,
+                            mermaid: null,
+                            message: `Entry ${String(input.entry_id)} not found`,
+                        });
+                    }
                     // Use recursive CTE to get connected entries up to depth
                     entriesResult = rawDb.exec(`
                         WITH RECURSIVE connected_entries(id, distance) AS (
@@ -1193,8 +1379,12 @@ function getAllToolDefinitions(context) {
                 }
                 if (!entriesResult[0] || entriesResult[0].values.length === 0) {
                     return Promise.resolve({
-                        message: 'No entries found with relationships matching your criteria',
+                        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
@@ -1352,8 +1542,17 @@ function getAllToolDefinitions(context) {
             handler: (params) => {
                 const { entry_id, permanent } = DeleteEntrySchema.parse(params);
                 const success = db.deleteEntry(entry_id, permanent);
+                // P154: Surface structured error for nonexistent entries
+                if (!success) {
+                    return Promise.resolve({
+                        success: false,
+                        entryId: entry_id,
+                        permanent,
+                        error: `Entry ${String(entry_id)} not found`,
+                    });
+                }
                 // Remove from vector index (non-critical if fails)
-                if (success && vectorManager) {
+                if (vectorManager) {
                     vectorManager.removeEntry(entry_id).catch(() => {
                         // Non-critical failure, entry already deleted from DB
                     });
@@ -1858,6 +2057,10 @@ function getAllToolDefinitions(context) {
                 body: z.string().optional().describe('Issue body/description'),
                 labels: z.array(z.string()).optional().describe('Labels to apply'),
                 assignees: z.array(z.string()).optional().describe('Users to assign'),
+                milestone_number: z
+                    .number()
+                    .optional()
+                    .describe('Milestone number to assign this issue to'),
                 project_number: z
                     .number()
                     .optional()
@@ -1889,6 +2092,7 @@ function getAllToolDefinitions(context) {
                     body: z.string().optional(),
                     labels: z.array(z.string()).optional(),
                     assignees: z.array(z.string()).optional(),
+                    milestone_number: z.number().optional(),
                     project_number: z.number().optional(),
                     initial_status: z.string().optional(),
                     owner: z.string().optional(),
@@ -1912,7 +2116,7 @@ function getAllToolDefinitions(context) {
                     };
                 }
                 // Create the GitHub issue
-                const issue = await github.createIssue(owner, repo, input.title, input.body, input.labels, input.assignees);
+                const issue = await github.createIssue(owner, repo, input.title, input.body, input.labels, input.assignees, input.milestone_number);
                 if (!issue) {
                     return {
                         error: 'Failed to create GitHub issue. Check GITHUB_TOKEN permissions.',
@@ -2196,6 +2400,389 @@ function getAllToolDefinitions(context) {
                 };
             },
         },
+        // Milestone tools
+        {
+            name: 'get_github_milestones',
+            title: 'List GitHub Milestones',
+            description: 'List GitHub milestones for the repository with completion percentages and due dates.',
+            group: 'github',
+            inputSchema: z.object({
+                state: z
+                    .enum(['open', 'closed', 'all'])
+                    .optional()
+                    .default('open')
+                    .describe('Filter by state (default: open)'),
+                limit: z
+                    .number()
+                    .optional()
+                    .default(20)
+                    .describe('Max milestones to return (default: 20)'),
+                owner: z.string().optional().describe('LEAVE EMPTY to auto-detect from git'),
+                repo: z.string().optional().describe('LEAVE EMPTY to auto-detect from git'),
+            }),
+            outputSchema: GitHubMilestonesListOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            handler: async (params) => {
+                const input = z
+                    .object({
+                    state: z.enum(['open', 'closed', 'all']).optional().default('open'),
+                    limit: z.number().optional().default(20),
+                    owner: z.string().optional(),
+                    repo: z.string().optional(),
+                })
+                    .parse(params);
+                if (!github) {
+                    return { error: 'GitHub integration not available' };
+                }
+                const repoInfo = await 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: 'STOP: Could not auto-detect repository. DO NOT GUESS. You MUST ask the user to provide the GitHub owner and repository name.',
+                        requiresUserInput: true,
+                        detectedOwner,
+                        detectedRepo,
+                        instruction: 'Ask the user: "What GitHub repository should I list milestones for? Please provide the owner and repo name (e.g., owner/repo)."',
+                    };
+                }
+                const milestones = await github.getMilestones(owner, repo, input.state, input.limit);
+                const milestonesWithPercentage = milestones.map((ms) => {
+                    const total = ms.openIssues + ms.closedIssues;
+                    const completionPercentage = total > 0 ? Math.round((ms.closedIssues / total) * 100) : 0;
+                    return { ...ms, completionPercentage };
+                });
+                return {
+                    milestones: milestonesWithPercentage,
+                    count: milestonesWithPercentage.length,
+                    owner,
+                    repo,
+                    detectedOwner,
+                    detectedRepo,
+                };
+            },
+        },
+        {
+            name: 'get_github_milestone',
+            title: 'Get GitHub Milestone Details',
+            description: 'Get detailed information about a specific GitHub milestone including progress and linked issue counts.',
+            group: 'github',
+            inputSchema: z.object({
+                milestone_number: z.number().describe('Milestone number'),
+                owner: z.string().optional().describe('LEAVE EMPTY to auto-detect from git'),
+                repo: z.string().optional().describe('LEAVE EMPTY to auto-detect from git'),
+            }),
+            outputSchema: GitHubMilestoneResultOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            handler: async (params) => {
+                const input = z
+                    .object({
+                    milestone_number: z.number(),
+                    owner: z.string().optional(),
+                    repo: z.string().optional(),
+                })
+                    .parse(params);
+                if (!github) {
+                    return { error: 'GitHub integration not available' };
+                }
+                const repoInfo = await 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: 'STOP: Could not auto-detect repository. DO NOT GUESS. You MUST ask the user to provide the GitHub owner and repository name.',
+                        requiresUserInput: true,
+                        detectedOwner,
+                        detectedRepo,
+                        instruction: 'Ask the user: "What GitHub repository is this milestone from? Please provide the owner and repo name (e.g., owner/repo)."',
+                    };
+                }
+                const milestone = await github.getMilestone(owner, repo, input.milestone_number);
+                if (!milestone) {
+                    return {
+                        error: `Milestone #${String(input.milestone_number)} not found`,
+                        owner,
+                        repo,
+                        detectedOwner,
+                        detectedRepo,
+                    };
+                }
+                const total = milestone.openIssues + milestone.closedIssues;
+                const completionPercentage = total > 0 ? Math.round((milestone.closedIssues / total) * 100) : 0;
+                return {
+                    milestone: { ...milestone, completionPercentage },
+                    owner,
+                    repo,
+                    detectedOwner,
+                    detectedRepo,
+                };
+            },
+        },
+        {
+            name: 'create_github_milestone',
+            title: 'Create GitHub Milestone',
+            description: 'Create a new GitHub milestone for tracking progress toward a project goal.',
+            group: 'github',
+            inputSchema: z.object({
+                title: z.string().min(1).describe('Milestone title'),
+                description: z.string().optional().describe('Milestone description'),
+                due_on: z.string().optional().describe('Due date in YYYY-MM-DD format (optional)'),
+                owner: z.string().optional().describe('LEAVE EMPTY to auto-detect'),
+                repo: z.string().optional().describe('LEAVE EMPTY to auto-detect'),
+            }),
+            outputSchema: CreateMilestoneOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+            handler: async (params) => {
+                const input = z
+                    .object({
+                    title: z.string().min(1),
+                    description: z.string().optional(),
+                    due_on: z.string().optional(),
+                    owner: z.string().optional(),
+                    repo: z.string().optional(),
+                })
+                    .parse(params);
+                if (!github) {
+                    return { error: 'GitHub integration not available' };
+                }
+                const repoInfo = await 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.',
+                        requiresUserInput: true,
+                        instruction: 'Ask the user: "What GitHub repository should I create the milestone in?"',
+                    };
+                }
+                // Format due_on to ISO 8601 if provided (GitHub expects YYYY-MM-DDTHH:MM:SSZ)
+                const dueOn = input.due_on ? `${input.due_on}T08:00:00Z` : undefined;
+                const milestone = await github.createMilestone(owner, repo, input.title, input.description, dueOn);
+                if (!milestone) {
+                    return {
+                        error: 'Failed to create milestone. Check GITHUB_TOKEN permissions.',
+                    };
+                }
+                return {
+                    success: true,
+                    milestone: { ...milestone, completionPercentage: 0 },
+                    message: `Created milestone #${String(milestone.number)}: ${milestone.title}`,
+                };
+            },
+        },
+        {
+            name: 'update_github_milestone',
+            title: 'Update GitHub Milestone',
+            description: 'Update a GitHub milestone (title, description, due date, or state). Use state "closed" to close a completed milestone.',
+            group: 'github',
+            inputSchema: z.object({
+                milestone_number: z.number().describe('Milestone number to update'),
+                title: z.string().optional().describe('New title'),
+                description: z.string().optional().describe('New description'),
+                due_on: z.string().optional().describe('New due date in YYYY-MM-DD format'),
+                state: z
+                    .enum(['open', 'closed'])
+                    .optional()
+                    .describe('Set to "closed" to close the milestone'),
+                owner: z.string().optional().describe('LEAVE EMPTY to auto-detect'),
+                repo: z.string().optional().describe('LEAVE EMPTY to auto-detect'),
+            }),
+            outputSchema: UpdateMilestoneOutputSchema,
+            annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+            handler: async (params) => {
+                const input = z
+                    .object({
+                    milestone_number: z.number(),
+                    title: z.string().optional(),
+                    description: z.string().optional(),
+                    due_on: z.string().optional(),
+                    state: z.enum(['open', 'closed']).optional(),
+                    owner: z.string().optional(),
+                    repo: z.string().optional(),
+                })
+                    .parse(params);
+                if (!github) {
+                    return { error: 'GitHub integration not available' };
+                }
+                const repoInfo = await 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.',
+                        requiresUserInput: true,
+                        instruction: 'Ask the user: "What GitHub repository is this milestone in?"',
+                    };
+                }
+                const dueOn = input.due_on ? `${input.due_on}T08:00:00Z` : undefined;
+                const milestone = await github.updateMilestone(owner, repo, input.milestone_number, {
+                    title: input.title,
+                    description: input.description,
+                    dueOn,
+                    state: input.state,
+                });
+                if (!milestone) {
+                    return {
+                        error: `Failed to update milestone #${String(input.milestone_number)}. Check that it exists and GITHUB_TOKEN has permissions.`,
+                    };
+                }
+                const total = milestone.openIssues + milestone.closedIssues;
+                const completionPercentage = total > 0 ? Math.round((milestone.closedIssues / total) * 100) : 0;
+                return {
+                    success: true,
+                    milestone: { ...milestone, completionPercentage },
+                    message: `Updated milestone #${String(milestone.number)}: ${milestone.title}`,
+                };
+            },
+        },
+        {
+            name: 'delete_github_milestone',
+            title: 'Delete GitHub Milestone',
+            description: 'Permanently delete a GitHub milestone. Issues assigned to the milestone will be un-assigned but not deleted.',
+            group: 'github',
+            inputSchema: z.object({
+                milestone_number: z.number().describe('Milestone number to delete'),
+                confirm: z.literal(true).describe('Must be set to true to confirm deletion'),
+                owner: z.string().optional().describe('LEAVE EMPTY to auto-detect'),
+                repo: z.string().optional().describe('LEAVE EMPTY to auto-detect'),
+            }),
+            outputSchema: DeleteMilestoneOutputSchema,
+            annotations: {
+                readOnlyHint: false,
+                idempotentHint: false,
+                destructiveHint: true,
+                openWorldHint: true,
+            },
+            handler: async (params) => {
+                const input = z
+                    .object({
+                    milestone_number: z.number(),
+                    confirm: z.literal(true),
+                    owner: z.string().optional(),
+                    repo: z.string().optional(),
+                })
+                    .parse(params);
+                if (!github) {
+                    return { error: 'GitHub integration not available' };
+                }
+                const repoInfo = await 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.',
+                        requiresUserInput: true,
+                        instruction: 'Ask the user: "What GitHub repository is this milestone in?"',
+                    };
+                }
+                const result = await github.deleteMilestone(owner, repo, input.milestone_number);
+                if (!result.success) {
+                    return {
+                        success: false,
+                        milestoneNumber: input.milestone_number,
+                        message: `Failed to delete milestone #${String(input.milestone_number)}`,
+                        error: result.error ?? undefined,
+                    };
+                }
+                return {
+                    success: true,
+                    milestoneNumber: input.milestone_number,
+                    message: `Deleted milestone #${String(input.milestone_number)}`,
+                };
+            },
+        },
+        // Repository insights tool
+        {
+            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) => {
+                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 (!github) {
+                    return { error: 'GitHub integration not available' };
+                }
+                const repoInfo = await 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 = {
+                    owner,
+                    repo,
+                    section,
+                };
+                // Stars section (default)
+                if (section === 'stars' || section === 'all') {
+                    const stats = await 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;
+                        }
+                    }
+                }
+                // Traffic section
+                if (section === 'traffic' || section === 'all') {
+                    const traffic = await github.getTrafficData(owner, repo);
+                    if (traffic) {
+                        result['traffic'] = traffic;
+                    }
+                }
+                // Referrers section
+                if (section === 'referrers' || section === 'all') {
+                    const referrers = await github.getTopReferrers(owner, repo, 5);
+                    result['referrers'] = referrers;
+                }
+                // Paths section
+                if (section === 'paths' || section === 'all') {
+                    const paths = await github.getPopularPaths(owner, repo, 5);
+                    result['paths'] = paths;
+                }
+                return result;
+            },
+        },
         // Backup tools
         {
             name: 'backup_journal',