issue-scribe-mcp 1.2.0 → 1.3.0

package/dist/tools/comments.js

@@ -0,0 +1,233 @@
+import { z } from "zod";
+import { getOctokit } from "../lib/octokit.js";
+import { executeTool } from "../lib/response.js";
+import { assertConfirmation } from "../lib/safety.js";
+const REACTION_MAP = {
+    thumbs_up: "+1",
+    thumbs_down: "-1",
+    laugh: "laugh",
+    confused: "confused",
+    heart: "heart",
+    hooray: "hooray",
+    rocket: "rocket",
+    eyes: "eyes",
+};
+const AddCommentSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    issue_number: z.number(),
+    body: z.string(),
+});
+const UpdateCommentSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    comment_id: z.number(),
+    body: z.string(),
+});
+const DeleteCommentSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    comment_id: z.number(),
+    dry_run: z.boolean().optional(),
+    confirm_token: z.string().optional(),
+    expected_body_substring: z.string().optional(),
+});
+const AddReactionSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    comment_id: z.number().optional(),
+    issue_number: z.number().optional(),
+    reaction: z.enum(["thumbs_up", "thumbs_down", "laugh", "confused", "heart", "hooray", "rocket", "eyes"]),
+}).refine((data) => Boolean(data.comment_id) !== Boolean(data.issue_number), {
+    message: "Provide exactly one of comment_id or issue_number",
+});
+export const commentTools = [
+    {
+        definition: {
+            name: "github_add_comment",
+            description: "Add a comment to a GitHub issue or pull request",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    issue_number: { type: "number", description: "Issue or PR number" },
+                    body: { type: "string", description: "Comment body" },
+                },
+                required: ["owner", "repo", "issue_number", "body"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(rawArgs, AddCommentSchema, "Failed to add comment", async (args) => {
+            const comment = await getOctokit().rest.issues.createComment({
+                owner: args.owner,
+                repo: args.repo,
+                issue_number: args.issue_number,
+                body: args.body,
+            });
+            return {
+                success: true,
+                comment: {
+                    id: comment.data.id,
+                    body: comment.data.body,
+                    user: comment.data.user?.login,
+                    html_url: comment.data.html_url,
+                    created_at: comment.data.created_at,
+                },
+                message: `Comment added successfully to issue/PR #${args.issue_number}`,
+            };
+        }),
+    },
+    {
+        definition: {
+            name: "github_update_comment",
+            description: "Update an existing GitHub issue/PR comment",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    comment_id: { type: "number", description: "Comment ID" },
+                    body: { type: "string", description: "Updated comment body" },
+                },
+                required: ["owner", "repo", "comment_id", "body"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(rawArgs, UpdateCommentSchema, "Failed to update comment", async (args) => {
+            const comment = await getOctokit().rest.issues.updateComment({
+                owner: args.owner,
+                repo: args.repo,
+                comment_id: args.comment_id,
+                body: args.body,
+            });
+            return {
+                success: true,
+                comment: {
+                    id: comment.data.id,
+                    body: comment.data.body,
+                    user: comment.data.user?.login,
+                    html_url: comment.data.html_url,
+                    updated_at: comment.data.updated_at,
+                },
+                message: `Comment #${args.comment_id} updated successfully`,
+            };
+        }),
+    },
+    {
+        definition: {
+            name: "github_delete_comment",
+            description: "Delete a comment with dry-run and confirmation safeguards",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    comment_id: { type: "number", description: "Comment ID to delete" },
+                    dry_run: { type: "boolean", description: "Preview deletion without executing (optional, default: false)" },
+                    confirm_token: { type: "string", description: "Must be \"CONFIRM\" to execute delete when dry_run=false" },
+                    expected_body_substring: { type: "string", description: "Optional guard: comment must include this substring" },
+                },
+                required: ["owner", "repo", "comment_id"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(rawArgs, DeleteCommentSchema, "Failed to delete comment", async (args) => {
+            const comment = await getOctokit().rest.issues.getComment({
+                owner: args.owner,
+                repo: args.repo,
+                comment_id: args.comment_id,
+            });
+            if (args.expected_body_substring && !comment.data.body?.includes(args.expected_body_substring)) {
+                return {
+                    success: false,
+                    dry_run: true,
+                    message: "Comment body guard check failed. Deletion skipped.",
+                    expected_body_substring: args.expected_body_substring,
+                    current_comment_preview: comment.data.body?.slice(0, 200) ?? "",
+                };
+            }
+            if (args.dry_run ?? false) {
+                return {
+                    success: true,
+                    dry_run: true,
+                    action: "delete_comment",
+                    target: {
+                        comment_id: args.comment_id,
+                        html_url: comment.data.html_url,
+                        body_preview: comment.data.body?.slice(0, 200) ?? "",
+                    },
+                    message: "Dry run only. No deletion executed.",
+                };
+            }
+            assertConfirmation(args.confirm_token, "Comment deletion");
+            await getOctokit().rest.issues.deleteComment({
+                owner: args.owner,
+                repo: args.repo,
+                comment_id: args.comment_id,
+            });
+            return {
+                success: true,
+                dry_run: false,
+                message: `Comment #${args.comment_id} deleted successfully`,
+            };
+        }),
+    },
+    {
+        definition: {
+            name: "github_add_reaction",
+            description: "Add a reaction to an issue/PR or to a specific comment",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    comment_id: { type: "number", description: "Comment ID target (optional)" },
+                    issue_number: { type: "number", description: "Issue/PR number target (optional)" },
+                    reaction: {
+                        type: "string",
+                        enum: ["thumbs_up", "thumbs_down", "laugh", "confused", "heart", "hooray", "rocket", "eyes"],
+                        description: "Reaction type",
+                    },
+                },
+                required: ["owner", "repo", "reaction"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(rawArgs, AddReactionSchema, "Failed to add reaction", async (args) => {
+            const reactionContent = REACTION_MAP[args.reaction] ?? args.reaction;
+            if (args.comment_id) {
+                const reaction = await getOctokit().rest.reactions.createForIssueComment({
+                    owner: args.owner,
+                    repo: args.repo,
+                    comment_id: args.comment_id,
+                    content: reactionContent,
+                });
+                return {
+                    success: true,
+                    target: `comment #${args.comment_id}`,
+                    reaction: {
+                        id: reaction.data.id,
+                        content: reaction.data.content,
+                        user: reaction.data.user?.login,
+                        created_at: reaction.data.created_at,
+                    },
+                    message: `Reaction \"${args.reaction}\" added to comment #${args.comment_id}`,
+                };
+            }
+            const reaction = await getOctokit().rest.reactions.createForIssue({
+                owner: args.owner,
+                repo: args.repo,
+                issue_number: args.issue_number,
+                content: reactionContent,
+            });
+            return {
+                success: true,
+                target: `issue/PR #${args.issue_number}`,
+                reaction: {
+                    id: reaction.data.id,
+                    content: reaction.data.content,
+                    user: reaction.data.user?.login,
+                    created_at: reaction.data.created_at,
+                },
+                message: `Reaction \"${args.reaction}\" added to issue/PR #${args.issue_number}`,
+            };
+        }),
+    },
+];

package/dist/tools/index.js

@@ -0,0 +1,29 @@
+import { ToolValidationError } from "../lib/errors.js";
+import { failure } from "../lib/response.js";
+import { branchTools } from "./branches.js";
+import { commentTools } from "./comments.js";
+import { issueTools } from "./issues.js";
+import { labelTools } from "./labels.js";
+import { pullRequestTools } from "./pull-requests.js";
+const toolRegistry = [
+    ...issueTools,
+    ...pullRequestTools,
+    ...commentTools,
+    ...labelTools,
+    ...branchTools,
+];
+const toolMap = new Map(toolRegistry.map((tool) => [tool.definition.name, tool.handler]));
+export const toolDefinitions = toolRegistry.map((tool) => tool.definition);
+export const toolCount = toolDefinitions.length;
+export async function dispatchTool(name, args) {
+    const handler = toolMap.get(name);
+    if (!handler) {
+        return failure(new ToolValidationError(`Unknown tool: ${name}`, 404), `Unknown tool requested: ${name}`);
+    }
+    try {
+        return await handler(args);
+    }
+    catch (error) {
+        return failure(error, `Unexpected error while executing tool: ${name}`);
+    }
+}

package/dist/tools/issues.js

@@ -0,0 +1,393 @@
+import { z } from "zod";
+import { getOctokit } from "../lib/octokit.js";
+import { collectPaginated, PaginationSchema, resolvePagination } from "../lib/pagination.js";
+import { executeTool } from "../lib/response.js";
+import { buildRepositorySearchQuery, normalizeSearchSort } from "../lib/search.js";
+const IssueContextSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    issue_number: z.number(),
+    comments_page: z.number().int().min(1).optional(),
+    comments_per_page: z.number().int().min(1).max(100).optional(),
+    comments_fetch_all: z.boolean().optional(),
+});
+const CreateIssueSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    title: z.string(),
+    body: z.string().optional(),
+    labels: z.array(z.string()).optional(),
+    assignees: z.array(z.string()).optional(),
+});
+const UpdateIssueSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    issue_number: z.number(),
+    title: z.string().optional(),
+    body: z.string().optional(),
+    state: z.enum(["open", "closed"]).optional(),
+    labels: z.array(z.string()).optional(),
+    assignees: z.array(z.string()).optional(),
+});
+const SearchIssuesSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    query: z.string().optional(),
+    state: z.enum(["open", "closed", "all"]).optional(),
+    labels: z.array(z.string()).optional(),
+    qualifiers: z.array(z.string()).optional(),
+    sort: z.enum(["created", "updated", "comments", "best-match"]).optional(),
+    direction: z.enum(["asc", "desc"]).optional(),
+}).merge(PaginationSchema);
+const ListRecentIssuesSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    state: z.enum(["open", "closed", "all"]).optional(),
+    sort: z.enum(["created", "updated", "comments"]).optional(),
+    direction: z.enum(["asc", "desc"]).optional(),
+}).merge(PaginationSchema);
+async function searchIssuesWithPagination(args) {
+    const pagination = resolvePagination(args, {
+        page: 1,
+        perPage: 30,
+        fetchAll: false,
+    });
+    const q = buildRepositorySearchQuery({
+        owner: args.owner,
+        repo: args.repo,
+        kind: "issue",
+        state: args.state,
+        query: args.query,
+        labels: args.labels,
+        qualifiers: args.qualifiers,
+    });
+    const sort = normalizeSearchSort(args.sort);
+    const order = args.direction;
+    if (!pagination.fetchAll) {
+        const response = await getOctokit().rest.search.issuesAndPullRequests({
+            q,
+            sort: sort,
+            order: order,
+            page: pagination.page,
+            per_page: pagination.perPage,
+        });
+        const issues = response.data.items.filter((item) => !("pull_request" in item));
+        return {
+            query: q,
+            total_count: response.data.total_count,
+            incomplete_results: response.data.incomplete_results,
+            page: pagination.page,
+            per_page: pagination.perPage,
+            fetch_all: false,
+            count: issues.length,
+            issues: issues.map((issue) => ({
+                number: issue.number,
+                title: issue.title,
+                state: issue.state,
+                user: issue.user?.login,
+                labels: issue.labels,
+                comments: issue.comments,
+                created_at: issue.created_at,
+                updated_at: issue.updated_at,
+                html_url: issue.html_url,
+                score: issue.score,
+            })),
+        };
+    }
+    const allItems = [];
+    let page = pagination.page;
+    let totalCount = 0;
+    let incompleteResults = false;
+    while (true) {
+        const response = await getOctokit().rest.search.issuesAndPullRequests({
+            q,
+            sort: sort,
+            order: order,
+            page,
+            per_page: pagination.perPage,
+        });
+        if (page === pagination.page) {
+            totalCount = response.data.total_count;
+            incompleteResults = response.data.incomplete_results;
+        }
+        allItems.push(...response.data.items);
+        if (response.data.items.length < pagination.perPage) {
+            break;
+        }
+        if (allItems.length >= 1000) {
+            break;
+        }
+        page += 1;
+    }
+    const issues = allItems.filter((item) => !("pull_request" in item));
+    return {
+        query: q,
+        total_count: totalCount,
+        incomplete_results: incompleteResults,
+        page: pagination.page,
+        per_page: pagination.perPage,
+        fetch_all: true,
+        pages_fetched: page - pagination.page + 1,
+        count: issues.length,
+        issues: issues.map((issue) => ({
+            number: issue.number,
+            title: issue.title,
+            state: issue.state,
+            user: issue.user?.login,
+            labels: issue.labels,
+            comments: issue.comments,
+            created_at: issue.created_at,
+            updated_at: issue.updated_at,
+            html_url: issue.html_url,
+            score: issue.score,
+        })),
+    };
+}
+export const issueTools = [
+    {
+        definition: {
+            name: "github_get_issue_context",
+            description: "Get GitHub Issue context including metadata, reactions, and paginated comments",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    issue_number: { type: "number", description: "Issue number" },
+                    comments_page: { type: "number", description: "Comments page number (optional, default: 1)" },
+                    comments_per_page: { type: "number", description: "Comments per page, max 100 (optional, default: 100)" },
+                    comments_fetch_all: { type: "boolean", description: "Fetch all comment pages (optional, default: true)" },
+                },
+                required: ["owner", "repo", "issue_number"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(rawArgs, IssueContextSchema, "Failed to fetch issue context", async (args) => {
+            const issue = await getOctokit().rest.issues.get({
+                owner: args.owner,
+                repo: args.repo,
+                issue_number: args.issue_number,
+            });
+            const commentPagination = resolvePagination({
+                page: args.comments_page,
+                per_page: args.comments_per_page,
+                fetch_all: args.comments_fetch_all,
+            }, {
+                page: 1,
+                perPage: 100,
+                fetchAll: true,
+            });
+            const commentsResult = await collectPaginated(commentPagination, async (page, perPage) => {
+                const comments = await getOctokit().rest.issues.listComments({
+                    owner: args.owner,
+                    repo: args.repo,
+                    issue_number: args.issue_number,
+                    page,
+                    per_page: perPage,
+                });
+                return comments.data;
+            });
+            return {
+                issue: {
+                    number: issue.data.number,
+                    title: issue.data.title,
+                    body: issue.data.body,
+                    state: issue.data.state,
+                    user: issue.data.user?.login,
+                    assignees: issue.data.assignees?.map((assignee) => assignee.login),
+                    milestone: issue.data.milestone
+                        ? {
+                            title: issue.data.milestone.title,
+                            due_on: issue.data.milestone.due_on,
+                        }
+                        : null,
+                    labels: issue.data.labels.map((label) => (typeof label === "string" ? label : label.name)),
+                    reactions: issue.data.reactions,
+                    created_at: issue.data.created_at,
+                    updated_at: issue.data.updated_at,
+                    html_url: issue.data.html_url,
+                },
+                comments: commentsResult.items.map((comment) => ({
+                    id: comment.id,
+                    user: comment.user?.login,
+                    body: comment.body,
+                    reactions: comment.reactions,
+                    created_at: comment.created_at,
+                    updated_at: comment.updated_at,
+                    html_url: comment.html_url,
+                })),
+                comments_pagination: {
+                    page: commentsResult.page,
+                    per_page: commentsResult.per_page,
+                    fetch_all: commentsResult.fetch_all,
+                    pages_fetched: commentsResult.pages_fetched,
+                    count: commentsResult.items.length,
+                },
+            };
+        }),
+    },
+    {
+        definition: {
+            name: "github_create_issue",
+            description: "Create a new GitHub issue",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    title: { type: "string", description: "Issue title" },
+                    body: { type: "string", description: "Issue body (optional)" },
+                    labels: { type: "array", items: { type: "string" }, description: "Labels (optional)" },
+                    assignees: { type: "array", items: { type: "string" }, description: "Assignees (optional)" },
+                },
+                required: ["owner", "repo", "title"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(rawArgs, CreateIssueSchema, "Failed to create issue", async (args) => {
+            const issue = await getOctokit().rest.issues.create({
+                owner: args.owner,
+                repo: args.repo,
+                title: args.title,
+                body: args.body,
+                labels: args.labels,
+                assignees: args.assignees,
+            });
+            return {
+                success: true,
+                issue: {
+                    number: issue.data.number,
+                    title: issue.data.title,
+                    state: issue.data.state,
+                    html_url: issue.data.html_url,
+                    created_at: issue.data.created_at,
+                },
+                message: `Issue #${issue.data.number} created successfully`,
+            };
+        }),
+    },
+    {
+        definition: {
+            name: "github_update_issue",
+            description: "Update an existing GitHub issue",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    issue_number: { type: "number", description: "Issue number" },
+                    title: { type: "string", description: "New title (optional)" },
+                    body: { type: "string", description: "New body (optional)" },
+                    state: { type: "string", enum: ["open", "closed"], description: "Issue state (optional)" },
+                    labels: { type: "array", items: { type: "string" }, description: "New labels (optional)" },
+                    assignees: { type: "array", items: { type: "string" }, description: "New assignees (optional)" },
+                },
+                required: ["owner", "repo", "issue_number"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(rawArgs, UpdateIssueSchema, "Failed to update issue", async (args) => {
+            const issue = await getOctokit().rest.issues.update({
+                owner: args.owner,
+                repo: args.repo,
+                issue_number: args.issue_number,
+                title: args.title,
+                body: args.body,
+                state: args.state,
+                labels: args.labels,
+                assignees: args.assignees,
+            });
+            return {
+                success: true,
+                issue: {
+                    number: issue.data.number,
+                    title: issue.data.title,
+                    state: issue.data.state,
+                    html_url: issue.data.html_url,
+                    updated_at: issue.data.updated_at,
+                },
+                message: `Issue #${issue.data.number} updated successfully`,
+            };
+        }),
+    },
+    {
+        definition: {
+            name: "github_search_issues",
+            description: "Search repository issues using GitHub Search API and optional qualifiers",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    query: { type: "string", description: "Search text (optional)" },
+                    state: { type: "string", enum: ["open", "closed", "all"], description: "Issue state (optional)" },
+                    labels: { type: "array", items: { type: "string" }, description: "Filter by labels (optional)" },
+                    qualifiers: { type: "array", items: { type: "string" }, description: "Extra GitHub search qualifiers like author:foo (optional)" },
+                    sort: { type: "string", enum: ["created", "updated", "comments", "best-match"], description: "Sort strategy (optional)" },
+                    direction: { type: "string", enum: ["asc", "desc"], description: "Sort direction (optional)" },
+                    page: { type: "number", description: "Page number (optional, default: 1)" },
+                    per_page: { type: "number", description: "Results per page, max 100 (optional, default: 30)" },
+                    fetch_all: { type: "boolean", description: "Fetch all pages up to GitHub search limit (optional, default: false)" },
+                },
+                required: ["owner", "repo"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(rawArgs, SearchIssuesSchema, "Failed to search issues", async (args) => searchIssuesWithPagination(args)),
+    },
+    {
+        definition: {
+            name: "github_list_recent_issues",
+            description: "List recent repository issues with pagination support",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    state: { type: "string", enum: ["open", "closed", "all"], description: "Issue state (optional, default: open)" },
+                    sort: { type: "string", enum: ["created", "updated", "comments"], description: "Sort field (optional, default: created)" },
+                    direction: { type: "string", enum: ["asc", "desc"], description: "Sort direction (optional, default: desc)" },
+                    page: { type: "number", description: "Page number (optional, default: 1)" },
+                    per_page: { type: "number", description: "Results per page, max 100 (optional, default: 30)" },
+                    fetch_all: { type: "boolean", description: "Fetch all pages (optional, default: false)" },
+                },
+                required: ["owner", "repo"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(rawArgs, ListRecentIssuesSchema, "Failed to list recent issues", async (args) => {
+            const pagination = resolvePagination(args, {
+                page: 1,
+                perPage: 30,
+                fetchAll: false,
+            });
+            const issues = await collectPaginated(pagination, async (page, perPage) => {
+                const response = await getOctokit().rest.issues.listForRepo({
+                    owner: args.owner,
+                    repo: args.repo,
+                    state: args.state ?? "open",
+                    sort: args.sort ?? "created",
+                    direction: args.direction ?? "desc",
+                    page,
+                    per_page: perPage,
+                });
+                return response.data.filter((issue) => !issue.pull_request);
+            });
+            return {
+                count: issues.items.length,
+                issues: issues.items.map((issue) => ({
+                    number: issue.number,
+                    title: issue.title,
+                    state: issue.state,
+                    user: issue.user?.login,
+                    labels: issue.labels.map((label) => (typeof label === "string" ? label : label.name)),
+                    created_at: issue.created_at,
+                    updated_at: issue.updated_at,
+                    comments: issue.comments,
+                    html_url: issue.html_url,
+                })),
+                pagination: {
+                    page: issues.page,
+                    per_page: issues.per_page,
+                    fetch_all: issues.fetch_all,
+                    pages_fetched: issues.pages_fetched,
+                },
+            };
+        }),
+    },
+];