list_projects
Retrieve and filter GitHub repository projects by state to manage project organization and track progress.
Instructions
List projects for a repository
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| owner | Yes | Repository owner (username or organization) | |
| repo | Yes | Repository name | |
| state | No | Filter projects by state | |
| per_page | No | Results per page (max 100) | |
| page | No | Page number of the results |
Implementation Reference
- src/operations/projects.ts:101-127 (handler)Core handler function that executes the list_projects tool: constructs GitHub API URL for repo projects, appends query params, makes authenticated request, parses response with ProjectSchema array.
export async function listProjects( github_pat: string, owner: string, repo: string, options: { state?: "open" | "closed" | "all"; per_page?: number; page?: number; } = {} ): Promise<z.infer<typeof ProjectSchema>[]> { const url = new URL(`https://api.github.com/repos/${owner}/${repo}/projects`); if (options.state) url.searchParams.append("state", options.state); if (options.per_page) url.searchParams.append("per_page", options.per_page.toString()); if (options.page) url.searchParams.append("page", options.page.toString()); const response = await githubRequest( github_pat, url.toString(), { headers: { "Accept": "application/vnd.github.inertia-preview+json", }, } ); return z.array(ProjectSchema).parse(response); } - src/operations/projects.ts:49-60 (schema)Zod input schemas for list_projects: public ListProjectsSchema (owner, repo, state, per_page, page) and internal _ListProjectsSchema extending with github_pat.
export const ListProjectsSchema = z.object({ owner: z.string().describe("Repository owner (username or organization)"), repo: z.string().describe("Repository name"), state: z.enum(["open", "closed", "all"]).optional().describe("Filter projects by state"), per_page: z.number().optional().describe("Results per page (max 100)"), page: z.number().optional().describe("Page number of the results"), }); export const _ListProjectsSchema = ListProjectsSchema.extend({ github_pat: z.string().describe("GitHub Personal Access Token"), }); - src/index.ts:249-253 (registration)Tool registration in the listTools response: defines name, description, and converts ListProjectsSchema to JSON schema for MCP protocol.
{ name: "list_projects", description: "List projects for a repository", inputSchema: zodToJsonSchema(projects.ListProjectsSchema), }, - src/index.ts:685-692 (handler)Wrapper handler in main CallToolRequest switch: parses arguments with _ListProjectsSchema, extracts params, calls projects.listProjects, formats result as MCP content.
case "list_projects": { const args = projects._ListProjectsSchema.parse(params.arguments); const { github_pat, owner, repo, ...options } = args; const result = await projects.listProjects(github_pat, owner, repo, options); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], }; }