BookStack MCP Server

Instructions

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