t4l-server 0.1.0__tar.gz

t4l_server-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: Publish Python package
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Package index target"
+        required: true
+        default: "testpypi"
+        type: choice
+        options:
+          - testpypi
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and check package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Install build dependencies
+        run: python -m pip install --upgrade build twine
+      - name: Build distributions
+        run: python -m build
+      - name: Check distributions
+        run: twine check dist/*
+      - uses: actions/upload-artifact@v5
+        with:
+          name: dist
+          path: dist/*
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/t4l-server/
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/project/t4l-server/
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: dist
+          path: dist
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

t4l_server-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+__pycache__/

t4l_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 T4L Trainer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

t4l_server-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: t4l-server
+Version: 0.1.0
+Summary: Self-hosted REST and MCP server for T4L Trainer agent workflows.
+Project-URL: Homepage, https://github.com/BigSlikTobi/t4l-server
+Project-URL: Repository, https://github.com/BigSlikTobi/t4l-server
+Project-URL: Issues, https://github.com/BigSlikTobi/t4l-server/issues
+Author: T4L Trainer
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: build>=1.3; extra == 'dev'
+Requires-Dist: mypy>=1.18; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.14; extra == 'dev'
+Requires-Dist: twine>=6.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+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.
+
+## Agent setup
+
+Agents should read the public instruction repo first:
+
+```text
+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.
+
+## Compatibility
+
+The old command remains available for one transition cycle:
+
+```bash
+t4l-bridge serve --dir ~/CodexFitnessExchange
+```
+
+New setups should use `t4l-server serve --data-dir ~/T4LServerData`.
+
+## Safety model
+
+- REST, MCP, and compatibility file endpoints require the API key.
+- JSON artifacts are stored in `t4l.sqlite`.
+- Image blobs are stored under `blobs/`.
+- Only known exchange files and `meal_images/` are accessible through
+  compatibility endpoints.
+- Path traversal and arbitrary file access are rejected.
+
+## Development
+
+```bash
+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/*
+```

t4l_server-0.1.0/README.md

@@ -0,0 +1,62 @@
+# 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
+
+```bash
+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.
+
+## Agent setup
+
+Agents should read the public instruction repo first:
+
+```text
+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.
+
+## Compatibility
+
+The old command remains available for one transition cycle:
+
+```bash
+t4l-bridge serve --dir ~/CodexFitnessExchange
+```
+
+New setups should use `t4l-server serve --data-dir ~/T4LServerData`.
+
+## Safety model
+
+- REST, MCP, and compatibility file endpoints require the API key.
+- JSON artifacts are stored in `t4l.sqlite`.
+- Image blobs are stored under `blobs/`.
+- Only known exchange files and `meal_images/` are accessible through
+  compatibility endpoints.
+- Path traversal and arbitrary file access are rejected.
+
+## Development
+
+```bash
+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/*
+```

t4l_server-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "t4l-server"
+version = "0.1.0"
+description = "Self-hosted REST and MCP server for T4L Trainer agent workflows."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "T4L Trainer" }]
+dependencies = []
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+
+[project.urls]
+Homepage = "https://github.com/BigSlikTobi/t4l-server"
+Repository = "https://github.com/BigSlikTobi/t4l-server"
+Issues = "https://github.com/BigSlikTobi/t4l-server/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.3",
+  "mypy>=1.18",
+  "pytest>=8.0",
+  "ruff>=0.14",
+  "twine>=6.2",
+]
+
+[project.scripts]
+t4l-server = "t4l_server.cli:main"
+t4l-bridge = "t4l_server.cli:_bridge_main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/t4l_server"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src", "tests"]

t4l_server-0.1.0/src/t4l_server/__init__.py

@@ -0,0 +1,5 @@
+"""Self-hosted REST and MCP server for T4L Trainer."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

t4l_server-0.1.0/src/t4l_server/cli.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import argparse
+import secrets
+import socket
+from pathlib import Path
+
+from .server import ServerConfig, run_server
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="t4l-server")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    serve = subparsers.add_parser("serve", help="Start the self-hosted T4L server.")
+    serve.add_argument(
+        "--data-dir",
+        type=Path,
+        help="Server data directory. Stores t4l.sqlite and blobs.",
+    )
+    serve.add_argument(
+        "--dir",
+        type=Path,
+        help="Compatibility alias for --data-dir.",
+    )
+    serve.add_argument("--host", default="0.0.0.0", help="Bind host.")
+    serve.add_argument("--port", default=8787, type=int, help="Bind port.")
+    serve.add_argument(
+        "--api-key",
+        default=None,
+        help="API key. Defaults to a new key for every start.",
+    )
+    serve.add_argument(
+        "--token",
+        default=None,
+        help="Compatibility alias for --api-key.",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command == "serve":
+        data_dir = args.data_dir or args.dir
+        if data_dir is None:
+            parser.error("serve requires --data-dir")
+        token = args.api_key or args.token or _new_api_key()
+        config = ServerConfig(
+            exchange_dir=data_dir.expanduser().resolve(),
+            host=args.host,
+            port=args.port,
+            token=token,
+        )
+        _print_startup(config)
+        run_server(config)
+        return 0
+    return 1
+
+
+def _bridge_main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        import sys
+
+        argv = sys.argv[1:]
+    translated = ["serve" if item == "serve" else item for item in argv]
+    if "--data-dir" not in translated and "--dir" in translated:
+        # The parser accepts --dir directly; this keeps the old command shape.
+        pass
+    return main(translated)
+
+
+def _new_api_key() -> str:
+    return secrets.token_urlsafe(24)
+
+
+def _print_startup(config: ServerConfig) -> None:
+    lan_host = _lan_ip() if config.host in {"0.0.0.0", "::"} else config.host
+    print("T4L Self-Hosted Server")
+    print(f"Data dir: {config.data_dir}")
+    print(f"Server URL: http://{lan_host}:{config.port}")
+    print(f"MCP URL: http://{lan_host}:{config.port}/mcp")
+    print(f"API key: {config.token}")
+    print("Enter the server URL and API key in the T4L Trainer Settings screen.")
+
+
+def _lan_ip() -> str:
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+        try:
+            sock.connect(("8.8.8.8", 80))
+            return str(sock.getsockname()[0])
+        except OSError:
+            return "127.0.0.1"
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

t4l_server-0.1.0/src/t4l_server/mcp.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import Any
+
+from . import __version__
+from .store import Artifact, ArtifactStore
+
+
+def handle_mcp_message(store: ArtifactStore, message: dict[str, Any]) -> dict[str, Any]:
+    method = str(message.get("method") or "")
+    request_id = message.get("id")
+    if method == "initialize":
+        return _result(
+            request_id,
+            {
+                "protocolVersion": "2025-06-18",
+                "serverInfo": {"name": "t4l-server", "version": __version__},
+                "capabilities": {"tools": {}},
+            },
+        )
+    if method == "tools/list":
+        return _result(request_id, {"tools": _tools()})
+    if method == "tools/call":
+        params = message.get("params")
+        if not isinstance(params, dict):
+            return _error(request_id, -32602, "Invalid params.")
+        return _call_tool(store, request_id, params)
+    return _error(request_id, -32601, f"Unsupported MCP method: {method}")
+
+
+def _call_tool(
+    store: ArtifactStore,
+    request_id: object,
+    params: dict[str, Any],
+) -> dict[str, Any]:
+    name = str(params.get("name") or "")
+    arguments = params.get("arguments")
+    args = arguments if isinstance(arguments, dict) else {}
+    if name == "get_day_context":
+        return _artifact_result(request_id, store.latest("day_context"))
+    if name == "get_app_snapshot":
+        return _artifact_result(request_id, store.latest("app_snapshot"))
+    if name == "get_profile":
+        return _artifact_result(request_id, store.latest("athlete_profile"))
+    if name == "get_pending_requests":
+        return _payload_result(
+            request_id,
+            {
+                "requests": [
+                    artifact.summary()
+                    for artifact in [
+                        store.latest("training_block_request"),
+                        store.latest("nutrition_analysis_request"),
+                    ]
+                    if artifact is not None
+                ]
+            },
+        )
+    write_kinds = {
+        "write_training_block_plan": "training_block_plan",
+        "write_fuel_guidance": "fuel_guidance",
+        "write_nutrition_analysis_result": "nutrition_analysis_result",
+    }
+    if name in write_kinds:
+        payload = args.get("payload")
+        if not isinstance(payload, dict):
+            return _error(request_id, -32602, "Tool requires object argument: payload.")
+        artifact = store.upsert_artifact(write_kinds[name], payload, status="pending")
+        return _payload_result(request_id, {"stored": artifact.summary()})
+    return _error(request_id, -32602, f"Unknown tool: {name}")
+
+
+def _artifact_result(request_id: object, artifact: Artifact | None) -> dict[str, Any]:
+    if artifact is None:
+        return _payload_result(request_id, None)
+    return _payload_result(request_id, artifact.payload)
+
+
+def _payload_result(request_id: object, payload: object) -> dict[str, Any]:
+    return _result(
+        request_id,
+        {
+            "content": [
+                {
+                    "type": "text",
+                    "text": _json_text(payload),
+                }
+            ],
+            "structuredContent": payload,
+        },
+    )
+
+
+def _json_text(payload: object) -> str:
+    import json
+
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _tools() -> list[dict[str, Any]]:
+    object_schema = {
+        "type": "object",
+        "properties": {"payload": {"type": "object"}},
+        "required": ["payload"],
+    }
+    return [
+        {
+            "name": "get_day_context",
+            "description": "Read latest day context.",
+            "inputSchema": {"type": "object"},
+        },
+        {
+            "name": "get_app_snapshot",
+            "description": "Read latest full app snapshot.",
+            "inputSchema": {"type": "object"},
+        },
+        {
+            "name": "get_profile",
+            "description": "Read latest athlete profile.",
+            "inputSchema": {"type": "object"},
+        },
+        {
+            "name": "get_pending_requests",
+            "description": "List pending app requests.",
+            "inputSchema": {"type": "object"},
+        },
+        {
+            "name": "write_training_block_plan",
+            "description": "Write a pending training block plan.",
+            "inputSchema": object_schema,
+        },
+        {
+            "name": "write_fuel_guidance",
+            "description": "Write pending fuel guidance.",
+            "inputSchema": object_schema,
+        },
+        {
+            "name": "write_nutrition_analysis_result",
+            "description": "Write a pending nutrition result.",
+            "inputSchema": object_schema,
+        },
+    ]
+
+
+def _result(request_id: object, result: dict[str, Any]) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+
+def _error(request_id: object, code: int, message: str) -> dict[str, Any]:
+    return {
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "error": {"code": code, "message": message},
+    }