Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/todos.ts:227-242 (handler)

  The handler function that executes the tool's core logic: initializes the Basecamp client and calls the complete method on the specified todo.
  async (params) => { try { const client = await initializeBasecampClient(); await client.todos.complete({ params: { bucketId: params.bucket_id, todoId: params.todo_id }, }); return { content: [{ type: "text", text: "Todo marked as completed!" }], }; } catch (error) { return { content: [{ type: "text", text: handleBasecampError(error) }], }; } },
• src/tools/todos.ts:216-219 (schema)

  Input schema definition for the tool parameters bucket_id and todo_id.
  inputSchema: { bucket_id: BasecampIdSchema, todo_id: BasecampIdSchema, },
• src/schemas/common.ts:10-12 (schema)

  Reusable Zod schema for Basecamp IDs used in the tool's input schema.
  export const BasecampIdSchema = z .number() .describe("Basecamp resource identifier");
• src/tools/todos.ts:211-243 (registration)

  Registration of the basecamp_complete_todo tool including title, description, inputSchema, annotations, and handler.
  server.registerTool( "basecamp_complete_todo", { title: "Complete Basecamp Todo", description: "Mark a todo as completed.", inputSchema: { bucket_id: BasecampIdSchema, todo_id: BasecampIdSchema, }, annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true, }, }, async (params) => { try { const client = await initializeBasecampClient(); await client.todos.complete({ params: { bucketId: params.bucket_id, todoId: params.todo_id }, }); return { content: [{ type: "text", text: "Todo marked as completed!" }], }; } catch (error) { return { content: [{ type: "text", text: handleBasecampError(error) }], }; } }, );
• src/index.ts:63-63 (registration)

  Top-level call to register all todo tools, including basecamp_complete_todo.
  registerTodoTools(server);
• src/utils/auth.ts:24-64 (helper)

  Helper function to initialize authenticated Basecamp client used in the tool handler.
  export async function initializeBasecampClient(): Promise<Client> { // Validate required environment variables const requiredEnvVars = [ "BASECAMP_CLIENT_ID", "BASECAMP_CLIENT_SECRET", "BASECAMP_REFRESH_TOKEN", "BASECAMP_ACCOUNT_ID", ]; const missing = requiredEnvVars.filter((varName) => !process.env[varName]); if (missing.length > 0) { throw new Error( `Missing required environment variables: ${missing.join(", ")}. ` + `Please set these in your environment or .env file.`, ); } // Get bearer token (cache if possible to avoid repeated OAuth requests) if (!cachedBearerToken) { try { cachedBearerToken = await getBearerToken({ clientId: process.env.BASECAMP_CLIENT_ID!, clientSecret: process.env.BASECAMP_CLIENT_SECRET!, refreshToken: process.env.BASECAMP_REFRESH_TOKEN!, userAgent: process.env.BASECAMP_USER_AGENT, }); } catch (error) { throw new Error( `Failed to obtain Basecamp access token: ${error instanceof Error ? error.message : String(error)}. ` + `Check your BASECAMP_CLIENT_ID, BASECAMP_CLIENT_SECRET, and BASECAMP_REFRESH_TOKEN are correct.`, ); } } // Build and return client return buildClient({ bearerToken: cachedBearerToken, accountId: process.env.BASECAMP_ACCOUNT_ID!, userAgent: process.env.BASECAMP_USER_AGENT, }); }
• src/utils/errorHandlers.ts:11-89 (helper)

  Helper function to format Basecamp API errors for user-friendly responses.
  export function handleBasecampError(error: unknown): string { // Handle HTTP response errors if (error && typeof error === "object" && "status" in error) { const status = (error as { status: number }).status; switch (status) { case 400: return ( "Error: Bad request. Check that all required parameters are provided and formatted correctly. " + extractErrorDetails(error) ); case 401: return ( "Error: Authentication failed. Your access token may have expired. " + "Try restarting the server to refresh the token, or check your BASECAMP_REFRESH_TOKEN is valid." ); case 403: return ( "Error: Access denied. You don't have permission to access this resource. " + "Check that you're using the correct account ID and that your Basecamp user has access to this project/resource." ); case 404: return ( "Error: Resource not found. The requested resource (message, todo, project, etc.) doesn't exist or has been deleted. " + "Verify the ID is correct and the resource hasn't been moved to trash." ); case 422: return ( "Error: Validation failed. The request data didn't pass Basecamp's validation rules. " + extractErrorDetails(error) + " Check the data format and required fields." ); case 429: return ( "Error: Rate limit exceeded. Too many requests have been made to the Basecamp API. " + "Please wait a moment before trying again." ); case 500: case 502: case 503: case 504: return ( "Error: Basecamp server error. The Basecamp API is experiencing issues. " + "Please try again in a moment." ); default: return `Error: API request failed with status ${status}. ${extractErrorDetails(error)}`; } } // Handle network/connection errors if (error && typeof error === "object" && "code" in error) { const code = (error as { code: string }).code; if (code === "ECONNABORTED" || code === "ETIMEDOUT") { return ( "Error: Request timed out. The Basecamp API took too long to respond. " + "Please try again." ); } if (code === "ECONNREFUSED" || code === "ENOTFOUND") { return ( "Error: Unable to connect to Basecamp API. " + "Check your internet connection and try again." ); } } // Generic error fallback return `Error: ${error instanceof Error ? error.message : String(error)}`; }