memory-journal-mcp 4.4.2 → 5.0.0

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

@@ -0,0 +1,328 @@
+/**
+ * GitHub Read Tools - 5 tools
+ *
+ * Tools: get_github_issues, get_github_prs, get_github_issue, get_github_pr, get_github_context
+ */
+
+import { z } from 'zod'
+import type { ToolDefinition, ToolContext } from '../../../types/index.js'
+import type { GitHubIntegration } from '../../../github/GitHubIntegration.js'
+import { formatHandlerError } from '../../../utils/error-helpers.js'
+import {
+    GitHubIssuesListOutputSchema,
+    GitHubIssueResultOutputSchema,
+    GitHubPRsListOutputSchema,
+    GitHubPRResultOutputSchema,
+    GitHubContextOutputSchema,
+} from './schemas.js'
+
+// ============================================================================
+// Helper: owner/repo resolution with "STOP" pattern
+// ============================================================================
+
+async function resolveOwnerRepo(
+    context: ToolContext,
+    input: { owner?: string; repo?: string },
+    entityLabel: 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. You MUST ask the user to provide the GitHub owner and repository name.`,
+                requiresUserInput: true,
+                detectedOwner,
+                detectedRepo,
+                instruction: `Ask the user: "What GitHub repository ${entityLabel}? Please provide the owner and repo name (e.g., owner/repo)."`,
+            },
+        }
+    }
+
+    return { owner, repo, detectedOwner, detectedRepo, github: context.github }
+}
+
+// ============================================================================
+// Tool Definitions
+// ============================================================================
+
+export function getGitHubReadTools(context: ToolContext): ToolDefinition[] {
+    return [
+        {
+            name: 'get_github_issues',
+            title: 'Get GitHub Issues',
+            description:
+                'List issues from a GitHub repository. IMPORTANT: Do NOT guess owner/repo values - leave them empty to auto-detect from the current git repository.',
+            group: 'github',
+            inputSchema: z.object({
+                owner: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'Repository owner - LEAVE EMPTY to auto-detect from git. Only specify if user explicitly provides.'
+                    ),
+                repo: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'Repository name - LEAVE EMPTY to auto-detect from git. Only specify if user explicitly provides.'
+                    ),
+                state: z.string().optional().default('open'),
+                limit: z.number().optional().default(20),
+            }),
+            outputSchema: GitHubIssuesListOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            handler: async (params: unknown) => {
+                try {
+                    const input = z
+                        .object({
+                            owner: z.string().optional(),
+                            repo: z.string().optional(),
+                            state: z.enum(['open', 'closed', 'all']).optional().default('open'),
+                            limit: z.number().optional().default(20),
+                        })
+                        .parse(params)
+
+                    const resolved = await resolveOwnerRepo(
+                        context,
+                        input,
+                        'would you like to query'
+                    )
+                    if ('error' in resolved) return resolved.response
+
+                    const issues = await resolved.github.getIssues(
+                        resolved.owner,
+                        resolved.repo,
+                        input.state,
+                        input.limit
+                    )
+                    return {
+                        owner: resolved.owner,
+                        repo: resolved.repo,
+                        detectedOwner: resolved.detectedOwner,
+                        detectedRepo: resolved.detectedRepo,
+                        issues,
+                        count: issues.length,
+                    }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'get_github_prs',
+            title: 'Get GitHub Pull Requests',
+            description:
+                'List pull requests from a GitHub repository. IMPORTANT: Do NOT guess owner/repo values - leave them empty to auto-detect from the current git repository.',
+            group: 'github',
+            inputSchema: z.object({
+                owner: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'Repository owner - LEAVE EMPTY to auto-detect from git. Only specify if user explicitly provides.'
+                    ),
+                repo: z
+                    .string()
+                    .optional()
+                    .describe(
+                        'Repository name - LEAVE EMPTY to auto-detect from git. Only specify if user explicitly provides.'
+                    ),
+                state: z.string().optional().default('open'),
+                limit: z.number().optional().default(20),
+            }),
+            outputSchema: GitHubPRsListOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            handler: async (params: unknown) => {
+                try {
+                    const input = z
+                        .object({
+                            owner: z.string().optional(),
+                            repo: z.string().optional(),
+                            state: z.enum(['open', 'closed', 'all']).optional().default('open'),
+                            limit: z.number().optional().default(20),
+                        })
+                        .parse(params)
+
+                    const resolved = await resolveOwnerRepo(
+                        context,
+                        input,
+                        'would you like to query'
+                    )
+                    if ('error' in resolved) return resolved.response
+
+                    const pullRequests = await resolved.github.getPullRequests(
+                        resolved.owner,
+                        resolved.repo,
+                        input.state,
+                        input.limit
+                    )
+                    return {
+                        owner: resolved.owner,
+                        repo: resolved.repo,
+                        detectedOwner: resolved.detectedOwner,
+                        detectedRepo: resolved.detectedRepo,
+                        pullRequests,
+                        count: pullRequests.length,
+                    }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'get_github_issue',
+            title: 'Get GitHub Issue Details',
+            description:
+                'Get detailed information about a specific GitHub issue. IMPORTANT: Do NOT guess owner/repo values - leave them empty to auto-detect from the current git repository.',
+            group: 'github',
+            inputSchema: z.object({
+                issue_number: z.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: GitHubIssueResultOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            handler: async (params: unknown) => {
+                try {
+                    const input = z
+                        .object({
+                            issue_number: z.number(),
+                            owner: z.string().optional(),
+                            repo: z.string().optional(),
+                        })
+                        .parse(params)
+
+                    const resolved = await resolveOwnerRepo(context, input, 'is this issue from')
+                    if ('error' in resolved) return resolved.response
+
+                    const issue = await resolved.github.getIssue(
+                        resolved.owner,
+                        resolved.repo,
+                        input.issue_number
+                    )
+                    if (!issue) {
+                        return {
+                            error: `Issue #${String(input.issue_number)} not found`,
+                            owner: resolved.owner,
+                            repo: resolved.repo,
+                            detectedOwner: resolved.detectedOwner,
+                            detectedRepo: resolved.detectedRepo,
+                        }
+                    }
+                    return {
+                        issue,
+                        owner: resolved.owner,
+                        repo: resolved.repo,
+                        detectedOwner: resolved.detectedOwner,
+                        detectedRepo: resolved.detectedRepo,
+                    }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'get_github_pr',
+            title: 'Get GitHub PR Details',
+            description:
+                'Get detailed information about a specific GitHub pull request. IMPORTANT: Do NOT guess owner/repo values - leave them empty to auto-detect from the current git repository.',
+            group: 'github',
+            inputSchema: z.object({
+                pr_number: z.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: GitHubPRResultOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            handler: async (params: unknown) => {
+                try {
+                    const input = z
+                        .object({
+                            pr_number: z.number(),
+                            owner: z.string().optional(),
+                            repo: z.string().optional(),
+                        })
+                        .parse(params)
+
+                    const resolved = await resolveOwnerRepo(context, input, 'is this PR from')
+                    if ('error' in resolved) return resolved.response
+
+                    const pullRequest = await resolved.github.getPullRequest(
+                        resolved.owner,
+                        resolved.repo,
+                        input.pr_number
+                    )
+                    if (!pullRequest) {
+                        return {
+                            error: `PR #${String(input.pr_number)} not found`,
+                            owner: resolved.owner,
+                            repo: resolved.repo,
+                            detectedOwner: resolved.detectedOwner,
+                            detectedRepo: resolved.detectedRepo,
+                        }
+                    }
+                    return {
+                        pullRequest,
+                        owner: resolved.owner,
+                        repo: resolved.repo,
+                        detectedOwner: resolved.detectedOwner,
+                        detectedRepo: resolved.detectedRepo,
+                    }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+        {
+            name: 'get_github_context',
+            title: 'Get GitHub Repository Context',
+            description:
+                'Get current repository context including branch, open issues, and open PRs. Only counts OPEN items (closed items excluded).',
+            group: 'github',
+            inputSchema: z.object({}),
+            outputSchema: GitHubContextOutputSchema,
+            annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+            handler: async (_params: unknown) => {
+                try {
+                    if (!context.github) {
+                        return { error: 'GitHub integration not available' }
+                    }
+
+                    const ctx = await context.github.getRepoContext()
+                    return {
+                        repoName: ctx.repoName,
+                        branch: ctx.branch,
+                        commit: ctx.commit,
+                        remoteUrl: ctx.remoteUrl,
+                        issues: ctx.issues,
+                        pullRequests: ctx.pullRequests,
+                        issueCount: ctx.issues.length,
+                        prCount: ctx.pullRequests.length,
+                    }
+                } catch (err) {
+                    return formatHandlerError(err)
+                }
+            },
+        },
+    ]
+}

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

@@ -0,0 +1,369 @@
+/**
+ * Shared GitHub Output Schemas
+ */
+
+import { z } from 'zod'
+
+// ============================================================================
+// Issue Schemas
+// ============================================================================
+
+export const GitHubIssueOutputSchema = z.object({
+    number: z.number(),
+    title: z.string(),
+    url: z.string(),
+    state: z.enum(['OPEN', 'CLOSED']),
+    milestone: z
+        .object({
+            number: z.number(),
+            title: z.string(),
+        })
+        .nullable()
+        .optional(),
+})
+
+export const GitHubIssueDetailsOutputSchema = GitHubIssueOutputSchema.extend({
+    body: z.string().nullable(),
+    labels: z.array(z.string()),
+    assignees: z.array(z.string()),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    closedAt: z.string().nullable(),
+    commentsCount: z.number(),
+})
+
+export const GitHubIssuesListOutputSchema = z.object({
+    owner: z.string().optional(),
+    repo: z.string().optional(),
+    detectedOwner: z.string().nullable().optional(),
+    detectedRepo: z.string().nullable().optional(),
+    issues: z.array(GitHubIssueOutputSchema).optional(),
+    count: z.number().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+})
+
+export const GitHubIssueResultOutputSchema = z.object({
+    issue: GitHubIssueDetailsOutputSchema.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(),
+})
+
+// ============================================================================
+// PR Schemas
+// ============================================================================
+
+export const GitHubPullRequestOutputSchema = z.object({
+    number: z.number(),
+    title: z.string(),
+    url: z.string(),
+    state: z.enum(['OPEN', 'CLOSED', 'MERGED']),
+})
+
+export const GitHubPRDetailsOutputSchema = GitHubPullRequestOutputSchema.extend({
+    body: z.string().nullable(),
+    draft: z.boolean(),
+    headBranch: z.string(),
+    baseBranch: z.string(),
+    author: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    mergedAt: z.string().nullable(),
+    closedAt: z.string().nullable(),
+    additions: z.number(),
+    deletions: z.number(),
+    changedFiles: z.number(),
+})
+
+export const GitHubPRsListOutputSchema = z.object({
+    owner: z.string().optional(),
+    repo: z.string().optional(),
+    detectedOwner: z.string().nullable().optional(),
+    detectedRepo: z.string().nullable().optional(),
+    pullRequests: z.array(GitHubPullRequestOutputSchema).optional(),
+    count: z.number().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+})
+
+export const GitHubPRResultOutputSchema = z.object({
+    pullRequest: GitHubPRDetailsOutputSchema.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(),
+})
+
+// ============================================================================
+// Context Schema
+// ============================================================================
+
+export const GitHubContextOutputSchema = z.object({
+    repoName: z.string().nullable().optional(),
+    branch: z.string().nullable().optional(),
+    commit: z.string().nullable().optional(),
+    remoteUrl: z.string().nullable().optional(),
+    issues: z.array(GitHubIssueOutputSchema).optional(),
+    pullRequests: z.array(GitHubPullRequestOutputSchema).optional(),
+    issueCount: z.number().optional(),
+    prCount: z.number().optional(),
+    error: z.string().optional(),
+})
+
+// ============================================================================
+// Kanban Schemas
+// ============================================================================
+
+const KanbanItemOutputSchema = z.object({
+    id: z.string(),
+    title: z.string(),
+    url: z.string(),
+    type: z.enum(['ISSUE', 'PULL_REQUEST', 'DRAFT_ISSUE']),
+    status: z.string().nullable(),
+    number: z.number().optional(),
+    labels: z.array(z.string()).optional(),
+    assignees: z.array(z.string()).optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+})
+
+const StatusOptionOutputSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    color: z.string().optional(),
+})
+
+const KanbanColumnOutputSchema = z.object({
+    status: z.string(),
+    statusOptionId: z.string(),
+    items: z.array(KanbanItemOutputSchema),
+})
+
+export const KanbanBoardOutputSchema = z.object({
+    projectId: z.string().optional(),
+    projectNumber: z.number().optional(),
+    projectTitle: z.string().optional(),
+    statusFieldId: z.string().optional(),
+    statusOptions: z.array(StatusOptionOutputSchema).optional(),
+    columns: z.array(KanbanColumnOutputSchema).optional(),
+    totalItems: z.number().optional(),
+    owner: z.string().optional(),
+    detectedOwner: z.string().nullable().optional(),
+    detectedRepo: z.string().nullable().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    hint: z.string().optional(),
+    instruction: z.string().optional(),
+})
+
+export const MoveKanbanItemOutputSchema = z.object({
+    success: z.boolean().optional(),
+    itemId: z.string().optional(),
+    newStatus: z.string().optional(),
+    projectNumber: z.number().optional(),
+    message: z.string().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    hint: z.string().optional(),
+})
+
+// ============================================================================
+// Issue Lifecycle Schemas
+// ============================================================================
+
+export const CreateGitHubIssueWithEntryOutputSchema = z.object({
+    success: z.boolean().optional(),
+    issue: z
+        .object({
+            number: z.number(),
+            title: z.string(),
+            url: z.string(),
+        })
+        .optional(),
+    project: z
+        .object({
+            projectNumber: z.number(),
+            added: z.boolean(),
+            message: z.string(),
+            initialStatus: z
+                .object({
+                    status: z.string(),
+                    set: z.boolean(),
+                })
+                .optional(),
+        })
+        .optional(),
+    journalEntry: z
+        .object({
+            id: z.number(),
+            linkedToIssue: z.number(),
+        })
+        .optional(),
+    message: z.string().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+})
+
+export const CloseGitHubIssueWithEntryOutputSchema = z.object({
+    success: z.boolean().optional(),
+    issue: z
+        .object({
+            number: z.number(),
+            title: z.string(),
+            url: z.string(),
+            previousState: z.string(),
+            newState: z.string(),
+        })
+        .optional(),
+    journalEntry: z
+        .object({
+            id: z.number(),
+            linkedToIssue: z.number(),
+            significanceType: z.string(),
+        })
+        .optional(),
+    kanban: z
+        .object({
+            moved: z.boolean(),
+            projectNumber: z.number(),
+            message: z.string().optional(),
+        })
+        .optional(),
+    message: z.string().optional(),
+    error: z.string().optional(),
+    requiresUserInput: z.boolean().optional(),
+    instruction: z.string().optional(),
+})
+
+// ============================================================================
+// Milestone Schemas
+// ============================================================================
+
+export 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(),
+})
+
+export 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(),
+})
+
+export 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(),
+})
+
+export 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(),
+})
+
+export 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(),
+})
+
+export 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(),
+})
+
+// ============================================================================
+// Insights Schema
+// ============================================================================
+
+export 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(),
+})