Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/todosets.ts:32-58 (handler)

  Executes the core logic of the 'get_todoset' tool: resolves the todoset ID and URL from the Basecamp project dock, and optionally fetches the list of todo lists.

  async ({ project_id, include_lists }) => {
    const resolved = await getTodosetFromDock(project_id);
    if (!resolved) {
      return {
        content: [
          { type: "text", text: "No to-do set found in the project's dock." },
        ],
      };
    }
    if (!include_lists) {
      return {
        content: [{ type: "text", text: JSON.stringify(resolved, null, 2) }],
      };
    }
    const lists = await bcRequest<any[]>(
      "GET",
      `/buckets/${project_id}/todosets/${resolved.id}/todolists.json`
    );
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ todoset: resolved, lists }, null, 2),
        },
      ],
    };
  }

• src/tools/todosets.ts:23-30 (schema)

  Input schema, title, and description for the 'get_todoset' tool, using Zod for validation.

  {
    title: "Get a project's to-do set (via dock)",
    description:
      "Resolves the project's to-do set by reading the dock; can include lists.",
    inputSchema: {
      project_id: z.number().int(),
      include_lists: z.boolean().optional(),
    },

• src/tools/todosets.ts:21-59 (registration)

  Registers the 'get_todoset' tool on the MCP server with its name, schema, and handler function.

  server.registerTool(
    "get_todoset",
    {
      title: "Get a project's to-do set (via dock)",
      description:
        "Resolves the project's to-do set by reading the dock; can include lists.",
      inputSchema: {
        project_id: z.number().int(),
        include_lists: z.boolean().optional(),
      },
    },
    async ({ project_id, include_lists }) => {
      const resolved = await getTodosetFromDock(project_id);
      if (!resolved) {
        return {
          content: [
            { type: "text", text: "No to-do set found in the project's dock." },
          ],
        };
      }
      if (!include_lists) {
        return {
          content: [{ type: "text", text: JSON.stringify(resolved, null, 2) }],
        };
      }
      const lists = await bcRequest<any[]>(
        "GET",
        `/buckets/${project_id}/todosets/${resolved.id}/todolists.json`
      );
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({ todoset: resolved, lists }, null, 2),
          },
        ],
      };
    }
  );

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

  Helper function that queries the Basecamp project dock to extract the todoset ID and URL.

  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)

  Invokes registerTodosetTools to register the todoset-related tools, including 'get_todoset', on the main MCP server.

  registerTodosetTools(server);