create_role
Create a new user role in BookStack with customizable permissions, display names, and descriptions to manage access control within your wiki.
Instructions
Create a new role
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| display_name | Yes | Display name for the role (required) | |
| description | No | Role description | |
| external_auth_id | No | External authentication ID | |
| permissions | No | Array of permission names to assign to the role |
Implementation Reference
- src/tools/search-user-tools.ts:434-451 (handler)The handler function for the 'create_role' tool within handleSearchAndUserTool. Extracts and validates input arguments, constructs the data object, invokes BookStackClient.createRole, and formats the response.
case "create_role": { const { display_name, description, external_auth_id, permissions } = args; if (!display_name) { throw new Error("display_name is required"); } const data = { display_name, description, external_auth_id, permissions: permissions || [], }; const result = await client.createRole(data); return formatApiResponse(result); } - src/tools/search-user-tools.ts:174-197 (registration)Tool registration object in createSearchAndUserTools function array, including name, description, and inputSchema (JSON schema for validation). This defines the MCP tool.
{ name: "create_role", description: "Create a new role", inputSchema: { type: "object", properties: { display_name: { type: "string", description: "Display name for the role (required)", }, description: { type: "string", description: "Role description" }, external_auth_id: { type: "string", description: "External authentication ID", }, permissions: { type: "array", description: "Array of permission names to assign to the role", items: { type: "string" }, }, }, required: ["display_name"], }, }, - src/lib/bookstack-client.ts:320-322 (helper)BookStackClient helper method that wraps the axios POST request to the BookStack /roles endpoint to create a new role.
async createRole(data: CreateRoleRequest): Promise<Role> { return this.post<Role>("/roles", data); } - src/types/index.ts:316-322 (schema)TypeScript interface defining the CreateRoleRequest type used by the client.createRole method.
export interface CreateRoleRequest { display_name: string; description?: string; mfa_enforced?: boolean; external_auth_id?: string; permissions?: string[]; } - src/lib/validation.ts:92-100 (schema)Zod validation schema for CreateRoleRequest, providing runtime validation (though manual validation is used in handler).
export const CreateRoleSchema = z.object({ display_name: z.string().min(3).max(180), description: z.string().max(180).optional(), mfa_enforced: z.boolean().optional(), external_auth_id: z.string().max(180).optional(), permissions: z.array(z.string()).optional(), }); export const UpdateRoleSchema = CreateRoleSchema.partial();