safari-reading-list-mcp

An Anthropic MCP server project for Apple Safari Reading List workflows on macOS.

This repository now provides a working MCP server and CLI for exporting Safari Reading List data to JSON.

Project Status

• Feature 001 is complete: export Safari Reading List entries (all, default week, custom range).

• MCP server entrypoint is active via main.py and safari_reading_list_mcp/server.py.

• CLI entrypoint srl is available with export and serve commands.

• Quality checks are automated with mise tasks for lint, type checks, and tests.

Related MCP server: @xbghc/zotero-mcp

Goals

• Expose MCP tools/resources to read and export Safari Reading List items.

• Support adding new items to Safari Reading List.

• Keep implementation and decisions documented for durable project memory.

Requirements

• macOS (Safari Reading List target platform)

• Python 3.14

• uv

• Optional: mise for tool version management

Quick Start

1. Install dependencies:

   • uv sync

2. Run MCP server (stdio transport):

   • uv run python main.py

3. Use CLI:

   • srl --help

4. Run all checks:

   • mise run test:all

Repository Layout

• main.py - runtime entrypoint that starts the MCP server

• safari_reading_list_mcp/ - implementation modules (server, service, adapter, time/filter/export helpers, CLI)

• pyproject.toml - project metadata and dependencies

• mise.toml - local tool/runtime configuration

• .mise/tasks/ - reusable project tasks (lint, types, unit, coverage)

• AGENTS.md - primary agent/human collaboration conventions

• docs/ - project memory (plans, features, design, decisions, guides)

• .github/prompts/ - reusable workflow prompts for agent sessions

Development Workflow

Use the documentation cycle:

• define behavior in docs/features/

• create execution plans in docs/plans/

• capture hard-to-reverse decisions in docs/decisions/

• maintain architecture rationale in docs/design/

• keep practical usage notes in docs/guides/

For agent/human operating conventions, start with AGENTS.md.