BookStack MCP Server

Instructions

Implementation Reference

• src/bookstack-client.ts:702-727 (handler)

  The backend client method 'getAttachments' that performs the API request.

  async getAttachments(options?: {
    offset?: number;
    count?: number;
    sort?: string;
    filter?: Record<string, any>;
  }): Promise<ListResponse<Attachment>> {
    const params: any = {
      offset: options?.offset || 0,
      count: Math.min(options?.count || 50, 500)
    };
    
    if (options?.sort) params.sort = options.sort;
    if (options?.filter) params.filter = JSON.stringify(options.filter);
    
    const response = await this.client.get('/attachments', { params });
    const data = response.data;
    
    return {
      ...data,
      data: data.data.map((attachment: Attachment) => ({
        ...attachment,
        page_url: `${this.baseUrl}/books/${Math.floor(attachment.uploaded_to / 1000)}/page/${attachment.uploaded_to}`,
        direct_link: `[${attachment.name}](${this.baseUrl}/attachments/${attachment.id})`
      }))
    };
  }

• src/index.ts:403-425 (registration)

  MCP tool registration for 'get_attachments' and the handler implementation that calls the client.

  server.registerTool(
    "get_attachments",
    {
      title: "List Attachments",
      description: "List attachments (files and links) with filtering and sorting",
      inputSchema: {
        offset: z.coerce.number().default(0).describe("Pagination offset"),
        count: z.coerce.number().max(500).default(50).describe("Number of results to return"),
        sort: z.string().optional().describe("Sort field"),
        filter: z.record(z.any()).optional().describe("Filter criteria")
      }
    },
    async (args) => {
      const attachments = await client.getAttachments({
        offset: args.offset,
        count: args.count,
        sort: args.sort,
        filter: args.filter
      });
      return {
        content: [{ type: "text", text: JSON.stringify(attachments, null, 2) }]
      };
    }

• src/index.ts:408-413 (schema)

  Input schema definition for the 'get_attachments' tool.

  inputSchema: {
    offset: z.coerce.number().default(0).describe("Pagination offset"),
    count: z.coerce.number().max(500).default(50).describe("Number of results to return"),
    sort: z.string().optional().describe("Sort field"),
    filter: z.record(z.any()).optional().describe("Filter criteria")
  }