memory-journal-mcp 4.3.0 → 4.4.0

package/src/handlers/tools/index.ts

@@ -213,10 +213,18 @@ 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(),
 })
 
@@ -362,6 +370,7 @@ const CrossProjectInsightsOutputSchema = z.object({
             last_entry_date: z.string(),
         })
     ),
+    inactiveThresholdDays: z.number(), // Cutoff for inactive classification
     time_distribution: z.array(
         z.object({
             project_number: z.number(),
@@ -399,6 +408,7 @@ const DeleteEntryOutputSchema = z.object({
     success: z.boolean(),
     entryId: z.number(),
     permanent: z.boolean(),
+    error: z.string().optional(),
 })
 
 /**
@@ -423,6 +433,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(),
 })
 
 /**
@@ -593,6 +610,63 @@ 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
 // ============================================================================
@@ -770,6 +844,93 @@ const CloseGitHubIssueWithEntryOutputSchema = z.object({
     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.
  */
@@ -915,8 +1076,13 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
                 if (!entry) {
                     return Promise.resolve({ error: `Entry ${entry_id} not found` })
                 }
-                const importance = db.calculateImportance(entry_id)
-                const result: Record<string, unknown> = { entry, importance }
+                const { score: importance, breakdown: importanceBreakdown } =
+                    db.calculateImportance(entry_id)
+                const result: Record<string, unknown> = {
+                    entry,
+                    importance,
+                    importanceBreakdown,
+                }
                 if (include_relationships) {
                     result['relationships'] = db.getRelationships(entry_id)
                 }
@@ -1162,8 +1328,13 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
 
                 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`,
                     })
                 }
 
@@ -1238,6 +1409,7 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
                         top_tags: projectTags[p['project_number'] as number] ?? [],
                     })),
                     inactive_projects: inactiveProjects,
+                    inactiveThresholdDays: 7,
                     time_distribution: distribution,
                 })
             },
@@ -1271,13 +1443,29 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
                     })
                 }
 
-                const relationship = db.linkEntries(
-                    input.from_entry_id,
-                    input.to_entry_id,
-                    input.relationship_type as RelationshipType,
-                    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 as RelationshipType,
+                        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',
+                    })
+                }
             },
         },
         {
@@ -1316,6 +1504,19 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
                 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(
                         `
@@ -1378,8 +1579,12 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
 
                 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',
                     })
                 }
 
@@ -1569,8 +1774,18 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
                 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
                     })
@@ -2146,6 +2361,10 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
                 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()
@@ -2179,6 +2398,7 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
                         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(),
@@ -2212,7 +2432,8 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
                     input.title,
                     input.body,
                     input.labels,
-                    input.assignees
+                    input.assignees,
+                    input.milestone_number
                 )
 
                 if (!issue) {
@@ -2540,6 +2761,458 @@ function getAllToolDefinitions(context: ToolContext): ToolDefinition[] {
                 }
             },
         },
+        // 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: unknown) => {
+                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: unknown) => {
+                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: unknown) => {
+                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: unknown) => {
+                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: unknown) => {
+                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: unknown) => {
+                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: Record<string, any> = {
+                    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',