# 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.

## 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`.