basecamp_list_todos

Retrieve active or archived tasks from a Basecamp todo list to track project progress and manage workflow.

Instructions

List todos in a todo list. Filter by status: 'active' or 'archived'.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`bucket_id`	Yes	Basecamp resource identifier
`todolist_id`	Yes
`status`	No		active
`completed`	No

Implementation Reference

src/tools/todos.ts:112-151 (handler)

The asynchronous handler function that lists todos in a Basecamp todo list. It uses the Basecamp client to fetch paged todos, serializes assignees, and returns a structured JSON response with count and todo details.

async (params) => {
  try {
    const client = await initializeBasecampClient();
    const todos = await asyncPagedToArray({
      fetchPage: client.todos.list,
      request: {
        params: {
          bucketId: params.bucket_id,
          todolistId: params.todolist_id,
        },
        query: { status: params.status, completed: params.completed },
      },
    });

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              count: todos.length,
              todos: todos.map((t) => ({
                id: t.id,
                title: t.content,
                completed: t.completed,
                assignees: t.assignees.map(serializePerson),
              })),
            },
            null,
            2,
          ),
        },
      ],
    };
  } catch (error) {
    return {
      content: [{ type: "text", text: handleBasecampError(error) }],
    };
  }
},

src/tools/todos.ts:93-152 (registration)

Registers the 'basecamp_list_todos' tool on the MCP server, defining its title, description, input schema (using Zod), annotations, and references the handler function.

server.registerTool(
  "basecamp_list_todos",
  {
    title: "List Basecamp Todos",
    description:
      "List todos in a todo list. Filter by status: 'active' or 'archived'.",
    inputSchema: {
      bucket_id: BasecampIdSchema,
      todolist_id: BasecampIdSchema,
      status: z.enum(["active", "archived"]).default("active").optional(),
      completed: z.enum(["true"]).optional(),
    },
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true,
    },
  },
  async (params) => {
    try {
      const client = await initializeBasecampClient();
      const todos = await asyncPagedToArray({
        fetchPage: client.todos.list,
        request: {
          params: {
            bucketId: params.bucket_id,
            todolistId: params.todolist_id,
          },
          query: { status: params.status, completed: params.completed },
        },
      });

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                count: todos.length,
                todos: todos.map((t) => ({
                  id: t.id,
                  title: t.content,
                  completed: t.completed,
                  assignees: t.assignees.map(serializePerson),
                })),
              },
              null,
              2,
            ),
          },
        ],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: handleBasecampError(error) }],
      };
    }
  },
);

src/tools/todos.ts:99-104 (schema)

Input schema for the basecamp_list_todos tool, validating bucket_id, todolist_id (using BasecampIdSchema), status, and completed parameters.

inputSchema: {
  bucket_id: BasecampIdSchema,
  todolist_id: BasecampIdSchema,
  status: z.enum(["active", "archived"]).default("active").optional(),
  completed: z.enum(["true"]).optional(),
},

src/schemas/common.ts:10-12 (schema)
Reusable Zod schema for Basecamp IDs (number), used in basecamp_list_todos input schema for bucket_id and todolist_id.
```
export const BasecampIdSchema = z
  .number()
  .describe("Basecamp resource identifier");
```
src/index.ts:63-63 (registration)
Top-level call to registerTodoTools on the MCP server instance, which includes registration of basecamp_list_todos among other todo-related tools.
```
registerTodoTools(server);
```

Basecamp MCP Server