fgbytes/sansfiction-mcp

sansfiction-mcp MCP server

Connect AI agents to SansFiction — a digital library for books, collections, reading journals, and discovery.

The same capabilities are exposed two ways, both authenticated with the same bearer token:

• MCP server (Streamable HTTP): https://sansfiction.com/api/mcp
• REST API (v1): https://sansfiction.com/api/v1

Quick start (MCP)

claude mcp add --transport http sansfiction https://sansfiction.com/api/mcp

Or point any MCP client at the streamable-HTTP endpoint above. Public catalog tools need no auth; personal library tools require a bearer token (generate one at sansfiction.com/docs/agents).

Quick start (REST)

# Public catalog — no auth
curl "https://sansfiction.com/api/v1/catalog/search?q=dune&limit=5"

# Personal library — bearer token
curl -H "Authorization: Bearer $SF_TOKEN" \
  "https://sansfiction.com/api/v1/library/books?status=reading"

Capabilities

Public catalog (no auth)

• GET /api/v1/catalog/search?q=…&searchType=all|author|series|mood|isbn
• GET /api/v1/catalog/books/{bookId}
• GET /api/v1/catalog/series/{seriesId}
• GET /api/v1/catalog/collections

Personal library (bearer token)

• GET/POST /api/v1/library/books · PATCH/DELETE /api/v1/library/books/{bookId}
• GET /api/v1/library/search
• GET /api/v1/library/collections · GET /api/v1/library/collections/{id} · POST …/items
• GET /api/v1/library/stats

Discovery

• Agent Skill: SKILL.md — also served at https://sansfiction.com/.well-known/agent-skills/sansfiction-catalog/SKILL.md
• MCP Registry manifest: server.json
• OpenAPI: https://sansfiction.com/openapi.json
• MCP server card: https://sansfiction.com/.well-known/mcp/server-card.json

Authentication

Generate a personal access token (sf_mcp_…) while signed in at sansfiction.com/docs/agents. The same token authenticates both the MCP server and the REST API. Rate limits: 60 req/min anonymous, 180 req/min authenticated.

License

The SansFiction service is proprietary. This repository documents its public agent interface for discovery and integration.

Run locally as an MCP server (stdio)

This repo also ships a small stdio MCP server that proxies to the hosted REST API, so you can run it anywhere an MCP client expects a local command:

npx sansfiction-mcp
# or
npm install && node index.js

Environment variables:

• SANSFICTION_TOKEN — bearer token (sf_mcp_…) for the personal-library tools (generate at https://sansfiction.com/docs/agents). Public catalog tools need none.
• SANSFICTION_BASE_URL — override the API base (default https://sansfiction.com).

Tools: search_books, get_book, get_series, list_public_collections, list_my_books, add_book_to_library, update_library_book, remove_book_from_library, search_my_library, list_my_collections, get_reading_stats.

Glama build configuration

• Build steps: ["npm install"]
• CMD arguments: ["mcp-proxy","--","node","index.js"]

tools/list requires no network or credentials, so the introspection check passes without a token.