GitHub Mapper MCP Server

Instructions

Implementation Reference

• src/index.ts:43-55 (registration)

  Registration of the 'map-github-repo' tool in the ListToolsRequestSchema handler, including name, description, and input schema.

    name: "map-github-repo",
    description: "Map a GitHub repository structure and provide summary information",
    inputSchema: {
      type: "object",
      properties: {
        repoUrl: {
          type: "string",
          description: "URL of the GitHub repository (e.g., https://github.com/username/repo)",
        },
      },
      required: ["repoUrl"],
    },
  },

• src/index.ts:76-108 (handler)

  Main handler logic for executing the 'map-github-repo' tool within the CallToolRequestSchema handler. Parses URL, fetches repo info and structure using helpers, formats, and returns text content.

  } else if (name === "map-github-repo") {
    if (!githubToken || !octokit) {
      throw new Error("GitHub token not set. Please use the set-github-token tool first.");
    }
  
    const { repoUrl } = args as { repoUrl: string };
  
    try {
      const { owner, repo } = parseGitHubUrl(repoUrl);
      const repoInfo = await getRepoInfo(owner, repo);
      const repoStructure = await getRepoStructure(owner, repo);
      const formattedOutput = formatOutput(repoInfo, repoStructure);
  
      return {
        content: [
          {
            type: "text",
            text: formattedOutput,
          },
        ],
      };
    } catch (error: unknown) {
      console.error("Error mapping repository:", error);
      const errorMessage = error instanceof Error ? error.message : 'An unknown error occurred';
      return {
        content: [
          {
            type: "text",
            text: `Error mapping repository: ${errorMessage}`,
          },
        ],
      };
    }

• src/index.ts:114-120 (helper)

  Helper function to parse GitHub repository URL into owner and repository name.

  function parseGitHubUrl(url: string): { owner: string; repo: string } {
    const match = url.match(/github\.com\/([^\/]+)\/([^\/]+)/);
    if (!match) {
      throw new Error("Invalid GitHub URL format");
    }
    return { owner: match[1], repo: match[2] };
  }

• src/index.ts:122-136 (helper)

  Helper function to fetch repository metadata (name, description, stars, etc.) using Octokit.

  async function getRepoInfo(owner: string, repo: string) {
    if (!octokit) {
      throw new Error("GitHub client not initialized");
    }
    const { data } = await octokit.repos.get({ owner, repo });
    return {
      name: data.name,
      description: data.description,
      stars: data.stargazers_count,
      forks: data.forks_count,
      language: data.language,
      createdAt: data.created_at,
      updatedAt: data.updated_at,
    };
  }

• src/index.ts:138-159 (helper)

  Recursive helper function to build the full directory structure tree of the repository by fetching contents recursively.

  async function getRepoStructure(owner: string, repo: string, path = "") {
    if (!octokit) {
      throw new Error("GitHub client not initialized");
    }
    const { data } = await octokit.repos.getContent({ owner, repo, path });
    
    if (!Array.isArray(data)) {
      throw new Error("Unable to retrieve repository structure");
    }
  
    const structure: { [key: string]: any } = {};
  
    for (const item of data) {
      if (item.type === "file") {
        structure[item.name] = null;
      } else if (item.type === "dir") {
        structure[item.name] = await getRepoStructure(owner, repo, item.path);
      }
    }
  
    return structure;
  }