issue-scribe-mcp 1.2.0 → 1.3.0

package/src/lib/env.ts

@@ -0,0 +1,15 @@
+import "dotenv/config";
+
+import { ToolValidationError } from "./errors.js";
+
+export function getGithubToken(): string {
+    const token = process.env.GITHUB_TOKEN;
+    if (!token) {
+        throw new ToolValidationError(
+            "GITHUB_TOKEN environment variable is required. Set it via env or .env file.",
+            500
+        );
+    }
+
+    return token;
+}

package/src/lib/errors.ts

@@ -0,0 +1,64 @@
+import { ZodError } from "zod";
+
+export class ToolValidationError extends Error {
+    public readonly status: number;
+
+    public constructor(message: string, status = 400) {
+        super(message);
+        this.name = "ToolValidationError";
+        this.status = status;
+    }
+}
+
+type ErrorWithMetadata = Error & {
+    status?: number;
+    response?: {
+        headers?: Record<string, string | number | undefined>;
+        data?: unknown;
+    };
+};
+
+function isErrorWithMetadata(error: unknown): error is ErrorWithMetadata {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+
+    return true;
+}
+
+export function buildErrorPayload(error: unknown, detail: string): Record<string, unknown> {
+    if (error instanceof ZodError) {
+        return {
+            error: "Invalid parameters",
+            status: 400,
+            detail,
+            validation_issues: error.issues,
+        };
+    }
+
+    if (isErrorWithMetadata(error)) {
+        const payload: Record<string, unknown> = {
+            error: error.message,
+            status: error.status,
+            detail,
+        };
+
+        const headers = error.response?.headers;
+        const rateLimitRemaining = headers?.["x-ratelimit-remaining"];
+        const rateLimitReset = headers?.["x-ratelimit-reset"];
+
+        if (rateLimitRemaining !== undefined || rateLimitReset !== undefined) {
+            payload.rate_limit = {
+                remaining: rateLimitRemaining,
+                reset: rateLimitReset,
+            };
+        }
+
+        return payload;
+    }
+
+    return {
+        error: "Unknown error",
+        detail,
+    };
+}

package/src/lib/octokit.ts

@@ -0,0 +1,17 @@
+import { Octokit } from "@octokit/rest";
+
+import { getGithubToken } from "./env.js";
+import { SERVER_VERSION } from "./version.js";
+
+let octokitInstance: Octokit | null = null;
+
+export function getOctokit(): Octokit {
+    if (!octokitInstance) {
+        octokitInstance = new Octokit({
+            auth: getGithubToken(),
+            userAgent: `issue-scribe-mcp/${SERVER_VERSION}`,
+        });
+    }
+
+    return octokitInstance;
+}

package/src/lib/pagination.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+
+export const PaginationSchema = z.object({
+    page: z.number().int().min(1).optional(),
+    per_page: z.number().int().min(1).max(100).optional(),
+    fetch_all: z.boolean().optional(),
+});
+
+export interface PaginationOptions {
+    page: number;
+    perPage: number;
+    fetchAll: boolean;
+}
+
+export interface PaginationResult<T> {
+    items: T[];
+    page: number;
+    per_page: number;
+    fetch_all: boolean;
+    pages_fetched: number;
+}
+
+export function resolvePagination(
+    pagination: { page?: number; per_page?: number; fetch_all?: boolean },
+    defaults?: Partial<PaginationOptions>
+): PaginationOptions {
+    return {
+        page: pagination.page ?? defaults?.page ?? 1,
+        perPage: pagination.per_page ?? defaults?.perPage ?? 30,
+        fetchAll: pagination.fetch_all ?? defaults?.fetchAll ?? false,
+    };
+}
+
+export async function collectPaginated<T>(
+    options: PaginationOptions,
+    fetchPage: (page: number, perPage: number) => Promise<T[]>
+): Promise<PaginationResult<T>> {
+    if (!options.fetchAll) {
+        const items = await fetchPage(options.page, options.perPage);
+        return {
+            items,
+            page: options.page,
+            per_page: options.perPage,
+            fetch_all: false,
+            pages_fetched: 1,
+        };
+    }
+
+    const allItems: T[] = [];
+    let currentPage = options.page;
+    let pagesFetched = 0;
+
+    while (true) {
+        const pageItems = await fetchPage(currentPage, options.perPage);
+        allItems.push(...pageItems);
+        pagesFetched += 1;
+
+        if (pageItems.length < options.perPage) {
+            break;
+        }
+
+        currentPage += 1;
+    }
+
+    return {
+        items: allItems,
+        page: options.page,
+        per_page: options.perPage,
+        fetch_all: true,
+        pages_fetched: pagesFetched,
+    };
+}

