create_program_edition

Instructions

Implementation Reference

• src/tools/program_editions.ts:94-102 (handler)

  The handler function for the create_program_edition tool. It receives the validated body (program_id, name, etc.), makes a POST request to /program/editions, logs the response, and returns a formatted success result.

  async (body) => {
    try {
      const record = await apiPost<EduframeRecord>("/program/editions", body);
      void logResponse("create_program_edition", body, record);
      return formatCreate(record, "program edition");
    } catch (error) {
      return formatError(error);
    }
  },

• src/tools/program_editions.ts:65-92 (schema)

  Input schema for create_program_edition. Defines the Zod validation for fields: program_id (required), name (required), start_date, end_date, cost, cost_scheme (enum: student/order/tbd/free), min_participants, max_participants, is_published, custom, and custom_associations.

  description: "Create a program edition",
  annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
  inputSchema: {
    program_id: z.number().int().describe("Unique identifier of associated program."),
    name: z.string().describe("Name of the program edition."),
    start_date: z.string().optional().describe("Nominal start date of the edition."),
    end_date: z.string().optional().describe("Nominal end date of the edition (inclusive)."),
    cost: z
      .number()
      .optional()
      .describe(
        "The price to be paid for this edition. Required if cost_scheme is student (default value) or order.",
      ),
    cost_scheme: programEditionCostSchemeEnum.optional().describe("How should the edition be paid by default."),
    min_participants: z
      .number()
      .int()
      .optional()
      .describe("A number representing the minimum number of participants."),
    max_participants: z
      .number()
      .int()
      .optional()
      .describe("A number representing the maximum number of participants."),
    is_published: z.boolean().optional().describe("Boolean representing the publishable status of the edition."),
    custom: z.record(z.unknown()).optional(),
    custom_associations: z.record(z.unknown()).optional(),
  },

• src/tools/program_editions.ts:62-103 (registration)

  Registration of the create_program_edition tool via server.registerTool() with the name 'create_program_edition', the input schema, and the handler function.

  server.registerTool(
    "create_program_edition",
    {
      description: "Create a program edition",
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
      inputSchema: {
        program_id: z.number().int().describe("Unique identifier of associated program."),
        name: z.string().describe("Name of the program edition."),
        start_date: z.string().optional().describe("Nominal start date of the edition."),
        end_date: z.string().optional().describe("Nominal end date of the edition (inclusive)."),
        cost: z
          .number()
          .optional()
          .describe(
            "The price to be paid for this edition. Required if cost_scheme is student (default value) or order.",
          ),
        cost_scheme: programEditionCostSchemeEnum.optional().describe("How should the edition be paid by default."),
        min_participants: z
          .number()
          .int()
          .optional()
          .describe("A number representing the minimum number of participants."),
        max_participants: z
          .number()
          .int()
          .optional()
          .describe("A number representing the maximum number of participants."),
        is_published: z.boolean().optional().describe("Boolean representing the publishable status of the edition."),
        custom: z.record(z.unknown()).optional(),
        custom_associations: z.record(z.unknown()).optional(),
      },
    },
    async (body) => {
      try {
        const record = await apiPost<EduframeRecord>("/program/editions", body);
        void logResponse("create_program_edition", body, record);
        return formatCreate(record, "program edition");
      } catch (error) {
        return formatError(error);
      }
    },
  );

• src/tools/index.ts:128-132 (registration)

  The registerAllTools function iterates over all tool registration functions, including registerProgramEditionTools which registers create_program_edition.

  export function registerAllTools(server: McpServer): void {
    for (const register of tools) {
      register(server);
    }
  }

• src/api.ts:157-229 (helper)

  The apiPost helper function used by the handler to call the Eduframe API via POST to /program/editions.

  /**
   * Perform a POST request to create a resource.
   *
   * @param path - API path, e.g. "/leads"
   * @param body - Request body
   */
  export async function apiPost<T>(path: string, body: unknown): Promise<T> {
    const { token } = getConfig();
    const url = buildUrl(path);
  
    const response = await fetch(url.toString(), {
      method: "POST",
      headers: buildHeaders(token),
      body: JSON.stringify(body),
    });
  
    return handleResponse<T>(response);
  }
  
  /**
   * Perform a PUT request to update a resource.
   *
   * @param path - API path, e.g. "/leads/1"
   * @param body - Request body
   */
  export async function apiPut<T>(path: string, body: unknown): Promise<T> {
    const { token } = getConfig();
    const url = buildUrl(path);
  
    const response = await fetch(url.toString(), {
      method: "PUT",
      headers: buildHeaders(token),
      body: JSON.stringify(body),
    });
  
    return handleResponse<T>(response);
  }
  
  /**
   * Perform a PATCH request to partially update a resource.
   *
   * @param path - API path, e.g. "/leads/1"
   * @param body - Request body
   */
  export async function apiPatch<T>(path: string, body: unknown): Promise<T> {
    const { token } = getConfig();
    const url = buildUrl(path);
  
    const response = await fetch(url.toString(), {
      method: "PATCH",
      headers: buildHeaders(token),
      body: JSON.stringify(body),
    });
  
    return handleResponse<T>(response);
  }
  
  /**
   * Perform a DELETE request to remove a resource.
   *
   * @param path - API path, e.g. "/leads/1"
   */
  export async function apiDelete<T>(path: string): Promise<T> {
    const { token } = getConfig();
    const url = buildUrl(path);
  
    const response = await fetch(url.toString(), {
      method: "DELETE",
      headers: buildHeaders(token),
    });
  
    return handleResponse<T>(response);
  }