BookStack MCP Server

Instructions

Implementation Reference

• src/bookstack-client.ts:430-473 (handler)

  The `exportPage` method in `BookStackClient` handles exporting a page by either generating a web download link for binary formats (PDF, ZIP) or fetching the content via API for text formats (HTML, Markdown, Plaintext).

  async exportPage(id: number, format: 'html' | 'pdf' | 'markdown' | 'plaintext' | 'zip'): Promise<any> {
    try {
      // For binary formats (PDF, ZIP), return BookStack web URL using slugs
      if (format === 'pdf' || format === 'zip') {
        // First fetch the page data to get slugs
        const page = await this.getPage(id);
        const book = await this.getBook(page.book_id);
        
        // Construct the correct web URL with slugs
        const directUrl = `${this.baseUrl}/books/${book.slug}/page/${page.slug}/export/${format}`;
        const filename = `${page.slug}.${format}`;
        const contentType = format === 'pdf' ? 'application/pdf' : 'application/zip';
        
        return {
          format: format,
          filename: filename,
          download_url: directUrl,
          content_type: contentType,
          export_success: true,
          page_id: id,
          page_name: page.name,
          book_name: book.name,
          direct_download: true,
          note: "This is a direct link to BookStack's web export. You may need to be logged in to BookStack to access it."
        };
      } else {
        // For text formats, fetch the content via API
        console.error(`Exporting page ${id} as ${format}...`);
        const response = await this.client.get(`/pages/${id}/export/${format}`);
        console.error(`Export response status: ${response.status}`);
        
        // For text formats, validate and return as string
        if (!response.data) {
          throw new Error(`Empty ${format} content returned from BookStack API`);
        }
        
        console.error(`Text export length: ${response.data.length} characters`);
        return response.data;
      }
    } catch (error) {
      console.error(`Export error for page ${id}:`, error);
      throw new Error(`Failed to export page ${id} as ${format}: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:232-267 (registration)

  Registration of the `export_page` tool in `src/index.ts`, which invokes `client.exportPage` and handles the output formatting for the MCP client.

  server.registerTool(
    "export_page",
    {
      title: "Export Page",
      description: "Export a page in various formats (PDF/ZIP provide direct BookStack download URLs)",
      inputSchema: {
        id: z.coerce.number().min(1).describe("Page ID"),
        format: z.enum(["html", "pdf", "markdown", "plaintext", "zip"]).describe("Export format")
      }
    },
    async (args) => {
      const content = await client.exportPage(args.id, args.format);
  
      // Handle binary formats with direct URLs
      if (typeof content === 'object' && content.download_url && content.direct_download) {
        const format = args.format.toUpperCase();
        return {
          content: [{
            type: "text",
            text: `✅ **${format} Export Ready**\n\n` +
                  `📄 **Page:** ${content.page_name}\n` +
                  `📚 **Book:** ${content.book_name}\n` +
                  `📁 **File:** ${content.filename}\n\n` +
                  `🚀 **Direct Download Link:**\n${content.download_url}\n\n` +
                  `ℹ️  **Note:** ${content.note}`
          }]
        };
      }
  
      // Handle text formats
      const text = typeof content === 'string' ? content : JSON.stringify(content, null, 2);
      return {
        content: [{ type: "text", text }]
      };
    }
  );