create_role
Create a new user role in BookStack with custom display name, description, and permission assignments to manage access control within the wiki system.
Instructions
Create a new role
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| description | No | Role description | |
| display_name | Yes | Display name for the role (required) | |
| 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)Handler function that executes the create_role MCP tool: validates input, calls BookStackClient.createRole, formats and returns the API 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); }
- MCP Tool object definition for create_role, including inputSchema for validation.{ 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/index.ts:103-128 (registration)Registers create_role by including it in searchUserToolNames and dispatching tool calls to the appropriate handler in the MCP server's CallToolRequestSchema handler.const searchUserToolNames = [ "search_all", "list_users", "get_user", "create_user", "update_user", "delete_user", "list_roles", "get_role", "create_role", "update_role", "delete_role", "list_attachments", "get_attachment", "delete_attachment", "list_images", "get_image", "update_image", "delete_image", ]; if (contentToolNames.includes(name)) { result = await handleContentTool(name, args, bookStackClient); } else if (searchUserToolNames.includes(name)) { result = await handleSearchAndUserTool(name, args, bookStackClient); } else {
- src/index.ts:56-59 (registration)Adds the create_role tool (via createSearchAndUserTools) to the list of available MCP tools served by ListToolsRequestSchema.const allTools: Tool[] = [ ...createContentTools(bookStackClient), ...createSearchAndUserTools(bookStackClient), ];
- src/lib/bookstack-client.ts:320-322 (helper)BookStackClient helper method that performs the actual API POST request to /roles to create the role.async createRole(data: CreateRoleRequest): Promise<Role> { return this.post<Role>("/roles", data); }