Reading Companion

A 4-stage reading companion that helps you set goals, discover books, track progress, and deepen learning through reflection.

Works as an MCP (Model Context Protocol) server integrated with Claude Desktop.

The 4 Stages

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   STAGE 1    │     │   STAGE 2    │     │   STAGE 3    │
│ Interviewer  │ ──▶ │   Context    │ ──▶ │   Syllabus   │
│              │     │   Builder    │     │   Builder    │
│ "Who are you │     │  "Extract    │     │ "Build your  │
│  as a reader"│     │   patterns"  │     │  book stacks"│
└──────────────┘     └──────────────┘     └──────────────┘
       │                                          │
       │              ┌──────────────┐            │
       └────────────▶ │   STAGE 4    │ ◀──────────┘
                      │  Reflection  │
                      │   Partner    │
                      │              │
                      │ "What did    │
                      │  you learn?" │
                      └──────────────┘

1. Interviewer - Builds your reading profile through conversation
2. Context Builder - Extracts deeper patterns from your profile
3. Syllabus Builder - Creates curated book stacks for each domain
4. Reflection Partner - Helps process books and track growth

Installation

Prerequisites

• Python 3.10+
• uv (Python package manager)
• Claude Desktop

Setup

# Clone the repo
git clone https://github.com/aby0/reading-companion
cd reading-companion

# Install dependencies
uv sync

Configure Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "reading-companion": {
      "command": "uv",
      "args": ["--directory", "/path/to/reading-companion", "run", "reading-companion"]
    }
  }
}

Replace /path/to/reading-companion with the actual path where you cloned the repo.

Restart Claude Desktop. You should see "Reading Companion" in the MCP servers list (hammer icon).

Usage

Initial Setup (Do Once)

Step 1: Run the Interview

You: "Interview me for my reading goals"

Claude will ask about your goals, preferences, and context. At the end, your profile is saved.

Step 2: Extract Context (Optional)

You: "Analyze my reading profile"

Claude extracts deeper patterns to improve recommendations.

Step 3: Build Your Book Stacks

You: "Build me a reading stack for classic literature"

Get curated book recommendations for each domain.

Ongoing Use

Log a completed book:

You: "I just finished Anna Karenina by Tolstoy"

Reflect on a book:

You: "I want to reflect on Anna Karenina"

Check progress:

You: "How's my reading progress?"

Get next recommendation:

You: "What should I read next?"

Add a book manually:

You: "Add 'War and Peace' to my classic lit stack"

Available Tools

Stage 1: Interviewer

Tool	Description
start_interview	Begin the reading goal interview
save_profile	Save interview results as profile
get_profile	View current profile

Stage 2: Context Builder

Tool	Description
extract_context	Analyze profile for deeper patterns
update_latent_features	Save extracted features

Stage 3: Syllabus Builder

Tool	Description
build_bookstack	Generate recommendations for a domain
save_bookstack	Save generated book stack
get_bookstacks	View all book stacks
get_next_book	Get next unread book
add_book_to_stack	Manually add a book

Stage 4: Reflection

Tool	Description
log_book	Quick log a completed book
start_reflection	Begin deep reflection session
save_reflection	Save reflection insights
get_reading_log	View reading history
get_progress	Get progress summary

Author & Pattern Analysis

Tool	Description
analyze_reading_patterns	Analyze your reading history for patterns
get_author_profile	View profile for an author you've read
update_author_notes	Add style notes about an author
get_favorite_authors	List your top authors by affinity
add_book_connection	Link related books together
get_similar_books	Find books connected to one you've read

Data Storage

All your reading data is stored in ~/reading-companion-data/ (separate from the code):

~/reading-companion-data/
├── profile.md                    # Your profile (human-readable)
├── profile.json                  # Profile data (system)
├── bookstacks.json               # All stacks data (system)
├── authors.json                  # Author tracking (system)
├── patterns.json                 # Reading patterns (system)
├── connections.json              # Book connections (system)
│
├── bookstacks/                   # Book recommendations
│   ├── _index.md                 # Overview of all stacks
│   ├── classic_lit.md            # One file per domain
│   └── neuroscience.md
│
├── progress/                     # Progress tracking
│   ├── _current.md               # Current status with progress bars
│   ├── _insights.md              # Reading pattern insights
│   └── reading_log.json          # Structured log (system)
│
├── authors/                      # Author profiles
│   ├── _index.md                 # All authors by affinity
│   ├── leo-tolstoy.md            # One file per author
│   └── james-clear.md
│
└── reflections/                  # Book reflections
    ├── _index.md                 # Index of all books read
    ├── anna-karenina.md          # One file per book
    └── atomic-habits.md

Key feature: All .md files are human-readable and can be opened in VS Code, Obsidian, or any text editor.

Customization

Prompts

The prompts that guide each stage are in the reading_companion/prompts/ directory:

• interviewer.md - How interviews are conducted
• context_builder.md - How profiles are analyzed
• syllabus_builder.md - How books are curated
• reflection.md - How reflections are guided

Feel free to customize these to match your preferences.

Domains

You can have any reading domains you want - they're not hardcoded. During the interview, define whatever areas interest you:

• Classic Literature
• Science Fiction
• Neuroscience
• Philosophy
• Engineering
• History
• Whatever you're curious about!

Principles

• Intentional over random - Every book serves a purpose
• Learning over consuming - Reflection matters as much as reading
• Progress over perfection - Steady beats ambitious
• Personal over popular - What fits YOU, not bestseller lists

Troubleshooting

"Reading Companion not appearing in Claude Desktop"

• Check that the path in claude_desktop_config.json is correct
• Restart Claude Desktop
• Check the MCP logs for errors

"No profile found"

• Run start_interview first to create your profile

"Domain not found"

• Check your domain ID matches what's in your profile
• Use get_profile to see available domains

Development

To run the server directly for testing:

uv run reading-companion

To test with the MCP inspector:

npx @modelcontextprotocol/inspector uv run reading-companion

License

MIT