package/src/lib/response.ts

@@ -0,0 +1,42 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { z } from "zod";
+
+import { buildErrorPayload } from "./errors.js";
+
+export function success(data: unknown): CallToolResult {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+
+export function failure(error: unknown, detail: string): CallToolResult {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(buildErrorPayload(error, detail), null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+
+export async function executeTool<T>(
+    rawArgs: unknown,
+    schema: z.ZodType<T>,
+    detail: string,
+    run: (args: T) => Promise<unknown>
+): Promise<CallToolResult> {
+    try {
+        const parsedArgs = schema.parse(rawArgs);
+        const payload = await run(parsedArgs);
+        return success(payload);
+    } catch (error: unknown) {
+        return failure(error, detail);
+    }
+}

package/src/lib/safety.ts

@@ -0,0 +1,25 @@
+import { ToolValidationError } from "./errors.js";
+
+export const CONFIRM_TOKEN_VALUE = "CONFIRM";
+
+export function assertConfirmation(confirmToken: string | undefined, actionLabel: string): void {
+    if (confirmToken !== CONFIRM_TOKEN_VALUE) {
+        throw new ToolValidationError(
+            `${actionLabel} requires confirm_token=\"${CONFIRM_TOKEN_VALUE}\". Use dry_run=true to preview without executing.`,
+            400
+        );
+    }
+}
+
+export function assertExpectedValue(
+    expectedValue: string | undefined,
+    actualValue: string,
+    valueName: string
+): void {
+    if (expectedValue && expectedValue !== actualValue) {
+        throw new ToolValidationError(
+            `${valueName} mismatch. expected=${expectedValue}, actual=${actualValue}`,
+            409
+        );
+    }
+}

package/src/lib/search.ts

@@ -0,0 +1,52 @@
+export interface RepositorySearchQueryOptions {
+    owner: string;
+    repo: string;
+    kind: "issue" | "pr";
+    state?: "open" | "closed" | "all";
+    query?: string;
+    labels?: string[];
+    qualifiers?: string[];
+}
+
+export function buildRepositorySearchQuery(options: RepositorySearchQueryOptions): string {
+    const parts: string[] = [];
+
+    if (options.query && options.query.trim()) {
+        parts.push(options.query.trim());
+    }
+
+    parts.push(`repo:${options.owner}/${options.repo}`);
+    parts.push(`is:${options.kind}`);
+
+    if (options.state && options.state !== "all") {
+        parts.push(`is:${options.state}`);
+    }
+
+    for (const label of options.labels ?? []) {
+        parts.push(`label:\"${label}\"`);
+    }
+
+    for (const qualifier of options.qualifiers ?? []) {
+        if (qualifier.trim()) {
+            parts.push(qualifier.trim());
+        }
+    }
+
+    return parts.join(" ");
+}
+
+export function normalizeSearchSort(sort: string | undefined): string | undefined {
+    if (!sort || sort === "best-match") {
+        return undefined;
+    }
+
+    if (sort === "popularity") {
+        return "comments";
+    }
+
+    if (sort === "long-running") {
+        return "updated";
+    }
+
+    return sort;
+}

package/src/lib/version.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = resolve(currentDir, "../../package.json");
+
+let packageVersion = "0.0.0";
+
+try {
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8")) as {
+        version?: string;
+    };
+    packageVersion = packageJson.version ?? packageVersion;
+} catch {
+    packageVersion = "0.0.0";
+}
+
+export const SERVER_VERSION = packageVersion;

package/src/tools/branches.ts

@@ -0,0 +1,287 @@
+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 { assertConfirmation, assertExpectedValue } from "../lib/safety.js";
+import type { ToolRegistration } from "./types.js";
+
+const ListBranchesSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    protected: z.boolean().optional(),
+}).merge(PaginationSchema);
+
+const CreateBranchSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    branch: z.string(),
+    ref: z.string(),
+});
+
+const DeleteBranchSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    branch: z.string(),
+    dry_run: z.boolean().optional(),
+    confirm_token: z.string().optional(),
+    expected_sha: z.string().optional(),
+});
+
+const CompareBranchesSchema = z.object({
+    owner: z.string(),
+    repo: z.string(),
+    base: z.string(),
+    head: z.string(),
+    max_commits: z.number().int().min(1).max(500).optional(),
+    max_files: z.number().int().min(1).max(500).optional(),
+});
+
+export const branchTools: ToolRegistration[] = [
+    {
+        definition: {
+            name: "github_list_branches",
+            description: "List repository branches with pagination",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    protected: { type: "boolean", description: "Filter by protected status (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 (optional, default: false)" },
+                },
+                required: ["owner", "repo"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(
+            rawArgs,
+            ListBranchesSchema,
+            "Failed to list branches",
+            async (args) => {
+                const pagination = resolvePagination(args, {
+                    page: 1,
+                    perPage: 30,
+                    fetchAll: false,
+                });
+
+                const branches = await collectPaginated(pagination, async (page, perPage) => {
+                    const response = await getOctokit().rest.repos.listBranches({
+                        owner: args.owner,
+                        repo: args.repo,
+                        protected: args.protected,
+                        page,
+                        per_page: perPage,
+                    });
+                    return response.data;
+                });
+
+                return {
+                    success: true,
+                    count: branches.items.length,
+                    branches: branches.items.map((branch) => ({
+                        name: branch.name,
+                        commit: {
+                            sha: branch.commit.sha,
+                            url: branch.commit.url,
+                        },
+                        protected: branch.protected,
+                    })),
+                    pagination: {
+                        page: branches.page,
+                        per_page: branches.per_page,
+                        fetch_all: branches.fetch_all,
+                        pages_fetched: branches.pages_fetched,
+                    },
+                };
+            }
+        ),
+    },
+    {
+        definition: {
+            name: "github_create_branch",
+            description: "Create a new branch from an existing branch or commit SHA",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    branch: { type: "string", description: "New branch name" },
+                    ref: { type: "string", description: "Source branch name or commit SHA" },
+                },
+                required: ["owner", "repo", "branch", "ref"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(
+            rawArgs,
+            CreateBranchSchema,
+            "Failed to create branch",
+            async (args) => {
+                let sha: string;
+
+                try {
+                    const branchRef = await getOctokit().rest.git.getRef({
+                        owner: args.owner,
+                        repo: args.repo,
+                        ref: `heads/${args.ref}`,
+                    });
+                    sha = branchRef.data.object.sha;
+                } catch {
+                    const commit = await getOctokit().rest.git.getCommit({
+                        owner: args.owner,
+                        repo: args.repo,
+                        commit_sha: args.ref,
+                    });
+                    sha = commit.data.sha;
+                }
+
+                const newBranch = await getOctokit().rest.git.createRef({
+                    owner: args.owner,
+                    repo: args.repo,
+                    ref: `refs/heads/${args.branch}`,
+                    sha,
+                });
+
+                return {
+                    success: true,
+                    branch: {
+                        name: args.branch,
+                        ref: newBranch.data.ref,
+                        sha: newBranch.data.object.sha,
+                        url: newBranch.data.url,
+                    },
+                    message: `Branch \"${args.branch}\" created successfully from \"${args.ref}\"`,
+                };
+            }
+        ),
+    },
+    {
+        definition: {
+            name: "github_delete_branch",
+            description: "Delete a branch with dry-run, expected SHA check, and confirmation safeguards",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    branch: { type: "string", description: "Branch name to delete" },
+                    dry_run: { type: "boolean", description: "Preview deletion without executing (optional, default: false)" },
+                    expected_sha: { type: "string", description: "Optional guard: branch HEAD SHA must match this value" },
+                    confirm_token: { type: "string", description: "Must be \"CONFIRM\" to execute delete when dry_run=false" },
+                },
+                required: ["owner", "repo", "branch"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(
+            rawArgs,
+            DeleteBranchSchema,
+            "Failed to delete branch",
+            async (args) => {
+                const refData = await getOctokit().rest.git.getRef({
+                    owner: args.owner,
+                    repo: args.repo,
+                    ref: `heads/${args.branch}`,
+                });
+                const currentSha = refData.data.object.sha;
+
+                assertExpectedValue(args.expected_sha, currentSha, "branch head sha");
+
+                if (args.dry_run ?? false) {
+                    return {
+                        success: true,
+                        dry_run: true,
+                        action: "delete_branch",
+                        target: {
+                            branch: args.branch,
+                            current_sha: currentSha,
+                        },
+                        message: "Dry run only. No deletion executed.",
+                    };
+                }
+
+                assertConfirmation(args.confirm_token, "Branch deletion");
+
+                await getOctokit().rest.git.deleteRef({
+                    owner: args.owner,
+                    repo: args.repo,
+                    ref: `heads/${args.branch}`,
+                });
+
+                return {
+                    success: true,
+                    dry_run: false,
+                    message: `Branch \"${args.branch}\" deleted successfully from ${args.owner}/${args.repo}`,
+                };
+            }
+        ),
+    },
+    {
+        definition: {
+            name: "github_compare_branches",
+            description: "Compare two branches and return commit/file differences",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    owner: { type: "string", description: "Repository owner" },
+                    repo: { type: "string", description: "Repository name" },
+                    base: { type: "string", description: "Base branch" },
+                    head: { type: "string", description: "Head branch to compare" },
+                    max_commits: { type: "number", description: "Max commits to include in response (optional, default: 250)" },
+                    max_files: { type: "number", description: "Max files to include in response (optional, default: 250)" },
+                },
+                required: ["owner", "repo", "base", "head"],
+            },
+        },
+        handler: async (rawArgs) => executeTool(
+            rawArgs,
+            CompareBranchesSchema,
+            "Failed to compare branches",
+            async (args) => {
+                const comparison = await getOctokit().rest.repos.compareCommits({
+                    owner: args.owner,
+                    repo: args.repo,
+                    base: args.base,
+                    head: args.head,
+                });
+
+                const maxCommits = args.max_commits ?? 250;
+                const maxFiles = args.max_files ?? 250;
+                const commits = comparison.data.commits.slice(0, maxCommits);
+                const files = (comparison.data.files ?? []).slice(0, maxFiles);
+
+                return {
+                    success: true,
+                    comparison: {
+                        status: comparison.data.status,
+                        ahead_by: comparison.data.ahead_by,
+                        behind_by: comparison.data.behind_by,
+                        total_commits: comparison.data.total_commits,
+                        base_commit: {
+                            sha: comparison.data.base_commit.sha,
+                            message: comparison.data.base_commit.commit.message,
+                        },
+                        commits: commits.map((commit) => ({
+                            sha: commit.sha,
+                            message: commit.commit.message,
+                            author: commit.commit.author?.name,
+                            date: commit.commit.author?.date,
+                        })),
+                        files: files.map((file) => ({
+                            filename: file.filename,
+                            status: file.status,
+                            additions: file.additions,
+                            deletions: file.deletions,
+                            changes: file.changes,
+                        })),
+                        truncated: {
+                            commits: comparison.data.commits.length > maxCommits,
+                            files: (comparison.data.files?.length ?? 0) > maxFiles,
+                        },
+                    },
+                    message: `Comparing ${args.base}...${args.head}: ${comparison.data.ahead_by} commits ahead, ${comparison.data.behind_by} commits behind`,
+                };
+            }
+        ),
+    },
+];