Octocode MCP

Instructions

Implementation Reference

• packages/octocode-mcp/src/tools/github_search_repos.ts:122-209 (handler)

  Core execution logic for the githubSearchRepositories tool: expands queries for topics/keywords, performs bulk GitHub repository searches via API, processes results, generates pagination and search-specific hints.

  async function searchMultipleGitHubRepos(
    queries: GitHubReposSearchQuery[],
    authInfo?: AuthInfo,
    sessionId?: string
  ): Promise<CallToolResult> {
    const expandedQueries = expandQueriesWithBothSearchTypes(queries);
  
    return executeBulkOperation(
      expandedQueries,
      async (query: GitHubReposSearchQuery, _index: number) => {
        try {
          const apiResult = await searchGitHubReposAPI(
            query,
            authInfo,
            sessionId
          );
  
          const apiError = handleApiError(apiResult, query);
          if (apiError) return apiError;
  
          const repositories =
            'data' in apiResult
              ? apiResult.data.repositories || []
              : ([] satisfies SimplifiedRepository[]);
  
          const pagination =
            'data' in apiResult ? apiResult.data.pagination : undefined;
  
          // Generate pagination hints with full context for navigation
          const paginationHints: string[] = [];
          if (pagination) {
            const { currentPage, totalPages, totalMatches, perPage, hasMore } =
              pagination;
            const startItem = (currentPage - 1) * perPage + 1;
            const endItem = Math.min(currentPage * perPage, totalMatches);
  
            // Main pagination summary
            paginationHints.push(
              `Page ${currentPage}/${totalPages} (showing ${startItem}-${endItem} of ${totalMatches} repos)`
            );
  
            // Navigation hints
            if (hasMore) {
              paginationHints.push(`Next: page=${currentPage + 1}`);
            }
            if (currentPage > 1) {
              paginationHints.push(`Previous: page=${currentPage - 1}`);
            }
            if (!hasMore) {
              paginationHints.push('Final page');
            }
  
            // Quick navigation hint for multi-page results
            if (totalPages > 2) {
              paginationHints.push(
                `Jump to: page=1 (first) or page=${totalPages} (last)`
              );
            }
          }
  
          // Generate search-type specific hints from metadata
          const searchHints = generateSearchSpecificHints(
            query,
            repositories.length > 0
          );
  
          // Use unified pattern: extraHints for pagination and search-specific hints
          return createSuccessResult(
            query,
            { repositories, pagination },
            repositories.length > 0,
            TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
            {
              extraHints: [...paginationHints, ...(searchHints || [])],
            }
          );
        } catch (error) {
          return handleCatchError(error, query);
        }
      },
      {
        toolName: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
        keysPriority: ['repositories', 'pagination', 'error'] satisfies Array<
          keyof RepoSearchResult
        >,
      }
    );
  }

• packages/octocode-mcp/src/scheme/github_search_repos.ts:54-58 (schema)

  Zod schema for input validation of githubSearchRepositories tool queries, supporting bulk queries with keywords/topics search, filters, sorting, and pagination.

  export const GitHubReposSearchQuerySchema = createBulkQuerySchema(
    TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
    GitHubReposSearchSingleQuerySchema
  );

• packages/octocode-mcp/src/tools/github_search_repos.ts:26-64 (registration)

  Registers the githubSearchRepositories tool on the MCP server, specifying name, description, input schema, annotations, and security-wrapped handler function.

  export function registerSearchGitHubReposTool(
    server: McpServer,
    callback?: ToolInvocationCallback
  ) {
    return server.registerTool(
      TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
      {
        description: DESCRIPTIONS[TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES],
        inputSchema: GitHubReposSearchQuerySchema,
        annotations: {
          title: 'GitHub Repository Search',
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },
      withSecurityValidation(
        TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
        async (
          args: {
            queries: GitHubReposSearchQuery[];
          },
          authInfo,
          sessionId
        ): Promise<CallToolResult> => {
          const queries = args.queries || [];
  
          await invokeCallbackSafely(
            callback,
            TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
            queries
          );
  
          return searchMultipleGitHubRepos(queries, authInfo, sessionId);
        }
      )
    );
  }

• packages/octocode-mcp/src/github/repoSearch.ts:74-169 (helper)

  Helper function implementing the GitHub repository search API call using Octokit, query building, result mapping to simplified repositories, pagination calculation, and error handling.

  async function searchGitHubReposAPIInternal(
    params: GitHubReposSearchQuery,
    authInfo?: AuthInfo
  ): Promise<
    GitHubAPIResponse<{
      repositories: SimplifiedRepository[];
      pagination?: RepoSearchPagination;
    }>
  > {
    try {
      const octokit = await getOctokit(authInfo);
      const query = buildRepoSearchQuery(params);
  
      if (!query.trim()) {
        await logSessionError(
          TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
          SEARCH_ERRORS.QUERY_EMPTY.code
        );
        return {
          error: SEARCH_ERRORS.QUERY_EMPTY.message,
          type: 'http',
          status: 400,
        };
      }
  
      const perPage = Math.min(params.limit || 30, 100);
      const currentPage = params.page || 1;
  
      const searchParams: SearchReposParameters = {
        q: query,
        per_page: perPage,
        page: currentPage,
      };
  
      if (params.sort && params.sort !== 'best-match') {
        searchParams.sort = params.sort as SearchReposParameters['sort'];
      }
  
      const result = await octokit.rest.search.repos(searchParams);
  
      const repositories = result.data.items.map((repo: RepoSearchResultItem) => {
        const fullName = repo.full_name;
        const parts = fullName.split('/');
        const owner = parts[0] || '';
        const repoName = parts[1] || '';
  
        return {
          owner,
          repo: repoName,
          defaultBranch: repo.default_branch,
          stars: repo.stargazers_count || 0,
          description: repo.description
            ? repo.description.length > 150
              ? repo.description.substring(0, 150) + '...'
              : repo.description
            : 'No description',
          url: repo.html_url,
          createdAt: repo.created_at,
          updatedAt: repo.updated_at,
          pushedAt: repo.pushed_at,
          visibility: repo.visibility,
          ...(repo.topics && repo.topics.length > 0 && { topics: repo.topics }),
          ...(repo.forks_count &&
            repo.forks_count > 0 && {
              forksCount: repo.forks_count,
            }),
          ...(repo.open_issues_count &&
            repo.open_issues_count > 0 && {
              openIssuesCount: repo.open_issues_count,
            }),
        };
      });
  
      // GitHub caps at 1000 total results
      const totalMatches = Math.min(result.data.total_count, 1000);
      const totalPages = Math.min(Math.ceil(totalMatches / perPage), 10);
      const hasMore = currentPage < totalPages;
  
      return {
        data: {
          repositories,
          pagination: {
            currentPage,
            totalPages,
            perPage,
            totalMatches,
            hasMore,
          },
        },
        status: 200,
        headers: result.headers,
      };
    } catch (error: unknown) {
      return handleGitHubAPIError(error);
    }
  }

• packages/octocode-mcp/src/tools/toolConfig.ts:63-70 (registration)

  Tool configuration entry that defines and exports the registration function for githubSearchRepositories in the ALL_TOOLS array.

  export const GITHUB_SEARCH_REPOSITORIES: ToolConfig = {
    name: TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES,
    description: getDescription(TOOL_NAMES.GITHUB_SEARCH_REPOSITORIES),
    isDefault: true,
    isLocal: false,
    type: 'search',
    fn: registerSearchGitHubReposTool,
  };