BookStack MCP Server

Instructions

Implementation Reference

• src/tools/search-user-tools.ts:369-400 (handler)

  Handler logic for the 'create_user' tool in handleSearchAndUserTool function. Validates inputs, constructs data object, calls BookStackClient.createUser, and formats response.

  case "create_user": {
    const {
      name,
      email,
      password,
      roles,
      language,
      external_auth_id,
      send_invite,
    } = args;
  
    if (!name || !email || !password) {
      throw new Error("name, email, and password are required");
    }
  
    if (password.length < 8) {
      throw new Error("Password must be at least 8 characters long");
    }
  
    const data = {
      name,
      email,
      password,
      roles: roles || [],
      language,
      external_auth_id,
      send_invite,
    };
  
    const result = await client.createUser(data);
    return formatApiResponse(result);
  }

• src/tools/search-user-tools.ts:61-99 (registration)

  Tool registration object defining the 'create_user' tool, including name, description, and inputSchema. Returned by createSearchAndUserTools and included in MCP server's tool list.

  {
    name: "create_user",
    description: "Create a new user account",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "Full name of the user (required)",
        },
        email: {
          type: "string",
          description: "Email address (required, must be unique)",
        },
        password: {
          type: "string",
          description: "Password (required, min 8 characters)",
        },
        roles: {
          type: "array",
          description: "Array of role IDs to assign to the user",
          items: { type: "number" },
        },
        language: {
          type: "string",
          description: "User interface language code",
        },
        external_auth_id: {
          type: "string",
          description: "External authentication ID",
        },
        send_invite: {
          type: "boolean",
          description: "Send invitation email to user",
        },
      },
      required: ["name", "email", "password"],
    },
  },

• src/lib/validation.ts:80-88 (schema)

  Zod schema for user creation input validation (CreateUserSchema), matching the tool's inputSchema.

  export const CreateUserSchema = z.object({
    name: z.string().min(1).max(100),
    email: z.string().email(),
    external_auth_id: z.string().optional(),
    language: z.string().max(15).optional(),
    password: z.string().min(8).optional(),
    roles: z.array(z.number()).optional(),
    send_invite: z.boolean().optional(),
  });

• src/lib/bookstack-client.ts:292-293 (helper)

  BookStackClient method that performs the actual API POST to /users endpoint to create the user.

  async createUser(data: CreateUserRequest): Promise<User> {
    return this.post<User>("/users", data);

• src/types/index.ts:306-314 (schema)

  TypeScript interface defining the shape of CreateUserRequest used by the client and handler.

  export interface CreateUserRequest {
    name: string;
    email: string;
    external_auth_id?: string;
    language?: string;
    password?: string;
    roles?: number[];
    send_invite?: boolean;
  }