Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/kanban.ts:558-648 (handler)

  Handler function that updates kanban card properties (title, content with partial operations support, due_on, assignees, notify) and processes steps (create/update/delete/reposition/complete) using processStepOperations helper.
  async (params) => { try { // Validate at least one operation is provided validateContentOperations(params, [ "title", "due_on", "notify", "assignee_ids", "steps", ]); const client = await initializeBasecampClient(); let finalContent: string | undefined; let currentCard: any = null; // Check if we need to fetch current content for partial operations const hasPartialOps = params.content_append || params.content_prepend || params.search_replace; if (hasPartialOps || params.content !== undefined || params.steps) { // Fetch current card if needed for partial operations or steps if (hasPartialOps || params.steps) { const currentResponse = await client.cardTableCards.get({ params: { bucketId: params.bucket_id, cardId: params.card_id, }, }); if (currentResponse.status !== 200 || !currentResponse.body) { throw new Error( `Failed to fetch current card: ${currentResponse.status}`, ); } currentCard = currentResponse.body; if (hasPartialOps) { const currentContent = currentCard.content || ""; finalContent = applyContentOperations(currentContent, params); } } else { // Full content replacement finalContent = params.content; } } const response = await client.cardTableCards.update({ params: { bucketId: params.bucket_id, cardId: params.card_id }, body: { ...(params.title ? { title: params.title } : {}), ...(finalContent !== undefined ? { content: finalContent } : {}), ...(params.due_on !== undefined ? { due_on: params.due_on } : {}), ...(params.notify !== undefined ? { notify: params.notify } : {}), ...(params.assignee_ids !== undefined ? { assignee_ids: params.assignee_ids } : {}), }, }); if (response.status !== 200 || !response.body) { throw new Error("Failed to update card"); } // Process step operations if provided if (params.steps) { await processStepOperations( client, params.bucket_id, params.card_id, currentCard?.steps || [], params.steps, ); } return { content: [ { type: "text", text: `Card updated successfully!\n\nID: ${response.body.id}\nTitle: ${response.body.title}`, }, ], }; } catch (error) { return { content: [{ type: "text", text: handleBasecampError(error) }], }; } },
• src/tools/kanban.ts:506-550 (schema)

  Input schema for the tool using Zod, including bucket_id, card_id, optional title, content operations, due_on, notify, assignee_ids, and steps array with full CRUD semantics.
  inputSchema: { bucket_id: BasecampIdSchema, card_id: BasecampIdSchema, title: z.string().min(1).optional().describe("New card title"), ...ContentOperationFields, due_on: z .string() .optional() .describe("Due date (YYYY-MM-DD format) or null to clear"), notify: z .boolean() .optional() .describe("Whether to notify assignees of the update"), assignee_ids: z .array(z.number()) .optional() .describe("Array of user IDs to assign to the card"), steps: z .array( z.object({ id: z .number() .optional() .describe("Step ID for updates. Omit for new steps."), title: z.string().describe("Step title. Required for new steps."), due_on: z .string() .nullable() .optional() .describe("Due date (YYYY-MM-DD) or null to clear"), assignee_ids: z .array(z.number()) .optional() .describe("Array of user IDs to assign"), completed: z .boolean() .optional() .describe("Whether step is completed"), }), ) .optional() .describe( "Complete array of desired steps. Array order defines position. Steps not in array will be deleted.", ), },
• src/tools/kanban.ts:501-649 (registration)

  Tool registration call within registerKanbanTools function, specifying title, description, inputSchema, annotations, and handler.
  server.registerTool( "basecamp_update_kanban_card", { title: "Update Kanban Card", description: `Update a kanban card including its steps. At least one field (title, content, partial content operations, or steps) must be provided. Use partial content operations when possible to save on token usage. ${htmlRules}`, inputSchema: { bucket_id: BasecampIdSchema, card_id: BasecampIdSchema, title: z.string().min(1).optional().describe("New card title"), ...ContentOperationFields, due_on: z .string() .optional() .describe("Due date (YYYY-MM-DD format) or null to clear"), notify: z .boolean() .optional() .describe("Whether to notify assignees of the update"), assignee_ids: z .array(z.number()) .optional() .describe("Array of user IDs to assign to the card"), steps: z .array( z.object({ id: z .number() .optional() .describe("Step ID for updates. Omit for new steps."), title: z.string().describe("Step title. Required for new steps."), due_on: z .string() .nullable() .optional() .describe("Due date (YYYY-MM-DD) or null to clear"), assignee_ids: z .array(z.number()) .optional() .describe("Array of user IDs to assign"), completed: z .boolean() .optional() .describe("Whether step is completed"), }), ) .optional() .describe( "Complete array of desired steps. Array order defines position. Steps not in array will be deleted.", ), }, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true, }, }, async (params) => { try { // Validate at least one operation is provided validateContentOperations(params, [ "title", "due_on", "notify", "assignee_ids", "steps", ]); const client = await initializeBasecampClient(); let finalContent: string | undefined; let currentCard: any = null; // Check if we need to fetch current content for partial operations const hasPartialOps = params.content_append || params.content_prepend || params.search_replace; if (hasPartialOps || params.content !== undefined || params.steps) { // Fetch current card if needed for partial operations or steps if (hasPartialOps || params.steps) { const currentResponse = await client.cardTableCards.get({ params: { bucketId: params.bucket_id, cardId: params.card_id, }, }); if (currentResponse.status !== 200 || !currentResponse.body) { throw new Error( `Failed to fetch current card: ${currentResponse.status}`, ); } currentCard = currentResponse.body; if (hasPartialOps) { const currentContent = currentCard.content || ""; finalContent = applyContentOperations(currentContent, params); } } else { // Full content replacement finalContent = params.content; } } const response = await client.cardTableCards.update({ params: { bucketId: params.bucket_id, cardId: params.card_id }, body: { ...(params.title ? { title: params.title } : {}), ...(finalContent !== undefined ? { content: finalContent } : {}), ...(params.due_on !== undefined ? { due_on: params.due_on } : {}), ...(params.notify !== undefined ? { notify: params.notify } : {}), ...(params.assignee_ids !== undefined ? { assignee_ids: params.assignee_ids } : {}), }, }); if (response.status !== 200 || !response.body) { throw new Error("Failed to update card"); } // Process step operations if provided if (params.steps) { await processStepOperations( client, params.bucket_id, params.card_id, currentCard?.steps || [], params.steps, ); } return { content: [ { type: "text", text: `Card updated successfully!\n\nID: ${response.body.id}\nTitle: ${response.body.title}`, }, ], }; } catch (error) { return { content: [{ type: "text", text: handleBasecampError(error) }], }; } }, );
• src/tools/kanban.ts:41-219 (helper)

  Helper function to process step operations on a kanban card: validates inputs, identifies create/update/delete/reposition/completion changes, executes API calls accordingly, using complete array replacement semantics.
  async function processStepOperations( client: Awaited<ReturnType<typeof initializeBasecampClient>>, bucketId: number, cardId: number, currentSteps: CurrentStep[], desiredSteps: StepInput[], ): Promise<void> { // ===== VALIDATION ===== // Validate new steps have titles for (const step of desiredSteps) { if (!step.id && !step.title) { throw new Error("New steps (without id) must have a title"); } } // Check for duplicate IDs const stepIds = desiredSteps.filter((s) => s.id).map((s) => s.id!); if (new Set(stepIds).size !== stepIds.length) { throw new Error("Duplicate step IDs found in steps array"); } // Validate all step IDs exist on current card const currentStepIds = new Set(currentSteps.map((s) => s.id)); for (const id of stepIds) { if (!currentStepIds.has(id)) { const available = Array.from(currentStepIds).join(", "); throw new Error( `Step ID ${id} not found on card. ${ available ? `Available IDs: ${available}` : "No steps exist on this card." }`, ); } } // ===== IDENTIFY OPERATIONS ===== const desiredStepIds = new Set(stepIds); // Steps to delete: in current but not in desired const toDelete = currentSteps.filter((s) => !desiredStepIds.has(s.id)); // Steps to create: no ID provided const toCreate = desiredSteps.filter((s) => !s.id); // Steps to update/reposition/complete const toProcess = desiredSteps.filter((s) => s.id); // ===== DELETE OPERATIONS ===== for (const step of toDelete) { await client.recordings.trash({ params: { bucketId, recordingId: step.id }, }); } // ===== CREATE OPERATIONS ===== const createdStepIds: number[] = []; // Track new IDs for repositioning for (const step of toCreate) { const response = await client.cardTableSteps.create({ params: { bucketId, cardId }, body: { title: step.title, ...(step.due_on !== undefined ? { due_on: step.due_on || undefined } : {}), ...(step.assignee_ids ? { assignees: step.assignee_ids.join(",") } : {}), }, }); if (response.status !== 201 || !response.body) { throw new Error(`Failed to create step: ${step.title}`); } createdStepIds.push(response.body.id); // Set completion if specified if (step.completed !== undefined && step.completed) { await client.cardTableSteps.setCompletion({ params: { bucketId, stepId: response.body.id }, body: { completion: "on" }, }); } } // ===== UPDATE OPERATIONS ===== // Build a map of current steps for comparison const currentStepMap = new Map(currentSteps.map((s) => [s.id, s])); for (const step of toProcess) { const currentStep = currentStepMap.get(step.id!); if (!currentStep) continue; // Should not happen due to validation // Check what changed const titleChanged = step.title && step.title !== currentStep.title; const dueOnChanged = step.due_on !== undefined && step.due_on !== currentStep.due_on; const currentAssigneeIds = currentStep.assignees?.map((a) => a.id) || []; const desiredAssigneeIds = step.assignee_ids || []; const assigneesChanged = step.assignee_ids !== undefined && (currentAssigneeIds.length !== desiredAssigneeIds.length || !currentAssigneeIds.every((id, i) => id === desiredAssigneeIds[i])); // Only update if something changed if (titleChanged || dueOnChanged || assigneesChanged) { await client.cardTableSteps.update({ params: { bucketId, stepId: step.id! }, body: { ...(step.title ? { title: step.title } : {}), ...(step.due_on !== undefined ? { due_on: step.due_on || undefined } : {}), ...(step.assignee_ids ? { assignees: step.assignee_ids.join(",") } : {}), }, }); } // Handle completion status changes if ( step.completed !== undefined && step.completed !== currentStep.completed ) { await client.cardTableSteps.setCompletion({ params: { bucketId, stepId: step.id! }, body: { completion: step.completed ? "on" : "off" }, }); } } // ===== REPOSITION OPERATIONS ===== // Build final list of step IDs in desired order (mix of existing and new) const finalStepIds: number[] = []; let createIndex = 0; for (const step of desiredSteps) { if (step.id) { finalStepIds.push(step.id); } else { // This was a created step, use the ID we tracked if (createIndex < createdStepIds.length) { finalStepIds.push(createdStepIds[createIndex++]); } } } // Get current positions after all operations // We need to reposition if the order doesn't match const currentPositions = new Map( currentSteps .filter((s) => finalStepIds.includes(s.id)) .map((s, i) => [s.id, i]), ); // Reposition each step to match the desired array order for (let i = 0; i < finalStepIds.length; i++) { const stepId = finalStepIds[i]; const currentPos = currentPositions.get(stepId); // Only reposition if needed if (currentPos !== undefined && currentPos !== i) { await client.cardTableSteps.reposition({ params: { bucketId, cardId }, body: { source_id: stepId, position: i }, }); } } }
• src/index.ts:66-66 (registration)

  Invocation of registerKanbanTools during server initialization, which registers the kanban tools including basecamp_update_kanban_card.
  registerKanbanTools(server);