t4l-server 0.2.0

Self-hosted REST and MCP server for T4L Trainer agent workflows.

T4L Server

Self-hosted REST and MCP server for exchanging T4L Trainer JSON artifacts between the iPhone app and a coaching agent.

The phone remains the source of truth for accepted training state. The server stores synced context and pending agent results in SQLite so local agents, home-server agents, and private VPS agents can work through the same protocol.

Install

pipx install t4l-server
t4l-server serve --data-dir ~/T4LServerData

The command prints the server URL, MCP URL, and API key. Enter the server URL and API key in the T4L Trainer Settings screen. Pass --log-level DEBUG for verbose request and error logging (logs go to stderr; the API key is only ever printed to stdout on startup).

Agent setup

Agents should read the public instruction repo first:

https://github.com/BigSlikTobi/t4l-agent-instructions

Those instructions explain how to start or verify this server, connect through MCP, wait for fresh phone context, and write app-consumed results safely.

Safety model

• REST and MCP endpoints require the API key, compared in constant time.
• Request bodies over 25 MiB are rejected (413) to bound memory use.
• JSON artifacts are stored in t4l.sqlite (WAL mode; writes use an immediate transaction so concurrent upserts cannot interleave).
• Image blobs are stored under blobs/.
• Path traversal and arbitrary file access are rejected.
• Stored payloads are structurally validated before persisting.

Architecture

Zero runtime dependencies by design — the server is built on the Python standard library (http.server) so it installs and runs anywhere pipx does. Keep it dependency-free.

• constants.py: single source of truth for artifact kinds, route maps, limits.
• store.py: SQLite artifact store (WAL, immediate-transaction upserts).
• server.py: REST handler, auth, body limits, logging.
• mcp.py: JSON-RPC MCP tools (read context / write results).
• validation.py: structural payload validation shared by REST + MCP writes.
• cli.py: serve entrypoint and logging configuration.

Development

python -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
ruff format --check .
ruff check .
mypy
pytest
python -m build
twine check dist/*