open-webSearch

Instructions

Implementation Reference

• src/tools/setupTools.ts:302-343 (registration)

  Registers the 'fetchGithubReadme' MCP tool (configurable via MCP_TOOL_FETCH_GITHUB_NAME env var) with input schema and execution handler.

  server.tool(
      fetchGithubToolName,
      "Fetch README content from a GitHub repository URL",
      {
          url: z.string().min(1).refine(
              (url) => validateGithubUrl(url),
              "URL must be a valid GitHub repository URL (supports HTTPS, SSH formats)"
          )
      },
      async ({url}) => {
          try {
              console.error(`Fetching GitHub README: ${url}`);
              const result = await fetchGithubReadme(url);
  
              if (result) {
                  return {
                      content: [{
                          type: 'text',
                          text: result
                      }]
                  };
              } else {
                  return {
                      content: [{
                          type: 'text',
                          text: 'README not found or repository does not exist'
                      }],
                      isError: true
                  };
              }
          } catch (error) {
              console.error('Failed to fetch GitHub README:', error);
              return {
                  content: [{
                      type: 'text',
                      text: `Failed to fetch README: ${error instanceof Error ? error.message : 'Unknown error'}`
                  }],
                  isError: true
              };
          }
      }
  );

• src/engines/github/github.ts:124-126 (handler)

  Main exported handler function for fetching GitHub README content from repository URL.

  export async function fetchGithubReadme(githubUrl: string): Promise<string | null> {
      return getReadmeFromUrl(githubUrl);
  }

• src/tools/setupTools.ts:305-310 (schema)

  Input schema using Zod to validate GitHub repository URL.

  {
      url: z.string().min(1).refine(
          (url) => validateGithubUrl(url),
          "URL must be a valid GitHub repository URL (supports HTTPS, SSH formats)"
      )
  },

• src/tools/setupTools.ts:104-129 (helper)

  Helper function to validate GitHub repository URLs (HTTPS and SSH formats) used in schema refinement.

  const validateGithubUrl = (url: string): boolean => {
      try {
  
          const isSshGithub = /^git@github\.com:/.test(url);
  
          if (isSshGithub) {
              // SSH 格式: git@github.com:owner/repo.git
              return /^git@github\.com:[^\/]+\/[^\/]+/.test(url);
          }
  
          const urlObj = new URL(url);
  
          // 支持多种 GitHub URL 格式
          const isHttpsGithub = urlObj.hostname === 'github.com' || urlObj.hostname === 'www.github.com';
  
          if (isHttpsGithub) {
              // 检查路径格式: /owner/repo
              const pathParts = urlObj.pathname.split('/').filter(part => part.length > 0);
              return pathParts.length >= 2;
          }
  
          return false;
      } catch {
          return false;
      }
  };

• src/engines/github/github.ts:13-41 (helper)

  Helper to extract owner and repo from GitHub URLs (HTTPS, SSH). Used in README fetching logic.

  function extractOwnerAndRepo(url: string): { owner: string; repo: string } | null {
      try {
          const normalizedUrl = url.trim().toLowerCase();
  
          // Regex patterns for HTTPS and SSH URLs
          const patterns = [
              /(?:https?:\/\/)?(?:www\.)?github\.com\/([^\/\s]+)\/([^\/\s]+)/i,
              /git@github\.com:([^\/\s]+)\/([^\/\s]+)\.git/i
          ];
  
          for (const pattern of patterns) {
              const match = url.match(pattern);
              if (match) {
                  const [, owner, rawRepo] = match;
  
                  // Clean repo name: remove query params, fragments, .git suffix, paths
                  const repo = rawRepo.replace(/(?:[?#].*$|\.git$|\/.*$)/g, '');
                  if (owner && repo && owner.length > 0 && repo.length > 0) {
                      return { owner: owner.trim(), repo: repo.trim() };
                  }
              }
          }
  
          return null;
      } catch (error) {
          console.warn('Failed to parse GitHub URL:', url, error);
          return null;
      }
  }