Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/comments.ts:151-219 (handler)

  Core execution logic for the basecamp_update_comment tool: validates operations, handles partial/full updates by fetching current content if necessary, applies transformations, calls Basecamp API to update, and returns success/error messages.

  async (params) => {
    try {
      // Validate at least one operation is provided
      validateContentOperations(params);
  
      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 comment if needed for partial operations
        if (hasPartialOps) {
          const currentResponse = await client.comments.get({
            params: {
              bucketId: params.bucket_id,
              commentId: params.comment_id,
            },
          });
  
          if (currentResponse.status !== 200 || !currentResponse.body) {
            throw new Error(
              `Failed to fetch current comment: ${currentResponse.status}`,
            );
          }
  
          const currentContent = currentResponse.body.content || "";
          finalContent = applyContentOperations(currentContent, params);
        } else {
          // Full content replacement
          finalContent = params.content;
        }
      }
  
      // If no content changes (shouldn't happen due to validation, but be safe)
      if (finalContent === undefined) {
        throw new Error("No content operations resulted in changes");
      }
  
      // Update the comment
      const response = await client.comments.update({
        params: {
          bucketId: params.bucket_id,
          commentId: params.comment_id,
        },
        body: { content: finalContent },
      });
  
      if (response.status !== 200 || !response.body) {
        throw new Error("Failed to update comment");
      }
  
      return {
        content: [
          {
            type: "text",
            text: `Comment updated successfully!\n\nID: ${response.body.id}`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: handleBasecampError(error) }],
      };
    }

• src/tools/comments.ts:134-221 (registration)

  Registration of the basecamp_update_comment tool within registerCommentTools, including title, description, input schema (bucket_id, comment_id, content operations), annotations, and inline handler.

  server.registerTool(
    "basecamp_update_comment",
    {
      title: "Update Basecamp Comment",
      description: `Update a comment. Use partial content operations when possible to save on token usage. ${htmlRules}`,
      inputSchema: {
        bucket_id: BasecampIdSchema,
        comment_id: BasecampIdSchema,
        ...ContentOperationFields,
      },
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: true,
      },
    },
    async (params) => {
      try {
        // Validate at least one operation is provided
        validateContentOperations(params);
  
        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 comment if needed for partial operations
          if (hasPartialOps) {
            const currentResponse = await client.comments.get({
              params: {
                bucketId: params.bucket_id,
                commentId: params.comment_id,
              },
            });
  
            if (currentResponse.status !== 200 || !currentResponse.body) {
              throw new Error(
                `Failed to fetch current comment: ${currentResponse.status}`,
              );
            }
  
            const currentContent = currentResponse.body.content || "";
            finalContent = applyContentOperations(currentContent, params);
          } else {
            // Full content replacement
            finalContent = params.content;
          }
        }
  
        // If no content changes (shouldn't happen due to validation, but be safe)
        if (finalContent === undefined) {
          throw new Error("No content operations resulted in changes");
        }
  
        // Update the comment
        const response = await client.comments.update({
          params: {
            bucketId: params.bucket_id,
            commentId: params.comment_id,
          },
          body: { content: finalContent },
        });
  
        if (response.status !== 200 || !response.body) {
          throw new Error("Failed to update comment");
        }
  
        return {
          content: [
            {
              type: "text",
              text: `Comment updated successfully!\n\nID: ${response.body.id}`,
            },
          ],
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: handleBasecampError(error) }],
        };
      }
    },
  );

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

  Shared schema fields for content operations (full replace, append, prepend, search-replace) spread into the tool's inputSchema.

  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.",
      ),
  };

• src/schemas/common.ts:10-12 (schema)

  Common Zod schema for Basecamp IDs used in bucket_id and comment_id parameters.

  export const BasecampIdSchema = z
    .number()
    .describe("Basecamp resource identifier");

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

  Helper function to apply content operations (full or partial) to existing comment content, used in the handler.

  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;
  }