create_shelf
Create a new shelf in BookStack to organize books by adding a name, description, and optional books or tags.
Instructions
Create a new shelf
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Shelf name (required, max 255 chars) | |
| description | No | Shelf description (plain text) | |
| description_html | No | Shelf description (HTML format) | |
| books | No | Array of book IDs to add to shelf | |
| tags | No | Array of tags with name and value |
Implementation Reference
- src/tools/content-tools.ts:745-753 (handler)Main execution logic for the 'create_shelf' MCP tool: validates arguments using Zod schema, converts tags to proper format, invokes BookStackClient.createShelf API wrapper, and returns a formatted JSON response.
case "create_shelf": { const validatedData = CreateShelfSchema.parse(args); const data = { ...validatedData, tags: convertTags(validatedData.tags), }; const result = await client.createShelf(data); return formatApiResponse(result); } - src/lib/validation.ts:70-76 (schema)Zod runtime validation schema for 'create_shelf' tool inputs, used in the handler to parse and validate arguments.
export const CreateShelfSchema = z.object({ name: z.string().min(1).max(255), description: z.string().optional(), description_html: z.string().optional(), books: z.array(z.number()).optional(), tags: z.array(TagSchema).optional(), }); - src/tools/content-tools.ts:447-486 (registration)MCP Tool registration object defining name, description, and inputSchema for 'create_shelf', returned by createContentTools().
{ name: "create_shelf", description: "Create a new shelf", inputSchema: { type: "object", properties: { name: { type: "string", description: "Shelf name (required, max 255 chars)", }, description: { type: "string", description: "Shelf description (plain text)", }, description_html: { type: "string", description: "Shelf description (HTML format)", }, books: { type: "array", description: "Array of book IDs to add to shelf", items: { type: "number" }, }, tags: { type: "array", description: "Array of tags with name and value", items: { type: "object", properties: { name: { type: "string" }, value: { type: "string" }, order: { type: "number" }, }, required: ["name", "value"], }, }, }, required: ["name"], }, }, - src/index.ts:56-59 (registration)Combines content tools (including create_shelf) with other tools into allTools list, used for MCP server tool listing.
const allTools: Tool[] = [ ...createContentTools(bookStackClient), ...createSearchAndUserTools(bookStackClient), ]; - src/lib/bookstack-client.ts:267-269 (helper)BookStackClient helper method that performs the actual API POST request to create a shelf.
async createShelf(data: CreateShelfRequest): Promise<Shelf> { return this.post<Shelf>("/shelves", data); } - src/tools/content-tools.ts:21-30 (helper)Helper function to convert input tags to the proper Tag format expected by BookStack API.
function convertTags( inputTags?: { name: string; value: string; order?: number }[] ): Tag[] | undefined { if (!inputTags) return undefined; return inputTags.map((tag) => ({ name: tag.name, value: tag.value, order: tag.order ?? 0, })); }