fitlog-mcp

An Alexa+ add-on backed by a self-hosted MCP server that gives Alexa a memory for your training: log sets by voice, ask for personal records, get today's plan and protein targets.

Built for the Alexa+ track of the Amazon "Build, Ship, Shape" Developer Hackathon 2026: a working self-hosted MCP server implementing MCP spec 2025-11-25 over Streamable HTTP with the Alexa+ authentication checklist (OAuth 2.1 + PKCE account linking, 401s with no WWW-Authenticate header, RFC 9728 Protected Resource Metadata) — zero dependencies, MIT licensed.

Run it (3 steps, no pip install)

Requires Python 3.9+.

git clone https://github.com/hahahahahahahahah6/fitlog-mcp.git
cd fitlog-mcp
python3 server.py

The server listens on http://127.0.0.1:8765 (/mcp endpoint). Environment variables:

Related MCP server: super-hevy-mcp

Connect an MCP client

The endpoint is http://127.0.0.1:8765/mcp (Streamable HTTP). Every /mcp request needs a bearer token — either from the OAuth flow or the static FITLOG_API_TOKEN you set for local dev. Example client config (Claude Code / MCP Inspector style):

{
  "mcpServers": {
    "fitlog": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer <FITLOG_API_TOKEN>" }
    }
  }
}

Or verify with the MCP Inspector CLI:

FITLOG_API_TOKEN=devtoken python3 server.py &
npx -y @modelcontextprotocol/inspector --cli \
  --transport http --server-url http://127.0.0.1:8765/mcp \
  --header "Authorization: Bearer devtoken" \
  --method tools/list

Connect Alexa+ (official path)

1. Expose the server over HTTPS, e.g. with a cloudflared quick tunnel: cloudflared tunnel --url http://127.0.0.1:8765, and set FITLOG_PUBLIC_URL=https://<your-tunnel>.trycloudflare.com. Also set FITLOG_OWNER_PASSWORD to a strong password — public exposure without it is refused at startup, and the /authorize page will ask for the password before showing the Approve button.

2. Install the Alexa AI CLI (npm install -g @alexa/alexa-ai or per the MCP toolkit quickstart).

3. Put your tunnel URL into addon-package/addon.json (integrations[0].config.endpoints.default.uri, plus /mcp).

4. cd addon-package && alexa-ai deploy — deploys to the development stage.

5. Enable the add-on in the Alexa+ web simulator, link the account (OAuth 2.1 + PKCE flow against your server), then talk to it: "Ask FitLog to log my bench press: 5 reps at 185 pounds."

The demo video script (demo/demo_script.md) follows exactly this path.

No Alexa developer account? Use the bundled web simulator instead (simulator/): an Echo-style page that runs the same OAuth account-linking flow and calls the same 6 tools over Streamable HTTP, with a live JSON-RPC inspector. ./simulator/start.sh, then open http://127.0.0.1:8799/.

Tools

Resources: program://current (the training split), pr://all (PR table).

Spec compliance notes

• Streamable HTTP: POST /mcp for JSON-RPC, optional GET /mcp SSE stream, DELETE /mcp terminates the session (Mcp-Session-Id).

• Alexa+ auth checklist: OAuth 2.1 authorization-code + PKCE (S256); /.well-known/oauth-protected-resource (RFC 9728) and /.well-known/oauth-authorization-server metadata; authorize and token requests must carry the canonical MCP resource parameter. Unauthenticated requests to /mcp get HTTP 401 with no WWW-Authenticate header, as required.

• Origin header is MUST-validated: a present-but-untrusted origin gets HTTP 403 (DNS-rebinding mitigation). Loopback origins are trusted by default.

• MCP-Protocol-Version is checked on every post-initialize request: unsupported versions get HTTP 400.

• JSON-RPC batches are rejected (removed in spec 2025-11-25) with -32600 over HTTP 400.

• Tool annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint) are set per the 2025-11-25 spec.

Tests

python3 -m unittest discover -s tests   # 51 tests, incl. the full OAuth PKCE round-trip

License

MIT — see LICENSE.