SansFiction Library (Authorized)

What this skill does

Library management (auth required): add/remove books, set reading status, log progress, view “currently reading”, and reading stats.
Daily check-in: schedule a reminder that asks “How much did you read today?” and then logs what the user reports.

Hard rules

Never ask for or store passwords. Use a SansFiction token only.
Never echo the token back to the user or write it into chat logs.
No side effects without confirmation when the target book is ambiguous (multiple matches).

Setup (one-time) — get the token

If SANSFICTION_TOKEN is missing, do this immediately:

1) Tell the user to open SansFiction → Connect AI Agents and use Manual Token: - Go to: https://sansfiction.com/docs/agents - In Manual Token, click Generate token - Copy the token

2) Ask the user to paste the token once in this chat.

3) Persist it (recommended):

In ~/.openclaw/openclaw.json:
- skills.entries.sansfiction-library.apiKey: "<TOKEN>"
- (this maps to env var SANSFICTION_TOKEN)
Or set:
- skills.entries.sansfiction-library.env.SANSFICTION_TOKEN: "<TOKEN>"

If you can’t edit config automatically, give the user the exact snippet to paste.

How to talk to SansFiction (MCP over HTTP)

Endpoint:

https://sansfiction.com/api/mcp

Use JSON-RPC with Bearer auth.

1) List available tools (discover exact tool names)

curl -s https://sansfiction.com/api/mcp \
  -H "Authorization: Bearer $SANSFICTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

2) Call a tool

Replace TOOL_NAME and ARGS with what tools/list returns.

curl -s https://sansfiction.com/api/mcp \
  -H "Authorization: Bearer $SANSFICTION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":ARGS}}'

Error handling
    • If you get 401 Unauthorized, auth is missing/invalid. Ask user to regenerate token and update config.
    • If tools/list is empty, verify the URL is exactly /api/mcp and auth header is present.

⸻

Library management playbook (what to do for each request)

A) Add a book to the user’s library

When user says: “add X” / “put X in my library”
    1.  Use MCP search tools (discover name via tools/list). Prefer search by:
    • ISBN (best) → exact match
    • Title + author
    2.  If multiple plausible matches:
    • Show up to 5 options with distinguishing details (author, year, edition, pages/publisher if available).
    • Ask the user to pick one.
    3.  Call the “add to library” tool.
    4.  Confirm:
    • Book added
    • Current status (ask if they want “to-read” vs “reading”)

B) Set reading status

When user says: “mark as reading/finished/paused/abandoned”
    1.  Resolve the book (same matching rules as above).
    2.  Call the “set status” tool with the exact status enum required by SansFiction.
    • If the server rejects your status string, use the allowed values from the error/tool schema and retry.
    3.  Confirm the new status.

C) Log progress

When user says: “I read 20 pages” / “I’m at page 150” / “read 30 minutes”
    1.  Ask which book if not explicitly stated AND they have more than one active book.
    2.  Call the “log progress” / “update progress” tool.
    • Prefer page number if provided.
    • Otherwise log pages read or minutes read, whichever the tool supports.
    3.  Confirm what was recorded (book + new page/progress + date).

D) List currently reading

When user says: “what am I reading?” / “list currently reading”
    1.  Call the “list library” tool filtered to “currently reading”.
    2.  Return:
    • Title + author
    • Current progress (page/% if available)

E) Stats

When user asks: “monthly stats”, “how many books this year”
    1.  Call the “stats” tool(s).
    2.  Summarize clearly (books finished, pages/minutes, streak if available).

⸻

Daily reading reminder (cron)

Goal: once per day, ask:

“How much did you read today? Reply with: book (optional), pages or minutes, and current page if you know it.”

Turn it on

If the user asks for the reminder (or says “enable daily check-in”):
    1.  Schedule a cron job (timezone: Europe/Warsaw) at a reasonable default (21:00 local), unless the user specifies a time.

CLI example:

openclaw cron add \
  --name "SansFiction reading check-in" \
  --cron "0 21 * * *" \
  --tz "Europe/Warsaw" \
  --session isolated \
  --message "Reading check-in: how much did you read today? Reply with pages/minutes and (optionally) which book + your current page." \
  --deliver \
  --channel last

What to do when the user replies

Treat their reply as a progress log:
    • Parse pages/minutes and optional book/current page.
    • If book is missing/ambiguous, ask one quick follow-up.
    • Then log progress via MCP and confirm.

Turn it off

If the user says “disable reading reminder”:
    • Remove the cron job named SansFiction reading check-in.

⸻

User-facing examples (how users can invoke this skill)
    • “/sansfiction-library add Project Hail Mary”
    • “/sansfiction-library mark Dune finished”
    • “/sansfiction-library log Dune page 150”
    • “/sansfiction-library what am I currently reading?”
    • “/sansfiction-library enable daily reading reminder at 20:30”

Sources used: SansFiction MCP endpoint + token flow  [oai_citation:0‡SansFiction](https://sansfiction.com/docs/agents), 
OpenClaw skill frontmatter/metadata + config injection  [oai_citation:1‡OpenClaw](https://docs.openclaw.ai/tools/skills), 
OpenClaw cron scheduling (for the daily reminder)  [oai_citation:2‡OpenClaw](https://docs.openclaw.ai/automation/cron-jobs).

Library