Server anatomy

The workflow-server codebase in src/: entry point, tool registrars, loaders, session machinery, and validators.

For contributors. Build and test instructions: Development guide (source).

The shape of the codebase

Startup is a short, linear path: the entry point parses configuration, a factory builds the MCP server, and two registrar functions attach all sixteen tools as closures. There is no routing layer and no dependency-injection framework — the registrars close over the ServerConfig and call shared machinery directly.

Module map

Grouped by what a request touches. Tool handlers sit on shared machinery; machinery reads definitions and reads or writes session state on disk.

Primary source files by group:

Startup

Definitions and validation

Persistence and delivery

The layer every call passes through

There is no central router — each tool is a closure registered at startup — but session-bound handlers follow the same skeleton so logging, seal checks, and persistence are uniform. Bootstrap entry points (discover, list_workflows, health_check, start_session) get audit logging only. The worked example is request lifecycle.

Stage by stage:

1. withAuditLog (logging.ts) — outermost wrapper on every registered handler. It times the call, emits a structured audit event to stderr, and — when the parameters include a session_index — appends a trace event to the session's in-process TraceStore buffer. This runs on success and on thrown errors alike, so a failed seal check or validation still leaves an audit and trace record.
2. loadSessionForTool (session/resolver.ts) — resolves the six-character session_index to a planning folder (how the index maps to disk), verifies the HMAC seal on session.json against .session-token, and parses the file into typed SessionFile state. Child sessions dispatched via dispatch_child live inside the parent's session.json; the loader navigates to the embedded sub-state the index addresses. If the seal does not match or the file fails schema validation, the call stops here — the handler never runs on state the server cannot vouch for.
3. advanceSession and saveSessionForTool (session/resolver.ts) — the write path. Handlers that change state build the next snapshot with advanceSession (increments seq, refreshes ts, applies a mutator callback), then pass it to saveSessionForTool, which merges embedded child updates back into the top-level file, canonicalises the JSON, recomputes the HMAC, and atomically writes session.json and .session-token. Read-only tools such as get_activity may still call save when they record delivery or fetch events in history.

Everything cryptographic — session seals, session indexes, trace tokens — funnels to a single 32-byte server key created lazily at ~/.workflow-server/secret (file mode 0600) by session/crypto.ts. One key, three uses, one place to reason about it.

Error discipline

Loaders return Result<T, E> values rather than throwing, and failures that must cross the tool boundary are typed so handlers can map them to user-facing responses without string matching:

How these surface to a calling agent — and how they differ from non-blocking validation warnings — is covered in Protocol.

Where things live on disk

Three locations, three lifetimes — definitions are read-only content, session state belongs to the workspace, and the server key is per-user infrastructure.

Next

Follow one request through this structure in the request lifecycle, or read how state is kept honest in the session store.