Basecamp MCP Server

Instructions

Implementation Reference

• src/tools/todos.ts:23-41 (handler)

  The handler function for the 'create_todo' tool that constructs a payload and makes a POST request to the Basecamp API using bcRequest to create a new todo item.

  async ({ project_id, todolist_id, content, description, due_on }) => {
    const payload: any = { content };
    if (description) payload.description = description;
    if (due_on) payload.due_on = due_on;
  
    const todo = await bcRequest<any>(
      "POST",
      `/buckets/${project_id}/todolists/${todolist_id}/todos.json`,
      payload
    );
    return {
      content: [
        {
          type: "text",
          text: `Created to-do ${todo.id} in list ${todolist_id}.`,
        },
      ],
    };
  }

• src/tools/todos.ts:12-21 (schema)

  Zod-based input schema defining parameters for the 'create_todo' tool: project_id, todolist_id, content, optional description and due_on (YYYY-MM-DD format).

  inputSchema: {
    project_id: z.number().int(),
    todolist_id: z.number().int(),
    content: z.string(),
    description: z.string().optional(),
    due_on: z
      .string()
      .regex(/^\d{4}-\d{2}-\d{2}$/)
      .optional(), // YYYY-MM-DD
  },

• src/tools/todos.ts:7-42 (registration)

  Direct registration of the 'create_todo' tool using server.registerTool, including schema and handler.

  server.registerTool(
    "create_todo",
    {
      title: "Create a to-do",
      description: "Create a new to-do in the given list.",
      inputSchema: {
        project_id: z.number().int(),
        todolist_id: z.number().int(),
        content: z.string(),
        description: z.string().optional(),
        due_on: z
          .string()
          .regex(/^\d{4}-\d{2}-\d{2}$/)
          .optional(), // YYYY-MM-DD
      },
    },
    async ({ project_id, todolist_id, content, description, due_on }) => {
      const payload: any = { content };
      if (description) payload.description = description;
      if (due_on) payload.due_on = due_on;
  
      const todo = await bcRequest<any>(
        "POST",
        `/buckets/${project_id}/todolists/${todolist_id}/todos.json`,
        payload
      );
      return {
        content: [
          {
            type: "text",
            text: `Created to-do ${todo.id} in list ${todolist_id}.`,
          },
        ],
      };
    }
  );

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

  Invocation of registerTodoTools on the MCP server instance, which registers the 'create_todo' tool.

  registerTodoTools(server);

• src/lib/basecamp.ts:99-107 (helper)

  bcRequest utility function used in the create_todo handler to perform authenticated HTTP requests to the Basecamp API.

  export async function bcRequest<T = any>(
    method: string,
    path: string,
    body?: unknown,
    params?: Record<string, string | number | boolean>
  ): Promise<T> {
    const { data } = await bcRequestWithHeaders<T>(method, path, body, params);
    return data;
  }