BookStack MCP Server

Instructions

Implementation Reference

• src/tools/content-tools.ts:621-628 (handler)

  The handler function for the 'create_chapter' tool. Validates input arguments using CreateChapterSchema, processes tags, calls the BookStackClient.createChapter method, and returns a formatted API response.

  case "create_chapter": {
    const validatedData = CreateChapterSchema.parse(args);
    const data = {
      ...validatedData,
      tags: convertTags(validatedData.tags),
    };
    const result = await client.createChapter(data);
    return formatApiResponse(result);

• src/tools/content-tools.ts:187-226 (registration)

  MCP Tool registration definition for 'create_chapter', including the name, description, and JSON input schema used by the MCP server.

  {
    name: "create_chapter",
    description: "Create a new chapter in a book",
    inputSchema: {
      type: "object",
      properties: {
        book_id: { type: "number", description: "Parent book ID" },
        name: {
          type: "string",
          description: "Chapter name (required, max 255 chars)",
        },
        description: {
          type: "string",
          description: "Chapter description (plain text)",
        },
        description_html: {
          type: "string",
          description: "Chapter description (HTML format)",
        },
        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"],
          },
        },
        priority: { type: "number", description: "Chapter priority/order" },
        default_template_id: {
          type: "number",
          description: "Default template ID for new pages",
        },
      },
      required: ["book_id", "name"],
    },

• src/lib/validation.ts:29-37 (schema)

  Zod validation schema (CreateChapterSchema) used to parse and validate tool input arguments in the handler.

  export const CreateChapterSchema = z.object({
    book_id: z.number(),
    name: z.string().min(1).max(255),
    description: z.string().optional(),
    description_html: z.string().optional(),
    tags: z.array(TagSchema).optional(),
    priority: z.number().optional(),
    default_template_id: z.number().optional(),
  });

• src/lib/bookstack-client.ts:155-157 (helper)

  BookStackClient helper method that performs the actual HTTP POST request to the BookStack API endpoint '/chapters' to create the chapter.

  async createChapter(data: CreateChapterRequest): Promise<Chapter> {
    return this.post<Chapter>("/chapters", data);
  }

• src/types/index.ts:278-286 (schema)

  TypeScript interface defining the shape of CreateChapterRequest data passed to the client method.

  export interface CreateChapterRequest {
    book_id: number;
    name: string;
    description?: string;
    description_html?: string;
    tags?: Tag[];
    priority?: number;
    default_template_id?: number;
  }