Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/todos.ts:37-90 (handler)

  Handler function that fetches the specified todo set from Basecamp, retrieves all associated todo lists, and returns structured JSON data including todo set details and list summaries.

  async (params) => {
    try {
      const client = await initializeBasecampClient();
  
      const responseTodoSet = await client.todoSets.get({
        params: { bucketId: params.bucket_id, todosetId: params.todoset_id },
      });
  
      if (responseTodoSet.status !== 200 || !responseTodoSet.body) {
        throw new Error("Failed to fetch todo set");
      }
  
      const todoLists = await asyncPagedToArray({
        fetchPage: client.todoLists.list,
        request: {
          params: {
            bucketId: params.bucket_id,
            todosetId: params.todoset_id,
          },
          query: {},
        },
      });
  
      const todoSet = responseTodoSet.body;
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                id: todoSet.id,
                name: todoSet.name,
                url: todoSet.app_url,
                completed: todoSet.completed,
                todoLists: todoLists.map((list) => ({
                  id: list.id,
                  url: list.app_url,
                  title: list.title,
                  completed: list.completed,
                  position: list.position,
                })),
              },
              null,
              2,
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: handleBasecampError(error) }],
      };
    }
  },

• src/tools/todos.ts:20-91 (registration)

  Registers the basecamp_get_todoset tool with the MCP server, defining its title, description, input schema (using BasecampIdSchema for IDs), annotations, and references the handler function.

  server.registerTool(
    "basecamp_get_todoset",
    {
      title: "Get Basecamp Todo Set",
      description:
        "Get todo set container for a project. Returns todo lists and groups.",
      inputSchema: {
        bucket_id: BasecampIdSchema,
        todoset_id: BasecampIdSchema,
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: true,
      },
    },
    async (params) => {
      try {
        const client = await initializeBasecampClient();
  
        const responseTodoSet = await client.todoSets.get({
          params: { bucketId: params.bucket_id, todosetId: params.todoset_id },
        });
  
        if (responseTodoSet.status !== 200 || !responseTodoSet.body) {
          throw new Error("Failed to fetch todo set");
        }
  
        const todoLists = await asyncPagedToArray({
          fetchPage: client.todoLists.list,
          request: {
            params: {
              bucketId: params.bucket_id,
              todosetId: params.todoset_id,
            },
            query: {},
          },
        });
  
        const todoSet = responseTodoSet.body;
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(
                {
                  id: todoSet.id,
                  name: todoSet.name,
                  url: todoSet.app_url,
                  completed: todoSet.completed,
                  todoLists: todoLists.map((list) => ({
                    id: list.id,
                    url: list.app_url,
                    title: list.title,
                    completed: list.completed,
                    position: list.position,
                  })),
                },
                null,
                2,
              ),
            },
          ],
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: handleBasecampError(error) }],
        };
      }
    },
  );

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

  Zod schema definition for Basecamp resource IDs (numbers), used in the inputSchema for bucket_id and todoset_id parameters.

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

• src/index.ts:63-63 (registration)

  Top-level registration call in the main server file that invokes registerTodoTools to set up the basecamp_get_todoset tool among others.

  registerTodoTools(server);