create_user

Instructions

Implementation Reference

• src/tools/users.ts:62-123 (handler)

  The handler function for the 'create_user' tool. It accepts the validated input body, calls apiPost to POST /users, logs the response, and formats the result using formatCreate.

  server.registerTool(
    "create_user",
    {
      description: "Create a user.",
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
      inputSchema: {
        first_name: z.string().describe("First name of the user."),
        middle_name: z.string().optional().describe("Middle name of the user."),
        last_name: z.string().describe("Last name of the user."),
        email: z.string().describe("The e-mail of the user."),
        locale: userLocaleEnum.optional(),
        wants_newsletter: z
          .boolean()
          .optional()
          .describe("Boolean representing the possibility of the user to receive newsletters."),
        with_authentication: z
          .boolean()
          .optional()
          .describe(
            "If the user should be able to login and thus receive login details by mail. Only relevant when creating the user.",
          ),
        custom: z.object({}).optional().describe("The custom properties of the user."),
        address_attributes: z
          .object({
            addressee: z.string().optional().describe("The addressee of the address."),
            address: z.string().describe("Concatenation of the street and house number."),
            address_line2: z.string().optional().describe("A string representing the second line of the address."),
            postal_code: z.string().describe("A string representing the postal code."),
            city: z.string().describe("A string representing the city."),
            state_province: z.string().optional().describe("An letter USA state code."),
            country: z.string().describe("An ISO3166 two-letter country code."),
          })
          .optional(),
        invoice_address_attributes: z
          .object({
            addressee: z.string().optional().describe("The addressee of the address."),
            address: z.string().describe("Concatenation of the street and house number."),
            address_line2: z.string().optional().describe("A string representing the second line of the address."),
            postal_code: z.string().describe("A string representing the postal code."),
            city: z.string().describe("A string representing the city."),
            state_province: z.string().optional().describe("An letter USA state code."),
            country: z.string().describe("An ISO3166 two-letter country code."),
          })
          .optional(),
        label_ids: z
          .array(z.number().int())
          .optional()
          .describe(
            "An array containing the identifiers of the labels associated with the user. When updating this array, the existing labels are replaced with the new ones provided.\n",
          ),
      },
    },
    async (body) => {
      try {
        const record = await apiPost<EduframeRecord>("/users", body);
        void logResponse("create_user", body, record);
        return formatCreate(record, "user");
      } catch (error) {
        return formatError(error);
      }
    },
  );

• src/tools/users.ts:67-112 (schema)

  Input schema (inputSchema) for create_user, defined inline using Zod for validation. Includes fields like first_name, middle_name, last_name, email, locale, wants_newsletter, with_authentication, custom, address_attributes, invoice_address_attributes, and label_ids.

  inputSchema: {
    first_name: z.string().describe("First name of the user."),
    middle_name: z.string().optional().describe("Middle name of the user."),
    last_name: z.string().describe("Last name of the user."),
    email: z.string().describe("The e-mail of the user."),
    locale: userLocaleEnum.optional(),
    wants_newsletter: z
      .boolean()
      .optional()
      .describe("Boolean representing the possibility of the user to receive newsletters."),
    with_authentication: z
      .boolean()
      .optional()
      .describe(
        "If the user should be able to login and thus receive login details by mail. Only relevant when creating the user.",
      ),
    custom: z.object({}).optional().describe("The custom properties of the user."),
    address_attributes: z
      .object({
        addressee: z.string().optional().describe("The addressee of the address."),
        address: z.string().describe("Concatenation of the street and house number."),
        address_line2: z.string().optional().describe("A string representing the second line of the address."),
        postal_code: z.string().describe("A string representing the postal code."),
        city: z.string().describe("A string representing the city."),
        state_province: z.string().optional().describe("An letter USA state code."),
        country: z.string().describe("An ISO3166 two-letter country code."),
      })
      .optional(),
    invoice_address_attributes: z
      .object({
        addressee: z.string().optional().describe("The addressee of the address."),
        address: z.string().describe("Concatenation of the street and house number."),
        address_line2: z.string().optional().describe("A string representing the second line of the address."),
        postal_code: z.string().describe("A string representing the postal code."),
        city: z.string().describe("A string representing the city."),
        state_province: z.string().optional().describe("An letter USA state code."),
        country: z.string().describe("An ISO3166 two-letter country code."),
      })
      .optional(),
    label_ids: z
      .array(z.number().int())
      .optional()
      .describe(
        "An array containing the identifiers of the labels associated with the user. When updating this array, the existing labels are replaced with the new ones provided.\n",
      ),
  },

• src/tools/users.ts:62-123 (registration)

  Tool registration via server.registerTool() call in registerUserTools function, called from src/tools/index.ts when all tools are registered.

  server.registerTool(
    "create_user",
    {
      description: "Create a user.",
      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
      inputSchema: {
        first_name: z.string().describe("First name of the user."),
        middle_name: z.string().optional().describe("Middle name of the user."),
        last_name: z.string().describe("Last name of the user."),
        email: z.string().describe("The e-mail of the user."),
        locale: userLocaleEnum.optional(),
        wants_newsletter: z
          .boolean()
          .optional()
          .describe("Boolean representing the possibility of the user to receive newsletters."),
        with_authentication: z
          .boolean()
          .optional()
          .describe(
            "If the user should be able to login and thus receive login details by mail. Only relevant when creating the user.",
          ),
        custom: z.object({}).optional().describe("The custom properties of the user."),
        address_attributes: z
          .object({
            addressee: z.string().optional().describe("The addressee of the address."),
            address: z.string().describe("Concatenation of the street and house number."),
            address_line2: z.string().optional().describe("A string representing the second line of the address."),
            postal_code: z.string().describe("A string representing the postal code."),
            city: z.string().describe("A string representing the city."),
            state_province: z.string().optional().describe("An letter USA state code."),
            country: z.string().describe("An ISO3166 two-letter country code."),
          })
          .optional(),
        invoice_address_attributes: z
          .object({
            addressee: z.string().optional().describe("The addressee of the address."),
            address: z.string().describe("Concatenation of the street and house number."),
            address_line2: z.string().optional().describe("A string representing the second line of the address."),
            postal_code: z.string().describe("A string representing the postal code."),
            city: z.string().describe("A string representing the city."),
            state_province: z.string().optional().describe("An letter USA state code."),
            country: z.string().describe("An ISO3166 two-letter country code."),
          })
          .optional(),
        label_ids: z
          .array(z.number().int())
          .optional()
          .describe(
            "An array containing the identifiers of the labels associated with the user. When updating this array, the existing labels are replaced with the new ones provided.\n",
          ),
      },
    },
    async (body) => {
      try {
        const record = await apiPost<EduframeRecord>("/users", body);
        void logResponse("create_user", body, record);
        return formatCreate(record, "user");
      } catch (error) {
        return formatError(error);
      }
    },
  );

• src/api.ts:163-174 (helper)

  The apiPost helper function used by create_user to perform the HTTP POST request to the Eduframe API at '/users'.

  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);
  }

• src/formatters.ts:85-94 (helper)

  The formatCreate helper function used by create_user to format the created resource record as a human-readable success message.

  export function formatCreate(record: EduframeRecord, resourceName: string): CallToolResult {
    return {
      content: [
        {
          type: "text",
          text: `Successfully created ${resourceName}:\n\n${formatJSON(record)}${RESPONSE_LOG_HINT}`,
        },
      ],
    };
  }