How markzither/bookstack-mcp-server-dotnet works
This repository is a .NET MCP server that exposes BookStack content and administration to AI clients, with optional semantic search backed by a periodically synchronized vector index. The main request path is an MCP client invoking a tool or resource handler, which uses the BookStack API client to retrieve or change BookStack data. Semantic search adds embedding, chunking, and vector storage; an admin task subsystem is also registered by the server. Several handlers and storage implementations are unsampled, so their internal links are omitted where evidence is unavailable.
Main entry points: Program.cs MCP host · VectorIndexSyncService.cs Index synchronizer · IVectorStore.cs Vector store contract · EvaluationRunner.cs Evaluation runner
Components 25
MCP server
- MCP host
src/BookStack.Mcp.Server/Program.cs
BookStack access
- Content tools
src/BookStack.Mcp.Server/tools - Content resources
src/BookStack.Mcp.Server/resources - Text search tool
src/BookStack.Mcp.Server/tools/search/SearchToolHandler.cs - BookStack API client
src/BookStack.Mcp.Server/api/BookStackApiClient.cs - API contract
src/BookStack.Mcp.Server/api/IBookStackApiClient.cs - Access scoping
src/BookStack.Mcp.Server/config/ScopeFilter.cs
Semantic search
- Semantic search tool
src/BookStack.Mcp.Server/tools/semantic-search/SemanticSearchToolHandler.cs - Index synchronizer
src/BookStack.Mcp.Server/services/VectorIndexSyncService.cs - Text chunking
src/MarkZither.Rag.Chunking/SlideWindowChunkingService.cs - Embedding provider
src/BookStack.Mcp.Server/api/VectorSearchServiceCollectionExtensions.cs - Vector store contract
src/BookStack.Mcp.Server.Data.Abstractions/IVectorStore.cs - SQLite vector store
src/BookStack.Mcp.Server.Data.Sqlite/SqliteVectorStoreImpl.cs - Postgres vector store
src/BookStack.Mcp.Server.Data.Postgres/PgVectorStore.cs - Vector database
Administration
- Admin handlers
src/BookStack.Mcp.Server/Admin/AdminHandlers.cs - Admin task queue
src/BookStack.Mcp.Server/Admin/AdminTaskQueue.cs - Admin index worker
src/BookStack.Mcp.Server/Admin/AdminIndexWorkerService.cs
Search evaluation
- Evaluation harness
src/BookStack.Mcp.Server.Evaluation/EvaluationHarness.cs - Evaluation runner
src/BookStack.Mcp.Server.Evaluation/EvaluationRunner.cs - MCP HTTP client
src/BookStack.Mcp.Server.Evaluation/McpHttpClient.cs - Search metrics
src/BookStack.Mcp.Server.Evaluation/MetricsCalculator.cs - Markdown report
src/BookStack.Mcp.Server.Evaluation/MarkdownReportWriter.cs
Other components
- AI assistant
- BookStack instance
Connections 27
- AI assistant → MCP host: invokes MCP
README.md - MCP host → Content tools: exposes tools
- MCP host → Content resources: exposes resources
- Content tools → API contract: calls API
src/BookStack.Mcp.Server/tools/books/BookToolHandler.cs - Content resources → API contract: uses API
src/BookStack.Mcp.Server/resources/search/SearchResourceHandler.cs - Text search tool → API contract: searches content
src/BookStack.Mcp.Server/tools/search/SearchToolHandler.cs - BookStack API client → BookStack instance: sends API requests
- Text search tool → Access scoping: filters results
src/BookStack.Mcp.Server/tools/search/SearchToolHandler.cs - MCP host → Semantic search tool: exposes tool
- Semantic search tool → Vector store contract: searches vectors
src/BookStack.Mcp.Server/tools/semantic-search/SemanticSearchToolHandler.cs - MCP host → Index synchronizer: hosts service
- Index synchronizer → API contract: fetches pages
src/BookStack.Mcp.Server/services/VectorIndexSyncService.cs - Index synchronizer → Text chunking: chunks page text
src/BookStack.Mcp.Server/services/VectorIndexSyncService.cs - Index synchronizer → Embedding provider: generates embeddings
src/BookStack.Mcp.Server/services/VectorIndexSyncService.cs - Index synchronizer → Vector store contract: upserts vectors
src/BookStack.Mcp.Server/services/VectorIndexSyncService.cs - Embedding provider → Vector store contract: registers store
src/BookStack.Mcp.Server/api/VectorSearchServiceCollectionExtensions.cs - Vector store contract → SQLite vector store: implemented by
- Vector store contract → Postgres vector store: implemented by
src/BookStack.Mcp.Server.Data.Postgres/PostgresVectorStoreServiceCollectionExtensions.cs - SQLite vector store → Vector database: persists vectors
- Postgres vector store → Vector database: persists vectors
- MCP host → Admin handlers: registers admin
src/BookStack.Mcp.Server/Program.cs - Admin handlers → Admin task queue: queues tasks
- Admin index worker → Admin task queue: processes tasks
- Evaluation harness → Evaluation runner: runs evaluation
- Evaluation runner → MCP HTTP client: sends MCP requests
- Evaluation runner → Search metrics: calculates metrics
- Evaluation runner → Markdown report: writes report