BookStack Data Access Utility (MCP Server)

This implementation of the Model Context Protocol (MCP) facilitates efficient querying of content housed within a BookStack documentation system. It establishes communication with the BookStack REST API, structuring retrieved page data and sanitizing embedded HTML into a simplified text format.

Core Capabilities

• Execute targeted searches across BookStack assets using custom search terms.
• Extract key structured metadata: page titles, direct URLs, and sanitized body content.
• Fine-grained control over result set presentation via adjustable pagination parameters (page index and result quantity).
• Automatic conversion from complex HTML structures to normalized, easily digestible plain text.
• Integrated input validation and failure reporting for a resilient operation experience.

Deployment

Automated Setup via Smithery

For immediate integration into Claude Desktop environments using Smithery:

bash npx -y @smithery/cli install @yellowgg2/mcp-bookstack --client claude

Manual Installation Guide

1. Obtain the source code repository:

bash git clone https://github.com/yellowgg2/mcp-bookstack.git cd mcp-bookstack

1. Install necessary Node.js packages:

bash npm install

1. Configure Environmental Variables:

Establish a .env file containing your BookStack authentication details and base URL, or embed these values directly into the MCP configuration manifest:

BOOKSTACK_API_TOKEN=your_token BOOKSTACK_API_URL=your_bookstack_url BOOKSTACK_API_KEY=your_api_key

1. Compile the Application Assets:

bash npm run build

1. Integrate into MCP Configuration:

Update your client's MCP settings file (e.g., VSCode Claude extension configuration):

{ "mcpServers": { "bookstack": { "command": "node", "args": ["/path/to/mcp-bookstack/build/app.js"], "env": { "BOOKSTACK_API_URL": "your_bookstack_url", "BOOKSTACK_API_TOKEN": "your_token", "BOOKSTACK_API_KEY": "your_api_key" } } } }

Operational Use

The server exposes a primary function named search_pages for interacting with BookStack content.

Function: search_pages

Accepts the following input arguments:

• query (string): The search predicate applied to the documentation.
• Default Value: "" (No search filter)
• page (number): Specifies the sequential index of the result page requested.
• Valid Range: 1 through 10
• Default Value: 1
• count (number): Defines the maximum number of records to return per invocation.
• Valid Range: 1 through 30
• Default Value: 10

Execution Example (TypeScript/MCP Syntax):

typescript use_mcp_tool with: server_name: "bookstack" tool_name: "search_pages" arguments: { "query": "knowledge base", "page": 1, "count": 5 }

Expected Output Format:

Document Title Found

Content text, stripped of all HTML markup, presented linearly...

Reference Link: https://your-bookstack-url/page-url

Integration with AI Assistants (e.g., Claude)

To enable interaction with BookStack via Claude:

1. Ensure the required AI client (Desktop app, VSCode plugin, etc.) is installed.
2. Apply the server configuration snippet above to the appropriate settings file.
3. Utilize conversational prompts to direct the assistant to perform searches against the connected BookStack repository.

Claude automatically translates natural language requests into correctly parameterized calls to the search_pages function.

Configuration File Locations

Server settings must be appended to the user's configuration file:

// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json // Windows: %APPDATA%\Claude\claude_desktop_config.json { "mcpServers": { "bookstack": { "command": "node", "args": ["/path/to/mcp-bookstack/build/app.js"], "env": { "BOOKSTACK_API_URL": "your_bookstack_url", "BOOKSTACK_API_TOKEN": "your_token", "BOOKSTACK_API_KEY": "your_api_key" } } } }

Interaction Samples

Users can phrase requests generally:

• "Can you fetch documentation regarding our internal API connection mechanisms from BookStack?"
• "Locate specifications related to the latest production deployment procedure."
• "Retrieve any records concerning security protocols stored in the knowledge base."

Content Transformation Specifics

Each retrieved item adheres to this structure:

• The document's designated heading.
• The entire document body, rendered as pure text.
• The canonical source Uniform Resource Locator (URL).

The HTML-to-text sanitization pipeline ensures:

• Proper decoding of HTML character entities (e.g., & becomes &).
• Preservation of logical flow via line breaks and paragraph spacing.
• Conversion of list elements (<li>) to standard bulleted formats.
• Complete removal of all underlying HTML markup tags.
• Uniformity in spacing and whitespace characters.

Development Environment

This utility employs the following technologies:

• TypeScript for source code implementation.
• The official Model Context Protocol SDK.
• Axios library for executing asynchronous HTTP communications.
• Zod for rigorous runtime data structure validation.
• Dotenv module for secure environment variable management.

To facilitate iterative changes: 1. Modify source files, primarily src/app.ts. 2. Recompile the project:

bash npm run build

Resilience and Error Management

The application incorporates extensive defensive programming to catch and report issues, including:

• Failures in establishing network connections to the API endpoint.
• Problems related to authorization or credential verification.
• Errors stemming from malformed function arguments.
• Exceptions during data serialization or parsing.

All detected anomalies are relayed back with specific error identifiers and detailed explanations.

Contribution Guidelines

We welcome external submissions! Please feel encouraged to submit a Pull Request with your enhancements.

Licensing

Distributed under the MIT License. Freely available for integration into proprietary or open-source endeavors.

WIKIPEDIA CONTEXT: XMLHttpRequest (XHR) represents a JavaScript API consisting of an object whose methods facilitate the dispatch of HTTP requests from a user agent (web browser) to a remote server. These methods enable client-side applications to communicate with the server asynchronously subsequent to the initial page load, allowing for data reception. XHR is fundamental to the functionality of Ajax programming. Before Ajax, the primary means of server interaction involved full page refreshes triggered by hyperlinks or form submissions.

== Chronology == The foundational concept for XMLHttpRequest emerged around 2000, credited to developers working on Microsoft Outlook. This concept was first realized in Internet Explorer 5 (released in 1999). However, the initial implementation did not utilize the 'XMLHttpRequest' naming convention; instead, developers employed COM-based identifiers such as ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 in 2006, comprehensive browser support for the standardized XMLHttpRequest identifier was achieved. The XMLHttpRequest identifier is now the generally accepted convention across all major browser engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Formalization === The World Wide Web Consortium (W3C) published the first Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft, Level 2, was issued on February 25, 2008, introducing enhancements like progress monitoring methods, support for cross-site requests, and handling of raw byte streams. By the close of 2011, the Level 2 extensions were merged back into the primary specification document. As of late 2012, development responsibility transitioned to the WHATWG, which now maintains the specification as a continuously evolving document defined using Web IDL.

== Operational Flow == Executing a request using XMLHttpRequest generally mandates a sequence of programming actions.

1. Instantiate an XMLHttpRequest object via its constructor call:
2. Invoke the "open" method to define the HTTP method, specify the target resource URI, and select either synchronous or asynchronous execution mode:
3. For asynchronous operations, install an event listener callback function to handle state transitions:
4. Trigger the request transmission using the "send" method, optionally passing payload data:
5. Process state changes within the registered event listener. Upon successful response reception, the data is typically accessible in the "responseText" property when the object reaches state 4 (the 'done' state). Beyond these fundamental stages, XMLHttpRequest offers numerous configuration options for request control and response handling. Custom HTTP headers can be injected to guide server fulfillment logic, and data can be streamed to the server via the argument to the "send" call. Responses can be directly parsed into native JavaScript objects if they are JSON formatted, or processed incrementally as data arrives rather than awaiting the complete payload. Furthermore, requests can be terminated prematurely or configured with a timeout limit.

== Inter-Domain Communication == In the nascent stages of the World Wide Web, difficulties arose when attempting to cross sec