Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/todosets.ts:70-90 (handler)

  Executes the list_todolists tool: resolves todoset from project dock, fetches todolists via API, formats as numbered list.

  async ({ project_id }) => {
    const resolved = await getTodosetFromDock(project_id);
    if (!resolved) {
      return {
        content: [
          { type: "text", text: "No to-do set found in the project's dock." },
        ],
      };
    }
    const lists = await bcRequest<any[]>(
      "GET",
      `/buckets/${project_id}/todosets/${resolved.id}/todolists.json`
    );
    const text =
      Array.isArray(lists) && lists.length
        ? lists.map((t: any) => `${t.id}: ${t.name}`).join("\n")
        : "No to-do lists found.";
    return {
      content: [{ type: "text", text: `To-do set ${resolved.id}\n${text}` }],
    };
  }

• src/tools/todosets.ts:64-69 (schema)

  Input schema, title, and description for the list_todolists tool.

  {
    title: "List to-do lists for a project",
    description:
      "Resolves the project's to-do set from dock, then lists its to-do lists.",
    inputSchema: { project_id: z.number().int() },
  },

• src/tools/todosets.ts:62-91 (registration)

  Direct registration of the list_todolists tool within registerTodosetTools function.

  server.registerTool(
    "list_todolists",
    {
      title: "List to-do lists for a project",
      description:
        "Resolves the project's to-do set from dock, then lists its to-do lists.",
      inputSchema: { project_id: z.number().int() },
    },
    async ({ project_id }) => {
      const resolved = await getTodosetFromDock(project_id);
      if (!resolved) {
        return {
          content: [
            { type: "text", text: "No to-do set found in the project's dock." },
          ],
        };
      }
      const lists = await bcRequest<any[]>(
        "GET",
        `/buckets/${project_id}/todosets/${resolved.id}/todolists.json`
      );
      const text =
        Array.isArray(lists) && lists.length
          ? lists.map((t: any) => `${t.id}: ${t.name}`).join("\n")
          : "No to-do lists found.";
      return {
        content: [{ type: "text", text: `To-do set ${resolved.id}\n${text}` }],
      };
    }
  );

• src/tools/todosets.ts:6-17 (helper)

  Helper to resolve todoset ID and URL from a project's Basecamp dock, used by list_todolists.

  async function getTodosetFromDock(
    project_id: number
  ): Promise<{ id: number; url: string } | null> {
    const project = await bcRequest<any>("GET", `/projects/${project_id}.json`);
    const dock = Array.isArray(project?.dock) ? project.dock : [];
    const todoset = dock.find((d: any) => (d?.name || d?.app_name) === "todoset");
    if (!todoset) return null;
    const href: string =
      todoset.url || todoset.href || todoset.api_url || todoset.app_url || "";
    const m = href.match(/\/todosets\/(\d+)/);
    return m ? { id: Number(m[1]), url: href } : null;
  }

• src/basecamp-mcp.ts:13-13 (registration)

  Top-level registration call that invokes the function registering list_todolists.

  registerTodosetTools(server);