list_projects
Retrieve GitLab projects with simplified details to reduce token usage, or get full project information when needed. Filter by search terms, visibility level, and ownership status.
Instructions
List GitLab projects with minimal info by default (to reduce token usage from 40k+ to much less). Use simple=false for full project details when needed.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| owned | No | Show only owned projects (default: true for privacy) | |
| per_page | No | Number of results per page (max 100) | |
| search | No | Search projects by name | |
| simple | No | Use simplified project info to reduce response size (default: true). Set to false for full project details. | |
| visibility | No | Filter by visibility level |
Implementation Reference
- src/handlers/projects.ts:14-46 (handler)The main handler function `listProjects` that constructs GitLab API parameters based on input and fetches the list of projects.async listProjects(args: ListProjectsParams) { const params = new URLSearchParams(); const defaults = this.configManager.getDefaults(); if (args.search) params.append('search', args.search); if (args.visibility) params.append('visibility', args.visibility); // Use config default for project scope, fallback to owned=true for privacy const shouldShowOwned = args.owned !== false && (defaults.projectScope === 'owned' || defaults.projectScope === undefined); if (shouldShowOwned) params.append('owned', 'true'); // Use simple=true by default to reduce payload size (40k+ tokens -> much smaller) // Only use full details when explicitly requested with simple=false const useSimple = args.simple !== false; // Default to true unless explicitly set to false if (useSimple) { params.append('simple', 'true'); params.append('statistics', 'false'); // Also exclude statistics for even smaller payload } // Use config default for per_page params.append('per_page', String(args.per_page || defaults.perPage || 20)); const data = await this.client.get(`/projects?${params.toString()}`); return { content: [ { type: 'text', text: JSON.stringify(data, null, 2), }, ], }; }
- src/tools/projects.ts:5-36 (schema)MCP tool definition including name, description, and inputSchema for 'list_projects'.name: 'list_projects', description: 'List GitLab projects with minimal info by default (to reduce token usage from 40k+ to much less). Use simple=false for full project details when needed.', inputSchema: { type: 'object', properties: { search: { type: 'string', description: 'Search projects by name', }, visibility: { type: 'string', enum: ['public', 'internal', 'private'], description: 'Filter by visibility level', }, owned: { type: 'boolean', description: 'Show only owned projects (default: true for privacy)', default: true, }, per_page: { type: 'number', description: 'Number of results per page (max 100)', maximum: 100, default: 20, }, simple: { type: 'boolean', description: 'Use simplified project info to reduce response size (default: true). Set to false for full project details.', default: true, }, }, },
- src/types.ts:203-209 (schema)TypeScript interface defining the parameters for listProjects.export interface ListProjectsParams { search?: string; visibility?: 'public' | 'internal' | 'private'; owned?: boolean; per_page?: number; simple?: boolean; // Use simple=true for minimal project info (default: true) }
- src/server.ts:153-156 (registration)Dispatch/registration in the MCP CallToolRequest handler switch statement that routes 'list_projects' calls to the projectHandlers.listProjects method.case "list_projects": return await this.projectHandlers.listProjects( args as unknown as ListProjectsParams );