Skip to content

docs: expand Architecture section with actors and data flow diagram #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
paradoxbound merged 1 commit into from
Mar 8, 2026
Merged

docs: expand Architecture section with actors and data flow diagram #68

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 39 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,12 +295,45 @@ Check logs for error messages:

## Architecture

Built with modern MCP patterns:
- `McpServer` from `@modelcontextprotocol/sdk/server/mcp.js`
- `registerTool()` API with Zod schemas
- Stdio transport for local/LibreChat use
- Monorepo: `packages/core` (native fetch client), `packages/stdio` (MCP server entry)
- Type-safe with TypeScript 5.3+
### Actors

| Actor | Role |
|-------|------|
| **MCP Client** (Claude Desktop, LibreChat, etc.) | Sends tool-call requests over stdio; receives structured JSON responses |
| **bookstack-mcp server** (`packages/stdio`) | Validates inputs with Zod, dispatches to the BookStack API client, formats responses |
| **BookStack API client** (`packages/core`) | Authenticates with the BookStack instance, makes HTTP requests, enhances responses |
| **BookStack instance** | Stores and serves documentation content via its REST API |
| **Operator** | Configures environment variables (`BOOKSTACK_BASE_URL`, tokens, `BOOKSTACK_ENABLE_WRITE`) |

### Data flow

```
MCP Client (Claude Desktop / LibreChat / Smithery)
│ stdio: tool list request / tool call
▼
packages/stdio — McpServer
│ Zod input validation → registered tool handler
▼
packages/core — BookStackClient (native fetch)
│ HTTPS + Token auth → BookStack REST API
▼
BookStack instance
│ JSON response
▼
BookStackClient — response enhancement (URLs, previews, dates, word counts)
▼
packages/stdio — JSON serialised as MCP tool result
▼
MCP Client
```

### Key design decisions

- **Native fetch** — no axios; HTTP errors surface as `error.status` / `error.response`
- **Stdio transport** — single universal transport for local, LibreChat, and Claude Desktop use
- **Zod schemas** — all MCP tool inputs validated before the API is called
- **Write-gate** — write tools are only registered when `BOOKSTACK_ENABLE_WRITE=true`
- **Monorepo** — `packages/core` has no runtime dependencies; `packages/stdio` depends on core and the MCP SDK

## Dependency Management

Expand Down