basecamp_list_projects
Retrieve all active Basecamp projects with their IDs, names, and descriptions to identify project buckets needed for accessing messages, todos, and other resources.
Instructions
List all projects visible to the authenticated user in a Basecamp account. This tool returns active projects with their IDs, names, descriptions, and metadata. Use this to discover project/bucket IDs needed for accessing messages, todos, and other resources.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | Yes | Basecamp account ID |
Input Schema (JSON Schema)
{
"properties": {
"account_id": {
"description": "Basecamp account ID",
"type": "number"
}
},
"required": [
"account_id"
],
"type": "object"
}
Implementation Reference
- src/tools/projects.ts:39-84 (handler)The handler function that executes the basecamp_list_projects tool: initializes the Basecamp client, lists projects with pagination, filters if specified, and returns formatted JSON.async (params) => { try { const client = await initializeBasecampClient(); // Fetch projects with pagination const projects = await asyncPagedToArray({ fetchPage: client.projects.list, request: { query: {}, }, }); // Apply filter if provided let filteredProjects = projects; if (params.filter) { const regex = new RegExp(params.filter, "i"); filteredProjects = projects.filter( (p) => regex.test(p.name) || regex.test(p.description || ""), ); } return { content: [ { type: "text", text: JSON.stringify( filteredProjects.map((p) => ({ id: p.id, name: p.name, description: p.description || "", created_at: p.created_at, updated_at: p.updated_at, url: p.app_url, })), null, 2, ), }, ], }; } catch (error) { return { content: [{ type: "text", text: handleBasecampError(error) }], }; } },
- src/tools/projects.ts:24-31 (schema)Zod input schema defining the optional 'filter' parameter for project name/description filtering.inputSchema: { filter: z .string() .optional() .describe( "Optional regular expression to filter projects by name or description", ), },
- src/tools/projects.ts:19-85 (registration)Direct registration of the basecamp_list_projects tool on the MCP server within registerProjectTools function.server.registerTool( "basecamp_list_projects", { title: "List Basecamp Projects", description: `List all projects visible to the authenticated user in a Basecamp account. This tool returns active projects with their IDs, names, descriptions, and metadata. Use this to discover project/bucket IDs needed for accessing messages, todos, and other resources.`, inputSchema: { filter: z .string() .optional() .describe( "Optional regular expression to filter projects by name or description", ), }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, }, }, async (params) => { try { const client = await initializeBasecampClient(); // Fetch projects with pagination const projects = await asyncPagedToArray({ fetchPage: client.projects.list, request: { query: {}, }, }); // Apply filter if provided let filteredProjects = projects; if (params.filter) { const regex = new RegExp(params.filter, "i"); filteredProjects = projects.filter( (p) => regex.test(p.name) || regex.test(p.description || ""), ); } return { content: [ { type: "text", text: JSON.stringify( filteredProjects.map((p) => ({ id: p.id, name: p.name, description: p.description || "", created_at: p.created_at, updated_at: p.updated_at, url: p.app_url, })), null, 2, ), }, ], }; } catch (error) { return { content: [{ type: "text", text: handleBasecampError(error) }], }; } }, );
- src/index.ts:61-61 (registration)Invocation of registerProjectTools in the main server setup, which registers the basecamp_list_projects tool among others.registerProjectTools(server);