basecamp_list_messages

Retrieve and filter messages from a Basecamp message board to monitor project discussions and track communication within specific boards.

Instructions

List messages in a Basecamp message board

Input Schema

TableJSON Schema

Name	Required	Description
`bucket_id`	Yes	Project/bucket ID
`message_board_id`	Yes	Message board ID
`filter`	No	Optional regular expression to filter messages by title or content

Implementation Reference

src/tools/messages.ts:105-151 (handler)

The main handler function for basecamp_list_messages tool. Initializes the Basecamp client, lists messages from the specified message board using paginated fetching, applies an optional regex filter on title or content, maps to a simplified JSON structure using serializePerson for creator, and returns as text content.

  async (params) => {
    try {
      const client = await initializeBasecampClient();
      const messages = await asyncPagedToArray({
        fetchPage: client.messages.list,
        request: {
          params: {
            bucketId: params.bucket_id,
            messageBoardId: params.message_board_id,
          },
          query: {},
        },
      });

      // Apply filter if provided
      let filteredMessages = messages;
      if (params.filter) {
        const regex = new RegExp(params.filter, "i");
        filteredMessages = messages.filter(
          (m) => regex.test(m.title) || regex.test(m.content || ""),
        );
      }

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              filteredMessages.map((m) => ({
                id: m.id,
                title: m.title,
                creator: serializePerson(m.creator),
                created_at: m.created_at,
              })),
              null,
              2,
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: handleBasecampError(error) }],
      };
    }
  },
);

src/tools/messages.ts:85-104 (schema)

Input schema and metadata (title, description, annotations) for the basecamp_list_messages tool, using BasecampIdSchema for IDs and optional string filter.

{
  title: "List Basecamp Messages",
  description: `List messages in a Basecamp message board`,
  inputSchema: {
    bucket_id: BasecampIdSchema.describe("Project/bucket ID"),
    message_board_id: BasecampIdSchema.describe("Message board ID"),
    filter: z
      .string()
      .optional()
      .describe(
        "Optional regular expression to filter messages by title or content",
      ),
  },
  annotations: {
    readOnlyHint: true,
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: true,
  },
},

src/tools/messages.ts:83-151 (registration)

The server.registerTool call that registers the basecamp_list_messages tool with its schema and handler within the registerMessageTools function.

server.registerTool(
  "basecamp_list_messages",
  {
    title: "List Basecamp Messages",
    description: `List messages in a Basecamp message board`,
    inputSchema: {
      bucket_id: BasecampIdSchema.describe("Project/bucket ID"),
      message_board_id: BasecampIdSchema.describe("Message board ID"),
      filter: z
        .string()
        .optional()
        .describe(
          "Optional regular expression to filter messages by title or content",
        ),
    },
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true,
    },
  },
  async (params) => {
    try {
      const client = await initializeBasecampClient();
      const messages = await asyncPagedToArray({
        fetchPage: client.messages.list,
        request: {
          params: {
            bucketId: params.bucket_id,
            messageBoardId: params.message_board_id,
          },
          query: {},
        },
      });

      // Apply filter if provided
      let filteredMessages = messages;
      if (params.filter) {
        const regex = new RegExp(params.filter, "i");
        filteredMessages = messages.filter(
          (m) => regex.test(m.title) || regex.test(m.content || ""),
        );
      }

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              filteredMessages.map((m) => ({
                id: m.id,
                title: m.title,
                creator: serializePerson(m.creator),
                created_at: m.created_at,
              })),
              null,
              2,
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: handleBasecampError(error) }],
      };
    }
  },
);

src/index.ts:62-62 (registration)
Top-level call to registerMessageTools(server) in the main server initialization, which includes registration of basecamp_list_messages.
```
registerMessageTools(server);
```
src/schemas/common.ts:10-12 (schema)
Reusable BasecampIdSchema (z.number()) used in the input schema for bucket_id and message_board_id parameters.
```
export const BasecampIdSchema = z
  .number()
  .describe("Basecamp resource identifier");
```

Basecamp MCP Server