oculairmedia/bookstack-mcp

Purpose and Entry Points

This is a Python FastMCP server that exposes BookStack content and image-gallery operations as MCP tools for downstream AI clients. The normal launch path is the FastMCP package entry point in fastmcp_server/__init__.py; stdio-oriented execution is supported by fastmcp_server/run_stdio.py. Alternate/simplified server assembly exists in fastmcp_server/my_server.py and fastmcp_server/my_server_simplified.py.

MCP Server and Tool Registration

The server constructs a FastMCP application and registers consolidated BookStack tools. fastmcp_server/bookstack/tools.py is the primary registration boundary, exposing CRUD, list/filter, search, batch, and image workflows. fastmcp_server/bookstack/tools_selective.py and fastmcp_server/bookstack/tools_simplified.py provide alternate tool surfaces, likely for compatibility or reduced schemas.

BookStack API Boundary

All remote BookStack interaction is centralized behind the API client in fastmcp_server/bookstack/api_client.py. Tool handlers should translate MCP inputs into BookStack REST requests rather than directly coupling callers to HTTP details. Runtime configuration comes from environment credentials (BS_URL, BS_TOKEN_ID, BS_TOKEN_SECRET), with deployment definitions in Dockerfile, compose.yaml, and docker-compose.yml.

Content Management Pipeline

Content operations cover books, bookshelves, chapters, and pages through unified CRUD, listing/filtering, search, and batch actions. fastmcp_server/bookstack/content_operations.py contains the domain operation layer used by the public tool surface in fastmcp_server/bookstack/tools.py; request and response shapes are defined in fastmcp_server/bookstack/schemas.py. This separates MCP-facing contracts from BookStack endpoint mechanics.

Image Gallery Workflow

Image management is a first-class flow: callers create, read, update, delete, list, and search gallery images through the registered tools. fastmcp_server/bookstack/image_handling.py handles image input normalization and remote URL fetching; fastmcp_server/bookstack/tools.py exposes those operations; fastmcp_server/bookstack/api_client.py submits the resulting multipart/API requests. URL inputs are constrained to HTTP(S), screened against internal network targets and redirects, size-limited, MIME-validated, and converted into BookStack-compatible uploads. The key external service is the configured BookStack instance and its image-gallery REST API.

Validation, Caching, and Observability

Input constraints and domain checks are isolated in fastmcp_server/bookstack/validators.py, while model/schema enforcement resides in fastmcp_server/bookstack/schemas.py. fastmcp_server/bookstack/cache.py provides a cache boundary whose invalidation must follow content mutations. fastmcp_server/bookstack/metrics.py captures operational measurements, keeping instrumentation distinct from tool behavior.

Runtime and Client Compatibility

The principal runtime is Python with FastMCP and asynchronous tool execution. MCP clients discover registered tools when the server starts, then invoke tools over the selected transport, including stdio. The project explicitly supports Letta-oriented compatibility constraints, documented in docs/LETTA_COMPATIBILITY.md; containerized execution is supported through Dockerfile and Compose manifests.