github/build_url

Instructions

Implementation Reference

• src/server.ts:120-145 (handler)

  The main handler function 'buildGitHubUrl' that executes the tool logic: builds GitHub URL and validates repository status.

  export const buildGitHubUrl = async (args: { owner: string; repo: string }) => {
    const { owner, repo } = args;
  
    // Basic validation
    if (!owner.trim() || !repo.trim()) {
      throw new Error("Owner and repository name cannot be empty");
    }
  
    const url = `https://github.com/${owner}/${repo}`;
    const validation = await validateRepository(owner, repo);
  
    switch (validation.status) {
      case "error": {
        const errorInfo = validation.error ? ` (${validation.error})` : "";
        return `${url}\n\n❌ Error: Unable to verify repository${errorInfo}`;
      }
      case "not_found":
        return `${url}\n\n⚠️ Warning: Repository does not exist`;
      case "private":
        return `${url}\n\n🔒 Note: Repository exists but is private`;
      case "public":
        return url;
      default:
        return url;
    }
  };

• src/server.ts:204-216 (schema)

  Zod input schema defining 'owner' and 'repo' parameters with validation rules and descriptions.

    parameters: z.object({
      owner: z
        .string()
        .min(1, "Owner cannot be empty")
        .describe(
          "GitHub username or organization name (e.g., 'microsoft', 'facebook')",
        ),
      repo: z
        .string()
        .min(1, "Repository name cannot be empty")
        .describe("Repository name (e.g., 'vscode', 'react')"),
    }),
  });

• src/server.ts:194-216 (registration)

  Tool registration via server.addTool, specifying name 'github/build_url', handler, schema, description, and annotations.

  server.addTool({
    annotations: {
      openWorldHint: false, // No external system interaction beyond validation
      readOnlyHint: true, // Does not modify any data
      title: "Build GitHub URL",
    },
    description:
      "Converts GitHub owner and repository name into a properly formatted GitHub URL with validation",
    execute: buildGitHubUrl,
    name: "github/build_url",
    parameters: z.object({
      owner: z
        .string()
        .min(1, "Owner cannot be empty")
        .describe(
          "GitHub username or organization name (e.g., 'microsoft', 'facebook')",
        ),
      repo: z
        .string()
        .min(1, "Repository name cannot be empty")
        .describe("Repository name (e.g., 'vscode', 'react')"),
    }),
  });

• src/server.ts:13-76 (helper)

  Helper function 'validateRepository' that checks repository existence and accessibility via HEAD requests to GitHub, distinguishing public/private/not_found/error statuses. Used by the tool handler.

  const validateRepository = async (
    owner: string,
    repo: string,
  ): Promise<{
    error?: string;
    exists: boolean;
    isPrivate?: boolean;
    status: "error" | "not_found" | "private" | "public";
  }> => {
    try {
      const response = await fetch(`https://github.com/${owner}/${repo}`, {
        method: "HEAD",
        // Add timeout to prevent hanging
        signal: AbortSignal.timeout(5000),
      });
  
      if (response.status === 200) {
        return {
          exists: true,
          isPrivate: false,
          status: "public",
        };
      } else if (response.status === 404) {
        // 404 can mean either the repo doesn't exist or it's private
        // Try to access the owner's profile to distinguish
        const ownerResponse = await fetch(`https://github.com/${owner}`, {
          method: "HEAD",
          signal: AbortSignal.timeout(5000),
        });
  
        if (ownerResponse.status === 200) {
          // Owner exists, so the repo is likely private
          return {
            exists: true,
            isPrivate: true,
            status: "private",
          };
        } else {
          // Owner doesn't exist, so repo doesn't exist
          return {
            exists: false,
            status: "not_found",
          };
        }
      } else {
        // Other status codes (403, 500, etc.)
        return {
          error: `HTTP ${response.status}`,
          exists: false,
          status: "error",
        };
      }
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : "Unknown error";
      return {
        error: errorMessage.includes("timeout")
          ? "Request timeout"
          : "Network error",
        exists: false,
        status: "error",
      };
    }
  };