search_repositories

Instructions

Implementation Reference

• src/tools/search.ts:53-121 (handler)

  The 'search_repositories' MCP tool is defined here (line 54) via server.tool(). The handler (lines 73-120) calls octokit.rest.search.repos with the query, per_page, and page parameters, maps results to a concise format (full_name, description truncated to 150 chars, stars, language, recent updated date), and returns formatted text content.

  server.tool(
  	"search_repositories",
  	"Search for GitHub repositories. Returns a concise list with essential information. Use 'get_repository' for detailed information about a specific repository.",
  	{
  		query: z
  			.string()
  			.describe(
  				"Search query. Examples: 'language:typescript stars:>1000', 'org:facebook react', 'machine learning in:description', 'user:octocat', 'created:>2023-01-01', 'license:mit', 'topic:javascript', 'is:public archived:false'",
  			),
  		per_page: z
  			.number()
  			.optional()
  			.default(10)
  			.describe("Results per page (default 10, max 100)"),
  		page: z
  			.number()
  			.optional()
  			.default(1)
  			.describe("Page number (default 1)"),
  	},
  	async ({ query, per_page, page }) => {
  		try {
  			const response = await octokit.rest.search.repos({
  				q: query,
  				per_page,
  				page,
  			})
  
  			// Extract only essential information
  			const repositories = response.data.items.map(repo => ({
  				full_name: repo.full_name,
  				description:
  					repo.description?.slice(0, 150) +
  					(repo.description && repo.description.length > 150 ? "..." : ""),
  				stars: repo.stargazers_count,
  				language: repo.language,
  				// Only include updated_at if it's recent (within last year)
  				...(new Date(repo.updated_at).getTime() >
  				Date.now() - 365 * 24 * 60 * 60 * 1000
  					? { updated: new Date(repo.updated_at).toISOString().split("T")[0] }
  					: {}),
  			}))
  
  			// Format as simple text
  			const text = repositories
  				.map(
  					(repo, i) =>
  						`${i + 1}. **${repo.full_name}**${repo.stars ? ` - ${repo.stars.toLocaleString()} stars` : ""}${repo.language ? ` - \`${repo.language}\`` : ""}
    ${repo.description || "_No description_"}${repo.updated ? `\n   _Updated: ${repo.updated}_` : ""}`,
  				)
  				.join("\n\n")
  
  			return {
  				content: [
  					{
  						type: "text",
  						text: text
  							? `### Found ${repositories.length} repositories:\n\n${text}`
  							: "No repositories found",
  					},
  				],
  			}
  		} catch (e: any) {
  			return {
  				content: [{ type: "text", text: `Error: ${e.message}` }],
  			}
  		}
  	},
  )

• src/tools/search.ts:56-72 (schema)

  Input schema for 'search_repositories': query (string, required), per_page (number, optional, default 10), page (number, optional, default 1) — defined using Zod schemas.

  {
  	query: z
  		.string()
  		.describe(
  			"Search query. Examples: 'language:typescript stars:>1000', 'org:facebook react', 'machine learning in:description', 'user:octocat', 'created:>2023-01-01', 'license:mit', 'topic:javascript', 'is:public archived:false'",
  		),
  	per_page: z
  		.number()
  		.optional()
  		.default(10)
  		.describe("Results per page (default 10, max 100)"),
  	page: z
  		.number()
  		.optional()
  		.default(1)
  		.describe("Page number (default 1)"),
  },

• src/index.ts:14-38 (registration)

  Registration of the tool: registerSearchTools(server, octokit) called inside registerAllToolsAndResources which is invoked by both CLI and HTTP entry points.

  export function registerAllToolsAndResources(server: McpServer, octokit: Octokit): void {
  	registerSearchTools(server, octokit)
  	registerIssueTools(server, octokit)
  	registerRepositoryTools(server, octokit)
  	registerPullRequestTools(server, octokit)
  	registerRepositoryResource(server, octokit)
  
  	// Hello tool — verifies MCP server connectivity
  	server.tool(
  		"hello",
  		"A simple test tool to verify that the MCP server is working correctly",
  		{},
  		async () => ({
  			content: [
  				{
  					type: "text",
  					text: JSON.stringify({
  						message: "Hello from GitHub MCP Server!",
  						timestamp: new Date().toISOString(),
  					}, null, 2),
  				},
  			],
  		}),
  	)
  }

• src/index.ts:15-17 (registration)

  The registerSearchTools function is imported from './tools/search.js' and called during server initialization.

  registerSearchTools(server, octokit)
  registerIssueTools(server, octokit)
  registerRepositoryTools(server, octokit)