list-projects
Retrieve a paginated list of projects or workspaces from the Opik MCP Server. Supports sorting, filtering by workspace name, and customizable page size for efficient project management.
Instructions
Get a list of projects/workspaces
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | Page number for pagination | |
| size | Yes | Number of items per page | |
| sortBy | No | Sort projects by this field | |
| sortOrder | No | Sort order (asc or desc) | |
| workspaceName | No | Workspace name to use instead of the default |
Implementation Reference
- src/tools/project.ts:14-39 (handler)The main handler function for the 'list-projects' tool. It constructs the API URL with pagination parameters, calls makeApiRequest to fetch projects from the Opik API, and returns formatted MCP content blocks with summary and JSON data.
async (args: any) => { const { page, size, workspaceName } = args; const url = `/v1/private/projects?page=${page}&size=${size}`; const response = await makeApiRequest<ProjectResponse>(url, {}, workspaceName); if (!response.data) { return { content: [{ type: 'text', text: response.error || 'Failed to fetch projects' }], }; } return { content: [ { type: 'text', text: `Found ${response.data.total} projects (page ${response.data.page} of ${Math.ceil(response.data.total / response.data.size)})`, }, { type: 'text', text: JSON.stringify(response.data.content, null, 2), }, ], }; } ); - src/tools/project.ts:9-13 (schema)Zod schema defining the input parameters for the 'list-projects' tool: optional page (default 1), size (default 10), and workspaceName.
{ page: z.number().optional().default(1).describe('Page number for pagination'), size: z.number().optional().default(10).describe('Number of items per page'), workspaceName: z.string().optional().describe('Workspace name to use instead of the default'), }, - src/tools/project.ts:6-40 (registration)Registration of the 'list-projects' tool using server.tool(), including the tool name, description, input schema, and handler function within the loadProjectTools loader.
server.tool( 'list-projects', 'Get a list of projects with optional filtering', { page: z.number().optional().default(1).describe('Page number for pagination'), size: z.number().optional().default(10).describe('Number of items per page'), workspaceName: z.string().optional().describe('Workspace name to use instead of the default'), }, async (args: any) => { const { page, size, workspaceName } = args; const url = `/v1/private/projects?page=${page}&size=${size}`; const response = await makeApiRequest<ProjectResponse>(url, {}, workspaceName); if (!response.data) { return { content: [{ type: 'text', text: response.error || 'Failed to fetch projects' }], }; } return { content: [ { type: 'text', text: `Found ${response.data.total} projects (page ${response.data.page} of ${Math.ceil(response.data.total / response.data.size)})`, }, { type: 'text', text: JSON.stringify(response.data.content, null, 2), }, ], }; } ); - src/index.ts:86-89 (registration)Top-level conditional registration of project tools (including 'list-projects') by calling loadProjectTools(server) when 'projects' toolset is enabled.
if (config.enabledToolsets.includes('projects')) { server = loadProjectTools(server); logToFile('Loaded projects toolset'); }