get_planned_courses_by_course_id

Instructions

Implementation Reference

• src/tools/planned_courses.ts:39-93 (handler)

  Async handler function that calls apiList with the course_id and filter params, formats the result, and returns planned course records.

  async ({
    course_id,
    cursor,
    per_page,
    search,
    type,
    parents_published,
    published_public,
    start_date_from,
    start_date_until,
    availability_state,
    status,
    sort,
  }) => {
    try {
      const result = await apiList<EduframeRecord>(`/courses/${course_id}/planned_courses`, {
        cursor,
        per_page,
        search,
        type,
        parents_published,
        published_public,
        start_date_from,
        start_date_until,
        availability_state,
        status,
        sort,
      });
      void logResponse(
        "get_planned_courses_by_course_id",
        {
          course_id,
          cursor,
          per_page,
          search,
          type,
          parents_published,
          published_public,
          start_date_from,
          start_date_until,
          availability_state,
          status,
          sort,
        },
        result,
      );
      const toolResult = formatList(result.records, "planned courses");
      if (result.nextCursor) {
        toolResult.content.push({ type: "text", text: `\nNext page cursor: ${result.nextCursor}` });
      }
      return toolResult;
    } catch (error) {
      return formatError(error);
    }
  },

• src/tools/planned_courses.ts:13-37 (schema)

  Input schema definition for the tool: course_id (required), plus optional cursor, per_page, search, type, parents_published, published_public, start_date_from, start_date_until, availability_state, status, and sort parameters.

  {
    description: "Get all planned course records of a single course",
    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
    inputSchema: {
      course_id: z.number().int().positive().describe("ID of the parent resource"),
      cursor: z.string().optional().describe("Cursor for fetching the next page of results"),
      per_page: z.number().int().positive().optional().describe("Number of results per page (default: 25)"),
      search: z.string().optional().describe("Filter results on search"),
      type: z.enum(["FixedPlannedCourse", "FlexiblePlannedCourse"]).optional().describe("Filter results on type"),
      parents_published: z.enum(["parents_published"]).optional().describe("Filter results on parents_published"),
      published_public: z
        .enum(["published_public"])
        .optional()
        .describe("Only show courses that are published and are either planned or in progress"),
      start_date_from: z.string().optional().describe("Filter results on start_date_from"),
      start_date_until: z.string().optional().describe("Filter results on start_date_until"),
      availability_state: z.enum(["open", "closed"]).optional().describe("Filter results on availability_state"),
      status: z.enum(["planned", "active", "completed", "canceled"]).optional().describe("Filter results on status"),
      sort: z
        .array(z.enum(["start_date:asc", "start_date:desc"]))
        .optional()
        .describe(
          "Sort the results. Can change order by using `<sort_by>:<direction>` where `<direction>` is either `asc` or `desc`",
        ),
    },

• src/tools/planned_courses.ts:10-12 (registration)

  The tool is registered via server.registerTool() with the name "get_planned_courses_by_course_id" inside the registerPlannedCourseTools function.

  export function registerPlannedCourseTools(server: McpServer): void {
    server.registerTool(
      "get_planned_courses_by_course_id",

• src/tools/index.ts:40-103 (registration)

  Import and registration of registerPlannedCourseTools in the central tools index, wired into the registerAllTools function.

  import { registerPlannedCourseTools } from "./planned_courses";
  import { registerPlanningAttendeeTools } from "./planning_attendees";
  import { registerPlanningConflictTools } from "./planning_conflicts";
  import { registerPlanningEventTools } from "./planning_events";
  import { registerPlanningLocationTools } from "./planning_locations";
  import { registerPlanningMaterialTools } from "./planning_materials";
  import { registerPlanningRequiredTeacherGroupAttendeeTools } from "./planning_required_teacher_group_attendees";
  import { registerPlanningTeacherTools } from "./planning_teachers";
  import { registerProgramEditionTools } from "./program_editions";
  import { registerProgramElementTools } from "./program_elements";
  import { registerProgramEnrollmentTools } from "./program_enrollments";
  import { registerProgramPersonalProgramElementTools } from "./program_personal_program_elements";
  import { registerProgramProgramTools } from "./program_programs";
  import { registerReferralTools } from "./referrals";
  import { registerSignupQuestionTools } from "./signup_questions";
  import { registerTaskTools } from "./tasks";
  import { registerTeacherEnrollmentTools } from "./teacher_enrollments";
  import { registerTeacherRoleTools } from "./teacher_roles";
  import { registerTeacherTools } from "./teachers";
  import { registerTheseTools } from "./theses";
  import { registerUserTools } from "./users";
  import { registerWebhookNotificationTools } from "./webhook_notifications";
  import { registerWebhookTools } from "./webhooks";
  
  const tools: Array<(server: McpServer) => void> = [
    registerAccountTools,
    registerAffiliationTools,
    registerAttendanceTools,
    registerAuthenticationTools,
    registerCatalogProductTools,
    registerCatalogVariantTools,
    registerCategorieTools,
    registerCertificateTools,
    registerCommentTools,
    registerCourseLocationTools,
    registerCourseTabTools,
    registerCourseVariantTools,
    registerCourseTools,
    registerCreditCategorieTools,
    registerCreditTools,
    registerCustomAssociationTools,
    registerCustomFieldOptionTools,
    registerCustomObjectTools,
    registerCustomRecordTools,
    registerDiscountCodeTools,
    registerEditionDescriptionSectionTools,
    registerEducatorTools,
    registerEmailTools,
    registerEnrollmentTools,
    registerGradeTools,
    registerInvoiceVatTools,
    registerInvoiceTools,
    registerLabelTools,
    registerLeadTools,
    registerMaterialGroupTools,
    registerMaterialTools,
    registerMeetingLocationTools,
    registerMeetingTools,
    registerOrderTools,
    registerOrganizationTools,
    registerPaymentMethodTools,
    registerPaymentOptionTools,
    registerPaymentTools,
    registerPlannedCourseTools,

• src/api.ts:122-137 (helper)

  The apiList helper function performs the actual GET request to the API with cursor-based pagination, builds the URL with query params, and returns records with nextCursor.

  export async function apiList<T>(path: string, query?: Record<string, QueryValue>): Promise<ListResult<T>> {
    const { token } = getConfig();
    const url = buildUrl(path, query);
  
    const response = await fetch(url.toString(), {
      method: "GET",
      headers: buildHeaders(token),
    });
  
    await checkResponse(response);
  
    const records = (await response.json()) as T[];
    const nextCursor = parseNextCursor(response.headers.get("Link"));
  
    return { records, nextCursor };
  }