Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/messages.ts:301-367 (handler)

  The handler function implementing the core logic for updating a Basecamp message. Supports partial updates via content operations (append, prepend, search-replace), fetches current content if needed, applies changes, and calls the Basecamp API.

  async (params) => {
    try {
      // Validate at least one operation is provided
      validateContentOperations(params, ["subject", "message_type_id"]);
  
      const client = await initializeBasecampClient();
      let finalContent: string | undefined;
  
      // 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) {
        // Fetch current message if needed for partial operations
        if (hasPartialOps) {
          const currentResponse = await client.messages.get({
            params: {
              bucketId: params.bucket_id,
              messageId: params.message_id,
            },
          });
  
          if (currentResponse.status !== 200 || !currentResponse.body) {
            throw new Error(
              `Failed to fetch current message for partial update: ${currentResponse.status}`,
            );
          }
  
          const currentContent = currentResponse.body.content || "";
          finalContent = applyContentOperations(currentContent, params);
        } else {
          // Full content replacement
          finalContent = params.content;
        }
      }
  
      const response = await client.messages.update({
        params: { bucketId: params.bucket_id, messageId: params.message_id },
        body: {
          ...(params.subject ? { subject: params.subject } : {}),
          ...(finalContent !== undefined ? { content: finalContent } : {}),
          ...(params.message_type_id
            ? { category_id: params.message_type_id }
            : {}),
        },
      });
  
      if (response.status !== 200 || !response.body) {
        throw new Error(`Failed to update message`);
      }
  
      return {
        content: [
          {
            type: "text",
            text: `Message updated successfully!\n\nID: ${response.body.id}\nSubject: ${response.body.title}`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: handleBasecampError(error) }],
      };
    }
  },

• src/tools/messages.ts:280-293 (schema)

  The input schema for the basecamp_update_message tool, defining parameters like bucket_id, message_id, subject, message_type_id, and content operations using Zod.

  inputSchema: {
    bucket_id: BasecampIdSchema,
    message_id: BasecampIdSchema,
    subject: z
      .string()
      .min(1)
      .max(500)
      .optional()
      .describe("New message subject"),
    message_type_id: BasecampIdSchema.optional().describe(
      "Optional message type/category ID",
    ),
    ...ContentOperationFields,
  },

• src/utils/contentOperations.ts:78-131 (helper)

  Key helper function that applies partial content operations (full replace, append, prepend, search-replace) to existing message content, enabling efficient updates without full content resubmission.

  export function applyContentOperations(
    currentContent: string,
    operations: ContentOperationParams,
  ): string | undefined {
    const hasPartialOps =
      operations.content_append ||
      operations.content_prepend ||
      operations.search_replace;
  
    // Validate mutual exclusivity
    if (operations.content && hasPartialOps) {
      throw new Error(
        "Cannot use 'content' with partial operations (content_append, content_prepend, search_replace). Use either full replacement or partial operations, not both.",
      );
    }
  
    // If full content replacement, return it directly
    if (operations.content !== undefined) {
      return operations.content;
    }
  
    // If no operations at all, return undefined (no changes)
    if (!hasPartialOps) {
      return undefined;
    }
  
    // Apply partial operations
    let finalContent = currentContent;
  
    // Apply search-replace operations first
    if (operations.search_replace) {
      for (const operation of operations.search_replace) {
        // Check if the search string exists in the content
        if (!finalContent.includes(operation.find)) {
          throw new Error(
            `Search string not found: "${operation.find}". The content does not contain this text.`,
          );
        }
        finalContent = finalContent.replaceAll(operation.find, operation.replace);
      }
    }
  
    // Apply prepend
    if (operations.content_prepend) {
      finalContent = operations.content_prepend + finalContent;
    }
  
    // Apply append
    if (operations.content_append) {
      finalContent = finalContent + operations.content_append;
    }
  
    return finalContent;
  }

• src/utils/contentOperations.ts:140-162 (helper)

  Helper function to validate that at least one content operation or additional field (like subject) is provided for the update.

  export function validateContentOperations(
    operations: ContentOperationParams,
    additionalFields: string[] = [],
  ): void {
    const hasContentOp =
      operations.content ||
      operations.content_append ||
      operations.content_prepend ||
      operations.search_replace;
  
    const hasAdditionalFields = additionalFields.some(
      (field) => (operations as Record<string, unknown>)[field] !== undefined,
    );
  
    if (!hasContentOp && !hasAdditionalFields) {
      const fieldsStr = [
        "content",
        "partial operations",
        ...additionalFields,
      ].join(", ");
      throw new Error(`At least one field (${fieldsStr}) must be provided`);
    }
  }

• src/utils/contentOperations.ts:26-58 (schema)

  Shared Zod schema fields for content operations, spread into the tool's inputSchema to support partial updates.

  export const ContentOperationFields = {
    content: z
      .string()
      .optional()
      .describe(
        `If provided, replaces entire HTML content. Cannot be used with content_append, content_prepend, or search_replace.`,
      ),
    content_append: z
      .string()
      .optional()
      .describe(
        "Text to append to the end of current content. Cannot be used with content.",
      ),
    content_prepend: z
      .string()
      .optional()
      .describe(
        "Text to prepend to the beginning of current content. Cannot be used with content.",
      ),
    search_replace: z
      .array(
        z.object({
          find: z.string().describe("Text to search for"),
          replace: z
            .string()
            .describe("Text to replace ALL the occurrences with"),
        }),
      )
      .optional()
      .describe(
        "Array of search-replace operations to apply to current content. Cannot be used with content.",
      ),
  };