list_projects
Retrieve GitLab projects with simplified data to optimize token usage, or get full details when needed. Filter by search, visibility, and ownership.
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 |
|---|---|---|---|
| search | No | Search projects by name | |
| visibility | No | Filter by visibility level | |
| owned | No | Show only owned projects (default: true for privacy) | |
| per_page | No | Number of results per page (max 100) | |
| simple | No | Use simplified project info to reduce response size (default: true). Set to false for full project details. |
Implementation Reference
- src/handlers/projects.ts:14-46 (handler)The core handler function that implements the list_projects tool logic: constructs GitLab API query parameters based on input args and config defaults, fetches the projects list via GitLabClient, and returns the JSON-stringified data wrapped in MCP response format.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/types.ts:203-209 (schema)TypeScript type definition for the input parameters of the list_projects tool, used for type safety in handlers.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/tools/projects.ts:5-37 (registration)MCP tool definition registering 'list_projects' with its description and JSON input schema for validation.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/server.ts:153-156 (registration)Server dispatch logic that handles incoming 'list_projects' tool calls by invoking the projectHandlers.listProjects method.case "list_projects": return await this.projectHandlers.listProjects( args as unknown as ListProjectsParams );