Reading Companion

🚀 Reading Companion

A 4 - stage reading companion that assists you in setting goals, discovering books, tracking progress, and deepening learning through reflection. It functions as an MCP (Model Context Protocol) server integrated with Claude Desktop.

🚀 Quick Start

The Reading Companion is a 4 - stage tool that integrates with Claude Desktop via the MCP server. It helps you manage your reading journey from goal - setting to deep reflection.

✨ Features

• 4 - Stage Process: Guides you through building a reading profile, extracting patterns, curating book stacks, and reflecting on your reading.
• Customizable: Allows you to customize prompts and define your own reading domains.
• Data Storage: Stores all your reading - related data in a structured and human - readable format.

📦 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 the following 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. Then, restart Claude Desktop. You should see "Reading Companion" in the MCP servers list (hammer icon).

💻 Usage Examples

Initial Setup (Do Once)

Basic Usage

Step 1: Run the Interview

You: "Interview me for my reading goals"

Claude will inquire about your goals, preferences, and context. At the end, your profile will be saved.

Step 2: Extract Context (Optional)

You: "Analyze my reading profile"

Claude will extract deeper patterns to enhance recommendations.

Step 3: Build Your Book Stacks

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

You'll receive curated book recommendations for each domain.

Advanced Usage

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"

📚 Documentation

Available Tools

Stage 1: Interviewer

Stage 2: Context Builder

Stage 3: Syllabus Builder

Stage 4: Reflection

Author & Pattern Analysis

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

⚠️ Important Note

• "Reading Companion not appearing in Claude Desktop": Check that the path in claude_desktop_config.json is correct, restart Claude Desktop, and 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 and 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